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