1# @ohos.file.sendablePhotoAccessHelper (相册管理模块)(系统接口) 2 3该模块基于Sendable对象，提供相册管理模块能力，包括创建相册以及访问、修改相册中的媒体数据信息等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.file.sendablePhotoAccessHelper (基于Sendable对象的相册管理模块)](js-apis-sendablePhotoAccessHelper.md)。 9 10## 导入模块 11 12```ts 13import { sendablePhotoAccessHelper } from '@kit.MediaLibraryKit'; 14``` 15 16## PhotoAccessHelper 17 18### createAsset 19 20createAsset(displayName: string): Promise<PhotoAsset> 21 22指定待创建的图片或者视频的文件名，创建图片或视频资源，使用Promise方式返回结果。 23 24待创建的文件名参数规格为： 25- 应包含有效文件主名和图片或视频扩展名。 26- 文件名字符串长度为1~255。 27- 文件主名中不允许出现的非法英文字符，包括：<br> . .. \ / : * ? " ' ` < > | { } [ ] 28 29**系统接口**：此接口为系统接口。 30 31**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 32 33**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| ----------- | ------ | ---- | -------------------------- | 39| displayName | string | 是 | 创建的图片或者视频文件名。 | 40 41**返回值：** 42 43| 类型 | 说明 | 44| ---------------------------------------- | --------------------------------------- | 45| Promise<[PhotoAsset](#photoasset)> | Promise对象，返回创建的图片和视频结果。 | 46 47**错误码：** 48 49接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 50 51| 错误码ID | 错误信息 | 52| -------- | ------------------------------------------------------------ | 53| 202 | Called by non-system application. | 54| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 55| 201 | Permission denied. | 56| 13900020 | Invalid argument. | 57| 14000001 | Invalid display name. | 58| 14000011 | Internal system error | 59 60**示例：** 61 62```ts 63async function example() { 64 console.info('createAssetDemo'); 65 try { 66 let testFileName: string = 'testFile' + Date.now() + '.jpg'; 67 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName); 68 console.info('createAsset file displayName' + photoAsset.displayName); 69 console.info('createAsset successfully'); 70 } catch (err) { 71 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 72 } 73} 74``` 75 76### createAsset 77 78createAsset(displayName: string, options: PhotoCreateOptions): Promise<PhotoAsset> 79 80指定待创建的图片或者视频的文件名和创建选项，创建图片或视频资源，使用Promise方式返回结果。 81 82待创建的文件名参数规格为： 83- 应包含有效文件主名和图片或视频扩展名。 84- 文件名字符串长度为1~255。 85- 文件主名中不允许出现的非法英文字符，包括：<br> . .. \ / : * ? " ' ` < > | { } [ ] 86 87**系统接口**：此接口为系统接口。 88 89**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 90 91**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| ----------- | ------------------------------------------------------------ | ---- | -------------------------- | 97| displayName | string | 是 | 创建的图片或者视频文件名。 | 98| options | [PhotoCreateOptions](js-apis-photoAccessHelper-sys.md#photocreateoptions) | 是 | 图片或视频的创建选项。 | 99 100**返回值：** 101 102| 类型 | 说明 | 103| ---------------------------------------- | --------------------------------------- | 104| Promise<[PhotoAsset](#photoasset)> | Promise对象，返回创建的图片和视频结果。 | 105 106**错误码：** 107 108接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 109 110| 错误码ID | 错误信息 | 111| -------- | ------------------------------------------------------------ | 112| 202 | Called by non-system application. | 113| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 114| 201 | Permission denied. | 115| 13900020 | Invalid argument. | 116| 14000001 | Invalid display name. | 117| 14000011 | Internal system error | 118 119**示例：** 120 121```ts 122async function example() { 123 console.info('createAssetDemo'); 124 try { 125 let testFileName:string = 'testFile' + Date.now() + '.jpg'; 126 let createOption: photoAccessHelper.PhotoCreateOptions = { 127 subtype: photoAccessHelper.PhotoSubtype.DEFAULT 128 } 129 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName, createOption); 130 console.info('createAsset file displayName' + photoAsset.displayName); 131 console.info('createAsset successfully'); 132 } catch (err) { 133 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 134 } 135} 136``` 137 138### getHiddenAlbums 139 140getHiddenAlbums(mode: HiddenPhotosDisplayMode, options?: FetchOptions): Promise<FetchResult<Album>> 141 142根据隐藏文件显示模式和检索选项获取系统中的隐藏相册，使用Promise方式返回结果。 143 144**系统接口**：此接口为系统接口。 145 146**需要权限**：ohos.permission.READ_IMAGEVIDEO 和 ohos.permission.MANAGE_PRIVATE_PHOTOS 147 148**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ------- | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 154| mode | [HiddenPhotosDisplayMode](js-apis-photoAccessHelper-sys.md#hiddenphotosdisplaymode11) | 是 | 隐藏文件显示模式 | 155| options | [FetchOptions](js-apis-photoAccessHelper.md#fetchoptions) | 否 | 检索选项，不填时默认根据隐藏文件显示模式检索。 | 156 157**返回值：** 158 159| 类型 | 说明 | 160| ------------------------------------------------------------ | ----------------------------------- | 161| Promise<[FetchResult](js-apis-photoAccessHelper.md#fetchresult)<[Album](#album)>> | Promise对象，返回获取相册的结果集。 | 162 163**错误码：** 164 165接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 166 167| 错误码ID | 错误信息 | 168| -------- | ------------------------------------------------------------ | 169| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 170| 202 | Permission verification failed, application which is not a system application uses system API. | 171| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 172| 14000011 | Internal system error | 173 174**示例：** 175 176```ts 177import { dataSharePredicates } from '@kit.ArkData'; 178import { BusinessError } from '@kit.BasicServicesKit'; 179 180// 获取系统预置的隐藏相册 181async function getSysHiddenAlbum() { 182 console.info('getSysHiddenAlbumDemo'); 183 phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ASSETS_MODE) 184 .then( async (fetchResult) => { 185 if (fetchResult === undefined) { 186 console.error('getSysHiddenAlbumPromise fetchResult is undefined'); 187 return; 188 } 189 let hiddenAlbum: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 190 console.info('getAlbumsPromise successfully, albumUri: ' + hiddenAlbum.albumUri); 191 fetchResult.close(); 192 }).catch((err: BusinessError) => { 193 console.error(`getSysHiddenAlbumPromise failed with err: ${err.code}, ${err.message}`); 194 }); 195} 196 197// 获取隐藏相册-相册视图，即系统中包含隐藏文件的相册（不包含系统预置的隐藏相册本身和回收站相册） 198async function getHiddenAlbumsView() { 199 console.info('getHiddenAlbumsViewDemo'); 200 phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ALBUMS_MODE).then( async (fetchResult) => { 201 if (fetchResult === undefined) { 202 console.error('getHiddenAlbumsViewPromise fetchResult is undefined'); 203 return; 204 } 205 let albums: Array<sendablePhotoAccessHelper.Album> = await fetchResult.getAllObjects(); 206 console.info('getHiddenAlbumsViewPromise successfully, albums size: ' + albums.length); 207 208 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 209 let fetchOption: photoAccessHelper.FetchOptions = { 210 fetchColumns: [], 211 predicates: predicates 212 }; 213 for (let i = 0; i < albums.length; i++) { 214 // 获取相册中的隐藏文件 215 albums[i].getAssets(fetchOption).then((assetFetchResult) => { 216 console.info('album get hidden assets successfully, getCount: ' + assetFetchResult.getCount()); 217 }).catch((err: BusinessError) => { 218 console.error(`album get hidden assets failed with error: ${err.code}, ${err.message}`); 219 }); 220 } 221 fetchResult.close(); 222 }).catch((err: BusinessError) => { 223 console.error(`getHiddenAlbumsViewPromise failed with err: ${err.code}, ${err.message}`); 224 }); 225} 226``` 227 228## PhotoAsset 229 230提供封装文件属性的方法。 231 232### requestSource 233 234requestSource(): Promise<number> 235 236打开源文件并返回fd，该方法使用Promise形式来返回结果。 237 238**系统接口**：此接口为系统接口。 239 240**需要权限**：ohos.permission.READ_IMAGEVIDEO 241 242**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 243 244**返回值：** 245 246| 类型 | 说明 | 247| --------------------- | --------------------------- | 248| Promise<number> | Promise对象，返回源文件fd。 | 249 250**错误码：** 251 252接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 253 254| 错误码ID | 错误信息 | 255| -------- | ------------------------------------------------------------ | 256| 201 | Permission denied. | 257| 202 | Called by non-system application. | 258| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 259| 14000011 | Internal system error | 260 261**示例：** 262 263```ts 264import { dataSharePredicates } from '@kit.ArkData'; 265 266async function example() { 267 try { 268 console.info('requsetSourcePromiseDemo') 269 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 270 let fetchOptions: photoAccessHelper.FetchOptions = { 271 fetchColumns: [], 272 predicates: predicates 273 }; 274 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 275 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 276 let fd = await photoAsset.requestSource(); 277 console.info('Source fd is ' + fd); 278 } catch (err) { 279 console.error(`requsetSourcePromiseDemo failed with error: ${err.code}, ${err.message}`); 280 } 281} 282``` 283 284### getAnalysisData 285 286getAnalysisData(analysisType: AnalysisType): Promise\<string> 287 288根据智慧分析类型获取指定分析结果数据。 289 290**系统接口**：此接口为系统接口。 291 292**需要权限**：ohos.permission.READ\_IMAGEVIDEO 293 294**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| :----------- | :----------------------------------------------------------- | :--- | :----------------------- | 300| analysisType | [AnalysisType](js-apis-photoAccessHelper-sys.md#analysistype11) | 是 | 需要获取的智慧分析类型。 | 301 302**返回值：** 303 304| 类型 | 说明 | 305| :------------------ | :---------------------------------- | 306| Promise<void> | Promise对象，返回指定分析数据结果。 | 307 308**错误码：** 309 310接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 311 312| 错误码ID | 错误信息 | 313| :------- | :----------------------------------------------------------- | 314| 201 | Permission denied. | 315| 202 | Called by non-system application. | 316| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 317| 14000011 | Internal system error | 318 319**示例：** 320 321```ts 322import { dataSharePredicates } from '@kit.ArkData'; 323 324async function example() { 325 try { 326 console.info('getAnalysisDataDemo') 327 let fetchOptions: photoAccessHelper.FetchOptions = { 328 fetchColumns: [], 329 predicates: new dataSharePredicates.DataSharePredicates() 330 } 331 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = 332 await phAccessHelper.getAssets(fetchOptions); 333 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 334 if (photoAsset != undefined) { 335 let analysisData: string = await photoAsset.getAnalysisData( 336 photoAccessHelper.AnalysisType.ANALYSIS_OCR); 337 console.info('get ocr result: ' + JSON.stringify(analysisData)); 338 } 339 fetchResult.close(); 340 } catch (err) { 341 console.error(`getAnalysisDataDemofailed with error: ${err.code}, ${err.message}`); 342 } 343} 344``` 345 346### getFaceId<sup>13+</sup> 347 348getFaceId(): Promise\<string> 349 350获取人像相册或合影相册的封面人脸标识。 351 352**系统接口**：此接口为系统接口。 353 354**需要权限**：ohos.permission.READ\_IMAGEVIDEO 355 356**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 357 358**返回值：** 359 360| 类型 | 说明 | 361| :------------------ | :---------------------------------- | 362| Promise<string> | Promise对象，人像相册返回tag_id，合影相册返回group_tag，未找到返回空字符串。 | 363 364**错误码：** 365 366接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 367 368| 错误码ID | 错误信息 | 369| :------- | :----------------------------------------------------------- | 370| 201 | Permission denied. | 371| 202 | Called by non-system application. | 372| 14000011 | Internal system error | 373 374**示例：** 375 376```ts 377import { dataSharePredicates } from '@kit.ArkData'; 378 379async function example() { 380 try { 381 console.info('getFaceIdDemo'); 382 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 383 predicates.equalTo("user_display_level", 1); 384 let fetchOptions: photoAccessHelper.FetchOptions = { 385 fetchColumns: [], 386 predicates: predicates 387 }; 388 let fetchResult = 389 await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.SMART, 390 sendablePhotoAccessHelper.AlbumSubtype.PORTRAIT, 391 fetchOptions); 392 let album = await fetchResult?.getFirstObject(); 393 let faceId = await album?.getFaceId(); 394 console.info(`getFaceId successfully, faceId: ${faceId}`); 395 fetchResult.close(); 396 } catch (err) { 397 console.error(`getFaceId failed with err: ${err.code}, ${err.message}`); 398 } 399} 400``` 401 402## Album 403 404实体相册 405 406## AlbumType 407 408枚举，相册类型，表示是用户相册还是系统预置相册。 409 410**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 411 412| 名称 | 值 | 说明 | 413| ----- | ---- | ---------------------------------------------- | 414| SMART | 4096 | 智慧分析相册。**系统接口**：此接口为系统接口。 | 415 416## AlbumSubtype 417 418枚举，相册子类型，表示具体的相册类型。 419 420**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 421 422| 名称 | 值 | 说明 | 423| --------------------- | ---- | ---------------------------------------------------------- | 424| HIDDEN | 1027 | 隐藏相册。**系统接口**：此接口为系统接口。 | 425| TRASH | 1028 | 回收站。**系统接口**：此接口为系统接口。 | 426| SCREENSHOT | 1029 | 截屏和录屏相册。**系统接口**：此接口为系统接口。 | 427| CAMERA | 1030 | 相机拍摄的照片和视频相册。**系统接口**：此接口为系统接口。 | 428| SOURCE\_GENERIC | 2049 | 来源相册。**系统接口**：此接口为系统接口。 | 429| CLASSIFY | 4097 | 分类相册。**系统接口**：此接口为系统接口。 | 430| GEOGRAPHY\_LOCATION | 4099 | 地图相册。**系统接口**：此接口为系统接口。 | 431| GEOGRAPHY\_CITY | 4100 | 城市相册。**系统接口**：此接口为系统接口。 | 432| SHOOTING\_MODE | 4101 | 拍摄模式相册。**系统接口**：此接口为系统接口。 | 433| PORTRAIT | 4102 | 人像相册。**系统接口**：此接口为系统接口。 | 434| GROUP_PHOTO | 4103 | 合影相册。**系统接口**：此接口为系统接口。 | 435| HIGHLIGHT | 4104 | 时刻相册。**系统接口**：此接口为系统接口。 | 436| HIGHLIGHT_SUGGESTIONS | 4105 | 时刻建议相册。**系统接口**：此接口为系统接口。 | 437