1# @ohos.file.PhotoPickerComponent (PhotoPickerComponent) 2 3The **PhotoPickerComponent** component embedded in the UI of an application allows the application to access images or video files in the user directory without any permission. This component grants the application only the read permission. 4The user can directly tap this component to select images or videos. 5 6> **NOTE** 7> 8> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 9 10## Modules to Import 11 12```ts 13import { 14 PhotoPickerComponent, PickerController, PickerOptions, 15 DataType, BaseItemInfo, ItemInfo, PhotoBrowserInfo, AnimatorParams, 16 MaxSelected, ItemType, ClickType, PickerOrientation, 17 SelectMode, PickerColorMode, ReminderMode, MaxCountType, PhotoBrowserRange 18} from '@ohos.file.PhotoPickerComponent'; 19``` 20 21## Properties 22 23The [universal properties](../apis-arkui/arkui-ts/ts-universal-attributes-size.md) are supported. 24 25## PhotoPickerComponent 26 27PhotoPickerComponent({ 28 pickerOptions?: PickerOptions, 29 onSelect?: (uri: string) => void, 30 onDeselect?: (uri: string) => void, 31 onItemClicked?: (itemInfo: ItemInfo, clickType: ClickType) => boolean, 32 onEnterPhotoBrowser?: (photoBrowserInfo: PhotoBrowserInfo) => boolean, 33 onExitPhotoBrowser?: (photoBrowserInfo: PhotoBrowserInfo) => boolean, 34 onPickerControllerReady?: () => void, 35 onPhotoBrowserChanged?: (browserItemInfo: BaseItemInfo) => boolean, 36 pickerController: PickerController 37}) 38 39Allows the application to access images or video files in the user directory without any permission. 40 41> **NOTE** 42> 43>If **PhotoPickerComponent** is used with the **Tabs** component, the swipe gestures of the **Tabs** component conflict with those of the photo browser page. To prevent this problem, you can disable the swipe operation for the **Tabs** component in **onEnterPhotoBrowser()** and enable it in **onExitPhotoBrowser()**. This conflict will be resolved in later versions. 44 45**Decorator**: @Component 46 47**Atomic service API**: This API can be used in atomic services since API version 12. 48 49**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 50 51**Parameters** 52 53| Name | Type | Mandatory | Decorator Description | Description | 54|---------------|----------------|-----|------------|--------------------------| 55| pickerOptions | [PickerOptions](#pickeroptions) | No | - | Configuration of Picker. | 56| onSelect | (uri: string) => void | No | - | Callback to be invoked when an image is selected by using **PhotoPickerComponent**. This callback returns the URI of the image selected to the application. | 57| onDeselect | (uri: string) => void | No | - | Callback to be invoked when an image is deselected by using **PhotoPickerComponent**. This callback returns the URI of the image deselected to the application. | 58| onItemClicked | (itemInfo: [ItemInfo](#iteminfo), clickType: [ClickType](#clicktype)) => boolean | No | - | Callback to be invoked when an item in a Picker component is clicked.<br>For an image (thumbnail item), if **true** is returned, the image is selected. Otherwise, the image is not selected and the URI is not granted with the permission. For a camera item, if **true** is returned, the system camera is started. Otherwise, the camera is not started and the application handles the request.| 59| onEnterPhotoBrowser | (photoBrowserInfo: [PhotoBrowserInfo](#photobrowserinfo)) => boolean | No | - | Callback to be invoked when the photo browser page is displayed. The callback returns photo browser information to the application. | 60| onExitPhotoBrowser | (photoBrowserInfo: [PhotoBrowserInfo](#photobrowserinfo)) => boolean | No | - | Callback to be invoked when the photo browser page exits. The callback returns photo browser information to the application. | 61| onPickerControllerReady | () => void | No | - | Callback to be invoked when **pickerController** is available.<br>The **PickerController** APIs can be called only after this callback is invoked. | 62| onPhotoBrowserChanged | (browserItemInfo: [BaseItemInfo](#baseiteminfo)) => boolean | No | - | Callback to be invoked when the photo browser page is swiped left or right. The callback returns photo browser information to the application. | 63| pickerController | [PickerController](#pickercontroller) | No | @ObjectLink | Instance used to send data to **PhotoPickerComponent**. | 64 65## PickerOptions 66 67Defines the configuration of Picker. It inherits from [BaseSelectOptions](js-apis-photoAccessHelper.md#baseselectoptions12). 68 69 70 71**Atomic service API**: This API can be used in atomic services since API version 12. 72 73**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 74 75| Name | Type | Mandatory | Description | 76|-------------------------|-----------------------------------------|-----|--------| 77| checkBoxColor | string | No | Background color of the check box. The value is an 8-digit hexadecimal color code. | 78| backgroundColor | string | No | Background color of the Picker grid page. The value is an 8-digit hexadecimal color code. | 79| isRepeatSelectSupported | boolean | No | Whether to support repeated selection of a single image. The value **true** means a single image can be repeatedly selected. | 80| checkboxTextColor | string | No | Text color in the check box. The value is an 8-digit hexadecimal color code. (This capability is not supported currently.) | 81| photoBrowserBackgroundColorMode | [PickerColorMode](#pickercolormode) | No | Background color of the photo browser page. The options are **AUTO**, **LIGHT**, and **DARK**. The default value is **AUTO**. | 82| maxSelectedReminderMode | [ReminderMode](#remindermode) | No | Mode of the reminder when the number of selected items reaches the maximum. The options are **NONE**, **TOAST**, and **MASK**. The default value **TOAST**.| 83| orientation | [PickerOrientation](#pickerorientation) | No | Sliding preview direction of the grid page. The options are **HORIZONTAL** and **VERTICAL**. The default value is **VERTICAL**. (This capability is not supported currently.) | 84| selectMode | [SelectMode](#selectmode) | No | Select mode, which can be **SINGLE_SELECT** or **MULTI_SELECT**. The default value is **MULTI_SELECT**. | 85| maxPhotoSelectNumber | number | No | Maximum number of images that can be selected. The maximum value is **500**, which is limited by **MaxSelected**. | 86| maxVideoSelectNumber | number | No | Maximum number of videos that can be selected. The maximum value is **500**, which is limited by **MaxSelected**. | 87 88## PickerController 89 90Defines an instance used to send data to the **PhotoPicker** component. 91 92**Decorator Type**: @Observed 93 94**Atomic service API**: This API can be used in atomic services since API version 12. 95 96**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 97 98### setData 99 100setData(dataType: DataType, data: Object): void 101 102Sends data to **PhotoPickerComponent**. **DataType** specifies the type of data to be sent. 103 104**Atomic service API**: This API can be used in atomic services since API version 12. 105 106**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 107 108**Parameters** 109 110| Name | Type | Mandatory | Description | 111| ------------------------- | ------------------ | ----- | --------------- | 112| dataType | [DataType](#datatype) | Yes| Type of the data to send.| 113| data | Object | Yes| Data to send.| 114 115### setMaxSelected 116 117setMaxSelected(maxSelected: MaxSelected): void 118 119Sets the maximum number of images, maximum number of videos, and maximum number of total media assets that can be selected on a real-time basis. 120 121**Atomic service API**: This API can be used in atomic services since API version 12. 122 123**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 124 125**Parameters** 126 127| Name | Type | Mandatory | Description | 128| ------------------------- | ------------------ | ----- | --------------- | 129| maxSelected | [MaxSelected](#maxselected) | Yes| Maximum number of items that can be selected at a time.| 130 131### setPhotoBrowserItem 132 133setPhotoBrowserItem(uri: string, photoBrowserRange?: PhotoBrowserRange): void 134 135Switches from the Picker component to the photo browser page or from the photo browser page to the image to be viewed. 136 137**Atomic service API**: This API can be used in atomic services since API version 12. 138 139**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 140 141**Parameters** 142 143| Name | Type | Mandatory | Description | 144| ------------------------- | ------------------ | ----- | --------------- | 145| uri | string | Yes| URI of the image to view. Only the images selected by the user are supported.| 146| photoBrowserRange | [PhotoBrowserRange](#photobrowserrange) | No| View range on the photo browser page. The value can be **ALL** or **SELECTED_ONLY**. The default value is **ALL**, which means to view all images and videos.| 147 148## BaseItemInfo 149 150Represents image and video information. 151 152**Atomic service API**: This API can be used in atomic services since API version 12. 153 154**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 155 156| Name | Type | Mandatory | Description | 157|----------|--------|-----|---------------------------------------------------| 158| uri | string | No | Image or video URI. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty. | 159| mimeType | string | No | MIME type of the image or video. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty. | 160| width | number | No | Width of the image or video, in pixels. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty. | 161| height | number | No | Height of the image or video, in pixels. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty. | 162| size | number | No | Size of the image or video, in kilobytes. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty. | 163| duration | number | No | Video duration, in ms. This parameter is mandatory when **itemType** is **THUMBNAIL**. Otherwise, it is left empty.<br>The value **-1** indicates an image.| 164 165## ItemInfo 166 167Represents image and video information. It inherits from **BaseItemInfo** and contains only the parameter **itemType**. 168 169 170 171**Atomic service API**: This API can be used in atomic services since API version 12. 172 173**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 174 175| Name | Type | Mandatory | Description | 176|----------|--------|-----|---------------------------------------------------| 177| itemType | [ItemType](#itemtype) | No | Type of the item clicked, which can be **THUMBNAIL** or **CAMERA**. | 178 179## PhotoBrowserInfo 180 181Represents information about the photo browser page. 182 183**Atomic service API**: This API can be used in atomic services since API version 12. 184 185**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 186 187| Name | Type | Mandatory | Description | 188|----------|--------|-----|---------| 189| animatorParams | [AnimatorParams](#animatorparams) | No | Parameters for the animation for entering or exiting the photo browser page.| 190 191## AnimatorParams 192 193Animation parameters for entering or exiting the photo browser page. 194 195**Atomic service API**: This API can be used in atomic services since API version 12. 196 197**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 198 199| Name | Type | Mandatory | Description | 200|----------|--------|-----|--------------| 201| duration | number | No | Animation duration, in ms.| 202| curve | [Curve](../apis-arkui/js-apis-curve.md#curve) | [ICurve](../apis-arkui/js-apis-curve.md#icurve9) | string | No | Animation curve. | 203 204## MaxSelected 205 206Maximum number of items that can be selected at a time. 207 208**Atomic service API**: This API can be used in atomic services since API version 12. 209 210**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 211 212| Name | Type | Mandatory | Description | 213|----------|--------|-----|---------| 214| data | Map<[MaxCountType](#maxcounttype), number> | No | Maximum number of images that can be selected, maximum number of videos that can be selected, and maximum number of total items that can be selected.| 215 216## DataType 217 218Enumerates the types of data sent from **PickerController** to the **PhotoPicker** component. 219 220**Atomic service API**: This API can be used in atomic services since API version 12. 221 222**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 223 224| Name | Value | Description | 225|-------------------|-----|--------------------------------------------------------------------------------------------------------------------| 226| SET_SELECTED_URIS | 1 | Send a list of selected items to instruct the Picker component to refresh the selection status. A string array needs to be passed in.<br>For example, after an image is deleted from an application's page, the application calls **setData()** to notify the Picker component of the remaining selected items. Then, the Picker component refreshes the check box status.| 227| SET_ALBUM_URI | 2 | Maximum number of images that can be selected, maximum number of videos that can be selected, and maximum number of total items that can be selected.| 228 229## ItemType 230 231Enumerates the types of the item clicked. 232 233**Atomic service API**: This API can be used in atomic services since API version 12. 234 235**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 236 237| Name | Value | Description | 238|-------------------|-----|------------| 239| THUMBNAIL | 0 | Image or video (thumbnail).| 240| CAMERA | 1 | Camera item. | 241 242## ClickType 243 244Enumerates the click operation types. 245 246**Atomic service API**: This API can be used in atomic services since API version 12. 247 248**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 249 250| Name | Value | Description | 251|-------------------|-----|------------------------| 252| SELECTED | 0 | Select (select an image or click a camera item).| 253| DESELECTED | 1 | Deselect (deselect an image). | 254 255## PickerOrientation 256 257Enumerates the sliding preview directions of the Picker grid page. (This capability is not supported currently.) 258 259**Atomic service API**: This API can be used in atomic services since API version 12. 260 261**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 262 263| Name | Value | Description | 264|-------------------|-----|-------| 265| VERTICAL | 0 | Vertical direction.| 266| HORIZONTAL | 1 | Horizontal direction.| 267 268## SelectMode 269 270Enumerates the select modes. 271 272**Atomic service API**: This API can be used in atomic services since API version 12. 273 274**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 275 276| Name | Value | Description | 277|-------------------|-----|-------| 278| SINGLE_SELECT | 0 | Select a single option.| 279| MULTI_SELECT | 1 | Select multiple options.| 280 281## PickerColorMode 282 283Enumerates the Picker color modes. 284 285**Atomic service API**: This API can be used in atomic services since API version 12. 286 287**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 288 289| Name | Value | Description | 290|-------------------|-----|-------| 291| AUTO | 0 | Same with the system.| 292| LIGHT | 1 | Light mode.| 293| DARK | 2 | Dark mode.| 294 295## ReminderMode 296 297Enumerates the types of the reminder when the number of selected items reaches the maximum. 298 299**Atomic service API**: This API can be used in atomic services since API version 12. 300 301**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 302 303| Name | Value | Description | 304|-------------------|-----|-----------| 305| NONE | 0 | No reminder. | 306| TOAST | 1 | Toast message.| 307| MASK | 2 | Grayed-out hint. | 308 309## MaxCountType 310 311Enumerates the types of the maximum count. 312 313**Atomic service API**: This API can be used in atomic services since API version 12. 314 315**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 316 317| Name | Value | Description | 318|-------------------|-----|---------------------------| 319| TOTAL_MAX_COUNT | 0 | Maximum number of total items that can be selected. | 320| PHOTO_MAX_COUNT | 1 | Maximum number of images that can be selected. The value cannot be greater than **Total_MAX_Count**.| 321| VIDEO_MAX_COUNT | 2 | Maximum number of videos that can be selected. The value cannot be greater than **Total_MAX_Count**.| 322 323## PhotoBrowserRange 324 325Enumerates the view range on the photo browser page. 326 327**Atomic service API**: This API can be used in atomic services since API version 12. 328 329**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 330 331| Name | Value | Description | 332|-------------------|-----|---------------------------| 333| ALL | 0 | View all images and videos. | 334| SELECTED_ONLY | 1 | View selected images and videos only.| 335 336## Example 337 338```ts 339// xxx.ets 340import { 341 PhotoPickerComponent, PickerController, PickerOptions, 342 DataType, BaseItemInfo, ItemInfo, PhotoBrowserInfo, AnimatorParams, 343 MaxSelected, ItemType, ClickType, PickerOrientation, 344 SelectMode, PickerColorMode, ReminderMode, MaxCountType, PhotoBrowserRange 345} from '@ohos.file.PhotoPickerComponent'; 346import photoAccessHelper from '@ohos.file.photoAccessHelper'; 347 348@Entry 349@Component 350struct PickerDemo { 351 pickerOptions: PickerOptions = new PickerOptions(); 352 @State pickerController: PickerController = new PickerController(); 353 @State selectUris: Array<string> = new Array<string>(); 354 @State currentUri: string = ''; 355 @State isBrowserShow: boolean = false; 356 357 aboutToAppear() { 358 this.pickerOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE; 359 this.pickerOptions.maxSelectNumber = 5; 360 this.pickerOptions.isSearchSupported = false; 361 this.pickerOptions.isPhotoTakingSupported = false; 362 // Other attributes 363 } 364 365 private onSelect(uri: string): void { 366 // Add 367 if (uri) { 368 this.selectUris.push(uri); 369 } 370 } 371 372 private onDeselect(uri: string): void { 373 // Remove 374 if (uri) { 375 this.selectUris = this.selectUris.filter((item: string) => { 376 return item != uri; 377 }) 378 } 379 } 380 381 private onItemClicked(itemInfo: ItemInfo, clickType: ClickType): boolean { 382 if (!itemInfo) { 383 return false; 384 } 385 let type: ItemType | undefined = itemInfo.itemType; 386 let uri: string | undefined = itemInfo.uri; 387 if (type === ItemType.CAMERA) { 388 // Click a camera item. 389 return true; // If true is returned, the system camera is started. If false is returned, the app processes its services. 390 } else { 391 if (clickType === ClickType.SELECTED) { 392 // The application processes its services. 393 if (uri) { 394 this.selectUris.push(uri); 395 this.pickerOptions.preselectedUris = [...this.selectUris]; 396 } 397 return true; // If true is returned, the check box is selected. Otherwise, the check box is not selected. 398 } else { 399 if (uri) { 400 this.selectUris = this.selectUris.filter((item: string) => { 401 return item != uri; 402 }); 403 this.pickerOptions.preselectedUris = [...this.selectUris]; 404 } 405 } 406 return true; 407 } 408 } 409 410 private onEnterPhotoBrowser(photoBrowserInfo: PhotoBrowserInfo): boolean { 411 // Callback to be invoked when the photo browser page is displayed. 412 this.isBrowserShow = true; 413 return true; 414 } 415 416 private onExitPhotoBrowser(photoBrowserInfo: PhotoBrowserInfo): boolean { 417 // Callback to be invoked when the photo browser page is closed. 418 this.isBrowserShow = false; 419 return true; 420 } 421 422 private onPickerControllerReady(): void { 423 // After the callback is called, pickerController APIs can be called to send data to Picker. Before the callback is called, pickerController APIs do not take effect. 424 } 425 426 private onPhotoBrowserChanged(browserItemInfo: BaseItemInfo): boolean { 427 // Callback to be invoked when the photo browser is swiped left or right. 428 this.currentUri = browserItemInfo.uri ?? ''; 429 return true; 430 } 431 432 build() { 433 Flex({ 434 direction: FlexDirection.Column, 435 justifyContent: FlexAlign.Center, 436 alignItems: ItemAlign.Center 437 }) { 438 PhotoPickerComponent({ 439 pickerOptions: this.pickerOptions, 440 // onSelect: (uri: string): void => this.onSelect(uri), 441 // onDeselect: (uri: string): void => this.onDeselect(uri), 442 onItemClicked: (itemInfo: ItemInfo, clickType: ClickType): boolean => this.onItemClicked(itemInfo, clickType), // This API can replace the preceding two APIs. 443 onEnterPhotoBrowser: (photoBrowserInfo: PhotoBrowserInfo): boolean => this.onEnterPhotoBrowser(photoBrowserInfo), 444 onExitPhotoBrowser: (photoBrowserInfo: PhotoBrowserInfo): boolean => this.onExitPhotoBrowser(photoBrowserInfo), 445 onPickerControllerReady: (): void => this.onPickerControllerReady(), 446 onPhotoBrowserChanged: (browserItemInfo: BaseItemInfo): boolean => this.onPhotoBrowserChanged(browserItemInfo), 447 pickerController: this.pickerController, 448 }).height('60%').width('100%') 449 450 451 // Simulate the selection bar at the bottom of the application. 452 if (this.isBrowserShow) { 453 Row() { 454 ForEach(this.selectUris, (uri: string) => { 455 if (uri === this.currentUri) { 456 Image(uri).height('10%').width('10%').onClick(() => { 457 }).borderWidth(1).borderColor('red') 458 } else { 459 Image(uri).height('10%').width('10%').onClick(() => { 460 this.pickerController.setData(DataType.SET_SELECTED_URIS, this.selectUris); 461 this.pickerController.setPhotoBrowserItem(uri, PhotoBrowserRange.ALL); 462 }) 463 } 464 }, (uri: string) => JSON.stringify(uri)) 465 } 466 } else { 467 Button ('Preview').width ('33%').height('5%').onClick(() => { 468 if (this.selectUris.length > 0) { 469 this.pickerController.setPhotoBrowserItem(this.selectUris[0], PhotoBrowserRange.SELECTED_ONLY); 470 } 471 }) 472 } 473 } 474 } 475} 476``` 477