• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.file.AlbumPickerComponent (AlbumPickerComponent)
2
3The AlbumPickerComponent embedded in the UI of an application allows the application to access the albums in the user directory without any permission.
4
5This component must be used together with [PhotoPickerComponent](ohos-file-PhotoPickerComponent.md). When a user selects an album by using **AlbumPickerComponent**, **PhotoPickerComponent** is instructed to update the photos and videos in the album.
6
7> **NOTE**
8>
9> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.
10
11## Modules to Import
12
13```ts
14import { AlbumPickerComponent, AlbumPickerOptions, AlbumInfo, photoAccessHelper, EmptyAreaClickCallback } from '@kit.MediaLibraryKit';
15```
16
17## Properties
18
19The [universal properties](../apis-arkui/arkui-ts/ts-component-general-attributes.md) are supported.
20
21## AlbumPickerComponent
22
23AlbumPickerComponent({
24  albumPickerOptions?: AlbumPickerOptions,
25  onAlbumClick?: (albumInfo: AlbumInfo) => boolean,
26  onEmptyAreaClick?: EmptyAreaClickCallback
27})
28
29Allows the application to access the albums in the user directory without any permission.
30
31**Decorator**: @Component
32
33**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core
34
35**Parameters**
36
37| Name                | Type                                                 | Mandatory | Description                             |
38|--------------------|-----------------------------------------------------|-----|---------------------------------|
39| albumPickerOptions | [AlbumPickerOptions](#albumpickeroptions)           | No  | **AlbumPicker** configuration.<br>**Atomic service API**: This API can be used in atomic services since API version 12.             |
40| onAlbumClick       | (albumInfo: [AlbumInfo](#albuminfo)) => boolean     | No  | Callback used to return the album URI when an album is selected by a user.<br>**Atomic service API**: This API can be used in atomic services since API version 12.   |
41| onEmptyAreaClick<sup>13+</sup>   | [EmptyAreaClickCallback](#emptyareaclickcallback13) | No  | Callback to be invoked when the blank area of **AlbumPickerComponent** is tapped, which is used to notify the application of the tap.<br>**Atomic service API**: This API can be used in atomic services since API version 13.|
42
43## AlbumPickerOptions
44
45Represents the **AlbumPicker** configuration.
46
47**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core
48
49| Name            | Type | Mandatory | Description                                                         |
50|----------------|-------|-----|-------------------------------------------------------------|
51| themeColorMode | [PickerColorMode](ohos-file-PhotoPickerComponent.md#pickercolormode) | No  | Theme color of the album page. The options are **AUTO**, **Light**, and **Dark**. The default value is **AUTO**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.                        |
52| filterType<sup>13+</sup>     | [photoAccessHelper.PhotoViewMIMETypes](js-apis-photoAccessHelper.md#photoviewmimetypes) | No  | Type of the filter. You can use it to display images, videos, or both. If this parameter is not specified, images and videos are displayed in a specific album.<br>**Atomic service API**: This API can be used in atomic services since API version 13.|
53
54## EmptyAreaClickCallback<sup>13+</sup>
55
56type EmptyAreaClickCallback = () => void
57
58Called when the blank area of the **AlbumPickerComponent** component is tapped.
59
60**Atomic service API**: This API can be used in atomic services since API version 13.
61
62**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core
63
64## AlbumInfo
65
66Represents album information.
67
68**Atomic service API**: This API can be used in atomic services since API version 12.
69
70**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core
71
72| Name | Type | Mandatory | Description   |
73|------|------|-----|---------|
74| uri  | string | No  | Album URI.|
75| albumName  | string | No  | Album name.|
76
77## Example
78
79```ts
80// xxx.ets
81import { AlbumPickerComponent, AlbumPickerOptions, AlbumInfo, PickerColorMode, photoAccessHelper, EmptyAreaClickCallback } from '@kit.MediaLibraryKit';
82
83@Entry
84@Component
85struct PickerDemo {
86  albumPickerOptions: AlbumPickerOptions = new AlbumPickerOptions();
87  private emptyAreaClickCallback: EmptyAreaClickCallback = (): void => this.onEmptyAreaClick();
88
89  aboutToAppear() {
90    this.albumPickerOptions.themeColorMode = PickerColorMode.AUTO;
91    this.albumPickerOptions.filterType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE;
92  }
93
94  private onAlbumClick(albumInfo: AlbumInfo): boolean {
95    if (albumInfo?.uri) {
96      // pickerController instructs PhotoPickerComponent to refresh data.
97    }
98    if (albumInfo?.albumName) {
99      // Perform subsequent processing based on the obtained albumName.
100    }
101    return true;
102  }
103
104  private onEmptyAreaClick(): void {
105    // Callback when the blank area of the component is tapped.
106  }
107
108  build() {
109    Stack() {
110      AlbumPickerComponent({
111        albumPickerOptions: this.albumPickerOptions,
112        onAlbumClick:(albumInfo: AlbumInfo): boolean => this.onAlbumClick(albumInfo),
113        onEmptyAreaClick: this.emptyAreaClickCallback,
114      }).height('100%').width('100%')
115    }
116  }
117}
118