1# @ohos.file.picker (Picker) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @wang_zhangjun; @zhuangzhuang--> 5<!--Designer: @wang_zhangjun; @zhuangzhuang; @renguang1116--> 6<!--Tester: @liuhonggang123; @yue-ye2; @juxiaopang--> 7<!--Adviser: @foryourself--> 8 9> **NOTE** 10> 11> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12 13The **Picker** module encapsulates APIs such as **DocumentViewPicker**, **AudioViewPicker**, and **PhotoViewPicker** to provide capabilities of selecting and saving files of different types. An application can select the API as required. The APIs of this module must be called in UIAbility. Otherwise, the **FilePicker**, **AudioPicker**, or **PhotoPicker** cannot be started. 14Chinese characters and non-digit characters in the URI are compiled into the corresponding ASCII code and concatenated to the URI returned by calling these APIs. 15 16## Modules to Import 17 18```ts 19import { picker } from '@kit.CoreFileKit'; 20``` 21 22## DocumentViewPicker 23 24Provides APIs for selecting and saving documents in different formats. Before using the APIs of **DocumentViewPicker**, you need to create a **DocumentViewPicker** instance. 25 26**System capability**: SystemCapability.FileManagement.UserFileService 27 28### constructor<sup>12+</sup> 29 30constructor(context: Context) 31 32A constructor used to create a **DocumentViewPicker** instance. This constructor is recommended. For details about how to obtain the context, see [getHostContext](../apis-arkui/arkts-apis-uicontext-uicontext.md#gethostcontext12). 33 34**Atomic service API**: This API can be used in atomic services since API version 12. 35 36**System capability**: SystemCapability.FileManagement.UserFileService 37 38**Parameters** 39 40| Name | Type | Mandatory| Description | 41| ------- | ------- | ---- | ------------------------------------------------------------ | 42| context | Context| Yes | Application context (only **UIAbilityContext** is supported). For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 43 44**Example** 45 46```ts 47import { common } from '@kit.AbilityKit'; 48import { picker } from '@kit.CoreFileKit'; 49@Entry 50@Component 51struct Index { 52 @State message: string = 'hello World'; 53 54 build() { 55 Row() { 56 Column() { 57 Text(this.message) 58 .fontSize(50) 59 .fontWeight(FontWeight.Bold) 60 .onClick(()=>{ 61 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; // Ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 62 let documentPicker = new picker.DocumentViewPicker(context); 63 }) 64 } 65 .width('100%') 66 } 67 .height('100%') 68 } 69} 70``` 71 72### constructor<sup>12+</sup> 73 74constructor() 75 76A constructor used to create a **DocumentViewPicker** instance. This constructor is not recommended due to the potential risk of operation failure. 77 78**Atomic service API**: This API can be used in atomic services since API version 12. 79 80**System capability**: SystemCapability.FileManagement.UserFileService 81 82**Example** 83 84```ts 85let documentPicker = new picker.DocumentViewPicker(); // Construction without parameter is not recommended. There is a possibility that the DocumentViewPicker instance fails to start. 86``` 87 88### constructor<sup>13+</sup> 89 90constructor(context: Context, window: window.Window) 91 92A constructor used to create a **DocumentViewPicker** object in a window created by an application. In other scenarios, you are advised to use **constructor(context: Context)** to create a **DocumentViewPicker** object. 93 94> **NOTE** 95> 96> This method is supported on 2-in-1 devices and tablets since API version 19. 97 98**System capability**: SystemCapability.FileManagement.UserFileService 99 100**Parameters** 101 102| Name | Type | Mandatory| Description | 103| ------- | ------- | ---- | ------------------------------------------------------------ | 104| context | Context| Yes | Application context (only **UIAbilityContext** is supported). For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 105| window | [window.Window](../apis-arkui/arkts-apis-window-Window.md) | Yes | Window instance created by the application.| 106 107**Example** 108 109```ts 110import { common } from '@kit.AbilityKit'; 111import { picker } from '@kit.CoreFileKit'; 112import { window } from '@kit.ArkUI'; 113@Entry 114@Component 115struct Index { 116 @State message: string = 'hello World'; 117 118 build() { 119 Row() { 120 Column() { 121 Text(this.message) 122 .fontSize(50) 123 .fontWeight(FontWeight.Bold) 124 .onClick(()=>{ 125 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; // Ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 126 let windowClass: window.Window | undefined = undefined; 127 windowClass = window.findWindow('test'); // Ensure that the window has been created. Here, 'test' is the value of the name parameter when the window is created. 128 let documentPicker = new picker.DocumentViewPicker(context, windowClass); 129 }) 130 } 131 .width('100%') 132 } 133 .height('100%') 134 } 135} 136``` 137 138### select 139 140select(option?: DocumentSelectOptions): Promise<Array<string>> 141 142Starts a **documentPicker** page for the user to select one or more documents. This API uses a promise to return the result. You can pass in **DocumentSelectOptions** to specify the URIs of the documents to select. 143 144**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 145 146**Atomic service API**: This API can be used in atomic services since API version 12. 147 148**System capability**: SystemCapability.FileManagement.UserFileService 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| ------- | ------- | ---- | -------------------------- | 154| option | [DocumentSelectOptions](#documentselectoptions) | No | Options for selecting documents. If this parameter is not specified, the **documentPicker** page is displayed by default.| 155 156**Return value** 157 158| Type | Description | 159| ----------------------------- | :---- | 160| Promise<Array<string>> | Promise used to return the URIs of the documents selected.| 161 162**Example** 163 164```ts 165import { BusinessError } from '@kit.BasicServicesKit'; 166import { common } from '@kit.AbilityKit'; 167import { picker } from '@kit.CoreFileKit'; 168async function example07(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 169 try { 170 let documentSelectOptions = new picker.DocumentSelectOptions(); 171 let documentPicker = new picker.DocumentViewPicker(context); 172 documentPicker.select(documentSelectOptions).then((documentSelectResult: Array<string>) => { 173 console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult)); 174 }).catch((err: BusinessError) => { 175 console.error(`DocumentViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 176 }); 177 } catch (error) { 178 let err: BusinessError = error as BusinessError; 179 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 180 } 181} 182``` 183 184### select 185 186select(option: DocumentSelectOptions, callback: AsyncCallback<Array<string>>): void 187 188Starts a **documentPicker** page for the user to select one or more documents. This API uses an asynchronous callback to return the result. You can pass in **DocumentSelectOptions** to specify the URIs of the documents to select. 189 190**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 191 192**Atomic service API**: This API can be used in atomic services since API version 12. 193 194**System capability**: SystemCapability.FileManagement.UserFileService 195 196**Parameters** 197 198| Name | Type | Mandatory| Description | 199| ------- | ------- | ---- | -------------------------- | 200| option | [DocumentSelectOptions](#documentselectoptions) | Yes | Options for selecting documents.| 201| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents selected.| 202 203**Example** 204 205```ts 206import { BusinessError } from '@kit.BasicServicesKit'; 207import { common } from '@kit.AbilityKit'; 208import { picker } from '@kit.CoreFileKit'; 209async function example08(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 210 try { 211 let documentSelectOptions = new picker.DocumentSelectOptions(); 212 let documentPicker = new picker.DocumentViewPicker(context); 213 documentPicker.select(documentSelectOptions, (err: BusinessError, documentSelectResult: Array<string>) => { 214 if (err) { 215 console.error(`DocumentViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 216 return; 217 } 218 console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult)); 219 }); 220 } catch (error) { 221 let err: BusinessError = error as BusinessError; 222 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 223 } 224} 225``` 226 227### select 228 229select(callback: AsyncCallback<Array<string>>): void 230 231Starts a **documentPicker** page for the user to select one or more documents. This API uses an asynchronous callback to return the URIs of the documents selected. 232 233**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 234 235**Atomic service API**: This API can be used in atomic services since API version 12. 236 237**System capability**: SystemCapability.FileManagement.UserFileService 238 239**Parameters** 240 241| Name | Type | Mandatory| Description | 242| ------- | ------- | ---- | -------------------------- | 243| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents selected.| 244 245**Example** 246 247```ts 248import { BusinessError } from '@kit.BasicServicesKit'; 249import { common } from '@kit.AbilityKit'; 250import { picker } from '@kit.CoreFileKit'; 251async function example09(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 252 try { 253 let documentPicker = new picker.DocumentViewPicker(context); 254 documentPicker.select((err: BusinessError, documentSelectResult: Array<string>) => { 255 if (err) { 256 console.error(`DocumentViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 257 return; 258 } 259 console.info('DocumentViewPicker.select successfully, documentSelectResult uri: ' + JSON.stringify(documentSelectResult)); 260 }); 261 } catch (error) { 262 let err: BusinessError = error as BusinessError; 263 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 264 } 265} 266``` 267 268### save 269 270save(option?: DocumentSaveOptions): Promise<Array<string>> 271 272Starts a **documentPicker** page for the user to save one or more documents. This API uses a promise to return the result. You can pass in **DocumentSaveOptions** to specify the URIs of the documents to save. 273 274**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 275 276**Atomic service API**: This API can be used in atomic services since API version 12. 277 278**System capability**: SystemCapability.FileManagement.UserFileService 279 280**Parameters** 281 282| Name | Type | Mandatory| Description | 283| ------- | ------- | ---- | -------------------------- | 284| option | [DocumentSaveOptions](#documentsaveoptions) | No | Options for saving the documents. If this parameter is not specified, a **documentPicker** page will be displayed for the user to enter the names of the documents to save.| 285 286**Return value** 287 288| Type | Description | 289| ----------------------------- | :---- | 290| Promise<Array<string>> | Promise used to return the URIs of the documents saved.| 291 292**Example** 293 294```ts 295import { BusinessError } from '@kit.BasicServicesKit'; 296import { common } from '@kit.AbilityKit'; 297import { picker } from '@kit.CoreFileKit'; 298async function example10(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 299 try { 300 let documentSaveOptions = new picker.DocumentSaveOptions(); 301 documentSaveOptions.newFileNames = ['DocumentViewPicker01.txt']; 302 let documentPicker = new picker.DocumentViewPicker(context); 303 documentPicker.save(documentSaveOptions).then((documentSaveResult: Array<string>) => { 304 console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult)); 305 }).catch((err: BusinessError) => { 306 console.error(`DocumentViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 307 }); 308 } catch (error) { 309 let err: BusinessError = error as BusinessError; 310 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 311 } 312} 313``` 314 315### save 316 317save(option: DocumentSaveOptions, callback: AsyncCallback<Array<string>>): void 318 319Starts a **documentPicker** page for the user to save one or more documents. This API uses an asynchronous callback to return the result. You can pass in **DocumentSaveOptions** to specify the URIs of the documents to save. 320 321**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 322 323**Atomic service API**: This API can be used in atomic services since API version 12. 324 325**System capability**: SystemCapability.FileManagement.UserFileService 326 327**Parameters** 328 329| Name | Type | Mandatory| Description | 330| ------- | ------- | ---- | -------------------------- | 331| option | [DocumentSaveOptions](#documentsaveoptions) | Yes | Options for saving the documents.| 332| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents saved.| 333 334**Example** 335 336```ts 337import { BusinessError } from '@kit.BasicServicesKit'; 338import { common } from '@kit.AbilityKit'; 339import { picker } from '@kit.CoreFileKit'; 340async function example11(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 341 try { 342 let documentSaveOptions = new picker.DocumentSaveOptions(); 343 documentSaveOptions.newFileNames = ['DocumentViewPicker02.txt']; 344 let documentPicker = new picker.DocumentViewPicker(context); 345 documentPicker.save(documentSaveOptions, (err: BusinessError, documentSaveResult: Array<string>) => { 346 if (err) { 347 console.error(`DocumentViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 348 return; 349 } 350 console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult)); 351 }); 352 } catch (error) { 353 let err: BusinessError = error as BusinessError; 354 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 355 } 356} 357``` 358 359### save 360 361save(callback: AsyncCallback<Array<string>>): void 362 363Starts a **documentPicker** page for the user to save one or more documents. This API uses an asynchronous callback to return the URIs of the documents to save. 364 365**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 366 367**Atomic service API**: This API can be used in atomic services since API version 12. 368 369**System capability**: SystemCapability.FileManagement.UserFileService 370 371**Parameters** 372 373| Name | Type | Mandatory| Description | 374| ------- | ------- | ---- | -------------------------- | 375| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the documents saved.| 376 377**Example** 378 379```ts 380import { BusinessError } from '@kit.BasicServicesKit'; 381import { common } from '@kit.AbilityKit'; 382import { picker } from '@kit.CoreFileKit'; 383async function example12(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 384 try { 385 let documentPicker = new picker.DocumentViewPicker(context); 386 documentPicker.save((err: BusinessError, documentSaveResult: Array<string>) => { 387 if (err) { 388 console.error(`DocumentViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 389 return; 390 } 391 console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult)); 392 }); 393 } catch (error) { 394 let err: BusinessError = error as BusinessError; 395 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 396 } 397} 398``` 399 400### getSelectedIndex<sup>14+</sup> 401 402getSelectedIndex(): number 403 404Obtains the index of the file suffix type of the file saved. 405 406Only 2-in-1 devices are supported. 407 408This method takes effect only when used with [save()](#save). 409 410This method can be used only after [DocumentSaveOptions.fileSuffixChoices](#documentsaveoptions) is configured. 411 412The index (number) returned by this method indicates the location of the file suffix specified in [DocumentSaveOptions.fileSuffixChoices](#documentsaveoptions). If no file suffix is specified, **getSelectedIndex()** returns **-1**. 413 414**Atomic service API**: This API can be used in atomic services since API version 14. 415 416**System capability**: SystemCapability.FileManagement.UserFileService.FolderSelection 417 418**Return value** 419 420| Type | Description | 421| ----------------------------- | :---- | 422| number| Subscript (number) of the selected suffix type in [DocumentSaveOptions.fileSuffixChoices](#documentsaveoptions). The default value is **-1**.| 423 424```ts 425import { BusinessError } from '@kit.BasicServicesKit'; 426import { common } from '@kit.AbilityKit'; 427import { picker } from '@kit.CoreFileKit'; 428async function exampleIndex(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 429 try { 430 let documentSaveOptions = new picker.DocumentSaveOptions(); 431 // Name of the file to save. 432 documentSaveOptions.newFileNames = ['DocumentViewPicker01']; 433 // File suffix of the file to save. 434 documentSaveOptions.fileSuffixChoices = ['txt', 'mp4', 'pdf']; 435 let documentPicker = new picker.DocumentViewPicker(context); 436 documentPicker.save(documentSaveOptions).then((documentSaveResult: Array<string>) => { 437 if (documentSaveOptions.fileSuffixChoices != undefined && documentSaveResult != undefined) { 438 // Obtain the index of the file suffix type of the file saved. 439 let index = documentPicker.getSelectedIndex(); 440 // Obtain the file suffix type of the file saved. 441 let selectedsuffix = documentSaveOptions.fileSuffixChoices[index]; 442 console.info ('DocumentViewPicker.save selectedsuffix is ' + selectedsuffix); 443 } 444 console.info('DocumentViewPicker.save successfully, documentSaveResult uri: ' + JSON.stringify(documentSaveResult)); 445 }).catch((err: BusinessError) => { 446 console.error(`DocumentViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 447 }); 448 } catch (error) { 449 let err: BusinessError = error as BusinessError; 450 console.error(`DocumentViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 451 } 452} 453``` 454 455## AudioViewPicker 456 457Provides APIs for selecting and saving audio clips. Before using the APIs of **AudioViewPicker**, you need to create an **AudioViewPicker** instance. 458 459**System capability**: SystemCapability.FileManagement.UserFileService 460 461### constructor<sup>12+</sup> 462 463constructor(context: Context) 464 465A constructor used to create an **AudioViewPicker** instance. This constructor is recommended. For details about how to obtain the context, see [getHostContext](../apis-arkui/arkts-apis-uicontext-uicontext.md#gethostcontext12). 466 467**Atomic service API**: This API can be used in atomic services since API version 12. 468 469**System capability**: SystemCapability.FileManagement.UserFileService 470 471**Parameters** 472 473| Name | Type | Mandatory| Description | 474| ------- | ------- | ---- | ------------------------------------------------------------ | 475| context | Context| Yes | Application context (only **UIAbilityContext** is supported). For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 476 477**Example** 478 479```ts 480import { common } from '@kit.AbilityKit'; 481import { picker } from '@kit.CoreFileKit'; 482@Entry 483@Component 484struct Index { 485 @State message: string = 'hello World'; 486 487 build() { 488 Row() { 489 Column() { 490 Text(this.message) 491 .fontSize(50) 492 .fontWeight(FontWeight.Bold) 493 .onClick(()=>{ 494 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; // Ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 495 let audioPicker = new picker.AudioViewPicker(context); 496 }) 497 } 498 .width('100%') 499 } 500 .height('100%') 501 } 502} 503``` 504 505### constructor<sup>12+</sup> 506 507constructor() 508 509A constructor used to create an **AudioViewPicker** instance. This constructor is not recommended due to the potential risk of operation failure. 510 511**Atomic service API**: This API can be used in atomic services since API version 12. 512 513**System capability**: SystemCapability.FileManagement.UserFileService 514 515**Example** 516 517```ts 518let audioPicker = new picker.AudioViewPicker(); // Construction without parameter is not recommended. There is a possibility that the AudioViewPicker instance fails to start. 519``` 520 521### select 522 523select(option?: AudioSelectOptions): Promise<Array<string>> 524 525Starts an **audioPicker** page for the user to select one or more audio clips. This API uses a promise to return the result. You can pass in **AudioSelectOptions** to specify the URIs of the audio clips to select. 526 527**NOTE**<br>For details about how to use the returned URIs, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 528 529**Atomic service API**: This API can be used in atomic services since API version 12. 530 531**System capability**: SystemCapability.FileManagement.UserFileService 532 533**Parameters** 534 535| Name | Type | Mandatory| Description | 536| ------- | ------- | ---- | -------------------------- | 537| option | [AudioSelectOptions](#audioselectoptions) | No | Options for selecting audio clips. If this parameter is not specified, the **audioPicker** page is displayed by default. | 538 539**Return value** 540 541| Type | Description | 542| ----------------------------- | :---- | 543| Promise<Array<string>> | Promise used to return the URIs of the audio clips selected.| 544 545**Example** 546 547```ts 548import { BusinessError } from '@kit.BasicServicesKit'; 549import { common } from '@kit.AbilityKit'; 550import { picker } from '@kit.CoreFileKit'; 551async function example13(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 552 try { 553 let audioSelectOptions = new picker.AudioSelectOptions(); 554 let audioPicker = new picker.AudioViewPicker(context); 555 audioPicker.select(audioSelectOptions).then((audioSelectResult: Array<string>) => { 556 console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult)); 557 }).catch((err: BusinessError) => { 558 console.error(`AudioViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 559 }); 560 } catch (error) { 561 let err: BusinessError = error as BusinessError; 562 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 563 } 564} 565``` 566 567### select 568 569select(option: AudioSelectOptions, callback: AsyncCallback<Array<string>>): void 570 571Starts an **audioPicker** page for the user to select one or more audio clips. This API uses an asynchronous callback to return the result. You can pass in **AudioSelectOptions** to specify the URIs of the audio clips to select. 572 573**NOTE**<br>For details about how to use the returned URIs, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 574 575**System capability**: SystemCapability.FileManagement.UserFileService 576 577**Parameters** 578 579| Name | Type | Mandatory| Description | 580| ------- | ------- | ---- | -------------------------- | 581| option | [AudioSelectOptions](#audioselectoptions) | Yes | Options for selecting audio clips.| 582| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio clips selected.| 583 584**Example** 585 586```ts 587import { BusinessError } from '@kit.BasicServicesKit'; 588import { common } from '@kit.AbilityKit'; 589import { picker } from '@kit.CoreFileKit'; 590async function example14(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 591 try { 592 let audioSelectOptions = new picker.AudioSelectOptions(); 593 let audioPicker = new picker.AudioViewPicker(context); 594 audioPicker.select(audioSelectOptions, (err: BusinessError, audioSelectResult: Array<string>) => { 595 if (err) { 596 console.error(`AudioViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 597 return; 598 } 599 console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult)); 600 }); 601 } catch (error) { 602 let err: BusinessError = error as BusinessError; 603 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 604 } 605} 606``` 607 608### select 609 610select(callback: AsyncCallback<Array<string>>): void 611 612Starts an **audioPicker** page for the user to select one or more audio clips. This API uses an asynchronous callback to return the URIs of the audio clips selected. 613 614**NOTE**<br>For details about how to use the returned URIs, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 615 616**System capability**: SystemCapability.FileManagement.UserFileService 617 618**Parameters** 619 620| Name | Type | Mandatory| Description | 621| ------- | ------- | ---- | -------------------------- | 622| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio clips selected.| 623 624**Example** 625 626```ts 627import { BusinessError } from '@kit.BasicServicesKit'; 628import { common } from '@kit.AbilityKit'; 629import { picker } from '@kit.CoreFileKit'; 630async function example15(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 631 try { 632 let audioPicker = new picker.AudioViewPicker(context); 633 audioPicker.select((err: BusinessError, audioSelectResult: Array<string>) => { 634 if (err) { 635 console.error(`AudioViewPicker.select failed with err, code is: ${err.code}, message is: ${err.message}`); 636 return; 637 } 638 console.info('AudioViewPicker.select successfully, audioSelectResult uri: ' + JSON.stringify(audioSelectResult)); 639 }); 640 } catch (error) { 641 let err: BusinessError = error as BusinessError; 642 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 643 } 644} 645``` 646 647### save 648 649save(option?: AudioSaveOptions): Promise<Array<string>> 650 651Starts an **audioPicker** page (currently, a **documentPicker** page is displayed) for the user to save one or more audio clips. This API uses a promise to return the result. You can pass in **AudioSaveOptions** to specify the URIs of the audio clips to save. 652 653**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 654 655**Atomic service API**: This API can be used in atomic services since API version 12. 656 657**System capability**: SystemCapability.FileManagement.UserFileService 658 659**Parameters** 660 661| Name | Type | Mandatory| Description | 662| ------- | ------- | ---- | -------------------------- | 663| option | [AudioSaveOptions](#audiosaveoptions) | No | Options for saving audio clips. If this parameter is not specified, an **audioPicker** page will be displayed for the user to enter the names of the files to save.| 664 665**Return value** 666 667| Type | Description | 668| ----------------------------- | ---- | 669| Promise<Array<string>> | Promise used to return the URIs of the audio clips saved.| 670 671**Example** 672 673```ts 674import { BusinessError } from '@kit.BasicServicesKit'; 675import { common } from '@kit.AbilityKit'; 676import { picker } from '@kit.CoreFileKit'; 677async function example16(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 678 try { 679 let audioSaveOptions = new picker.AudioSaveOptions(); 680 audioSaveOptions.newFileNames = ['AudioViewPicker01.mp3']; 681 let audioPicker = new picker.AudioViewPicker(context); 682 audioPicker.save(audioSaveOptions).then((audioSaveResult: Array<string>) => { 683 console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult)) 684 }).catch((err: BusinessError) => { 685 console.error(`AudioViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 686 }); 687 } catch (error) { 688 let err: BusinessError = error as BusinessError; 689 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 690 } 691} 692``` 693 694### save 695 696save(option: AudioSaveOptions, callback: AsyncCallback<Array<string>>): void 697 698Starts an **audioPicker** page (currently, a **documentPicker** page is displayed) for the user to save one or more audio clips. This API uses an asynchronous callback to return the result. You can pass in **AudioSaveOptions** to specify the URIs of the audio clips to save. 699 700**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 701 702**System capability**: SystemCapability.FileManagement.UserFileService 703 704**Parameters** 705 706| Name | Type | Mandatory| Description | 707| ------- | ------- | ---- | -------------------------- | 708| option | [AudioSaveOptions](#audiosaveoptions) | Yes | Options for saving audio clips.| 709| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio clips saved.| 710 711**Example** 712 713```ts 714import { BusinessError } from '@kit.BasicServicesKit'; 715import { common } from '@kit.AbilityKit'; 716import { picker } from '@kit.CoreFileKit'; 717async function example17(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 718 try { 719 let audioSaveOptions = new picker.AudioSaveOptions(); 720 audioSaveOptions.newFileNames = ['AudioViewPicker02.mp3']; 721 let audioPicker = new picker.AudioViewPicker(context); 722 audioPicker.save(audioSaveOptions, (err: BusinessError, audioSaveResult: Array<string>) => { 723 if (err) { 724 console.error(`AudioViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 725 return; 726 } 727 console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult)); 728 }); 729 } catch (error) { 730 let err: BusinessError = error as BusinessError; 731 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 732 } 733} 734``` 735 736### save 737 738save(callback: AsyncCallback<Array<string>>): void 739 740Starts an **audioPicker** page (currently, a **documentPicker** page is displayed) for the user to save one or more audio clips. This API uses an asynchronous callback to return the URIs of the audio clips saved. 741 742**NOTE**<br>For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 743 744**System capability**: SystemCapability.FileManagement.UserFileService 745 746**Parameters** 747 748| Name | Type | Mandatory| Description | 749| ------- | ------- | ---- | -------------------------- | 750| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the audio clips saved.| 751 752**Example** 753 754```ts 755import { BusinessError } from '@kit.BasicServicesKit'; 756import { common } from '@kit.AbilityKit'; 757import { picker } from '@kit.CoreFileKit'; 758async function example18(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 759 try { 760 let audioPicker = new picker.AudioViewPicker(context); 761 audioPicker.save((err: BusinessError, audioSaveResult: Array<string>) => { 762 if (err) { 763 console.error(`AudioViewPicker.save failed with err, code is: ${err.code}, message is: ${err.message}`); 764 return; 765 } 766 console.info('AudioViewPicker.save successfully, audioSaveResult uri: ' + JSON.stringify(audioSaveResult)); 767 }); 768 } catch (error) { 769 let err: BusinessError = error as BusinessError; 770 console.error(`AudioViewPicker failed with err, code is: ${err.code}, message is: ${err.message}`); 771 } 772} 773``` 774 775## DocumentSelectMode<sup>11+</sup> 776 777Enumerates the types of documents selected. 778 779Only 2-in-1 devices are supported. 780 781**Atomic service API**: This API can be used in atomic services since API version 12. 782 783**System capability**: SystemCapability.FileManagement.UserFileService.FolderSelection 784 785| Name | Value| Description| 786| ----- | ---- | ---- | 787| FILE | 0 | File (default).| 788| FOLDER | 1 | Folder. | 789| MIXED | 2 | Mixed type of files and folders. | 790 791## DocumentSelectOptions 792 793Defines the options for selecting documents. 794 795**Atomic service API**: This API can be used in atomic services since API version 12. 796 797**System capability**: SystemCapability.FileManagement.UserFileService 798 799| Name | Type | Read-Only| Optional| Description | 800| :---------------------- |---------------------------------------------| ---- | ---- | ------------------------------------------| 801| maxSelectNumber<sup>10+</sup> | number | No | Yes| Maximum number of documents that can be selected.<br>Value range: 1 to 500.<br>Only the devices with the required system capability can select directories, and only one directory can be selected at a time. The default value is **500**.<br>**System capability**: SystemCapability.FileManagement.UserFileService | 802| defaultFilePathUri<sup>10+</sup> | string | No | Yes| URI of the file or directory that can be selected. It is empty by default (the recently opened page is displayed). | 803| fileSuffixFilters<sup>10+</sup> | Array<string> | No | Yes| Suffix of the document to select. <br>The value is a string array. Each element specifies an option, which includes at most two parts with a vertical bar (\|) in between. The first part is the description, and the second part is the document suffix. If there is no "\|", the option does not have the description. Each filter suffix can contain multiple suffixes, separated by a comma (,). The length of the input array cannot exceed 100 characters, for example, ['Images (.png, .jpg)\|.png,.jpg', 'Documents\|.txt', 'Videos\|.mp4', '.pdf'].<br>By default, no filtering is performed, that is, all documents are selected. The wildcard ['All files (\*.\*)\|.*'] can be used on 2-in-1 devices to display all files. (Mobile phones can support this configuration since API version 17.)<br>This parameter is available only to the devices that have the required system capability.<br>**System capability**: SystemCapability.FileManagement.UserFileService | 804| selectMode<sup>11+</sup> | [DocumentSelectMode](#documentselectmode11) | No | Yes| Only 2-in-1 devices are supported. The default value is **FILE**.<br>**System capability**: SystemCapability.FileManagement.UserFileService.FolderSelection | 805| authMode<sup>12+</sup> | boolean | No | Yes| Whether to start Picker.<br>Default value: **false**. If **authMode** is **true**, **defaultFilePathUri** is mandatory, which specifies the URI of the file allowed to access. Only 2-in-1 devices are supported.<br>**System capability**: SystemCapability.FileManagement.UserFileService.FolderSelection | 806|multiAuthMode<sup>15+</sup> | boolean |No | Yes| Whether to enable the batch authorization mode.<br>The value **false** (default) means to disable the batch authorization mode; the value **true** means to enable the batch authorization mode. The **multiUriArray** parameter only takes effect when **multAuthMode** is set to **true**.<br> **Device behavior differences**: This API can be called on mobile phones but has no effect on other devices.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 807|multiUriArray<sup>15+</sup> | Array<string> |No | Yes| Whether to pass the URIs for batch authorization (only files are supported). <br>This parameter is used with **multAuthMode**, and does not take effect when **multAuthMode** is set to **false**. By default, this parameter is left empty. (The files displayed on the batch authorization page are empty.)<br> **Device behavior differences**: This API can be called on mobile phones but has no effect on other devices.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 808|mergeMode<sup>15+</sup> | [MergeTypeMode](#mergetypemode15) |No | Yes| Whether to enable the aggregation view mode for a file management application. The default value is **DEFAULT**, indicating that this parameter does not take effect and the aggregation view is disabled. If this parameter is set to a value other than **DEFAULT**, other parameters do not take effect.<br> **Device behavior differences**: This API can be called on mobile phones but has no effect on other devices.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 809|isEncryptionSupported<sup>19+</sup> | boolean |No | Yes| Whether to support encryption (only files are supported). The default value is **false**. If this parameter is set to **true**, files can be encrypted on the Picker page.<br>**Atomic service API**: This API can be used in atomic services since API version 19.<br> **System capability**: SystemCapability.FileManagement.UserFileService| 810 811## DocumentPickerMode<sup>12+</sup> 812 813Enumerates the modes for saving documents. 814 815**Atomic service API**: This API can be used in atomic services since API version 12. 816 817**System capability**: SystemCapability.FileManagement.UserFileService 818 819| Name | Value| Description| 820| ----- | ---- | ---- | 821| DEFAULT | 0 | Standard mode.| 822| DOWNLOAD | 1 | Download mode.| 823 824## MergeTypeMode<sup>15+</sup> 825 826Enumerates file aggregation types. 827 828**Atomic service API**: This API can be used in atomic services since API version 15. 829 830**System capability**: SystemCapability.FileManagement.UserFileService 831 832**Device behavior differences**: This API can be called on mobile phones but has no effect on other devices. 833 834| Name | Value| Description| 835| ----- | ---- | ---- | 836| DEFAULT | 0 | Default mode, indicating that this parameter does not take effect.| 837| AUDIO | 1 | Audio mode.| 838| VIDEO | 2 | Video mode.| 839| DOCUMENT | 3 | Document mode.| 840| PICTURE | 4 | Image mode.| 841 842## DocumentSaveOptions 843 844Defines the options for saving documents. 845 846**Atomic service API**: This API can be used in atomic services since API version 12. 847 848**System capability**: SystemCapability.FileManagement.UserFileService 849 850| Name | Type | Mandatory| Description | 851| ----------------------- | ------------------- | ---- | ---------------------------- | 852| newFileNames | Array<string> | No | Name of the document to save. If this parameter is not specified, the user needs to enter the document name. | 853| defaultFilePathUri<sup>10+</sup> | string | No | URI of the file or directory to save. | 854| fileSuffixChoices<sup>10+</sup> | Array<string> | No | Document suffix of the document to save.<br>The value is a string array. Each element specifies an option, which includes at most two parts with a vertical bar (\|) in between. The first part is the description, and the second part is the document suffix. If there is no "\|", the option does not have the description. By default, all documents are saved.| 855| pickerMode<sup>12+</sup> | [DocumentPickerMode](#documentpickermode12) | No | Mode for starting Picker.<br>Default value: **DEFAULT**. If **pickerMode** is **DOWNLOAD**, the settings of **newFileNames**, **defaultFilePathUri**, and **fileSuffixChoices** do not take effect.| 856 857## AudioSelectOptions 858 859Defines the options for selecting audio clips. 860 861**Atomic service API**: This API can be used in atomic services since API version 12. 862 863**System capability**: SystemCapability.FileManagement.UserFileService 864 865| Name | Type | Mandatory| Description | 866| :---------------------- |---------------------------------------------| ---- |------------------------------------------| 867| maxSelectNumber<sup>12+</sup> | number | No | Maximum number of audio clips that can be selected.<br>Default value: **1**<br>Value range: 1 to 500| 868 869## AudioSaveOptions 870 871Defines the options for saving audio clips. 872 873**Atomic service API**: This API can be used in atomic services since API version 12. 874 875**System capability**: SystemCapability.FileManagement.UserFileService 876 877| Name | Type | Mandatory| Description | 878| ----------------------- | ------------------- | ---- | ---------------------------- | 879| newFileNames | Array<string> | No | File name of the audio clip to save. If this parameter is not specified, the user needs to enter the file name.| 880 881## PhotoViewPicker<sup>(deprecated)</sup> 882 883Provides APIs for selecting and saving images or videos. You are advised to use [PhotoViewPicker of PhotoAccessHelper](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md) to select a file. Before using the APIs of **PhotoViewPicker**, you need to create a **PhotoViewPicker** instance. 884 885> **NOTE** 886> 887> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoViewPicker](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md) instead. 888 889**System capability**: SystemCapability.FileManagement.UserFileService 890 891### constructor<sup>(deprecated)</sup> 892 893constructor(context: Context) 894 895**System capability**: SystemCapability.FileManagement.UserFileService 896 897**Parameters** 898 899| Name | Type | Mandatory| Description | 900| ------- | ------- | ---- | ------------------------------------------------------------ | 901| context | Context| Yes | Application context (only **UIAbilityContext** is supported). For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 902 903A constructor used to create a **PhotoViewPicker** instance. This constructor is recommended. For details about how to obtain the context, see [getHostContext](../apis-arkui/arkts-apis-uicontext-uicontext.md#gethostcontext12). 904 905> **NOTE** 906> 907> This API is deprecated since API version 12. 908 909**Example** 910 911```ts 912import { common } from '@kit.AbilityKit'; 913import { picker } from '@kit.CoreFileKit'; 914@Entry 915@Component 916struct Index { 917 @State message: string = 'hello World'; 918 919 build() { 920 Row() { 921 Column() { 922 Text(this.message) 923 .fontSize(50) 924 .fontWeight(FontWeight.Bold) 925 .onClick(()=>{ 926 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; // Ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 927 let photoPicker = new picker.PhotoViewPicker(context); 928 }) 929 } 930 .width('100%') 931 } 932 .height('100%') 933 } 934} 935``` 936 937### constructor<sup>(deprecated)</sup> 938 939constructor() 940 941**Atomic service API**: This API can be used in atomic services since API version 12. 942 943**System capability**: SystemCapability.FileManagement.UserFileService 944 945A constructor used to create a **PhotoViewPicker** instance. This constructor is not recommended due to the potential risk of operation failure. 946 947> **NOTE** 948> 949> This API is deprecated since API version 12. 950 951**Example** 952 953```ts 954let photoPicker = new picker.PhotoViewPicker(); // Construction without parameter is not recommended. There is a possibility that the PhotoViewPicker instance fails to start. 955``` 956 957### select<sup>(deprecated)</sup> 958 959select(option?: PhotoSelectOptions): Promise<PhotoSelectResult> 960 961Starts a **photoPicker** page for the user to select one or more images or videos. This API uses a promise to return the result. You can pass in **PhotoSelectOptions** to specify the type and maximum number of the files to select. 962 963> **NOTE** 964> 965> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoViewPicker#select](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md#select) instead. 966 967**NOTE**<br>The **photoUris** in the **PhotoSelectResult** object returned by this API can be used only by [photoAccessHelper.getAssets](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 968 969**Atomic service API**: This API can be used in atomic services since API version 11. 970 971**System capability**: SystemCapability.FileManagement.UserFileService 972 973**Parameters** 974 975| Name | Type | Mandatory| Description | 976| ------- | ------- | ---- | -------------------------- | 977| option | [PhotoSelectOptions](#photoselectoptionsdeprecated) | No | Options for selecting images or videos. If this parameter is not specified, images and videos are selected by default. A maximum of 50 files can be selected.| 978 979**Return value** 980 981| Type | Description | 982| ----------------------------- | :---- | 983| Promise<[PhotoSelectResult](#photoselectresultdeprecated)> | Promise used to return the URIs of the images or videos selected.| 984 985**Example** 986 987```ts 988import { BusinessError } from '@kit.BasicServicesKit'; 989import { common } from '@kit.AbilityKit'; 990import { picker } from '@kit.CoreFileKit'; 991async function example01(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 992 try { 993 let photoSelectOptions = new picker.PhotoSelectOptions(); 994 photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; 995 photoSelectOptions.maxSelectNumber = 5; 996 let photoPicker = new picker.PhotoViewPicker(context); 997 photoPicker.select(photoSelectOptions).then((photoSelectResult: picker.PhotoSelectResult) => { 998 console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult)); 999 }).catch((err: BusinessError) => { 1000 console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err)); 1001 }); 1002 } catch (error) { 1003 let err: BusinessError = error as BusinessError; 1004 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1005 } 1006} 1007``` 1008 1009### select<sup>(deprecated)</sup> 1010 1011select(option: PhotoSelectOptions, callback: AsyncCallback<PhotoSelectResult>): void 1012 1013Starts a **photoPicker** page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result. You can pass in **PhotoSelectOptions** to specify the type and maximum number of the files to select. 1014 1015> **NOTE** 1016> 1017> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoViewPicker#select](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md#select-1) instead. 1018 1019**NOTE**<br>The **photoUris** in the **PhotoSelectResult** object returned by this API can be used only by [photoAccessHelper.getAssets](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 1020 1021**Atomic service API**: This API can be used in atomic services since API version 11. 1022 1023**System capability**: SystemCapability.FileManagement.UserFileService 1024 1025**Parameters** 1026 1027| Name | Type | Mandatory| Description | 1028| ------- | ------- | ---- | -------------------------- | 1029| option | [PhotoSelectOptions](#photoselectoptionsdeprecated) | Yes | Options for selecting images or videos.| 1030| callback | AsyncCallback<[PhotoSelectResult](#photoselectresultdeprecated)> | Yes | Callback used to return the images or videos selected.| 1031 1032**Example** 1033 1034```ts 1035import { BusinessError } from '@kit.BasicServicesKit'; 1036import { common } from '@kit.AbilityKit'; 1037import { picker } from '@kit.CoreFileKit'; 1038async function example02(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 1039 try { 1040 let photoSelectOptions = new picker.PhotoSelectOptions(); 1041 photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE; 1042 photoSelectOptions.maxSelectNumber = 5; 1043 let photoPicker = new picker.PhotoViewPicker(context); 1044 photoPicker.select(photoSelectOptions, (err: BusinessError, photoSelectResult: picker.PhotoSelectResult) => { 1045 if (err) { 1046 console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err)); 1047 return; 1048 } 1049 console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult)); 1050 }); 1051 } catch (error) { 1052 let err: BusinessError = error as BusinessError; 1053 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1054 } 1055} 1056``` 1057 1058### select<sup>(deprecated)</sup> 1059 1060select(callback: AsyncCallback<PhotoSelectResult>): void 1061 1062Starts a **photoPicker** page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result. 1063 1064> **NOTE** 1065> 1066> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoViewPicker#select](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md#select-2) instead. 1067 1068**NOTE**<br>The **photoUris** in the **PhotoSelectResult** object returned by this API can be used only by [photoAccessHelper.getAssets](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). 1069 1070**Atomic service API**: This API can be used in atomic services since API version 11. 1071 1072**System capability**: SystemCapability.FileManagement.UserFileService 1073 1074**Parameters** 1075 1076| Name | Type | Mandatory| Description | 1077| ------- | ------- | ---- | -------------------------- | 1078| callback | AsyncCallback<[PhotoSelectResult](#photoselectresultdeprecated)> | Yes | Callback used to return the images or videos selected.| 1079 1080**Example** 1081 1082```ts 1083import { BusinessError } from '@kit.BasicServicesKit'; 1084import { common } from '@kit.AbilityKit'; 1085import { picker } from '@kit.CoreFileKit'; 1086async function example03(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 1087 try { 1088 let photoPicker = new picker.PhotoViewPicker(context); 1089 photoPicker.select((err: BusinessError, photoSelectResult: picker.PhotoSelectResult) => { 1090 if (err) { 1091 console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err)); 1092 return; 1093 } 1094 console.info('PhotoViewPicker.select successfully, photoSelectResult uri: ' + JSON.stringify(photoSelectResult)); 1095 }); 1096 } catch (error) { 1097 let err: BusinessError = error as BusinessError; 1098 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1099 } 1100} 1101``` 1102 1103### save<sup>(deprecated)</sup> 1104 1105save(option?: PhotoSaveOptions): Promise<Array<string>> 1106 1107Starts a **photoPicker** page for the user to save one or more images or videos. This API uses a promise to return the result. You can pass in **PhotoSaveOptions** to specify the URIs of the images or videos to save. 1108 1109> **NOTE** 1110> 1111> This API is supported since API version 9 and deprecated since API version 12. Use [SaveButton](../apis-arkui/arkui-ts/ts-security-components-savebutton.md) instead. 1112 1113**NOTE**<br>This API saves files in **Files**, not in **Gallery**. For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 1114 1115**System capability**: SystemCapability.FileManagement.UserFileService 1116 1117**Parameters** 1118 1119| Name | Type | Mandatory| Description | 1120| ------- | ------- | ---- | -------------------------- | 1121| option | [PhotoSaveOptions](#photosaveoptionsdeprecated) | No | Options for saving images or videos. If this parameter is not specified, a **photoPicker** page will be displayed for the user to enter the names of the files to save.| 1122 1123**Return value** 1124 1125| Type | Description | 1126| ----------------------------- | :---- | 1127| Promise<Array<string>> | Promise used to return the URIs of the images or videos saved.| 1128 1129**Example** 1130 1131```ts 1132import { BusinessError } from '@kit.BasicServicesKit'; 1133import { common } from '@kit.AbilityKit'; 1134import { picker } from '@kit.CoreFileKit'; 1135async function example04(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 1136 try { 1137 let photoSaveOptions = new picker.PhotoSaveOptions(); 1138 photoSaveOptions.newFileNames = ['PhotoViewPicker01.jpg', 'PhotoViewPicker01.mp4']; 1139 let photoPicker = new picker.PhotoViewPicker(context); 1140 photoPicker.save(photoSaveOptions).then((photoSaveResult: Array<string>) => { 1141 console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult)); 1142 }).catch((err: BusinessError) => { 1143 console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err)); 1144 }); 1145 } catch (error) { 1146 let err: BusinessError = error as BusinessError; 1147 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1148 } 1149} 1150``` 1151 1152### save<sup>(deprecated)</sup> 1153 1154save(option: PhotoSaveOptions, callback: AsyncCallback<Array<string>>): void 1155 1156Starts a **photoPicker** page for the user to save one or more images or videos. This API uses an asynchronous callback to return the result. You can pass in **PhotoSaveOptions** to specify the URIs of the images or videos to save. 1157 1158> **NOTE** 1159> 1160> This API is supported since API version 9 and deprecated since API version 12. Use [SaveButton](../apis-arkui/arkui-ts/ts-security-components-savebutton.md) instead. 1161 1162**NOTE**<br>This API saves files in **Files**, not in **Gallery**. For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 1163 1164**System capability**: SystemCapability.FileManagement.UserFileService 1165 1166**Parameters** 1167 1168| Name | Type | Mandatory| Description | 1169| ------- | ------- | ---- | -------------------------- | 1170| option | [PhotoSaveOptions](#photosaveoptionsdeprecated) | Yes | Options for saving images or videos.| 1171| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the images or videos saved.| 1172 1173**Example** 1174 1175```ts 1176import { BusinessError } from '@kit.BasicServicesKit'; 1177import { common } from '@kit.AbilityKit'; 1178import { picker } from '@kit.CoreFileKit'; 1179async function example05(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 1180 try { 1181 let photoSaveOptions = new picker.PhotoSaveOptions(); 1182 photoSaveOptions.newFileNames = ['PhotoViewPicker02.jpg','PhotoViewPicker02.mp4']; 1183 let photoPicker = new picker.PhotoViewPicker(context); 1184 photoPicker.save(photoSaveOptions, (err: BusinessError, photoSaveResult: Array<string>) => { 1185 if (err) { 1186 console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err)); 1187 return; 1188 } 1189 console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult)); 1190 }); 1191 } catch (error) { 1192 let err: BusinessError = error as BusinessError; 1193 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1194 } 1195} 1196``` 1197 1198### save<sup>(deprecated)</sup> 1199 1200save(callback: AsyncCallback<Array<string>>): void 1201 1202Starts a **photoPicker** page for the user to save one or more images or videos. This API uses an asynchronous callback to return the URIs of the images or videos to save. 1203 1204> **NOTE** 1205> 1206> This API is supported since API version 9 and deprecated since API version 12. Use [SaveButton](../apis-arkui/arkui-ts/ts-security-components-savebutton.md) instead. 1207 1208**NOTE**<br>This API saves files in **Files**, not in **Gallery**. For details about how to use the returned URIs, see [Using a Document URI](../../file-management/user-file-uri-intro.md#using-a-document-uri). 1209 1210**System capability**: SystemCapability.FileManagement.UserFileService 1211 1212**Parameters** 1213 1214| Name | Type | Mandatory| Description | 1215| ------- | ------- | ---- | -------------------------- | 1216| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the URIs of the images or videos saved.| 1217 1218**Example** 1219 1220```ts 1221import { BusinessError } from '@kit.BasicServicesKit'; 1222import { common } from '@kit.AbilityKit'; 1223import { picker } from '@kit.CoreFileKit'; 1224async function example06(context: common.UIAbilityContext) { // Ensure that context is converted from UIAbilityContext. 1225 try { 1226 let photoPicker = new picker.PhotoViewPicker(context); 1227 photoPicker.save((err: BusinessError, photoSaveResult: Array<string>) => { 1228 if (err) { 1229 console.error('PhotoViewPicker.save failed with err: ' + JSON.stringify(err)); 1230 return; 1231 } 1232 console.info('PhotoViewPicker.save successfully, photoSaveResult uri: ' + JSON.stringify(photoSaveResult)); 1233 }); 1234 } catch (error) { 1235 let err: BusinessError = error as BusinessError; 1236 console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err)); 1237 } 1238} 1239``` 1240 1241## PhotoViewMIMETypes<sup>(deprecated)</sup> 1242 1243Enumerates the media file types that can be selected. 1244 1245> **NOTE** 1246> 1247> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoViewMIMETypes](../apis-media-library-kit/arkts-apis-photoAccessHelper-e.md#photoviewmimetypes) instead. 1248 1249**Atomic service API**: This API can be used in atomic services since API version 11. 1250 1251**System capability**: SystemCapability.FileManagement.UserFileService 1252 1253| Name | Value| Description| 1254| ----- | ---- | ---- | 1255| IMAGE_TYPE | 'image/*' | Image. | 1256| VIDEO_TYPE | 'video/*' | Video. | 1257| IMAGE_VIDEO_TYPE | '\*/*' | Image and video. | 1258 1259## PhotoSelectOptions<sup>(deprecated)</sup> 1260 1261Defines the options for selecting images or videos. 1262 1263> **NOTE** 1264> 1265> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoSelectOptions](../apis-media-library-kit/arkts-apis-photoAccessHelper-class.md#photoselectoptions) instead. 1266 1267**Atomic service API**: This API can be used in atomic services since API version 11. 1268 1269**System capability**: SystemCapability.FileManagement.UserFileService 1270 1271| Name | Type | Mandatory| Description | 1272| ----------------------- | ------------------- | ---- | -------------------------------- | 1273| MIMEType | [PhotoViewMIMETypes](#photoviewmimetypesdeprecated) | No | Media file types to select. If this parameter is not specified, **IMAGE_VIDEO_TYPE** is used by default. | 1274| maxSelectNumber | number | No | Maximum number of media files that can be selected. The default value is **50**, and the maximum value is **500**. | 1275 1276## PhotoSelectResult<sup>(deprecated)</sup> 1277 1278Defines information about the images or videos selected. 1279 1280> **NOTE** 1281> 1282> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [photoAccessHelper.PhotoSelectResult](../apis-media-library-kit/arkts-apis-photoAccessHelper-class.md#photoselectresult) instead. 1283 1284**Atomic service API**: This API can be used in atomic services since API version 11. 1285 1286**System capability**: SystemCapability.FileManagement.UserFileService 1287 1288| Name | Type | Mandatory| Description | 1289| ----------------------- | ------------------- | ----| ------------------------------ | 1290| photoUris | Array<string> | Yes | URIs of the media files selected. This URI array can be used only by [photoAccessHelper.getAssets](../apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri). | 1291| isOriginalPhoto | boolean | Yes | Whether the selected image is the original one. The value **true** means the selected image is the original one; the value **false** means the opposite. | 1292 1293## PhotoSaveOptions<sup>(deprecated)</sup> 1294 1295Defines the options for saving images or videos. 1296 1297> **NOTE** 1298> 1299> This API is supported since API version 9 and deprecated since API version 12. There is no substitute API. 1300 1301**System capability**: SystemCapability.FileManagement.UserFileService 1302 1303| Name | Type | Mandatory| Description | 1304| ----------------------- | ------------------- | ---- | ---------------------------- | 1305| newFileNames | Array<string> | No | File name of the image or video to save. If this parameter is not specified, the user needs to enter the file name.| 1306
