1# @ohos.file.PhotoPickerComponent (PhotoPicker组件) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @xuchangda--> 5<!--Designer: @guxinggang--> 6<!--Tester: @wangbeibei--> 7<!--Adviser: @zengyawen--> 8 9应用可以在布局中嵌入PhotoPicker组件，通过此组件，应用无需申请权限，即可实现媒体文件选择功能。在用户选择媒体文件后，应用即可访问用户选中的图片或视频文件。仅包含读权限。 10需要注意的是PhotoPickerComponent不能嵌套使用，且不建议在PhotoPickerComponent上覆盖设置了overlay属性的组件，将导致PhotoPickerComponent无法接受手势事件。 11应用嵌入组件后，用户可直接在PhotoPicker组件中选择图片或视频文件。 12 13> **说明：** 14> 15> 该组件从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16 17## 导入模块 18 19```ts 20import { 21 PhotoPickerComponent, PickerController, PickerOptions, 22 DataType, BaseItemInfo, ItemInfo, PhotoBrowserInfo, ItemType, ClickType, 23 MaxCountType, PhotoBrowserRange, PhotoBrowserUIElement, 24 ItemsDeletedCallback, ExceedMaxSelectedCallback, CurrentAlbumDeletedCallback 25} from '@ohos.file.PhotoPickerComponent'; 26``` 27 28## 属性 29 30支持[通用属性](../apis-arkui/arkui-ts/ts-component-general-attributes.md)。 31 32## PhotoPickerComponent 33 34PhotoPickerComponent({ 35 pickerOptions?: PickerOptions, 36 onSelect?: (uri: string) => void, 37 onDeselect?: (uri: string) => void, 38 onItemClicked?: (itemInfo: ItemInfo, clickType: ClickType) => boolean, 39 onEnterPhotoBrowser?: (photoBrowserInfo: PhotoBrowserInfo) => boolean, 40 onExitPhotoBrowser?: (photoBrowserInfo: PhotoBrowserInfo) => boolean, 41 onPickerControllerReady?: () => void, 42 onPhotoBrowserChanged?: (browserItemInfo: BaseItemInfo) => boolean, 43 onSelectedItemsDeleted?: ItemsDeletedCallback, 44 onExceedMaxSelected?: ExceedMaxSelectedCallback, 45 onCurrentAlbumDeleted?: CurrentAlbumDeletedCallback, 46 onVideoPlayStateChanged?: videoPlayStateChangedCallback, 47 pickerController: PickerController 48}) 49 50应用可以在布局中嵌入PhotoPickerComponent组件，通过此组件，应用无需申请权限，即可访问公共目录中的图片或视频文件。 51 52> **说明：** 53> 如果当前PhotoPickerComponent组件嵌套在Tabs组件中使用，Tabs组件的左右滑动会与图片选择大图界面的左右滑动切换手势发生冲突。 54> 55> 可在进退大图的回调中设置Tabs组件是否支持滑动来规避，该问题将在后续版本修复。 56 57**装饰器类型**：@Component 58 59**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 60 61**参数：** 62 63| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 64|-------------------------|----------------------------------------------------------------------------------|-----|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 65| pickerOptions | [PickerOptions](#pickeroptions) | 否 | - | picker配置参数信息。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 66| onSelect | (uri: string) => void | 否 | - | 用户在Picker组件中勾选图片时产生的回调事件，将图片uri报给应用。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 67| onDeselect | (uri: string) => void | 否 | - | 用户在Picker组件中取消勾选图片时产生的回调事件，同时也会将图片uri报给应用。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 68| onItemClicked | (itemInfo: [ItemInfo](#iteminfo), clickType: [ClickType](#clicktype)) => boolean | 否 | - | 用户在picker组件中点击item产生的回调事件。<br>点击图片（缩略图item）时，返回值为true则勾选此图片，否则不响应勾选，uri不授权；点击相机item，返回值为true则拉起系统相机，否则不拉起相机，由应用自行处理。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 69| onEnterPhotoBrowser | (photoBrowserInfo: [PhotoBrowserInfo](#photobrowserinfo)) => boolean | 否 | - | 点击进入大图时产生的回调事件，将大图相关信息报给应用。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 70| onExitPhotoBrowser | (photoBrowserInfo: [PhotoBrowserInfo](#photobrowserinfo)) => boolean | 否 | - | 退出大图时产生的回调事件，将大图相关信息报给应用。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 71| onPickerControllerReady | () => void | 否 | - | 当pickerController可用时产生的回调事件。<br>调用PickerController相关接口需在该回调后才能生效。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 72| onPhotoBrowserChanged | (browserItemInfo: [BaseItemInfo](#baseiteminfo)) => boolean | 否 | - | 大图左右滑动时产生的回调事件，将大图相关信息报给应用。仅在多选模式下生效。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 73| onSelectedItemsDeleted<sup>13+</sup> | [ItemsDeletedCallback](#itemsdeletedcallback13) | 否 | - | 已勾选的图片被删除时产生的回调，并将被删除图片的相关信息回调给应用。<br>**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 | 74| onExceedMaxSelected<sup>13+</sup> | [ExceedMaxSelectedCallback](#exceedmaxselectedcallback13) | 否 | - | 选择达到最大选择数量（最大图片选择数量或者是最大视频选择数量亦或是总的最大选择数量）之后再次点击勾选时产生的回调。<br>- 若选择的数量达到了最大图片选择数量且未达到总的最大选择数量则回调的参数exceedMaxCountType为[MaxCountType](#maxcounttype).PHOTO_MAX_COUNT。<br>- 若选择的数量达到了最大视频选择数量且未达到总的最大选择数量则回调的参数exceedMaxCountType为[MaxCountType](#maxcounttype).VIDEO_MAX_COUNT。<br>- 只要选择的数量达到了总的最大选择数量则回调的参数exceedMaxCountType为[MaxCountType](#maxcounttype).TOTAL_MAX_COUNT。<br>**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 | 75| onCurrentAlbumDeleted<sup>13+</sup> | [CurrentAlbumDeletedCallback](#currentalbumdeletedcallback13) | 否 | - | 当前相册被删除时产生的回调。<br>当前相册是指通过pickerController.[setData](#setdata)([DataType](#datatype).SET_ALBUM_URI, currentAlbumUri)接口设置给宫格组件的相册，即“currentAlbumUri”。<br>当前相册被删除后若使用方刷新自己的相册标题栏，使用方可以设置自己的标题栏名称为默认的相册名例如“图片和视频”、“图片”或“视频”，然后通过pickerController.[setData](#setdata)([DataType](#datatype).SET_ALBUM_URI, '')接口传空串去刷新宫格页为默认相册。<br>**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 | 76| onVideoPlayStateChanged<sup>14+</sup> | [videoPlayStateChangedCallback](#videoplaystatechangedcallback14) | 否 | - | 大图页视频播放状态改变时回调。<br>**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 | 77| pickerController | [PickerController](#pickercontroller) | 否 | @ObjectLink | 应用可通过PickerController向Picker组件发送数据。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 78 79## PickerOptions 80 81Picker配置选项，继承自[BaseSelectOptions](arkts-apis-photoAccessHelper-class.md#baseselectoptions10)。 82 83Picker配置选项。 84 85**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 86 87| 名称 | 类型 | 必填 | 说明 | 88|---------------------------------|-----------------------------------------|-----|--------------------------------------------------------------------------| 89| checkBoxColor | string | 否 | 勾选框的背景色。格式为8位十六进制颜色代码。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 90| backgroundColor | string | 否 | picker宫格页面背景色。格式为8位十六进制颜色代码。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 91| isRepeatSelectSupported | boolean | 否 | 是否支持单张图片重复选择。true表示支持。默认不支持。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 92| checkboxTextColor | string | 否 | 勾选框内文本颜色。格式为8位十六进制颜色代码。 （该能力暂不支持）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 93| photoBrowserBackgroundColorMode | [PickerColorMode](#pickercolormode) | 否 | 大图背景颜色。包括跟随系统、浅色模式以及深色模式，默认为跟随系统。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 94| maxSelectedReminderMode | [ReminderMode](#remindermode) | 否 | 选择数量达到最大时的提示方式。包括弹toast提示、不提示以及蒙层提示，默认为弹toast提示。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 95| orientation | [PickerOrientation](#pickerorientation) | 否 | 宫格页面滑动预览方向，包括水平和竖直两个方向，默认为竖直方向。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 96| selectMode | [SelectMode](#selectmode) | 否 | 选择模式。包括多选和单选，默认为多选。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 97| maxPhotoSelectNumber | number | 否 | 图片最大的选择数量。最大值为500，受到最大选择总数的限制。默认为500。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 98| maxVideoSelectNumber | number | 否 | 视频最大的选择数量。最大值为500，受到最大选择总数的限制。默认为500。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 99| isSlidingSelectionSupported<sup>13+</sup> | boolean | 否 | 是否支持滑动多选，true表示支持。默认不支持。重复选择场景不支持滑动多选。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 100| photoBrowserCheckboxPosition<sup>13+</sup> | [number, number] | 否 | 设置大图页checkbox的位置。第一个参数为X方向偏移量，第二个参数为Y方向偏移量。传参范围0-1，代表距离组件左上角0%-100%的偏移量。默认值为[0, 0]。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 101| gridMargin<sup>14+</sup> | [Margin](../../reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md#margin) | 否 | 设置组件宫格页margin。<br>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 102| photoBrowserMargin<sup>14+</sup> | [Margin](../../reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md#margin) | 否 | 设置组件大图页margin。<br>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 103| singleLineConfig<sup>20+</sup> | [SingleLineConfig](#singlelineconfig) | 否 | 设置组件宫格页单行显示模式。单行模式下，组件不提供打开大图浏览相关功能。组件不支持大图相关回调，PickerController不支持大图相关的接口，接口调用将无效。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 104| uiComponentColorMode<sup>20+</sup> | [PickerColorMode](#pickercolormode) | 否 | Picker的颜色模式。Picker宫格界面除背景色之外其他组件的深浅色风格，包括搜索框、相机入口、安全使用图库提示组件、推荐气泡等组件，一般与backgroundColor配合使用。默认为PickerColorMode.AUTO，跟随系统深浅色切换。<br>该属性一般设置PickerColorMode.LIGHT时不与深颜色的backgroundColor搭配；设置PickerColorMode.DARK时不与浅颜色的backgroundColor搭配，否则会出现组件背景或文字无法看清楚的问题。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 105| gridStartOffset<sup>20+</sup> | number | 否 | 组件宫格缩略图第一行与组件顶部的预留空间。默认值0，单位vp。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 106| gridEndOffset<sup>20+</sup> | number | 否 | 组件宫格缩略图最后一行与组件底部的预留空间。默认值0，单位vp。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 107 108## ItemsDeletedCallback<sup>13+</sup> 109 110type ItemsDeletedCallback = (baseItemInfos: Array<BaseItemInfo>) => void 111 112已勾选的图片被删除时产生的回调事件。 113 114**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 115 116**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 117 118**参数：** 119 120| 参数名 | 类型 | 必填 | 说明 | 121| -------- |--------------------------------------------| -------- |----------| 122| baseItemInfos | Array<[BaseItemInfo](#baseiteminfo)> | 是 | 照片的基本信息。 | 123 124## ExceedMaxSelectedCallback<sup>13+</sup> 125 126type ExceedMaxSelectedCallback = (exceedMaxCountType: MaxCountType) => void 127 128选择达到最大选择数量之后再次点击勾选时的回调事件。 129 130**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 131 132**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| -------- |-------------------------------| -------- |----------------------------------------------| 138| exceedMaxCountType | [MaxCountType](#maxcounttype) | 是 | 达到最大选择数量的类型。类型包含图片最大选择数量、视频最大选择数量以及总的最大选择数量。 | 139 140## CurrentAlbumDeletedCallback<sup>13+</sup> 141 142type CurrentAlbumDeletedCallback = () => void 143 144当前相册被删除时的回调事件。 145 146**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 147 148**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 149 150## videoPlayStateChangedCallback<sup>14+</sup> 151 152type videoPlayStateChangedCallback = (state: VideoPlayerState) => void 153 154大图页视频播放状态改变时回调。 155 156**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 157 158**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| -------- |-------------------------------| -------- |----------------------------------------------| 164| state | [VideoPlayerState](#videoplayerstate14) | 是 | 视频播放状态。 | 165 166## PickerController 167 168应用可通过PickerController向picker组件发送数据。 169 170**装饰器类型**：@Observed 171 172**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 175 176### setData 177 178setData(dataType: DataType, data: Object): void 179 180应用可通过该接口向picker组件发送数据，并通过DataType来区分具体发送什么类型的数据。 181 182**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 183 184**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 185 186**参数：** 187 188| 参数名 | 类型 | 必填 | 说明 | 189| ------------------------- | ------------------ | ----- | --------------- | 190| dataType | [DataType](#datatype) | 是 | 发送数据的数据类型。| 191| data | Object | 是 | 发送的数据。 | 192 193### setMaxSelected 194 195setMaxSelected(maxSelected: MaxSelected): void 196 197应用可通过该接口，实时地设置图片的最大选择数量、视频的最大选择数量以及总的最大选择数量。 198 199**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 200 201**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------------------------- | ------------------ | ----- | --------------- | 207| maxSelected | [MaxSelected](#maxselected) | 是 | 最大选择数量。| 208 209### setPhotoBrowserItem 210 211setPhotoBrowserItem(uri: string, photoBrowserRange?: PhotoBrowserRange): void 212 213应用可通过该接口,切换picker组件至大图浏览模式浏览图片；当已处于大图浏览模式时，切换浏览的图片。 214 215**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 216 217**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ------------------------- | ------------------ | ----- | --------------- | 223| uri | string | 是 | 指定大图浏览的图片uri。仅支持指定用户已选择的图片，未选择的图片不生效。| 224| photoBrowserRange | [PhotoBrowserRange](#photobrowserrange) | 否 | 打开大图浏览模式后，左右滑动切换浏览图片的范围，可配置仅浏览用户选择的或浏览全部图片，视频。默认：PhotoBrowserRange.ALL。浏览全部图片，视频。 | 225 226### exitPhotoBrowser<sup>13+</sup> 227 228exitPhotoBrowser(): void 229 230应用可通过该接口，向picker发送退出大图的通知。 231 232**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 233 234**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 235 236### setPhotoBrowserUIElementVisibility<sup>13+</sup> 237 238setPhotoBrowserUIElementVisibility(elements: Array<PhotoBrowserUIElement>, isVisible: boolean): void 239 240应用可通过该接口，设置大图页大图预览组件外其他UI元素是否可见。不设置则默认可见。 241 242**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 243 244**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249|-------------|----------------------------------------------------------------| ----- |-------------------| 250| elements | Array<[PhotoBrowserUIElement](#photobrowseruielement13)> | 是 | 大图页大图预览组件外其他UI元素。 | 251| isVisible | boolean | 是 | 是否可见。true表示可见，默认为false。 | 252 253### replacePhotoPickerPreview<sup>15+</sup> 254 255replacePhotoPickerPreview(originalUri: string, newUri: string, callback: AsyncCallback<void>): void 256 257应用可通过该接口，将photoPicker中用户勾选的图片替换为应用后期编辑修改后的图片。 258 259**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 260 261**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266|-------------|----------------------------| -------------- |-------------------| 267| originalUri | string | 是 | 原uri，将会被替换掉的uri。 | 268| newUri | string | 是 | 新uri，即替换后的uri。基于originalUri修改后期望在photoPicker上替换originalUri显示的，暂存在应用沙箱的图片/视频uri。 | 269| callback | AsyncCallback<void> | 是 | 调用接口完成替换后的回调。 | 270 271### saveTrustedPhotoAssets<sup>15+</sup> 272 273saveTrustedPhotoAssets(trustedUris: Array<string>, callback: AsyncCallback<Array<string>>, configs?: Array<photoAccessHelper.PhotoCreationConfig>, saveMode?: SaveMode): void 274 275应用可通过该接口，保存对应uri列表的文件。使用时，一般结合[replacePhotoPickerPreview](#replacephotopickerpreview15)接口使用，将替换显示成功后的应用沙箱图片/视频newUris保存到图库。 276 277**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 278 279**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284|-------------|----------------------------------------------------------------| ----- |-------------------| 285| trustedUris | Array<string> | 是 | 需要保存到图库的应用沙箱图片/视频uri。trustedUris一般来自[replacePhotoPickerPreview](#replacephotopickerpreview15)替换显示成功的newUri。 | 286| callback | AsyncCallback<Array<string>> | 是 | 返回保存后新生成的媒体库文件对应的uri。 | 287| configs | Array<[photoAccessHelper.PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12)> | 否 | 需要保存的文件对应的配置参数。 | 288| saveMode | [SaveMode](#savemode15) | 否 | 图片保存模式。 | 289 290## BaseItemInfo 291 292图片、视频相关信息。 293 294**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 295 296**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 297 298| 名称 | 类型 | 必填 | 说明 | 299|----------|--------|-----|---------------------------------------------------| 300| uri | string | 否 | 图片、视频的uri（itemType为ThUMBNAIL时支持，否则为空）。 | 301| mimeType | string | 否 | 图片、视频的mimeType（itemType为ThUMBNAIL时支持，否则为空）。 | 302| width | number | 否 | 图片、视频的宽（单位：像素）（itemType为ThUMBNAIL时支持，否则为空）。 | 303| height | number | 否 | 图片、视频的高（单位：像素）（itemType为ThUMBNAIL时支持，否则为空）。 | 304| size | number | 否 | 图片、视频的大小（单位：字节）（itemType为ThUMBNAIL时支持，否则为空）。 | 305| duration | number | 否 | 视频的时长（单位：毫秒），图片时返回-1（itemType为ThUMBNAIL时支持，否则为空）。 | 306 307## ItemInfo 308 309继承自[BaseItemInfo](#baseiteminfo)，增加私有参数itemType。 310 311图片、视频相关信息。 312 313**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 314 315**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 316 317| 名称 | 类型 | 必填 | 说明 | 318|----------|--------|-----|---------------------------------------------------| 319| itemType | [ItemType](#itemtype) | 否 | 被点击的item类型。包括缩略图item和相机item。 | 320 321## PhotoBrowserInfo 322 323大图相关信息。 324 325**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 326 327**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 328 329| 名称 | 类型 | 必填 | 说明 | 330|----------|--------|-----|---------| 331| animatorParams | [AnimatorParams](#animatorparams) | 否 | 进入、退出大图界面时的动效参数。 | 332 333## AnimatorParams 334 335进退大图动效参数。 336 337**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 338 339**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 340 341| 名称 | 类型 | 必填 | 说明 | 342|----------|--------|-----|--------------| 343| duration | number | 否 | 动效时长（单位：毫秒）。 | 344| curve | [Curve](../apis-arkui/js-apis-curve.md#curve) | [ICurve](../apis-arkui/js-apis-curve.md#icurve9) | string | 否 | 动效曲线。 | 345 346## MaxSelected 347 348最大选择数量。 349 350**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 351 352**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 353 354| 名称 | 类型 | 必填 | 说明 | 355|----------|--------|-----|---------| 356| data | Map<[MaxCountType](#maxcounttype), number> | 否 | 最大选择数量（包含图片的最大选择数量、视频的最大选择数量以及总的最大选择数量） | 357 358## SingleLineConfig 359 360单行显示模式配置项。单行模式下，组件不提供打开大图浏览相关功能。组件不支持大图相关回调，PickerController不支持大图相关的接口，接口调用将无效。 361 362**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 363 364**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 365 366| 名称 | 类型 | 必填 | 说明 | 367| ---- | ------------------------------------------------ | ---- | ------------------------------------------------------------------------------ | 368| itemDisplayRatio | [ItemDisplayRatio](#itemdisplayratio20) | 否 | 宫格显示宽高比，支持1:1，原图宽高比两种模式，默认为宽高比1:1显示。 | 369| itemBorderRadius | [Length](../apis-arkui/arkui-ts/ts-types.md#length) | [BorderRadiuses](../apis-arkui/arkui-ts/ts-types.md#borderradiuses9) | [LocalizedBorderRadiuses](../apis-arkui/arkui-ts/ts-types.md#localizedborderradiuses12) | 否 | 宫格圆角属性。 | 370| itemGap | [Length](../apis-arkui/arkui-ts/ts-types.md#length) | 否 | 宫格间距。 | 371 372## DataType 373 374枚举，PickerController向picker组件发送数据的数据类型。 375 376**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 377 378**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 379 380| 名称 | 值 | 说明 | 381|-------------------|-----|--------------------------------------------------------------------------------------------------------------------| 382| SET_SELECTED_URIS | 1 | 发送已选择的数据列表，通知picker组件勾选状态刷新，需要传入string数组类型。<br>例如：应用在自己的页面中删除某张图片后，需要把剩下的已选择的数据列表通过setData接口通知到picker组件，从而触发picker组件勾选框状态刷新正确。 | 383| SET_ALBUM_URI | 2 | 发送已选择相册，通知picker组件刷新相册，需要传入string类型。<br>例如：应用在自己的页面中选择相册后，需要把已选择的相册uri通过setData接口通知到picker组件，从而触发picker组件刷新新相册数据。 | 384 385## ItemType 386 387被点击item的类型。 388 389**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 390 391**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 392 393| 名称 | 值 | 说明 | 394|-------------------|-----|------------| 395| THUMBNAIL | 0 | 图片、视频item（缩略图item）。 | 396| CAMERA | 1 | 相机item。 | 397 398## ClickType 399 400点击操作的类型。 401 402**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 403 404**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 405 406| 名称 | 值 | 说明 | 407|-------------------|-----|------------------------| 408| SELECTED | 0 | 选择操作（勾选图片或者点击相机item）。 | 409| DESELECTED | 1 | 取消选择操作（取消勾选图片）。 | 410 411## PickerOrientation 412 413Picker宫格页面滑动预览的方向。 414 415从API20开始，该能力支持配置；在API12-19，该能力设置不生效，默认为竖直方向。 416 417**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 418 419**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 420 421| 名称 | 值 | 说明 | 422|-------------------|-----|-------| 423| VERTICAL | 0 | 竖直方向。 | 424| HORIZONTAL | 1 | 水平方向。 | 425 426## SelectMode 427 428选择模式。 429 430**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 431 432**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 433 434| 名称 | 值 | 说明 | 435|-------------------|-----|-------| 436| SINGLE_SELECT | 0 | 单选模式。 | 437| MULTI_SELECT | 1 | 多选模式。 | 438 439## PickerColorMode 440 441Picker的颜色模式。 442 443**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 444 445**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core。 446 447| 名称 | 值 | 说明 | 448|-------------------|-----|-------| 449| AUTO | 0 | 跟随系统。 | 450| LIGHT | 1 | 浅色模式。 | 451| DARK | 2 | 深色模式。 | 452 453## ReminderMode 454 455最大选择数量提示方式。 456 457**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 458 459**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 460 461| 名称 | 值 | 说明 | 462|-------------------|-----|-----------| 463| NONE | 0 | 不提示。 | 464| TOAST | 1 | 弹toast提示。 | 465| MASK | 2 | 蒙灰提示。 | 466 467## MaxCountType 468 469最大选择数量的类型。 470 471**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 472 473**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 474 475| 名称 | 值 | 说明 | 476|-------------------|-----|---------------------------| 477| TOTAL_MAX_COUNT | 0 | 总的最大选择数量。 | 478| PHOTO_MAX_COUNT | 1 | 图片的最大选择数量（不能大于总的最大选择数量）。 | 479| VIDEO_MAX_COUNT | 2 | 视频的最大选择数量（不能大于总的最大选择数量）。 | 480 481## PhotoBrowserRange 482 483打开大图浏览模式后，左右滑动切换浏览图片的范围。 484 485**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 486 487**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 488 489| 名称 | 值 | 说明 | 490|-------------------|-----|---------------------------| 491| ALL | 0 | 全部图片，视频。 | 492| SELECTED_ONLY | 1 | 仅用户已选择的图片，视频。 | 493 494## PhotoBrowserUIElement<sup>13+</sup> 495 496大图页大图预览组件外其他UI元素。 497 498**原子化服务API**：从API version 13开始，该接口支持在原子化服务中使用。 499 500**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 501 502| 名称 | 值 | 说明 | 503|-------------|-----|----------| 504| CHECKBOX | 0 | 大图页勾选框。 | 505| BACK_BUTTON | 1 | 大图页返回按钮。 | 506 507## SaveMode<sup>15+</sup> 508 509图片/视频保存模式。 510 511**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 512 513**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 514 515| 名称 | 值 | 说明 | 516|-------------|-----|----------| 517| SAVE_AS | 0 | 另存为新的图片/视频。 | 518| OVERWRITE | 1 | 覆盖原有图片/视频，覆盖后支持在图库中将保存内容回退，还原成原始图片/视频。 | 519 520## VideoPlayerState<sup>14+</sup> 521 522视频播放状态。 523 524**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 525 526**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 527 528| 名称 | 值 | 说明 | 529|-------------------|-----|---------------------------| 530| PLAYING | 0 | 视频播放中。 | 531| PAUSED | 1 | 视频播放暂停。 | 532| STOPPED | 2 | 视频播放停止。 | 533| SEEK_START | 3 | 开始拖拽进度条。 | 534| SEEK_FINISH | 4 | 结束拖拽进度条。 | 535 536## ItemDisplayRatio<sup>20+</sup> 537 538单行布局宫格显示宽高比模式，包括1:1和原图宽高比两种模式。 539 540**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 541 542**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 543 544| 名称 | 值 | 说明 | 545| ------------------- | --- | -------------- | 546| SQUARE_RATIO | 0 | 1:1比例显示。 | 547| ORIGINAL_SIZE_RATIO | 1 | 原图宽高比显示。 | 548 549## 示例 550 551```ts 552// xxx.ets 553import { 554 PhotoPickerComponent, 555 PickerController, 556 PickerOptions, 557 DataType, 558 BaseItemInfo, 559 ItemInfo, 560 PhotoBrowserInfo, 561 ItemType, 562 ClickType, 563 MaxCountType, 564 PhotoBrowserRange, 565 PhotoBrowserUIElement, 566 ItemsDeletedCallback, 567 ExceedMaxSelectedCallback, 568 CurrentAlbumDeletedCallback, 569 videoPlayStateChangedCallback, 570 VideoPlayerState 571} from '@ohos.file.PhotoPickerComponent'; 572import { dataSharePredicates } from '@kit.ArkData'; 573import { photoAccessHelper } from '@kit.MediaLibraryKit'; 574import { common } from '@kit.AbilityKit'; 575 576@Entry 577@Component 578struct PickerDemo { 579 pickerOptions: PickerOptions = new PickerOptions(); 580 @State pickerController: PickerController = new PickerController(); 581 @State selectUris: string[] = []; 582 @State currentUri: string = ''; 583 @State isBrowserShow: boolean = false; 584 private selectedItemsDeletedCallback: ItemsDeletedCallback = 585 (baseItemInfos: Array<BaseItemInfo>) => this.onSelectedItemsDeleted(baseItemInfos); 586 private exceedMaxSelectedCallback: ExceedMaxSelectedCallback = 587 (exceedMaxCountType: MaxCountType) => this.onExceedMaxSelected(exceedMaxCountType); 588 private currentAlbumDeletedCallback: CurrentAlbumDeletedCallback = () => this.onCurrentAlbumDeleted(); 589 private videoPlayStateChangedCallback: videoPlayStateChangedCallback = 590 (state: VideoPlayerState) => this.videoPlayStateChanged(state); 591 private thumbnail: PixelMap[] = []; 592 private assets: photoAccessHelper.PhotoAsset[] = []; 593 594 aboutToAppear() { 595 this.pickerOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE; 596 this.pickerOptions.maxSelectNumber = 5; 597 this.pickerOptions.isSearchSupported = false; 598 this.pickerOptions.isPhotoTakingSupported = false; 599 this.pickerOptions.photoBrowserCheckboxPosition = [0.5, 0.5]; 600 // 其他属性..... 601 } 602 603 private onSelect(uri: string): void { 604 // 添加。 605 if (uri) { 606 this.selectUris.push(uri); 607 } 608 } 609 610 private onDeselect(uri: string): void { 611 // 移除。 612 if (uri) { 613 this.selectUris = this.selectUris.filter((item: string) => { 614 return item != uri; 615 }) 616 } 617 } 618 619 private onItemClicked(itemInfo: ItemInfo, clickType: ClickType): boolean { 620 if (!itemInfo) { 621 return false; 622 } 623 let type: ItemType | undefined = itemInfo.itemType; 624 let uri: string | undefined = itemInfo.uri; 625 if (type === ItemType.CAMERA) { 626 // 点击相机item。 627 return true; // 返回true则拉起系统相机，若应用需要自行处理则返回false。 628 } else { 629 if (clickType === ClickType.SELECTED) { 630 // 应用做自己的业务处理（注：非长耗时操作，例如opensync大文件）。 631 if (uri) { 632 this.selectUris.push(uri); 633 this.pickerOptions.preselectedUris = [...this.selectUris]; 634 } 635 return true; // 返回true则勾选，否则则不响应勾选。 636 } else { 637 if (uri) { 638 this.selectUris = this.selectUris.filter((item: string) => { 639 return item != uri; 640 }); 641 this.pickerOptions.preselectedUris = [...this.selectUris]; 642 } 643 } 644 return true; 645 } 646 } 647 648 private onEnterPhotoBrowser(photoBrowserInfo: PhotoBrowserInfo): boolean { 649 // 进入大图的回调。 650 this.isBrowserShow = true; 651 return true; 652 } 653 654 private onExitPhotoBrowser(photoBrowserInfo: PhotoBrowserInfo): boolean { 655 // 退出大图的回调。 656 this.isBrowserShow = false; 657 return true; 658 } 659 660 private onPickerControllerReady(): void { 661 // 接收到该回调后，便可通过pickerController相关接口向picker发送数据，在此之前不生效。 662 let elements: number[] = [PhotoBrowserUIElement.BACK_BUTTON]; 663 this.pickerController.setPhotoBrowserUIElementVisibility(elements, false); // 设置大图页不显示返回按钮。 664 } 665 666 private onPhotoBrowserChanged(browserItemInfo: BaseItemInfo): boolean { 667 // 大图左右滑动的回调。 668 this.currentUri = browserItemInfo.uri ?? ''; 669 return true; 670 } 671 672 private onSelectedItemsDeleted(baseItemInfos: Array<BaseItemInfo>): void { 673 // 已勾选图片被删除时的回调。 674 } 675 676 private onExceedMaxSelected(exceedMaxCountType: MaxCountType): void { 677 // 超过最大选择数量再次点击时的回调。 678 } 679 680 private onCurrentAlbumDeleted(): void { 681 // 当前相册被删除时的回调。 682 } 683 684 private videoPlayStateChanged(state: VideoPlayerState): void { 685 // 当视频播放状态变化时回调。 686 } 687 build() { 688 Flex({ 689 direction: FlexDirection.Column, 690 justifyContent: FlexAlign.Center, 691 alignItems: ItemAlign.Center 692 }) { 693 Column() { 694 if (this.isBrowserShow) { 695 // 这里模拟应用自己的大图返回按钮。 696 Row() { 697 Button("退出大图").width('33%').height('8%').onClick(() => { 698 this.pickerController.exitPhotoBrowser(); 699 }) 700 }.margin({ bottom: 20 }) 701 } 702 703 PhotoPickerComponent({ 704 pickerOptions: this.pickerOptions, 705 // onSelect: (uri: string): void => this.onSelect(uri), 706 // onDeselect: (uri: string): void => this.onDeselect(uri), 707 onItemClicked: (itemInfo: ItemInfo, clickType: ClickType): boolean => this.onItemClicked(itemInfo, 708 clickType), // 该接口可替代上面两个接口。 709 onEnterPhotoBrowser: (photoBrowserInfo: PhotoBrowserInfo): boolean => this.onEnterPhotoBrowser(photoBrowserInfo), 710 onExitPhotoBrowser: (photoBrowserInfo: PhotoBrowserInfo): boolean => this.onExitPhotoBrowser(photoBrowserInfo), 711 onPickerControllerReady: (): void => this.onPickerControllerReady(), 712 onPhotoBrowserChanged: (browserItemInfo: BaseItemInfo): boolean => this.onPhotoBrowserChanged(browserItemInfo), 713 onSelectedItemsDeleted: this.selectedItemsDeletedCallback, 714 onExceedMaxSelected: this.exceedMaxSelectedCallback, 715 onCurrentAlbumDeleted: this.currentAlbumDeletedCallback, 716 onVideoPlayStateChanged: this.videoPlayStateChangedCallback, 717 pickerController: this.pickerController, 718 }).height('60%').width('100%') 719 720 // 这里模拟应用侧底部的选择栏。 721 if (this.isBrowserShow) { 722 Row() { 723 ForEach(this.assets, async (asset: photoAccessHelper.PhotoAsset, index) => { 724 if (asset.uri === this.currentUri) { 725 Image(this.thumbnail[index]) 726 .height('10%') 727 .width('10%') 728 .onClick(() => { 729 }) 730 .borderWidth(1) 731 .borderColor('red') 732 } else { 733 Image(this.thumbnail[index]).height('10%').width('10%').onClick(() => { 734 this.pickerController.setData(DataType.SET_SELECTED_URIS, this.selectUris); 735 this.pickerController.setPhotoBrowserItem(asset.uri, PhotoBrowserRange.ALL); 736 }) 737 } 738 }, (uri: string) => JSON.stringify(uri)) 739 } 740 } else { 741 Button('预览').width('33%').height('5%').onClick(async () => { 742 if (this.selectUris.length > 0) { 743 this.thumbnail = []; 744 this.assets = []; 745 for (let selectUri of this.selectUris) { 746 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 747 predicates.equalTo(photoAccessHelper.PhotoKeys.URI, selectUri); 748 let fetchOptions: photoAccessHelper.FetchOptions = { 749 fetchColumns: [], 750 predicates: predicates 751 }; 752 let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 753 let photoHelper = photoAccessHelper.getPhotoAccessHelper(context); 754 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = 755 await photoHelper.getAssets(fetchOptions); 756 let asset = await fetchResult.getFirstObject() 757 this.assets.push(asset); 758 this.thumbnail.push(await asset.getThumbnail()) 759 } 760 this.pickerController.setPhotoBrowserItem(this.selectUris[0], PhotoBrowserRange.SELECTED_ONLY); 761 } 762 }) 763 } 764 } 765 } 766 } 767} 768``` 769