1# @ohos.print (Print) 2 3The **print** module provides APIs for basic print operations. 4 5> **NOTE** 6> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 7 8## Modules to Import 9 10```ts 11import { print } from '@kit.BasicServicesKit'; 12``` 13 14## PrintTask 15 16Implements event listeners for print tasks. 17 18### on 19 20on(type: 'block', callback: Callback<void>): void 21 22Registers a listener for the print task blocking event. This API uses a callback to return the result. 23 24**Required permissions**: ohos.permission.PRINT 25 26**System capability**: SystemCapability.Print.PrintFramework 27 28**Parameters** 29| **Name**| **Type**| **Mandatory**| **Description**| 30| -------- | -------- | -------- | -------- | 31| type | string | Yes| Listening type.<br>The value is fixed at **'block'**,<br>indicating blocking of the print task.| 32| callback | Callback<void> | Yes| Callback used to return the result.| 33 34**Error codes** 35 36For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 37 38| ID| Error Message | 39| -------- | ------------------------------------------- | 40| 201 | the application does not have permission to call this function. | 41| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 42 43**Example** 44 45```ts 46import { print } from '@kit.BasicServicesKit'; 47import { BusinessError } from '@ohos.base'; 48 49let file = ['file://data/print/a.png', 'file://data/print/b.png']; 50print.print(file).then((printTask: print.PrintTask) => { 51 printTask.on('block', () => { 52 console.log('print state is block'); 53 }) 54 // ... 55}).catch((error: BusinessError) => { 56 console.log('print err ' + JSON.stringify(error)); 57}) 58``` 59 60### on 61 62on(type: 'succeed', callback: Callback<void>): void 63 64Registers a listener for the print task blocking event. This API uses a callback to return the result. 65 66**Required permissions**: ohos.permission.PRINT 67 68**System capability**: SystemCapability.Print.PrintFramework 69 70**Parameters** 71| **Name**| **Type**| **Mandatory**| **Description**| 72| -------- | -------- | -------- | -------- | 73| type | string | Yes| Listening type.<br>The value is fixed at **'succeed'**,<br>indicating success of the print task.| 74| callback | Callback<void> | Yes| Callback used to return the result.| 75 76**Error codes** 77 78For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 79 80| ID| Error Message | 81| -------- | ------------------------------------------- | 82| 201 | the application does not have permission to call this function. | 83| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 84 85**Example** 86 87```ts 88import { print } from '@kit.BasicServicesKit'; 89import { BusinessError } from '@ohos.base'; 90 91let file = ['file://data/print/a.png', 'file://data/print/b.png']; 92print.print(file).then((printTask: print.PrintTask) => { 93 printTask.on('succeed', () => { 94 console.log('print state is succeed'); 95 }) 96 // ... 97}).catch((error: BusinessError) => { 98 console.log('print err ' + JSON.stringify(error)); 99}) 100``` 101 102### on 103 104on(type: 'fail', callback: Callback<void>): void 105 106Registers a listener for the print task blocking event. This API uses a callback to return the result. 107 108**Required permissions**: ohos.permission.PRINT 109 110**System capability**: SystemCapability.Print.PrintFramework 111 112**Parameters** 113| **Name**| **Type**| **Mandatory**| **Description**| 114| -------- | -------- | -------- | -------- | 115| type | string | Yes| Listening type.<br>The value is fixed at **'fail'**,<br>indicating failure of the print task.| 116| callback | Callback<void> | Yes| Callback used to return the result.| 117 118**Error codes** 119 120For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 121 122| ID| Error Message | 123| -------- | ------------------------------------------- | 124| 201 | the application does not have permission to call this function. | 125| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 126 127**Example** 128 129```ts 130import { print } from '@kit.BasicServicesKit'; 131import { BusinessError } from '@ohos.base'; 132 133let file = ['file://data/print/a.png', 'file://data/print/b.png']; 134print.print(file).then((printTask: print.PrintTask) => { 135 printTask.on('fail', () => { 136 console.log('print state is fail'); 137 }) 138 // ... 139}).catch((error: BusinessError) => { 140 console.log('print err ' + JSON.stringify(error)); 141}) 142``` 143 144### on 145 146on(type: 'cancel', callback: Callback<void>): void 147 148Registers a listener for the print task blocking event. This API uses a callback to return the result. 149 150**Required permissions**: ohos.permission.PRINT 151 152**System capability**: SystemCapability.Print.PrintFramework 153 154**Parameters** 155| **Name**| **Type**| **Mandatory**| **Description**| 156| -------- | -------- | -------- | -------- | 157| type | string | Yes| Listening type.<br>The value is fixed at **'cancel'**,<br>indicating canceling of the print task.| 158| callback | Callback<void> | Yes| Callback used to return the result.| 159 160**Error codes** 161 162For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 163 164| ID| Error Message | 165| -------- | ------------------------------------------- | 166| 201 | the application does not have permission to call this function. | 167| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 168 169**Example** 170 171```ts 172import { print } from '@kit.BasicServicesKit'; 173import { BusinessError } from '@ohos.base'; 174 175let file = ['file://data/print/a.png', 'file://data/print/b.png']; 176print.print(file).then((printTask: print.PrintTask) => { 177 printTask.on('cancel', () => { 178 console.log('print state is cancel'); 179 }) 180 // ... 181}).catch((error: BusinessError) => { 182 console.log('print err ' + JSON.stringify(error)); 183}) 184``` 185 186### off 187 188off(type: 'block', callback?: Callback<void>): void 189 190Unregisters the listener for the print task blocking event. This API uses a callback to return the result. 191 192**Required permissions**: ohos.permission.PRINT 193 194**System capability**: SystemCapability.Print.PrintFramework 195 196**Parameters** 197| **Name**| **Type**| **Mandatory**| **Description**| 198| -------- | -------- | -------- | -------- | 199| type | string | Yes| Listening type.<br>The value is fixed at **'block'**,<br>indicating blocking of the print task.| 200| callback | Callback<void> | No| Callback used to return the result.| 201 202**Error codes** 203 204For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 205 206| ID| Error Message | 207| -------- | ------------------------------------------- | 208| 201 | the application does not have permission to call this function. | 209| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 210 211**Example** 212 213```ts 214import { print } from '@kit.BasicServicesKit'; 215import { BusinessError } from '@ohos.base'; 216 217let file = ['file://data/print/a.png', 'file://data/print/b.png']; 218print.print(file).then((printTask: print.PrintTask) => { 219 printTask.off('block', () => { 220 console.log('unregister state block'); 221 }) 222 // ... 223}).catch((error: BusinessError) => { 224 console.log('print err ' + JSON.stringify(error)); 225}) 226``` 227 228### off 229 230off(type: 'succeed', callback?: Callback<void>): void 231 232Unregisters the listener for the print task blocking event. This API uses a callback to return the result. 233 234**Required permissions**: ohos.permission.PRINT 235 236**System capability**: SystemCapability.Print.PrintFramework 237 238**Parameters** 239| **Name**| **Type**| **Mandatory**| **Description**| 240| -------- | -------- | -------- | -------- | 241| type | string | Yes| Listening type.<br>The value is fixed at **'succeed'**,<br>indicating success of the print task.| 242| callback | Callback<void> | No| Callback used to return the result.| 243 244**Error codes** 245 246For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 247 248| ID| Error Message | 249| -------- | ------------------------------------------- | 250| 201 | the application does not have permission to call this function. | 251| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 252 253**Example** 254 255```ts 256import { print } from '@kit.BasicServicesKit'; 257import { BusinessError } from '@ohos.base'; 258 259let file = ['file://data/print/a.png', 'file://data/print/b.png']; 260print.print(file).then((printTask: print.PrintTask) => { 261 printTask.off('succeed', () => { 262 console.log('unregister state succeed'); 263 }) 264 // ... 265}).catch((error: BusinessError) => { 266 console.log('print err ' + JSON.stringify(error)); 267}) 268``` 269 270### off 271 272off(type: 'fail', callback?: Callback<void>): void 273 274Unregisters the listener for the print task blocking event. This API uses a callback to return the result. 275 276**Required permissions**: ohos.permission.PRINT 277 278**System capability**: SystemCapability.Print.PrintFramework 279 280**Parameters** 281| **Name**| **Type**| **Mandatory**| **Description**| 282| -------- | -------- | -------- | -------- | 283| type | string | Yes| Listening type.<br>The value is fixed at **'fail'**,<br>indicating failure of the print task.| 284| callback | Callback<void> | No| Callback used to return the result.| 285 286**Error codes** 287 288For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 289 290| ID| Error Message | 291| -------- | ------------------------------------------- | 292| 201 | the application does not have permission to call this function. | 293| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 294 295**Example** 296 297```ts 298import { print } from '@kit.BasicServicesKit'; 299import { BusinessError } from '@ohos.base'; 300 301let file = ['file://data/print/a.png', 'file://data/print/b.png']; 302print.print(file).then((printTask: print.PrintTask) => { 303 printTask.off('fail', () => { 304 console.log('unregister state fail'); 305 }) 306 // ... 307}).catch((error: BusinessError) => { 308 console.log('print err ' + JSON.stringify(error)); 309}) 310``` 311 312### off 313 314off(type: 'cancel', callback?: Callback<void>): void 315 316Unregisters the listener for the print task blocking event. This API uses a callback to return the result. 317 318**Required permissions**: ohos.permission.PRINT 319 320**System capability**: SystemCapability.Print.PrintFramework 321 322**Parameters** 323| **Name**| **Type**| **Mandatory**| **Description**| 324| -------- | -------- | -------- | -------- | 325| type | string | Yes| Listening type.<br>The value is fixed at **'cancel'**,<br>indicating canceling of the print task.| 326| callback | Callback<void> | No| Callback used to return the result.| 327 328**Error codes** 329 330For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 331 332| ID| Error Message | 333| -------- | ------------------------------------------- | 334| 201 | the application does not have permission to call this function. | 335| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 336 337**Example** 338 339```ts 340import { print } from '@kit.BasicServicesKit'; 341import { BusinessError } from '@ohos.base'; 342 343let file = ['file://data/print/a.png', 'file://data/print/b.png']; 344print.print(file).then((printTask: print.PrintTask) => { 345 printTask.off('cancel', () => { 346 console.log('unregister state cancel'); 347 }) 348 // ... 349}).catch((error: BusinessError) => { 350 console.log('print err ' + JSON.stringify(error)); 351}) 352``` 353 354## PrintDocumentAdapter<sup>11+</sup> 355 356Provides information about the document to print. This API must be implemented by a third-party application. 357 358### onStartLayoutWrite 359 360onStartLayoutWrite(jobId: string, oldAttrs: PrintAttributes, newAttrs: PrintAttributes, fd: number, writeResultCallback: (jobId: string, writeResult: PrintFileCreationState) => void): void 361 362Sends an empty PDF file descriptor to a third-party application. The third-party application updates the file with the new print attributes and then calls **writeResultCallback** to print the file. 363 364**Required permissions**: ohos.permission.PRINT 365 366**System capability**: SystemCapability.Print.PrintFramework 367 368**Parameters** 369| **Name**| **Type**| **Mandatory**| **Description**| 370| -------- | -------- | -------- | -------- | 371| jobId | string | Yes| ID of the print job.| 372| oldAttrs | PrintAttributes | Yes| Old print attributes.| 373| newAttrs | PrintAttributes | Yes| New print attributes.| 374| fd | number | Yes| PDF file descriptor sent to the API caller.| 375| writeResultCallback | (jobId: string, writeResult: PrintFileCreationState) | Yes| Callback used to print the updated file.| 376 377**Error codes** 378 379For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 380 381| ID| Error Message | 382| -------- | ------------------------------------------- | 383| 201 | the application does not have permission to call this function. | 384| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 385 386**Example** 387 388```ts 389import { print } from '@kit.BasicServicesKit'; 390import { BusinessError } from '@ohos.base'; 391 392class MyPrintDocumentAdapter implements print.PrintDocumentAdapter { 393 onStartLayoutWrite(jobId: string, oldAttrs: print.PrintAttributes, newAttrs: print.PrintAttributes, fd: number, 394 writeResultCallback: (jobId: string, writeResult: print.PrintFileCreationState) => void) { 395 writeResultCallback(jobId, print.PrintFileCreationState.PRINT_FILE_CREATED); 396 }; 397 onJobStateChanged(jobId: string, state: print.PrintDocumentAdapterState) { 398 if (state == print.PrintDocumentAdapterState.PREVIEW_DESTROY) { 399 console.log('PREVIEW_DESTROY'); 400 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_SUCCEED) { 401 console.log('PRINT_TASK_SUCCEED'); 402 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_FAIL) { 403 console.log('PRINT_TASK_FAIL'); 404 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_CANCEL) { 405 console.log('PRINT_TASK_CANCEL'); 406 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_BLOCK) { 407 console.log('PRINT_TASK_BLOCK'); 408 } 409 } 410} 411``` 412 413### onJobStateChanged 414 415onJobStateChanged(jobId: string, state: PrintDocumentAdapterState): void 416 417Registers a listener for print job state changes. 418 419**Required permissions**: ohos.permission.PRINT 420 421**System capability**: SystemCapability.Print.PrintFramework 422 423**Parameters** 424| **Name**| **Type**| **Mandatory**| **Description**| 425| -------- | -------- | -------- | -------- | 426| jobId | string | Yes| ID of the print job.| 427| state | PrintDocumentAdapterState | Yes| New state of the print job.| 428 429**Error codes** 430 431For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 432 433| ID| Error Message | 434| -------- | ------------------------------------------- | 435| 201 | the application does not have permission to call this function. | 436| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 437 438**Example** 439 440```ts 441import { print } from '@kit.BasicServicesKit'; 442import { BusinessError } from '@ohos.base'; 443 444class MyPrintDocumentAdapter implements print.PrintDocumentAdapter { 445 onStartLayoutWrite(jobId: string, oldAttrs: print.PrintAttributes, newAttrs: print.PrintAttributes, fd: number, 446 writeResultCallback: (jobId: string, writeResult: print.PrintFileCreationState) => void) { 447 writeResultCallback(jobId, print.PrintFileCreationState.PRINT_FILE_CREATED); 448 }; 449 onJobStateChanged(jobId: string, state: print.PrintDocumentAdapterState) { 450 if (state == print.PrintDocumentAdapterState.PREVIEW_DESTROY) { 451 console.log('PREVIEW_DESTROY'); 452 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_SUCCEED) { 453 console.log('PRINT_TASK_SUCCEED'); 454 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_FAIL) { 455 console.log('PRINT_TASK_FAIL'); 456 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_CANCEL) { 457 console.log('PRINT_TASK_CANCEL'); 458 } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_BLOCK) { 459 console.log('PRINT_TASK_BLOCK'); 460 } 461 } 462} 463``` 464 465## print 466 467print(files: Array<string>, callback: AsyncCallback<PrintTask>): void 468 469Prints files. This API uses an asynchronous callback to return the result. 470 471**Required permissions**: ohos.permission.PRINT 472 473**System capability**: SystemCapability.Print.PrintFramework 474 475**Parameters** 476| **Name**| **Type**| **Mandatory**| **Description**| 477| -------- | -------- | -------- | -------- | 478| files | Array<string> | Yes| List of files to print. Images (in .jpg, .png, .gif, .bmp, or .webp format) and PDF files are supported. Before a system application passes in the URI, it needs to call the **uriPermissionManager.grantUriPermission()** API to authorize the print application. This API is a system API. [print](#print11-2) is recommended for third-party application.| 479| callback | AsyncCallback<PrintTask> | Yes| Callback used to return the result.| 480 481**Error codes** 482 483For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 484 485| ID| Error Message | 486| -------- | ------------------------------------------- | 487| 201 | the application does not have permission to call this function. | 488| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 489 490**Example** 491 492```ts 493import { print } from '@kit.BasicServicesKit'; 494import { BusinessError } from '@ohos.base'; 495 496// Pass in the URIs of the files. 497let files = ['file://data/print/a.png', 'file://data/print/b.png']; 498// Alternatively, pass in the fd. 499//let files = ['fd://1', 'fd://2']; 500print.print(files, (err: BusinessError, printTask: print.PrintTask) => { 501 if (err) { 502 console.log('print err ' + JSON.stringify(err)); 503 } else { 504 printTask.on('succeed', () => { 505 console.log('print state is succeed'); 506 }) 507 // ... 508 } 509}) 510``` 511 512## print 513 514print(files: Array<string>): Promise<PrintTask> 515 516Prints files. This API uses a promise to return the result. 517 518**Required permissions**: ohos.permission.PRINT 519 520**System capability**: SystemCapability.Print.PrintFramework 521 522**Parameters** 523| **Name**| **Type**| **Mandatory**| **Description**| 524| -------- | -------- | -------- | -------- | 525| files | Array<string> | Yes| List of files to print. Images (in .jpg, .png, .gif, .bmp, or .webp format) and PDF files are supported. Before a system application passes in the URI, it needs to call the **uriPermissionManager.grantUriPermission()** API to authorize the print application. This API is a system API. [print](#print11-2) is recommended for third-party application.| 526 527**Return value** 528| **Type**| **Description**| 529| -------- | -------- | 530| Promise<PrintTask> | Print result.| 531 532**Error codes** 533 534For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 535 536| ID| Error Message | 537| -------- | ------------------------------------------- | 538| 201 | the application does not have permission to call this function. | 539| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 540 541**Example** 542 543```ts 544import { print } from '@kit.BasicServicesKit'; 545import { BusinessError } from '@ohos.base'; 546 547// Pass in the URIs of the files. 548let files = ['file://data/print/a.png', 'file://data/print/b.png']; 549// Alternatively, pass in the fd. 550//let files = ['fd://1', 'fd://2']; 551print.print(files).then((printTask: print.PrintTask) => { 552 printTask.on('succeed', () => { 553 console.log('print state is succeed'); 554 }) 555 // ... 556}).catch((error: BusinessError) => { 557 console.log('print err ' + JSON.stringify(error)); 558}) 559``` 560 561## print<sup>11+</sup> 562 563print(files: Array<string>, context: Context, callback: AsyncCallback<PrintTask>): void 564 565Prints files. This API uses an asynchronous callback to return the result. 566 567**Required permissions**: ohos.permission.PRINT 568 569**System capability**: SystemCapability.Print.PrintFramework 570 571**Parameters** 572| **Name**| **Type**| **Mandatory**| **Description**| 573| -------- | -------- | -------- | -------- | 574| files | Array<string> | Yes| List of files to print. Images (in .jpg, .png, .gif, .bmp, or .webp format) and PDF files are supported. Before a system application passes in the URI, it needs to call the **uriPermissionManager.grantUriPermission()** API to authorize the print application. This API is a system API. [print](#print11-2) is recommended for third-party application.| 575| context | Context | Yes| UIAbilityContext used to start the system print UI.| 576| callback | AsyncCallback<PrintTask> | Yes| Callback used to return the result.| 577 578**Error codes** 579 580For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 581 582| ID| Error Message | 583| -------- | ------------------------------------------- | 584| 201 | the application does not have permission to call this function. | 585| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 586 587**Example** 588 589```ts 590import { print } from '@kit.BasicServicesKit'; 591import { BusinessError } from '@ohos.base'; 592 593// Pass in the URIs of the files. 594let files = ['file://data/print/a.png', 'file://data/print/b.png']; 595// Alternatively, pass in the fd. 596//let files = ['fd://1', 'fd://2']; 597let context = getContext(this); 598print.print(files, context, (err: BusinessError, printTask: print.PrintTask) => { 599 if (err) { 600 console.log('print err ' + JSON.stringify(err)); 601 } else { 602 printTask.on('succeed', () => { 603 console.log('print state is succeed'); 604 }) 605 // ... 606 } 607}) 608``` 609 610## print<sup>11+</sup> 611 612print(files: Array<string>, context: Context): Promise<PrintTask> 613 614Prints files. This API uses a promise to return the result. 615 616**Required permissions**: ohos.permission.PRINT 617 618**System capability**: SystemCapability.Print.PrintFramework 619 620**Parameters** 621| **Name**| **Type**| **Mandatory**| **Description**| 622| -------- | -------- | -------- | -------- | 623| files | Array<string> | Yes| List of files to print. Images (in .jpg, .png, .gif, .bmp, or .webp format) and PDF files are supported. Before a system application passes in the URI, it needs to call the **uriPermissionManager.grantUriPermission()** API to authorize the print application. This API is a system API. [print](#print11-2) is recommended for third-party application.| 624| context | Context | Yes| UIAbilityContext used to start the system print UI.| 625 626**Return value** 627| **Type**| **Description**| 628| -------- | -------- | 629| Promise<PrintTask> | Print result.| 630 631**Error codes** 632 633For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 634 635| ID| Error Message | 636| -------- | ------------------------------------------- | 637| 201 | the application does not have permission to call this function. | 638| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 639 640**Example** 641 642```ts 643import { print } from '@kit.BasicServicesKit'; 644import { BusinessError } from '@ohos.base'; 645 646// Pass in the URIs of the files. 647let files = ['file://data/print/a.png', 'file://data/print/b.png']; 648// Alternatively, pass in the fd. 649//let files = ['fd://1', 'fd://2']; 650let context = getContext(this); 651print.print(files, context).then((printTask: print.PrintTask) => { 652 printTask.on('succeed', () => { 653 console.log('print state is succeed'); 654 }) 655 // ... 656}).catch((error: BusinessError) => { 657 console.log('print err ' + JSON.stringify(error)); 658}) 659``` 660 661## print<sup>11+</sup> 662 663print(jobName: string, printAdapter: PrintDocumentAdapter, printAttributes: PrintAttributes, context: Context): Promise<PrintTask> 664 665Prints a file. This API uses a promise to return the result. 666 667**Required permissions**: ohos.permission.PRINT 668 669**System capability**: SystemCapability.Print.PrintFramework 670 671**Parameters** 672| **Name**| **Type**| **Mandatory**| **Description**| 673| -------- | -------- | -------- | -------- | 674| jobName | string | Yes| Name of the file to print, for example, **test.pdf**. The printer uses the [onStartLayoutWrite](#onstartlayoutwrite) API to send the **fd** of the empty PDF file to the API caller. The API caller uses the new print attributes to update the file to print.| 675| printAdapter | PrintDocumentAdapter | Yes| [PrintDocumentAdapter](#printdocumentadapter11) API instance implemented by a third-party application.| 676| printAttributes | PrintAttributes | Yes| Print attributes.| 677| context | Context | Yes| UIAbilityContext used to start the system print UI.| 678 679**Return value** 680| **Type**| **Description**| 681| -------- | -------- | 682| Promise<PrintTask> | Print result.| 683 684**Error codes** 685 686For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 687 688| ID| Error Message | 689| -------- | ------------------------------------------- | 690| 201 | the application does not have permission to call this function. | 691| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 692 693**Example** 694 695```ts 696import { print } from '@kit.BasicServicesKit'; 697import { BusinessError } from '@ohos.base'; 698 699let jobName : string = "jobName"; 700let printAdapter : print.PrintDocumentAdapter | null = null; 701let printAttributes : print.PrintAttributes = { 702 copyNumber: 1, 703 pageRange: { 704 startPage: 0, 705 endPage: 5, 706 pages: [] 707 }, 708 pageSize: print.PrintPageType.PAGE_ISO_A3, 709 directionMode: print.PrintDirectionMode.DIRECTION_MODE_AUTO, 710 colorMode: print.PrintColorMode.COLOR_MODE_MONOCHROME, 711 duplexMode: print.PrintDuplexMode.DUPLEX_MODE_NONE 712} 713let context = getContext(); 714 715print.print(jobName, printAdapter, printAttributes, context).then((printTask: print.PrintTask) => { 716 printTask.on('succeed', () => { 717 console.log('print state is succeed'); 718 }) 719 // ... 720}).catch((error: BusinessError) => { 721 console.log('print err ' + JSON.stringify(error)); 722}) 723``` 724 725## PrintAttributes<sup>11+</sup> 726 727Defines the print attributes. 728 729**System capability**: SystemCapability.Print.PrintFramework 730 731**Attributes** 732| **Name**| **Type**| **Mandatory**| **Description**| 733| -------- | -------- | -------- | -------- | 734| copyNumber | number | No| Number of printed file copies.| 735| pageRange | PrintPageRange | No| Page range of the file to print.| 736| pageSize | PrintPageSize \| PrintPageType | No| Page size of the file to print.| 737| directionMode | PrintDirectionMode | No| Print direction mode.| 738| colorMode | PrintColorMode | No| Color mode of the files to print.| 739| duplexMode | PrintDuplexMode | No| Duplex mode of the files to print.| 740 741## PrintPageRange<sup>11+</sup> 742 743Defines the print range. 744 745**System capability**: SystemCapability.Print.PrintFramework 746 747**Attributes** 748| **Name**| **Type**| **Mandatory**| **Description**| 749| -------- | -------- | -------- | -------- | 750| startPage | number | No| Start page.| 751| endPage | number | No| End page.| 752| pages | Array<number> | No| Page range set of the file to print.| 753 754 755## PrintPageSize<sup>11+</sup> 756 757Defines the size of the printed page. 758 759**System capability**: SystemCapability.Print.PrintFramework 760 761**Attributes** 762| **Name**| **Type**| **Mandatory**| **Description**| 763| -------- | -------- | -------- | -------- | 764| id | string | Yes| Paper size ID.| 765| name | string | Yes| Paper size name.| 766| width | number | Yes| Page width, in millimeters.| 767| height | number | Yes| Page height, in millimeters.| 768 769## PrintDirectionMode<sup>11+</sup> 770 771Enumerates the print direction modes. 772 773**System capability**: SystemCapability.Print.PrintFramework 774 775| **Name**| **Value**| **Description**| 776| -------- | -------- | -------- | 777| DIRECTION_MODE_AUTO | 0 | Automatic.| 778| DIRECTION_MODE_PORTRAIT | 1 | Portrait mode.| 779| DIRECTION_MODE_LANDSCAPE | 2 | Landscape mode.| 780 781## PrintColorMode<sup>11+</sup> 782 783Enumerates the color modes. 784 785**System capability**: SystemCapability.Print.PrintFramework 786 787| **Name**| **Value**| **Description**| 788| -------- | -------- | -------- | 789| COLOR_MODE_MONOCHROME | 0 | Black and white.| 790| COLOR_MODE_COLOR | 1 | Color.| 791 792## PrintDuplexMode<sup>11+</sup> 793 794Enumerates the duplex modes. 795 796**System capability**: SystemCapability.Print.PrintFramework 797 798| **Name**| **Value**| **Description**| 799| -------- | -------- | -------- | 800| DUPLEX_MODE_NONE | 0 | Simplex (single-sided).| 801| DUPLEX_MODE_LONG_EDGE | 1 | Duplex (double-sided) with flipping on long edge.| 802| DUPLEX_MODE_SHORT_EDGE | 2 | Duplex (double-sided) with flipping on short edge.| 803 804## PrintPageType<sup>11+</sup> 805 806Enumerates the print page types. 807 808**System capability**: SystemCapability.Print.PrintFramework 809 810| **Name**| **Value**| **Description**| 811| -------- | -------- | -------- | 812| PAGE_ISO_A3 | 0 | A3.| 813| PAGE_ISO_A4 | 1 | A4.| 814| PAGE_ISO_A5 | 2 | A5.| 815| PAGE_JIS_B5 | 3 | B5.| 816| PAGE_ISO_C5 | 4 | C5.| 817| PAGE_ISO_DL | 5 | DL.| 818| PAGE_LETTER | 6 | Letter.| 819| PAGE_LEGAL | 7 | Legal.| 820| PAGE_PHOTO_4X6 | 8 | 4 x 6 photo paper.| 821| PAGE_PHOTO_5X7 | 9 | 5 x 7 photo paper.| 822| PAGE_INT_DL_ENVELOPE | 10 | International envelope DL.| 823| PAGE_B_TABLOID | 11 | B Tabloid.| 824 825## PrintDocumentAdapterState<sup>11+</sup> 826 827Enumerates the print job states. 828 829**System capability**: SystemCapability.Print.PrintFramework 830 831| **Name**| **Value**| **Description**| 832| -------- | -------- | -------- | 833| PREVIEW_DESTROY | 0 | The preview fails.| 834| PRINT_TASK_SUCCEED | 1 | The print job is successful.| 835| PRINT_TASK_FAIL | 2 | The print job is failed.| 836| PRINT_TASK_CANCEL | 3 | The print job is canceled.| 837| PRINT_TASK_BLOCK | 4 | The print job is blocked.| 838 839## PrintFileCreationState<sup>11+</sup> 840 841Enumerates the print file creation status. 842 843**System capability**: SystemCapability.Print.PrintFramework 844 845| **Name**| **Value**| **Description**| 846| -------- | -------- | -------- | 847| PRINT_FILE_CREATED | 0 | The print file is created successfully.| 848| PRINT_FILE_CREATION_FAILED | 1 | The print file fails to be created.| 849| PRINT_FILE_CREATED_UNRENDERED | 2 | The print file is successfully created but not rendered.| 850 851## PrinterState<sup>14+</sup> 852 853Enumerates the printer states. 854 855**System capability**: SystemCapability.Print.PrintFramework 856 857| **Name**| **Value**| **Description**| 858| -------- | -------- | -------- | 859| PRINTER_ADDED | 0 | A new printer is added.| 860| PRINTER_REMOVED | 1 | The printer is removed.| 861| PRINTER_CAPABILITY_UPDATED | 2 | The printer is updated.| 862| PRINTER_CONNECTED | 3 | The printer is connected.| 863| PRINTER_DISCONNECTED | 4 | The printer is disconnected.| 864| PRINTER_RUNNING | 5 | The printer is running.| 865 866## PrintJobState<sup>14+</sup> 867 868Enumerates the print job states. 869 870**System capability**: SystemCapability.Print.PrintFramework 871 872| **Name**| **Value**| **Description**| 873| -------- | -------- | -------- | 874| PRINT_JOB_PREPARE | 0 | The printer is prepared for the print job.| 875| PRINT_JOB_QUEUED | 1 | The print job is on the print queue of the printer.| 876| PRINT_JOB_RUNNING | 2 | The print job is being executed.| 877| PRINT_JOB_BLOCKED | 3 | The print job is blocked.| 878| PRINT_JOB_COMPLETED | 4 | The print job is complete.| 879 880## PrintJobSubState<sup>14+</sup> 881 882Enumerates the print job substates. 883 884**System capability**: SystemCapability.Print.PrintFramework 885 886| **Name**| **Value**| **Description**| 887| -------- | -------- | -------- | 888| PRINT_JOB_COMPLETED_SUCCESS | 0 | The print job is successful.| 889| PRINT_JOB_COMPLETED_FAILED | 1 | The print job is failed.| 890| PRINT_JOB_COMPLETED_CANCELLED | 2 | The print job is canceled by user.| 891| PRINT_JOB_COMPLETED_FILE_CORRUPTED | 3 | The print job is corrupted.| 892| PRINT_JOB_BLOCK_OFFLINE | 4 | The printer is offline.| 893| PRINT_JOB_BLOCK_BUSY | 5 | The printer is occupied by another process.| 894| PRINT_JOB_BLOCK_CANCELLED | 6 | The print job is canceled due to a block.| 895| PRINT_JOB_BLOCK_OUT_OF_PAPER | 7 | The printer is out of paper.| 896| PRINT_JOB_BLOCK_OUT_OF_INK | 8 | The printer is out of ink.| 897| PRINT_JOB_BLOCK_OUT_OF_TONER | 9 | The printer is out of toner.| 898| PRINT_JOB_BLOCK_JAMMED | 10 | The printer is in a paper jam.| 899| PRINT_JOB_BLOCK_DOOR_OPEN | 11 | The printer door is open.| 900| PRINT_JOB_BLOCK_SERVICE_REQUEST | 12 | Print service request.| 901| PRINT_JOB_BLOCK_LOW_ON_INK | 13 | The printer is low on ink.| 902| PRINT_JOB_BLOCK_LOW_ON_TONER | 14 | The printer is low on toner.| 903| PRINT_JOB_BLOCK_REALLY_LOW_ON_INK | 15 | The printer is extremely low on ink.| 904| PRINT_JOB_BLOCK_BAD_CERTIFICATE | 16 | The print certificate is incorrect.| 905| PRINT_JOB_BLOCK_ACCOUNT_ERROR | 18 | There is an error with the printer account.| 906| PRINT_JOB_BLOCK_PRINT_PERMISSION_ERROR | 19 | There is an error with the printer permission.| 907| PRINT_JOB_BLOCK_PRINT_COLOR_PERMISSION_ERROR | 20 | There is an error with the color printing permission.| 908| PRINT_JOB_BLOCK_NETWORK_ERROR | 21 | The printer fails to connect to the network.| 909| PRINT_JOB_BLOCK_SERVER_CONNECTION_ERROR | 22 | The printer fails to connect to the server.| 910| PRINT_JOB_BLOCK_LARGE_FILE_ERROR | 23 | There is an error with a large file printing.| 911| PRINT_JOB_BLOCK_FILE_PARSING_ERROR | 24 | There is an error with file parsing.| 912| PRINT_JOB_BLOCK_SLOW_FILE_CONVERSION | 25 | The file conversion is slow.| 913| PRINT_JOB_RUNNING_UPLOADING_FILES | 26 | The file is uploading.| 914| PRINT_JOB_RUNNING_CONVERTING_FILES | 27 | The file is converting.| 915| PRINT_JOB_BLOCK_UNKNOWN | 99 | There is an unknown error with the printer.| 916 917## PrintErrorCode<sup>14+</sup> 918 919Enumerates the print error codes. 920 921**System capability**: SystemCapability.Print.PrintFramework 922 923| **Name**| **Value**| **Description**| 924| -------- | -------- | -------- | 925| E_PRINT_NONE | 0 | No error.| 926| E_PRINT_NO_PERMISSION | 201 | No permission.| 927| E_PRINT_INVALID_PARAMETER | 401 | Invalid parameters.| 928| E_PRINT_GENERIC_FAILURE | 13100001 | Printing failure.| 929| E_PRINT_RPC_FAILURE | 13100002 | RPC failure.| 930| E_PRINT_SERVER_FAILURE | 13100003 | Print service failure.| 931| E_PRINT_INVALID_EXTENSION | 13100004 | Invalid printer extension.| 932| E_PRINT_INVALID_PRINTER | 13100005 | Invalid printer.| 933| E_PRINT_INVALID_PRINT_JOB | 13100006 | Invalid print job.| 934| E_PRINT_FILE_IO | 13100007 | Incorrect file input/output.| 935 936## ApplicationEvent<sup>14+</sup> 937 938Enumerates print application events. 939 940**System capability**: SystemCapability.Print.PrintFramework 941 942| **Name**| **Value**| **Description**| 943| -------- | -------- | -------- | 944| APPLICATION_CREATED | 0 | Starts the print application.| 945| APPLICATION_CLOSED_FOR_STARTED | 1 | Closes the print application by clicking **Start**.| 946| APPLICATION_CLOSED_FOR_CANCELED | 2 | Closes the print application by clicking **Cancel**.| 947 948## addPrinterToDiscovery<sup>14+</sup> 949 950addPrinterToDiscovery(printerInformation: PrinterInformation): Promise<void> 951 952Adds a printer to the printer discovery list. This API uses a promise to return the result. 953 954**Required permissions**: ohos.permission.PRINT 955 956**System capability**: SystemCapability.Print.PrintFramework 957 958**Parameters** 959| **Name**| **Type**| **Mandatory**| **Description**| 960| -------- | -------- | -------- | -------- | 961| printerInformation | PrinterInformation | Yes| The added printer.| 962 963**Return value** 964| **Type**| **Description**| 965| -------- | -------- | 966| Promise<void> | Result of adding a printer to the printer discovery list.| 967 968**Error codes** 969 970For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 971 972| ID| Error Message | 973| -------- | ------------------------------------------- | 974| 201 | the application does not have permission to call this function. | 975| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 976 977**Example** 978 979```ts 980import { print } from '@kit.BasicServicesKit'; 981import { BusinessError } from '@ohos.base'; 982 983let printerInformation : print.PrinterInformation = { 984 printerId : 'testPrinterId', 985 printerName : 'testPrinterName', 986 printerStatus : 0, 987 description : 'testDesc', 988 uri : 'testUri', 989 printerMake : 'testPrinterMake', 990 options : 'testOps' 991}; 992print.addPrinterToDiscovery(printerInformation).then((data : void) => { 993 console.log('addPrinterToDiscovery data : ' + JSON.stringify(data)); 994}).catch((error: BusinessError) => { 995 console.log('addPrinterToDiscovery error : ' + JSON.stringify(error)); 996}) 997``` 998 999## updatePrinterInDiscovery<sup>14+</sup> 1000 1001updatePrinterInDiscovery(printerInformation: PrinterInformation): Promise<void> 1002 1003Updates the printer capabilities to the printer discovery list. This API uses a promise to return the result. 1004 1005**Required permissions**: ohos.permission.PRINT 1006 1007**System capability**: SystemCapability.Print.PrintFramework 1008 1009**Parameters** 1010| **Name**| **Type**| **Mandatory**| **Description**| 1011| -------- | -------- | -------- | -------- | 1012| printerInformation | PrinterInformation | Yes| Printer whose capability is to be updated.| 1013 1014**Return value** 1015| **Type**| **Description**| 1016| -------- | -------- | 1017| Promise<void> | Result of updating the printer capabilitise to the printer discovery list.| 1018 1019**Error codes** 1020 1021For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 1022 1023| ID| Error Message | 1024| -------- | ------------------------------------------- | 1025| 201 | the application does not have permission to call this function. | 1026| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1027 1028**Example** 1029 1030```ts 1031import { print } from '@kit.BasicServicesKit'; 1032import { BusinessError } from '@ohos.base'; 1033 1034let testPageSize : print.PrintPageSize = { 1035 id : 'ISO_A4', 1036 name : 'iso_a4_210x297mm', 1037 width : 8268, 1038 height : 11692 1039}; 1040 1041let testCapability : print.PrinterCapabilities = { 1042 supportedPageSizes : [testPageSize], 1043 supportedColorModes : [print.PrintColorMode.COLOR_MODE_MONOCHROME], 1044 supportedDuplexModes : [print.PrintDuplexMode.DUPLEX_MODE_NONE], 1045 supportedMediaTypes : ['stationery'], 1046 supportedQualities : [print.PrintQuality.QUALITY_NORMAL], 1047 supportedOrientations : [print.PrintOrientationMode.ORIENTATION_MODE_PORTRAIT], 1048 options : 'testOptions' 1049}; 1050 1051let printerInformation : print.PrinterInformation = { 1052 printerId : 'testPrinterId', 1053 printerName : 'testPrinterName', 1054 printerStatus : 0, 1055 description : 'testDesc', 1056 capability : testCapability, 1057 uri : 'testUri', 1058 printerMake : 'testPrinterMake', 1059 options : 'testOptions' 1060}; 1061print.updatePrinterInDiscovery(printerInformation).then((data : void) => { 1062 console.log('updatePrinterInDiscovery data : ' + JSON.stringify(data)); 1063}).catch((error: BusinessError) => { 1064 console.log('updatePrinterInDiscovery error : ' + JSON.stringify(error)); 1065}) 1066``` 1067 1068## removePrinterFromDiscovery<sup>14+</sup> 1069 1070removePrinterFromDiscovery(printerId: string): Promise<void> 1071 1072Removes a printer from the printer discovery list. This API uses a promise to return the result. 1073 1074**Required permissions**: ohos.permission.PRINT 1075 1076**System capability**: SystemCapability.Print.PrintFramework 1077 1078**Parameters** 1079| **Name**| **Type**| **Mandatory**| **Description**| 1080| -------- | -------- | -------- | -------- | 1081| printerId | string | Yes| Printer to remove.| 1082 1083**Return value** 1084| **Type**| **Description**| 1085| -------- | -------- | 1086| Promise<void> | Result of removing a printer from the printer discovery list.| 1087 1088**Error codes** 1089 1090For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 1091 1092| ID| Error Message | 1093| -------- | ------------------------------------------- | 1094| 201 | the application does not have permission to call this function. | 1095| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1096 1097**Example** 1098 1099```ts 1100import { print } from '@kit.BasicServicesKit'; 1101import { BusinessError } from '@ohos.base'; 1102 1103let printerId : string = 'testPrinterId'; 1104print.removePrinterFromDiscovery(printerId).then((data : void) => { 1105 console.log('removePrinterFromDiscovery data : ' + JSON.stringify(data)); 1106}).catch((error: BusinessError) => { 1107 console.log('removePrinterFromDiscovery error : ' + JSON.stringify(error)); 1108}) 1109``` 1110 1111## getPrinterInformationById<sup>14+</sup> 1112 1113getPrinterInformationById(printerId: string): Promise<PrinterInformation> 1114 1115Obtains printer information based on the printer ID. This API uses a promise to return the result. 1116 1117**Required permissions**: ohos.permission.PRINT 1118 1119**System capability**: SystemCapability.Print.PrintFramework 1120 1121**Parameters** 1122| **Name**| **Type**| **Mandatory**| **Description**| 1123| -------- | -------- | -------- | -------- | 1124| printerId | string | Yes| Printer ID used to obtain information.| 1125 1126**Return value** 1127| **Type**| **Description**| 1128| -------- | -------- | 1129| Promise<PrinterInformation> | Printer information obtained based on the printer ID.| 1130 1131**Error codes** 1132 1133For details about the error codes, see [Error Codes of the Print Service](./errorcode-print.md). 1134 1135| ID| Error Message | 1136| -------- | ------------------------------------------- | 1137| 201 | the application does not have permission to call this function. | 1138| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1139 1140**Example** 1141 1142```ts 1143import { print } from '@kit.BasicServicesKit'; 1144import { BusinessError } from '@ohos.base'; 1145 1146let printerId : string = 'testPrinterId'; 1147print.getPrinterInformationById(printerId).then((printerInformation : print.PrinterInformation) => { 1148 console.log('getPrinterInformationById data : ' + JSON.stringify(printerInformation)); 1149}).catch((error: BusinessError) => { 1150 console.log('getPrinterInformationById error : ' + JSON.stringify(error)); 1151}) 1152``` 1153 1154## PrinterInformation<sup>14+</sup> 1155 1156Defines the printer information. 1157 1158**System capability**: SystemCapability.Print.PrintFramework 1159 1160**Attributes** 1161| **Name**| **Type**| **Mandatory**| **Description**| 1162| -------- | -------- | -------- | -------- | 1163| printerId | string | Yes| Printer ID.| 1164| printerName | string | Yes| Printer name.| 1165| printerStatus | PrinterStatus | Yes| Printer state.| 1166| description | string | No| Printer description.| 1167| capability | PrinterCapabilities | No| Printer capabilities.| 1168| uri | string | No| Printer URI.| 1169| printerMake | string | No| Printer model.| 1170| options | string | No| Printer details.| 1171 1172## PrinterCapabilities<sup>14+</sup> 1173 1174Defines the printer capabilities. 1175 1176**System capability**: SystemCapability.Print.PrintFramework 1177 1178**Attributes** 1179| **Name**| **Type**| **Mandatory**| **Description**| 1180| -------- | -------- | -------- | -------- | 1181| supportedPageSizes | Array<PrintPageSize> | Yes| List of paper sizes supported by the printer.| 1182| supportedColorModes | Array<PrintColorMode> | Yes| List of color modes supported by the printer.| 1183| supportedDuplexModes | Array<PrintDuplexMode> | Yes| List of single- and double-sided modes supported by the printer.| 1184| supportedMediaTypes | Array<string> | No| List of paper types supported by the printer.| 1185| supportedQualities | Array<PrintQuality> | No| List of print quality supported by the printer.| 1186| supportedOrientations | Array<PrintOrientationMode> | No| List of print directions supported by the printer.| 1187| options | string | No| Printer capability details.| 1188 1189## PrintQuality<sup>14+</sup> 1190 1191Enumerates the print qualities. 1192 1193**System capability**: SystemCapability.Print.PrintFramework 1194 1195| **Name**| **Value**| **Description**| 1196| -------- | -------- | -------- | 1197| QUALITY_DRAFT | 3 | Draft| 1198| QUALITY_NORMAL | 4 | Standard| 1199| QUALITY_HIGH | 5 | High| 1200 1201## PrintOrientationMode<sup>14+</sup> 1202 1203Enumerates the print directions. 1204 1205**System capability**: SystemCapability.Print.PrintFramework 1206 1207| **Name**| **Value**| **Description**| 1208| -------- | -------- | -------- | 1209| ORIENTATION_MODE_PORTRAIT | 0 | Portrait mode.| 1210| ORIENTATION_MODE_LANDSCAPE | 1 | Landscape mode.| 1211| ORIENTATION_MODE_REVERSE_LANDSCAPE | 2 | Reverse landscape mode.| 1212| ORIENTATION_MODE_REVERSE_PORTRAIT | 3 | Reverse portrait mode.| 1213| ORIENTATION_MODE_NONE | 4 | Adaptive mode.| 1214 1215## PrinterStatus<sup>14+</sup> 1216 1217Enumerates the printer states. 1218 1219**System capability**: SystemCapability.Print.PrintFramework 1220 1221| **Name**| **Value**| **Description**| 1222| -------- | -------- | -------- | 1223| PRINTER_IDLE | 0 | Idle| 1224| PRINTER_BUSY | 1 | Busy| 1225| PRINTER_UNAVAILABLE | 2 | Unavailable| 1226
