1# @ohos.file.photoAccessHelper (相册管理模块) 2 3该模块提供相册管理模块能力，包括创建相册以及访问、修改相册中的媒体数据信息等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import photoAccessHelper from '@ohos.file.photoAccessHelper'; 13``` 14 15## photoAccessHelper.getPhotoAccessHelper 16 17getPhotoAccessHelper(context: Context): PhotoAccessHelper 18 19获取相册管理模块的实例，用于访问和修改相册中的媒体文件。 20 21**模型约束**： 此接口仅可在Stage模型下使用。 22 23**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ------- | ---- | -------------------------- | 29| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| ----------------------------- | :---- | 35| [PhotoAccessHelper](#photoaccesshelper) | 相册管理模块的实例。 | 36 37**错误码：** 38 39接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 40 41| 错误码ID | 错误信息 | 42| -------- | ---------------------------------------- | 43| 401 | if parameter is invalid. | 44 45**示例：** 46 47```ts 48//此处获取的phAccessHelper实例为全局对象，后续使用到phAccessHelper的地方默认为使用此处获取的对象，如未添加此段代码报phAccessHelper未定义的错误请自行添加 49let context = getContext(this); 50let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context); 51``` 52 53## PhotoAccessHelper 54 55### getAssets 56 57getAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<PhotoAsset>>): void 58 59获取图片和视频资源，使用callback方式返回结果。 60 61**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 62 63**需要权限**：ohos.permission.READ_IMAGEVIDEO 64 65**参数：** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| -------- | ------------------------ | ---- | ------------------------- | 69| options | [FetchOptions](#fetchoptions) | 是 | 图片和视频检索选项。 | 70| callback | AsyncCallback<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | 是 | callback返回图片和视频检索结果集。 | 71 72**错误码：** 73 74接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 75 76| 错误码ID | 错误信息 | 77| -------- | ---------------------------------------- | 78| 401 | if parameter is invalid. | 79| 13900012 | Permission denied. | 80| 13900020 | Invalid argument. | 81| 14000011 | System inner fail. | 82 83**示例：** 84 85```ts 86import dataSharePredicates from '@ohos.data.dataSharePredicates'; 87 88async function example() { 89 console.info('getAssets'); 90 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 91 let fetchOptions: photoAccessHelper.FetchOptions = { 92 fetchColumns: [], 93 predicates: predicates 94 }; 95 96 phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => { 97 if (fetchResult !== undefined) { 98 console.info('fetchResult success'); 99 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 100 if (photoAsset !== undefined) { 101 console.info('photoAsset.displayName : ' + photoAsset.displayName); 102 } 103 } else { 104 console.error(`fetchResult fail with error: ${err.code}, ${err.message}`); 105 } 106 }); 107} 108``` 109 110### getAssets 111 112getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>> 113 114获取图片和视频资源，使用Promise方式返回结果。 115 116**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 117 118**需要权限**：ohos.permission.READ_IMAGEVIDEO 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| ------- | ------------------- | ---- | ---------------- | 124| options | [FetchOptions](#fetchoptions) | 是 | 图片和视频检索选项。 | 125 126**返回值：** 127 128| 类型 | 说明 | 129| --------------------------- | -------------- | 130| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise对象，返回图片和视频数据结果集。 | 131 132**错误码：** 133 134接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 135 136| 错误码ID | 错误信息 | 137| -------- | ---------------------------------------- | 138| 401 | if parameter is invalid. | 139| 13900012 | Permission denied. | 140| 13900020 | Invalid argument. | 141| 14000011 | System inner fail. | 142 143**示例：** 144 145```ts 146import dataSharePredicates from '@ohos.data.dataSharePredicates'; 147 148async function example() { 149 console.info('getAssets'); 150 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 151 let fetchOptions: photoAccessHelper.FetchOptions = { 152 fetchColumns: [], 153 predicates: predicates 154 }; 155 try { 156 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 157 if (fetchResult !== undefined) { 158 console.info('fetchResult success'); 159 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 160 if (photoAsset !== undefined) { 161 console.info('photoAsset.displayName :' + photoAsset.displayName); 162 } 163 } 164 } catch (err) { 165 console.error(`getAssets failed, error: ${err.code}, ${err.message}`); 166 } 167} 168``` 169 170### createAsset 171 172createAsset(photoType: PhotoType, extension: string, options: CreateOptions, callback: AsyncCallback<string>): void 173 174指定待创建的文件类型、后缀和创建选项，创建图片或视频资源，使用callback方式返回结果。 175 176此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考[开发指南](../../media/medialibrary/photoAccessHelper-resource-guidelines.md#使用安全控件创建媒体资源)。 177 178**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 179 180**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| -------- | ------------------------ | ---- | ------------------------- | 186| photoType | [PhotoType](#phototype) | 是 | 创建的文件类型，IMAGE或者VIDEO类型。 | 187| extension | string | 是 | 文件名后缀参数，例如：'jpg'。 | 188| options | [CreateOptions](#createoptions) | 是 | 创建选项，例如{title: 'testPhoto'}。 | 189| callback | AsyncCallback<string> | 是 | callback返回创建的图片和视频的uri。 | 190 191**错误码：** 192 193接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 194 195| 错误码ID | 错误信息 | 196| -------- | ---------------------------------------- | 197| 401 | if parameter is invalid. | 198| 13900012 | Permission denied. | 199| 13900020 | Invalid argument. | 200| 14000011 | System inner fail. | 201 202**示例：** 203 204```ts 205async function example() { 206 console.info('createAssetDemo'); 207 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 208 let extension:string = 'jpg'; 209 let options: photoAccessHelper.CreateOptions = { 210 title: 'testPhoto' 211 } 212 phAccessHelper.createAsset(photoType, extension, options, (err, uri) => { 213 if (uri !== undefined) { 214 console.info('createAsset uri' + uri); 215 console.info('createAsset successfully'); 216 } else { 217 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 218 } 219 }); 220} 221``` 222 223### createAsset 224 225createAsset(photoType: PhotoType, extension: string, callback: AsyncCallback<string>): void 226 227指定待创建的文件类型和后缀，创建图片或视频资源，使用callback方式返回结果。 228 229此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考[开发指南](../../media/medialibrary/photoAccessHelper-resource-guidelines.md#使用安全控件创建媒体资源)。 230 231**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 232 233**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| -------- | ------------------------ | ---- | ------------------------- | 239| photoType | [PhotoType](#phototype) | 是 | 创建的文件类型，IMAGE或者VIDEO类型。 | 240| extension | string | 是 | 文件名后缀参数，例如：'jpg'。 | 241| callback | AsyncCallback<string> | 是 | callback返回创建的图片和视频的uri。 | 242 243**错误码：** 244 245接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 246 247| 错误码ID | 错误信息 | 248| -------- | ---------------------------------------- | 249| 401 | if parameter is invalid. | 250| 13900012 | Permission denied. | 251| 13900020 | Invalid argument. | 252| 14000011 | System inner fail. | 253 254**示例：** 255 256```ts 257async function example() { 258 console.info('createAssetDemo'); 259 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 260 let extension: string = 'jpg'; 261 phAccessHelper.createAsset(photoType, extension, (err, uri) => { 262 if (uri !== undefined) { 263 console.info('createAsset uri' + uri); 264 console.info('createAsset successfully'); 265 } else { 266 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 267 } 268 }); 269} 270``` 271 272### createAsset 273 274createAsset(photoType: PhotoType, extension: string, options?: CreateOptions): Promise<string> 275 276指定待创建的文件类型、后缀和创建选项，创建图片或视频资源，使用Promise方式返回结果。 277 278此接口在未申请相册管理模块权限'ohos.permission.WRITE_IMAGEVIDEO'时，可以使用安全控件创建媒体资源，详情请参考[开发指南](../../media/medialibrary/photoAccessHelper-resource-guidelines.md#使用安全控件创建媒体资源)。 279 280**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 281 282**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| -------- | ------------------------ | ---- | ------------------------- | 288| photoType | [PhotoType](#phototype) | 是 | 创建的文件类型，IMAGE或者VIDEO类型。 | 289| extension | string | 是 | 文件名后缀参数，例如：'jpg'。 | 290| options | [CreateOptions](#createoptions) | 否 | 创建选项，例如{title: 'testPhoto'}。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| --------------------------- | -------------- | 296| Promise<string> | Promise对象，返回创建的图片和视频的uri。 | 297 298**错误码：** 299 300接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 301 302| 错误码ID | 错误信息 | 303| -------- | ---------------------------------------- | 304| 401 | if parameter is invalid. | 305| 13900012 | Permission denied. | 306| 13900020 | Invalid argument. | 307| 14000011 | System inner fail. | 308 309**示例：** 310 311```ts 312async function example() { 313 console.info('createAssetDemo'); 314 try { 315 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 316 let extension: string = 'jpg'; 317 let options: photoAccessHelper.CreateOptions = { 318 title: 'testPhoto' 319 } 320 let uri: string = await phAccessHelper.createAsset(photoType, extension, options); 321 console.info('createAsset uri' + uri); 322 console.info('createAsset successfully'); 323 } catch (err) { 324 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 325 } 326} 327``` 328 329### getAlbums 330 331getAlbums(type: AlbumType, subtype: AlbumSubtype, options: FetchOptions, callback: AsyncCallback<FetchResult<Album>>): void 332 333根据检索选项和相册类型获取相册，使用callback方式返回结果。 334 335获取相册前需先保证相册存在。 336 337**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 338 339**需要权限**：ohos.permission.READ_IMAGEVIDEO 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| -------- | ------------------------ | ---- | ------------------------- | 345| type | [AlbumType](#albumtype) | 是 | 相册类型。 | 346| subtype | [AlbumSubtype](#albumsubtype) | 是 | 相册子类型。 | 347| options | [FetchOptions](#fetchoptions) | 是 | 检索选项。 | 348| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | 是 | callback返回获取相册的结果集。 | 349 350**错误码：** 351 352接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 353 354| 错误码ID | 错误信息 | 355| -------- | ---------------------------------------- | 356| 401 | if parameter is invalid. | 357| 13900012 | Permission denied. | 358| 13900020 | Invalid argument. | 359| 14000011 | System inner fail. | 360 361**示例：** 362 363```ts 364import dataSharePredicates from '@ohos.data.dataSharePredicates'; 365 366async function example() { 367 // 示例代码中为获取相册名为newAlbumName的相册。 368 console.info('getAlbumsDemo'); 369 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 370 predicates.equalTo('album_name', 'newAlbumName'); 371 let fetchOptions: photoAccessHelper.FetchOptions = { 372 fetchColumns: [], 373 predicates: predicates 374 }; 375 phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions, async (err, fetchResult) => { 376 if (err) { 377 console.error(`getAlbumsCallback failed with err: ${err.code}, ${err.message}`); 378 return; 379 } 380 if (fetchResult === undefined) { 381 console.error('getAlbumsCallback fetchResult is undefined'); 382 return; 383 } 384 let album = await fetchResult.getFirstObject(); 385 console.info('getAlbumsCallback successfully, albumName: ' + album.albumName); 386 fetchResult.close(); 387 }); 388} 389``` 390 391### getAlbums 392 393getAlbums(type: AlbumType, subtype: AlbumSubtype, callback: AsyncCallback<FetchResult<Album>>): void 394 395根据相册类型获取相册，使用callback方式返回结果。 396 397获取相册前需先保证相册存在。 398 399**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 400 401**需要权限**：ohos.permission.READ_IMAGEVIDEO 402 403**参数：** 404 405| 参数名 | 类型 | 必填 | 说明 | 406| -------- | ------------------------ | ---- | ------------------------- | 407| type | [AlbumType](#albumtype) | 是 | 相册类型。 | 408| subtype | [AlbumSubtype](#albumsubtype) | 是 | 相册子类型。 | 409| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | 是 | callback返回获取相册的结果集。 | 410 411**错误码：** 412 413接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 414 415| 错误码ID | 错误信息 | 416| -------- | ---------------------------------------- | 417| 401 | if parameter is invalid. | 418| 13900012 | Permission denied. | 419| 13900020 | Invalid argument. | 420| 14000011 | System inner fail. | 421 422**示例：** 423 424```ts 425async function example() { 426 // 示例代码中为获取统相册VIDEO，默认已预置。 427 console.info('getAlbumsDemo'); 428 phAccessHelper.getAlbums(photoAccessHelper.AlbumType.SYSTEM, photoAccessHelper.AlbumSubtype.VIDEO, async (err, fetchResult) => { 429 if (err) { 430 console.error(`getAlbumsCallback failed with err: ${err.code}, ${err.message}`); 431 return; 432 } 433 if (fetchResult === undefined) { 434 console.error('getAlbumsCallback fetchResult is undefined'); 435 return; 436 } 437 let album: photoAccessHelper.Album = await fetchResult.getFirstObject(); 438 console.info('getAlbumsCallback successfully, albumUri: ' + album.albumUri); 439 fetchResult.close(); 440 }); 441} 442``` 443 444### getAlbums 445 446getAlbums(type: AlbumType, subtype: AlbumSubtype, options?: FetchOptions): Promise<FetchResult<Album>> 447 448根据检索选项和相册类型获取相册，使用Promise方式返回结果。 449 450获取相册前需先保证相册存在。 451 452**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 453 454**需要权限**：ohos.permission.READ_IMAGEVIDEO 455 456**参数：** 457 458| 参数名 | 类型 | 必填 | 说明 | 459| -------- | ------------------------ | ---- | ------------------------- | 460| type | [AlbumType](#albumtype) | 是 | 相册类型。 | 461| subtype | [AlbumSubtype](#albumsubtype) | 是 | 相册子类型。 | 462| options | [FetchOptions](#fetchoptions) | 否 | 检索选项，不填时默认根据相册类型检索。 | 463 464**返回值：** 465 466| 类型 | 说明 | 467| --------------------------- | -------------- | 468| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise对象，返回获取相册的结果集。 | 469 470**错误码：** 471 472接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 473 474| 错误码ID | 错误信息 | 475| -------- | ---------------------------------------- | 476| 401 | if parameter is invalid. | 477| 13900012 | Permission denied. | 478| 13900020 | Invalid argument. | 479| 14000011 | System inner fail. | 480 481**示例：** 482 483```ts 484import dataSharePredicates from '@ohos.data.dataSharePredicates'; 485import { BusinessError } from '@ohos.base'; 486 487async function example() { 488 // 示例代码中为获取相册名为newAlbumName的相册。 489 console.info('getAlbumsDemo'); 490 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 491 predicates.equalTo('album_name', 'newAlbumName'); 492 let fetchOptions: photoAccessHelper.FetchOptions = { 493 fetchColumns: [], 494 predicates: predicates 495 }; 496 phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions).then( async (fetchResult) => { 497 if (fetchResult === undefined) { 498 console.error('getAlbumsPromise fetchResult is undefined'); 499 return; 500 } 501 let album: photoAccessHelper.Album = await fetchResult.getFirstObject(); 502 console.info('getAlbumsPromise successfully, albumName: ' + album.albumName); 503 fetchResult.close(); 504 }).catch((err: BusinessError) => { 505 console.error(`getAlbumsPromise failed with err: ${err.code}, ${err.message}`); 506 }); 507} 508``` 509 510### registerChange 511 512registerChange(uri: string, forChildUris: boolean, callback: Callback<ChangeData>) : void 513 514注册对指定uri的监听，使用callback方式返回异步结果。 515 516**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 517 518**参数：** 519 520| 参数名 | 类型 | 必填 | 说明 | 521| --------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 522| uri | string | 是 | PhotoAsset的uri, Album的uri或[DefaultChangeUri](#defaultchangeuri)的值。 | 523| forChildUris | boolean | 是 | 是否模糊监听，uri为相册uri时，forChildUris为true能监听到相册中文件的变化，如果是false只能监听相册本身变化。uri为photoAsset时，forChildUris为true、false没有区别，uri为DefaultChangeUri时，forChildUris必须为true，如果为false将找不到该uri，收不到任何消息。 | 524| callback | Callback<[ChangeData](#changedata)> | 是 | 返回要监听的[ChangeData](#changedata)。注：uri可以注册多个不同的callback监听，[unRegisterChange](#unregisterchange)可以关闭该uri所有监听，也可以关闭指定callback的监听。 | 525 526**错误码：** 527 528接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 529 530| 错误码ID | 错误信息 | 531| -------- | ---------------------------------------- | 532| 401 | if parameter is invalid. | 533| 13900012 | Permission denied. | 534| 13900020 | Invalid argument. | 535 536**示例：** 537 538```ts 539import dataSharePredicates from '@ohos.data.dataSharePredicates'; 540 541async function example() { 542 console.info('registerChangeDemo'); 543 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 544 let fetchOptions: photoAccessHelper.FetchOptions = { 545 fetchColumns: [], 546 predicates: predicates 547 }; 548 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 549 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 550 if (photoAsset !== undefined) { 551 console.info('photoAsset.displayName : ' + photoAsset.displayName); 552 } 553 let onCallback1 = (changeData: photoAccessHelper.ChangeData) => { 554 console.info('onCallback1 success, changData: ' + JSON.stringify(changeData)); 555 //file had changed, do something 556 } 557 let onCallback2 = (changeData: photoAccessHelper.ChangeData) => { 558 console.info('onCallback2 success, changData: ' + JSON.stringify(changeData)); 559 //file had changed, do something 560 } 561 // 注册onCallback1监听 562 phAccessHelper.registerChange(photoAsset.uri, false, onCallback1); 563 // 注册onCallback2监听 564 phAccessHelper.registerChange(photoAsset.uri, false, onCallback2); 565 566 photoAsset.setFavorite(true, (err) => { 567 if (err === undefined) { 568 console.info('setFavorite successfully'); 569 } else { 570 console.error(`setFavorite failed with error: ${err.code}, ${err.message}`); 571 } 572 }); 573} 574``` 575 576### unRegisterChange 577 578unRegisterChange(uri: string, callback?: Callback<ChangeData>): void 579 580取消指定uri的监听，一个uri可以注册多个监听，存在多个callback监听时，可以取消指定注册的callback的监听；不指定callback时取消该uri的所有监听。 581 582**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 588| uri | string | 是 | PhotoAsset的uri, Album的uri或[DefaultChangeUri](#defaultchangeuri)的值。 | 589| callback | Callback<[ChangeData](#changedata)> | 否 | 取消[registerChange](#registerchange)注册时的callback的监听，不填时，取消该uri的所有监听。注：off指定注册的callback后不会进入此回调。 | 590 591**错误码：** 592 593接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 594 595| 错误码ID | 错误信息 | 596| -------- | ---------------------------------------- | 597| 401 | if parameter is invalid. | 598| 13900012 | Permission denied. | 599| 13900020 | Invalid argument. | 600 601**示例：** 602 603```ts 604import dataSharePredicates from '@ohos.data.dataSharePredicates'; 605 606async function example() { 607 console.info('offDemo'); 608 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 609 let fetchOptions: photoAccessHelper.FetchOptions = { 610 fetchColumns: [], 611 predicates: predicates 612 }; 613 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 614 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 615 if (photoAsset !== undefined) { 616 console.info('photoAsset.displayName : ' + photoAsset.displayName); 617 } 618 let onCallback1 = (changeData: photoAccessHelper.ChangeData) => { 619 console.info('onCallback1 on'); 620 } 621 let onCallback2 = (changeData: photoAccessHelper.ChangeData) => { 622 console.info('onCallback2 on'); 623 } 624 // 注册onCallback1监听 625 phAccessHelper.registerChange(photoAsset.uri, false, onCallback1); 626 // 注册onCallback2监听 627 phAccessHelper.registerChange(photoAsset.uri, false, onCallback2); 628 // 关闭onCallback1监听，onCallback2 继续监听 629 phAccessHelper.unRegisterChange(photoAsset.uri, onCallback1); 630 photoAsset.setFavorite(true, (err) => { 631 if (err === undefined) { 632 console.info('setFavorite successfully'); 633 } else { 634 console.error(`setFavorite failed with error: ${err.code}, ${err.message}`); 635 } 636 }); 637} 638``` 639 640### createDeleteRequest<sup>(deprecated)</sup> 641 642createDeleteRequest(uriList: Array<string>, callback: AsyncCallback<void>): void 643 644创建一个弹出框来删除照片，删除的文件进入到回收站，使用callback方式返回结果。 645 646> **说明：** 647> 648> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAssetChangeRequest.deleteAssets](#deleteassets11-1)替代。 649 650**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 651 652**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 653 654**参数：** 655 656| 参数名 | 类型 | 必填 | 说明 | 657| -------- | ------------------------- | ---- | ---------- | 658| uriList | Array<string> | 是 | 待删除的媒体文件uri数组，最大删除数量300。 | 659| callback | AsyncCallback<void> | 是 | callback返回void。 | 660 661**错误码：** 662 663接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 664 665| 错误码ID | 错误信息 | 666| -------- | ---------------------------------------- | 667| 401 | if parameter is invalid. | 668| 13900012 | Permission denied. | 669| 13900020 | Invalid argument. | 670| 14000011 | System inner fail. | 671 672**示例：** 673 674```ts 675import dataSharePredicates from '@ohos.data.dataSharePredicates'; 676 677async function example() { 678 console.info('createDeleteRequestDemo'); 679 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 680 let fetchOptions: photoAccessHelper.FetchOptions = { 681 fetchColumns: [], 682 predicates: predicates 683 }; 684 try { 685 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 686 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 687 if (asset === undefined) { 688 console.error('asset not exist'); 689 return; 690 } 691 phAccessHelper.createDeleteRequest([asset.uri], (err) => { 692 if (err === undefined) { 693 console.info('createDeleteRequest successfully'); 694 } else { 695 console.error(`createDeleteRequest failed with error: ${err.code}, ${err.message}`); 696 } 697 }); 698 } catch (err) { 699 console.error(`fetch failed, error: ${err.code}, ${err.message}`); 700 } 701} 702``` 703 704### createDeleteRequest<sup>(deprecated)</sup> 705 706createDeleteRequest(uriList: Array<string>): Promise<void> 707 708创建一个弹出框来删除照片，删除的文件进入到回收站，使用Promise方式返回结果。 709 710> **说明：** 711> 712> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAssetChangeRequest.deleteAssets](#deleteassets11-1)替代。 713 714**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 715 716**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 717 718**参数：** 719 720| 参数名 | 类型 | 必填 | 说明 | 721| -------- | ------------------------- | ---- | ---------- | 722| uriList | Array<string> | 是 | 待删除的媒体文件uri数组，最大删除数量300。 | 723 724**返回值：** 725 726| 类型 | 说明 | 727| --------------------------------------- | ----------------- | 728| Promise<void>| Promise对象，返回void。 | 729 730**错误码：** 731 732接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 733 734| 错误码ID | 错误信息 | 735| -------- | ---------------------------------------- | 736| 401 | if parameter is invalid. | 737| 13900012 | Permission denied. | 738| 13900020 | Invalid argument. | 739| 14000011 | System inner fail. | 740 741**示例：** 742 743```ts 744import dataSharePredicates from '@ohos.data.dataSharePredicates'; 745 746async function example() { 747 console.info('createDeleteRequestDemo'); 748 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 749 let fetchOptions: photoAccessHelper.FetchOptions = { 750 fetchColumns: [], 751 predicates: predicates 752 }; 753 try { 754 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 755 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 756 if (asset === undefined) { 757 console.error('asset not exist'); 758 return; 759 } 760 await phAccessHelper.createDeleteRequest([asset.uri]); 761 console.info('createDeleteRequest successfully'); 762 } catch (err) { 763 console.error(`createDeleteRequest failed with error: ${err.code}, ${err.message}`); 764 } 765} 766``` 767 768### applyChanges<sup>11+</sup> 769 770applyChanges(mediaChangeRequest: MediaChangeRequest): Promise<void> 771 772提交媒体变更请求，使用Promise方式返回结果。 773 774**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 775 776**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| -------- | ------------------------ | ---- | ------------------------- | 782| mediaChangeRequest | [MediaChangeRequest](#mediachangerequest11) | 是 | 媒体变更请求，支持资产变更请求和相册变更请求。 | 783 784**返回值：** 785 786| 类型 | 说明 | 787| --------------------------------------- | ----------------- | 788| Promise<void>| Promise对象，返回void。 | 789 790**错误码：** 791 792接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 793 794| 错误码ID | 错误信息 | 795| -------- | ---------------------------------------- | 796| 201 | Permission denied. | 797| 401 | if parameter is invalid. | 798| 14000011 | System inner fail. | 799 800**示例：** 801 802该接口依赖于[MediaChangeRequest](#mediachangerequest11)对象，详细代码示例请参见[MediaAssetChangeRequest](#mediaassetchangerequest11)和[MediaAlbumChangeRequest](#mediaalbumchangerequest11)中的接口示例。 803 804### release 805 806release(callback: AsyncCallback<void>): void 807 808释放PhotoAccessHelper实例，使用callback方式返回结果。 809当后续不需要使用PhotoAccessHelper实例中的方法时调用。 810 811**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 812 813**参数：** 814 815| 参数名 | 类型 | 必填 | 说明 | 816| -------- | ------------------------- | ---- | -------------------- | 817| callback | AsyncCallback<void> | 是 | 回调表示成功还是失败。 | 818 819**错误码：** 820 821接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 822 823| 错误码ID | 错误信息 | 824| -------- | ---------------------------------------- | 825| 401 | if parameter is invalid. | 826| 13900020 | Invalid argument. | 827| 14000011 | System inner fail. | 828 829**示例：** 830 831```ts 832async function example() { 833 console.info('releaseDemo'); 834 phAccessHelper.release((err) => { 835 if (err !== undefined) { 836 console.error(`release failed. error: ${err.code}, ${err.message}`); 837 } else { 838 console.info('release ok.'); 839 } 840 }); 841} 842``` 843 844### release 845 846release(): Promise<void> 847 848释放PhotoAccessHelper实例，使用Promise方式返回结果。 849当后续不需要使用PhotoAccessHelper 实例中的方法时调用。 850 851**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 852 853**返回值：** 854 855| 类型 | 说明 | 856| ------------------- | --------------------------------- | 857| Promise<void> | Promise对象，返回void。 | 858 859**错误码：** 860 861接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 862 863| 错误码ID | 错误信息 | 864| -------- | ---------------------------------------- | 865| 401 | if parameter is invalid. | 866| 13900020 | Invalid argument. | 867| 14000011 | System inner fail. | 868 869**示例：** 870 871```ts 872async function example() { 873 console.info('releaseDemo'); 874 try { 875 await phAccessHelper.release(); 876 console.info('release ok.'); 877 } catch (err) { 878 console.error(`release failed. error: ${err.code}, ${err.message}`); 879 } 880} 881``` 882 883## PhotoAsset 884 885提供封装文件属性的方法。 886 887### 属性 888 889**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 890 891| 名称 | 类型 | 可读 | 可写 | 说明 | 892| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | 893| uri | string | 是 | 否 | 媒体文件资源uri（如：file://media/Photo/1/IMG_datetime_0001/displayName.jpg），详情参见用户文件uri介绍中的[媒体文件uri](../../file-management/user-file-uri-intro.md#媒体文件uri)。 | 894| photoType | [PhotoType](#phototype) | 是 | 否 | 媒体文件类型 | 895| displayName | string | 是 | 否 | 显示文件名，包含后缀名。 | 896 897### get 898 899get(member: string): MemberType; 900 901获取PhotoAsset成员参数。 902 903**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| -------- | ------------------------- | ---- | ----- | 909| member | string | 是 | 成员参数名称，在get时，除了uri、photoType和displayName三个属性之外，其他的属性都需要在fetchColumns中填入需要get的[PhotoKeys](#photokeys)，例如：get title属性fetchColumns: ['title']。 | 910 911**返回值：** 912 913| 类型 | 说明 | 914| ------------------- | --------------------------------- | 915| [MemberType](#membertype) | 获取PhotoAsset成员参数的值。 | 916 917**错误码：** 918 919接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 920 921| 错误码ID | 错误信息 | 922| -------- | ---------------------------------------- | 923| 401 | if parameter is invalid. | 924| 13900020 | Invalid argument. | 925| 14000014 | Member is not a valid PhotoKey. | 926 927**示例：** 928 929```ts 930import dataSharePredicates from '@ohos.data.dataSharePredicates'; 931 932async function example() { 933 console.info('photoAssetGetDemo'); 934 try { 935 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 936 let fetchOption: photoAccessHelper.FetchOptions = { 937 fetchColumns: ['title'], 938 predicates: predicates 939 }; 940 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 941 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 942 let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE; 943 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString()); 944 console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle); 945 } catch (err) { 946 console.error(`release failed. error: ${err.code}, ${err.message}`); 947 } 948} 949``` 950 951### set 952 953set(member: string, value: string): void 954 955设置PhotoAsset成员参数。 956 957**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 958 959**参数：** 960 961| 参数名 | 类型 | 必填 | 说明 | 962| -------- | ------------------------- | ---- | ----- | 963| member | string | 是 | 成员参数名称例如：[PhotoKeys](#photokeys).TITLE。 | 964| value | string | 是 | 设置成员参数名称，只能修改[PhotoKeys](#photokeys).TITLE的值。 | 965 966**错误码：** 967 968接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 969 970| 错误码ID | 错误信息 | 971| -------- | ---------------------------------------- | 972| 401 | if parameter is invalid. | 973| 13900020 | Invalid argument. | 974| 14000014 | Member is not a valid PhotoKey. | 975 976**示例：** 977 978```ts 979import dataSharePredicates from '@ohos.data.dataSharePredicates'; 980 981async function example() { 982 console.info('photoAssetSetDemo'); 983 try { 984 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 985 let fetchOption: photoAccessHelper.FetchOptions = { 986 fetchColumns: ['title'], 987 predicates: predicates 988 }; 989 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 990 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 991 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 992 photoAsset.set(title, 'newTitle'); 993 } catch (err) { 994 console.error(`release failed. error: ${err.code}, ${err.message}`); 995 } 996} 997``` 998 999### commitModify 1000 1001commitModify(callback: AsyncCallback<void>): void 1002 1003修改文件的元数据，使用callback方式返回异步结果。 1004 1005**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 1006 1007**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1008 1009**参数：** 1010 1011| 参数名 | 类型 | 必填 | 说明 | 1012| -------- | ------------------------- | ---- | ----- | 1013| callback | AsyncCallback<void> | 是 | callback返回void。 | 1014 1015**错误码：** 1016 1017接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1018 1019| 错误码ID | 错误信息 | 1020| -------- | ---------------------------------------- | 1021| 401 | if values to commit is invalid. | 1022| 13900012 | Permission denied. | 1023| 13900020 | Invalid argument. | 1024| 14000001 | Invalid display name. | 1025| 14000011 | System inner fail. | 1026 1027**示例：** 1028 1029```ts 1030import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1031 1032async function example() { 1033 console.info('commitModifyDemo'); 1034 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1035 let fetchOption: photoAccessHelper.FetchOptions = { 1036 fetchColumns: ['title'], 1037 predicates: predicates 1038 }; 1039 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1040 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1041 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 1042 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 1043 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 1044 photoAsset.set(title, 'newTitle2'); 1045 photoAsset.commitModify((err) => { 1046 if (err === undefined) { 1047 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 1048 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 1049 } else { 1050 console.error(`commitModify failed, error: ${err.code}, ${err.message}`); 1051 } 1052 }); 1053} 1054``` 1055 1056### commitModify 1057 1058commitModify(): Promise<void> 1059 1060修改文件的元数据，使用promise方式返回异步结果。 1061 1062**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 1063 1064**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1065 1066**返回值：** 1067 1068| 类型 | 说明 | 1069| ------------------- | ---------- | 1070| Promise<void> | Promise对象，返回void。 | 1071 1072**错误码：** 1073 1074接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1075 1076| 错误码ID | 错误信息 | 1077| -------- | ---------------------------------------- | 1078| 401 | if values to commit is invalid. | 1079| 13900012 | Permission denied. | 1080| 13900020 | Invalid argument. | 1081| 14000001 | Invalid display name. | 1082| 14000011 | System inner fail. | 1083 1084**示例：** 1085 1086```ts 1087import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1088 1089async function example() { 1090 console.info('commitModifyDemo'); 1091 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1092 let fetchOption: photoAccessHelper.FetchOptions = { 1093 fetchColumns: ['title'], 1094 predicates: predicates 1095 }; 1096 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1097 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1098 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 1099 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 1100 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 1101 photoAsset.set(title, 'newTitle3'); 1102 try { 1103 await photoAsset.commitModify(); 1104 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 1105 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 1106 } catch (err) { 1107 console.error(`release failed. error: ${err.code}, ${err.message}`); 1108 } 1109} 1110``` 1111 1112### getReadOnlyFd<sup>(deprecated)</sup> 1113 1114getReadOnlyFd(callback: AsyncCallback<number>): void 1115 1116以只读方式打开当前文件，使用callback方式返回异步结果。 1117 1118> **说明：** 1119> 1120> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。 1121 1122**注意**：返回的文件描述符在使用完毕后需要调用close进行释放。 1123 1124**需要权限**：ohos.permission.READ_IMAGEVIDEO 1125 1126**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1127 1128**参数：** 1129 1130| 参数名 | 类型 | 必填 | 说明 | 1131| -------- | --------------------------- | ---- | ----------------------------------- | 1132| callback | AsyncCallback<number> | 是 | callback返回文件描述符。 | 1133 1134**错误码：** 1135 1136接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1137 1138| 错误码ID | 错误信息 | 1139| -------- | ---------------------------------------- | 1140| 401 | if parameter is invalid. | 1141| 13900012 | Permission denied. | 1142| 13900020 | Invalid argument. | 1143| 14000011 | System inner fail. | 1144 1145**示例：** 1146 1147```ts 1148async function example() { 1149 console.info('getReadOnlyFdDemo'); 1150 // 需要保证设备中存在可读取图片视频文件 1151 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1152 let fetchOptions: photoAccessHelper.FetchOptions = { 1153 fetchColumns: [], 1154 predicates: predicates 1155 }; 1156 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 1157 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 1158 photoAsset.getReadOnlyFd((err, fd) => { 1159 if (fd !== undefined) { 1160 console.info('File fd' + fd); 1161 photoAsset.close(fd); 1162 } else { 1163 console.error(`getReadOnlyFd err: ${err.code}, ${err.message}`); 1164 } 1165 }); 1166} 1167``` 1168 1169### getReadOnlyFd<sup>(deprecated)</sup> 1170 1171getReadOnlyFd(): Promise<number> 1172 1173以只读方式打开当前文件，使用promise方式返回异步结果。 1174 1175> **说明：** 1176> 1177> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。 1178 1179**注意**：返回的文件描述符在使用完毕后需要调用close进行释放。 1180 1181**需要权限**：ohos.permission.READ_IMAGEVIDEO 1182 1183**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1184 1185**返回值：** 1186 1187| 类型 | 说明 | 1188| --------------------- | ------------- | 1189| Promise<number> | Promise对象，返回文件描述符。 | 1190 1191**错误码：** 1192 1193接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1194 1195| 错误码ID | 错误信息 | 1196| -------- | ---------------------------------------- | 1197| 401 | if parameter is invalid. | 1198| 13900012 | Permission denied. | 1199| 13900020 | Invalid argument. | 1200| 14000011 | System inner fail. | 1201 1202**示例：** 1203 1204```ts 1205async function example() { 1206 console.info('getReadOnlyFdDemo'); 1207 try { 1208 // 需要保证设备中存在可读取图片视频文件 1209 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1210 let fetchOptions: photoAccessHelper.FetchOptions = { 1211 fetchColumns: [], 1212 predicates: predicates 1213 }; 1214 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 1215 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 1216 let fd: number = await photoAsset.getReadOnlyFd(); 1217 if (fd !== undefined) { 1218 console.info('File fd' + fd); 1219 photoAsset.close(fd); 1220 } else { 1221 console.error('getReadOnlyFd fail'); 1222 } 1223 } catch (err) { 1224 console.error(`getReadOnlyFd demo err: ${err.code}, ${err.message}`); 1225 } 1226} 1227``` 1228 1229### close<sup>(deprecated)</sup> 1230 1231close(fd: number, callback: AsyncCallback<void>): void 1232 1233关闭当前文件，使用callback方式返回异步结果。 1234 1235> **说明：** 1236> 1237> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。 1238 1239**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1240 1241**参数：** 1242 1243| 参数名 | 类型 | 必填 | 说明 | 1244| -------- | ------------------------- | ---- | ----- | 1245| fd | number | 是 | 文件描述符。 | 1246| callback | AsyncCallback<void> | 是 | callback返回void。 | 1247 1248**错误码：** 1249 1250接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1251 1252| 错误码ID | 错误信息 | 1253| -------- | ---------------------------------------- | 1254| 401 | if parameter is invalid. | 1255| 13900020 | Invalid argument. | 1256| 14000011 | System inner fail. | 1257 1258**示例：** 1259 1260```ts 1261import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1262 1263async function example() { 1264 console.info('closeDemo'); 1265 try { 1266 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1267 let fetchOption: photoAccessHelper.FetchOptions = { 1268 fetchColumns: [], 1269 predicates: predicates 1270 }; 1271 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1272 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1273 let fd: number = await photoAsset.open('rw'); 1274 console.info('file fd', fd); 1275 photoAsset.close(fd, (err) => { 1276 if (err === undefined) { 1277 console.info('asset close succeed.'); 1278 } else { 1279 console.error(`close failed, error: ${err.code}, ${err.message}`); 1280 } 1281 }); 1282 } catch (err) { 1283 console.error(`close failed, error: ${err.code}, ${err.message}`); 1284 } 1285} 1286``` 1287 1288### close<sup>(deprecated)</sup> 1289 1290close(fd: number): Promise<void> 1291 1292关闭当前文件，使用promise方式返回异步结果。 1293 1294> **说明：** 1295> 1296> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。 1297 1298**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1299 1300**参数：** 1301 1302| 参数名 | 类型 | 必填 | 说明 | 1303| ---- | ------ | ---- | ----- | 1304| fd | number | 是 | 文件描述符。 | 1305 1306**返回值：** 1307 1308| 类型 | 说明 | 1309| ------------------- | ---------- | 1310| Promise<void> | Promise对象，返回void。 | 1311 1312**错误码：** 1313 1314接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1315 1316| 错误码ID | 错误信息 | 1317| -------- | ---------------------------------------- | 1318| 401 | if parameter is invalid. | 1319| 13900020 | Invalid argument. | 1320| 14000011 | System inner fail. | 1321 1322**示例：** 1323 1324```ts 1325import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1326 1327async function example() { 1328 console.info('closeDemo'); 1329 try { 1330 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1331 let fetchOption: photoAccessHelper.FetchOptions = { 1332 fetchColumns: [], 1333 predicates: predicates 1334 }; 1335 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1336 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1337 let fd = await asset.open('rw'); 1338 console.info('file fd', fd); 1339 await asset.close(fd); 1340 console.info('asset close succeed.'); 1341 } catch (err) { 1342 console.error(`close failed, error: ${err.code}, ${err.message}`); 1343 } 1344} 1345``` 1346 1347### getThumbnail 1348 1349getThumbnail(callback: AsyncCallback<image.PixelMap>): void 1350 1351获取文件的缩略图，使用callback方式返回异步结果。 1352 1353**需要权限**：ohos.permission.READ_IMAGEVIDEO 1354 1355**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1356 1357**参数：** 1358 1359| 参数名 | 类型 | 必填 | 说明 | 1360| -------- | ----------------------------------- | ---- | ---------------- | 1361| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | callback返回缩略图的PixelMap。 | 1362 1363**错误码：** 1364 1365接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1366 1367| 错误码ID | 错误信息 | 1368| -------- | ---------------------------------------- | 1369| 401 | if parameter is invalid. | 1370| 13900012 | Permission denied. | 1371| 13900020 | Invalid argument. | 1372| 14000011 | System inner fail. | 1373 1374**示例：** 1375 1376```ts 1377import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1378 1379async function example() { 1380 console.info('getThumbnailDemo'); 1381 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1382 let fetchOption: photoAccessHelper.FetchOptions = { 1383 fetchColumns: [], 1384 predicates: predicates 1385 }; 1386 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1387 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1388 console.info('asset displayName = ', asset.displayName); 1389 asset.getThumbnail((err, pixelMap) => { 1390 if (err === undefined) { 1391 console.info('getThumbnail successful ' + pixelMap); 1392 } else { 1393 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 1394 } 1395 }); 1396} 1397``` 1398 1399### getThumbnail 1400 1401getThumbnail(size: image.Size, callback: AsyncCallback<image.PixelMap>): void 1402 1403获取文件的缩略图，传入缩略图尺寸，使用callback方式返回异步结果。 1404 1405**需要权限**：ohos.permission.READ_IMAGEVIDEO 1406 1407**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1408 1409**参数：** 1410 1411| 参数名 | 类型 | 必填 | 说明 | 1412| -------- | ----------------------------------- | ---- | ---------------- | 1413| size | [image.Size](../apis-image-kit/js-apis-image.md#size) | 是 | 缩略图尺寸。 | 1414| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | callback返回缩略图的PixelMap。 | 1415 1416**错误码：** 1417 1418接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1419 1420| 错误码ID | 错误信息 | 1421| -------- | ---------------------------------------- | 1422| 401 | if parameter is invalid. | 1423| 13900012 | Permission denied. | 1424| 13900020 | Invalid argument. | 1425| 14000011 | System inner fail. | 1426 1427**示例：** 1428 1429```ts 1430import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1431import image from '@ohos.multimedia.image' 1432 1433async function example() { 1434 console.info('getThumbnailDemo'); 1435 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1436 let fetchOption: photoAccessHelper.FetchOptions = { 1437 fetchColumns: [], 1438 predicates: predicates 1439 }; 1440 let size: image.Size = { width: 720, height: 720 }; 1441 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1442 let asset = await fetchResult.getFirstObject(); 1443 console.info('asset displayName = ', asset.displayName); 1444 asset.getThumbnail(size, (err, pixelMap) => { 1445 if (err === undefined) { 1446 console.info('getThumbnail successful ' + pixelMap); 1447 } else { 1448 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 1449 } 1450 }); 1451} 1452``` 1453 1454### getThumbnail 1455 1456getThumbnail(size?: image.Size): Promise<image.PixelMap> 1457 1458获取文件的缩略图，传入缩略图尺寸，使用promise方式返回异步结果。 1459 1460**需要权限**：ohos.permission.READ_IMAGEVIDEO 1461 1462**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1463 1464**参数：** 1465 1466| 参数名 | 类型 | 必填 | 说明 | 1467| ---- | -------------- | ---- | ----- | 1468| size | [image.Size](../apis-image-kit/js-apis-image.md#size) | 否 | 缩略图尺寸。 | 1469 1470**返回值：** 1471 1472| 类型 | 说明 | 1473| ----------------------------- | --------------------- | 1474| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回缩略图的PixelMap。 | 1475 1476**错误码：** 1477 1478接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1479 1480| 错误码ID | 错误信息 | 1481| -------- | ---------------------------------------- | 1482| 401 | if parameter is invalid. | 1483| 13900012 | Permission denied. | 1484| 13900020 | Invalid argument. | 1485| 14000011 | System inner fail. | 1486 1487**示例：** 1488 1489```ts 1490import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1491import image from '@ohos.multimedia.image' 1492import { BusinessError } from '@ohos.base'; 1493 1494async function example() { 1495 console.info('getThumbnailDemo'); 1496 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1497 let fetchOption: photoAccessHelper.FetchOptions = { 1498 fetchColumns: [], 1499 predicates: predicates 1500 }; 1501 let size: image.Size = { width: 720, height: 720 }; 1502 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1503 let asset = await fetchResult.getFirstObject(); 1504 console.info('asset displayName = ', asset.displayName); 1505 asset.getThumbnail(size).then((pixelMap) => { 1506 console.info('getThumbnail successful ' + pixelMap); 1507 }).catch((err: BusinessError) => { 1508 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 1509 }); 1510} 1511``` 1512 1513## PhotoViewPicker 1514 1515图库选择器对象，用来支撑选择图片/视频等用户场景。在使用前，需要先创建PhotoViewPicker实例。 1516 1517**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1518 1519**示例：** 1520 1521```ts 1522let photoPicker = new photoAccessHelper.PhotoViewPicker(); 1523``` 1524 1525### select 1526 1527select(option?: PhotoSelectOptions) : Promise<PhotoSelectResult> 1528 1529通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用promise异步返回形式，传入可选参数PhotoSelectOptions对象，返回PhotoSelectResult对象。 1530 1531**注意**：此接口返回的PhotoSelectResult对象中的photoUris只能通过临时授权的方式调用[photoAccessHelper.getAssets接口](#getassets)去使用，具体使用方式参见用户文件uri介绍中的[媒体文件uri的使用方式](../../file-management/user-file-uri-intro.md#媒体文件uri的使用方式)。 1532 1533**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1534 1535**参数：** 1536 1537| 参数名 | 类型 | 必填 | 说明 | 1538| ------- | ------- | ---- | -------------------------- | 1539| option | [PhotoSelectOptions](#photoselectoptions) | 否 | photoPicker选择选项，若无此参数，则默认选择媒体文件类型为图片和视频类型，选择媒体文件数量的最大值为50 | 1540 1541**返回值：** 1542 1543| 类型 | 说明 | 1544| ----------------------------- | :---- | 1545| Promise<[PhotoSelectResult](#photoselectresult)> | Promise对象。返回photoPicker选择后的结果集 | 1546 1547**错误码：** 1548 1549接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1550 1551| 错误码ID | 错误信息 | 1552| -------- | ---------------------------------------- | 1553| 401 | if parameter is invalid. | 1554| 13900042 | Unknown error. | 1555 1556**示例：** 1557 1558```ts 1559import { BusinessError } from '@ohos.base'; 1560async function example01() { 1561 try { 1562 let PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); 1563 PhotoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; 1564 PhotoSelectOptions.maxSelectNumber = 5; 1565 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 1566 photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => { 1567 console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); 1568 }).catch((err: BusinessError) => { 1569 console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`); 1570 }); 1571 } catch (error) { 1572 let err: BusinessError = error as BusinessError; 1573 console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`); 1574 } 1575} 1576``` 1577 1578### select 1579 1580select(option: PhotoSelectOptions, callback: AsyncCallback<PhotoSelectResult>) : void 1581 1582通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用callback异步返回形式，传入参数PhotoSelectOptions对象，返回PhotoSelectResult对象。 1583 1584**注意**：此接口返回的PhotoSelectResult对象中的photoUris只能通过临时授权的方式调用[photoAccessHelper.getAssets接口](#getassets)去使用，具体使用方式参见用户文件uri介绍中的[媒体文件uri的使用方式](../../file-management/user-file-uri-intro.md#媒体文件uri的使用方式)。 1585 1586**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1587 1588**参数：** 1589 1590| 参数名 | 类型 | 必填 | 说明 | 1591| ------- | ------- | ---- | -------------------------- | 1592| option | [PhotoSelectOptions](#photoselectoptions) | 是 | photoPicker选择选项 | 1593| callback | AsyncCallback<[PhotoSelectResult](#photoselectresult)> | 是 | callback 返回photoPicker选择后的结果集 | 1594 1595**错误码：** 1596 1597接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1598 1599| 错误码ID | 错误信息 | 1600| -------- | ---------------------------------------- | 1601| 401 | if parameter is invalid. | 1602| 13900042 | Unknown error. | 1603 1604**示例：** 1605 1606```ts 1607import { BusinessError } from '@ohos.base'; 1608async function example02() { 1609 try { 1610 let PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions(); 1611 PhotoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; 1612 PhotoSelectOptions.maxSelectNumber = 5; 1613 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 1614 photoPicker.select(PhotoSelectOptions, (err: BusinessError, PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => { 1615 if (err) { 1616 console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`); 1617 return; 1618 } 1619 console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); 1620 }); 1621 } catch (error) { 1622 let err: BusinessError = error as BusinessError; 1623 console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`); 1624 } 1625} 1626``` 1627 1628### select 1629 1630select(callback: AsyncCallback<PhotoSelectResult>) : void 1631 1632通过选择模式拉起photoPicker界面，用户可以选择一个或多个图片/视频。接口采用callback异步返回形式，返回PhotoSelectResult对象。 1633 1634**注意**：此接口返回的PhotoSelectResult对象中的photoUris只能通过临时授权的方式调用[photoAccessHelper.getAssets接口](#getassets)去使用，具体使用方式参见用户文件uri介绍中的[媒体文件uri的使用方式](../../file-management/user-file-uri-intro.md#媒体文件uri的使用方式)。 1635 1636**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1637 1638**参数：** 1639 1640| 参数名 | 类型 | 必填 | 说明 | 1641| ------- | ------- | ---- | -------------------------- | 1642| callback | AsyncCallback<[PhotoSelectResult](#photoselectresult)> | 是 | callback 返回photoPicker选择后的结果集 | 1643 1644**错误码：** 1645 1646接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1647 1648| 错误码ID | 错误信息 | 1649| -------- | ---------------------------------------- | 1650| 401 | if parameter is invalid. | 1651| 13900042 | Unknown error. | 1652 1653**示例：** 1654 1655```ts 1656import { BusinessError } from '@ohos.base'; 1657async function example03() { 1658 try { 1659 let photoPicker = new photoAccessHelper.PhotoViewPicker(); 1660 photoPicker.select((err: BusinessError, PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => { 1661 if (err) { 1662 console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`); 1663 return; 1664 } 1665 console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult)); 1666 }); 1667 } catch (error) { 1668 let err: BusinessError = error as BusinessError; 1669 console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`); 1670 } 1671} 1672``` 1673 1674## FetchResult 1675 1676文件检索结果集。 1677 1678### getCount 1679 1680getCount(): number 1681 1682获取文件检索结果中的文件总数。 1683 1684**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1685 1686**返回值：** 1687 1688| 类型 | 说明 | 1689| ------ | -------- | 1690| number | 检索到的文件总数。 | 1691 1692**错误码：** 1693 1694接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1695 1696| 错误码ID | 错误信息 | 1697| -------- | ---------------------------------------- | 1698| 401 | if parameter is invalid. | 1699| 13900020 | Invalid argument. | 1700| 14000011 | System inner fail. | 1701 1702**示例：** 1703 1704```ts 1705import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1706 1707async function example() { 1708 console.info('getCountDemo'); 1709 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1710 let fetchOption: photoAccessHelper.FetchOptions = { 1711 fetchColumns: [], 1712 predicates: predicates 1713 }; 1714 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1715 let fetchCount = fetchResult.getCount(); 1716 console.info('fetchCount = ', fetchCount); 1717} 1718``` 1719 1720### isAfterLast 1721 1722isAfterLast(): boolean 1723 1724检查结果集是否指向最后一行。 1725 1726**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1727 1728**返回值：** 1729 1730| 类型 | 说明 | 1731| ------- | ---------------------------------- | 1732| boolean | 当读到最后一条记录后，后续没有记录返回true，否则返回false。 | 1733 1734**错误码：** 1735 1736接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1737 1738| 错误码ID | 错误信息 | 1739| -------- | ---------------------------------------- | 1740| 401 | if parameter is invalid. | 1741| 13900020 | Invalid argument. | 1742| 14000011 | System inner fail. | 1743 1744**示例：** 1745 1746```ts 1747import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1748 1749async function example() { 1750 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1751 let fetchOption: photoAccessHelper.FetchOptions = { 1752 fetchColumns: [], 1753 predicates: predicates 1754 }; 1755 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1756 let fetchCount = fetchResult.getCount(); 1757 console.info('count:' + fetchCount); 1758 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 1759 if (fetchResult.isAfterLast()) { 1760 console.info('photoAsset isAfterLast displayName = ', photoAsset.displayName); 1761 } else { 1762 console.info('photoAsset not isAfterLast.'); 1763 } 1764} 1765``` 1766 1767### close 1768 1769close(): void 1770 1771释放FetchResult实例并使其失效。无法调用其他方法。 1772 1773**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1774 1775**错误码：** 1776 1777接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1778 1779| 错误码ID | 错误信息 | 1780| -------- | ---------------------------------------- | 1781| 401 | if parameter is invalid. | 1782| 13900020 | Invalid argument. | 1783| 14000011 | System inner fail. | 1784 1785**示例：** 1786 1787```ts 1788import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1789 1790async function example() { 1791 console.info('fetchResultCloseDemo'); 1792 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1793 let fetchOption: photoAccessHelper.FetchOptions = { 1794 fetchColumns: [], 1795 predicates: predicates 1796 }; 1797 try { 1798 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1799 fetchResult.close(); 1800 console.info('close succeed.'); 1801 } catch (err) { 1802 console.error(`close fail. error: ${err.code}, ${err.message}`); 1803 } 1804} 1805``` 1806 1807### getFirstObject 1808 1809getFirstObject(callback: AsyncCallback<T>): void 1810 1811获取文件检索结果中的第一个文件资产。此方法使用callback形式返回结果。 1812 1813**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1814 1815**参数：** 1816 1817| 参数名 | 类型 | 必填 | 说明 | 1818| -------- | --------------------------------------------- | ---- | ------------------------------------------- | 1819| callback | AsyncCallback<T> | 是 | 异步获取结果集中的第一个完成后的回调。 | 1820 1821**错误码：** 1822 1823接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1824 1825| 错误码ID | 错误信息 | 1826| -------- | ---------------------------------------- | 1827| 401 | if parameter is invalid. | 1828| 13900020 | Invalid argument. | 1829| 14000011 | System inner fail. | 1830 1831**示例：** 1832 1833```ts 1834import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1835 1836async function example() { 1837 console.info('getFirstObjectDemo'); 1838 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1839 let fetchOption: photoAccessHelper.FetchOptions = { 1840 fetchColumns: [], 1841 predicates: predicates 1842 }; 1843 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1844 fetchResult.getFirstObject((err, photoAsset) => { 1845 if (photoAsset !== undefined) { 1846 console.info('photoAsset displayName: ', photoAsset.displayName); 1847 } else { 1848 console.error(`photoAsset failed with err:${err.code}, ${err.message}`); 1849 } 1850 }); 1851} 1852``` 1853 1854### getFirstObject 1855 1856getFirstObject(): Promise<T> 1857 1858获取文件检索结果中的第一个文件资产。此方法使用promise方式来异步返回。 1859 1860**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1861 1862**返回值：** 1863 1864| 类型 | 说明 | 1865| --------------------------------------- | -------------------------- | 1866| Promise<T> | Promise对象，返回结果集中第一个对象。 | 1867 1868**错误码：** 1869 1870接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1871 1872| 错误码ID | 错误信息 | 1873| -------- | ---------------------------------------- | 1874| 401 | if parameter is invalid. | 1875| 13900020 | Invalid argument. | 1876| 14000011 | System inner fail. | 1877 1878**示例：** 1879 1880```ts 1881import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1882 1883async function example() { 1884 console.info('getFirstObjectDemo'); 1885 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1886 let fetchOption: photoAccessHelper.FetchOptions = { 1887 fetchColumns: [], 1888 predicates: predicates 1889 }; 1890 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1891 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 1892 console.info('photoAsset displayName: ', photoAsset.displayName); 1893} 1894``` 1895 1896### getNextObject 1897 1898getNextObject(callback: AsyncCallback<T>): void 1899 1900获取文件检索结果中的下一个文件资产。此方法使用callback形式返回结果。 1901在调用此方法之前，必须使用[isAfterLast()](#isafterlast)来检查当前位置是否为最后一行。 1902 1903**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1904 1905**参数：** 1906 1907| 参数名 | 类型 | 必填 | 说明 | 1908| --------- | --------------------------------------------- | ---- | ----------------------------------------- | 1909| callback | AsyncCallback<T> | 是 | 异步返回结果集中下一个之后的回调。 | 1910 1911**错误码：** 1912 1913接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1914 1915| 错误码ID | 错误信息 | 1916| -------- | ---------------------------------------- | 1917| 401 | if parameter is invalid. | 1918| 13900020 | Invalid argument. | 1919| 14000011 | System inner fail. | 1920 1921**示例：** 1922 1923```ts 1924import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1925 1926async function example() { 1927 console.info('getNextObjectDemo'); 1928 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1929 let fetchOption: photoAccessHelper.FetchOptions = { 1930 fetchColumns: [], 1931 predicates: predicates 1932 }; 1933 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1934 await fetchResult.getFirstObject(); 1935 if (!fetchResult.isAfterLast()) { 1936 fetchResult.getNextObject((err, photoAsset) => { 1937 if (photoAsset !== undefined) { 1938 console.info('photoAsset displayName: ', photoAsset.displayName); 1939 } else { 1940 console.error(`photoAsset failed with err: ${err.code}, ${err.message}`); 1941 } 1942 }); 1943 } 1944} 1945``` 1946 1947### getNextObject 1948 1949getNextObject(): Promise<T> 1950 1951获取文件检索结果中的下一个文件资产。此方法使用promise方式来异步返回。 1952在调用此方法之前，必须使用[isAfterLast()](#isafterlast)来检查当前位置是否为最后一行。 1953 1954**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 1955 1956**返回值：** 1957 1958| 类型 | 说明 | 1959| --------------------------------------- | ----------------- | 1960| Promise<T> | Promise对象，返回结果集中下一个对象。 | 1961 1962**错误码：** 1963 1964接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 1965 1966| 错误码ID | 错误信息 | 1967| -------- | ---------------------------------------- | 1968| 401 | if parameter is invalid. | 1969| 13900020 | Invalid argument. | 1970| 14000011 | System inner fail. | 1971 1972**示例：** 1973 1974```ts 1975import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1976 1977async function example() { 1978 console.info('getNextObjectDemo'); 1979 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1980 let fetchOption: photoAccessHelper.FetchOptions = { 1981 fetchColumns: [], 1982 predicates: predicates 1983 }; 1984 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 1985 await fetchResult.getFirstObject(); 1986 if (!fetchResult.isAfterLast()) { 1987 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getNextObject(); 1988 console.info('photoAsset displayName: ', photoAsset.displayName); 1989 } 1990} 1991``` 1992 1993### getLastObject 1994 1995getLastObject(callback: AsyncCallback<T>): void 1996 1997获取文件检索结果中的最后一个文件资产。此方法使用callback回调来返回。 1998 1999**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2000 2001**参数：** 2002 2003| 参数名 | 类型 | 必填 | 说明 | 2004| -------- | --------------------------------------------- | ---- | --------------------------- | 2005| callback | AsyncCallback<T> | 是 | 异步返回结果集中最后一个的回调。 | 2006 2007**错误码：** 2008 2009接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2010 2011| 错误码ID | 错误信息 | 2012| -------- | ---------------------------------------- | 2013| 401 | if parameter is invalid. | 2014| 13900020 | Invalid argument. | 2015| 14000011 | System inner fail. | 2016 2017**示例：** 2018 2019```ts 2020import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2021 2022async function example() { 2023 console.info('getLastObjectDemo'); 2024 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2025 let fetchOption: photoAccessHelper.FetchOptions = { 2026 fetchColumns: [], 2027 predicates: predicates 2028 }; 2029 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2030 fetchResult.getLastObject((err, photoAsset) => { 2031 if (photoAsset !== undefined) { 2032 console.info('photoAsset displayName: ', photoAsset.displayName); 2033 } else { 2034 console.error(`photoAsset failed with err: ${err.code}, ${err.message}`); 2035 } 2036 }); 2037} 2038``` 2039 2040### getLastObject 2041 2042getLastObject(): Promise<T> 2043 2044获取文件检索结果中的最后一个文件资产。此方法使用Promise方式来返回。 2045 2046**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2047 2048**返回值：** 2049 2050| 类型 | 说明 | 2051| --------------------------------------- | ----------------- | 2052| Promise<T> | Promise对象，返回结果集中最后一个对象。 | 2053 2054**错误码：** 2055 2056接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2057 2058| 错误码ID | 错误信息 | 2059| -------- | ---------------------------------------- | 2060| 401 | if parameter is invalid. | 2061| 13900020 | Invalid argument. | 2062| 14000011 | System inner fail. | 2063 2064**示例：** 2065 2066```ts 2067import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2068 2069async function example() { 2070 console.info('getLastObjectDemo'); 2071 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2072 let fetchOption: photoAccessHelper.FetchOptions = { 2073 fetchColumns: [], 2074 predicates: predicates 2075 }; 2076 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2077 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getLastObject(); 2078 console.info('photoAsset displayName: ', photoAsset.displayName); 2079} 2080``` 2081 2082### getObjectByPosition 2083 2084getObjectByPosition(index: number, callback: AsyncCallback<T>): void 2085 2086获取文件检索结果中具有指定索引的文件资产。此方法使用callback来返回。 2087 2088**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2089 2090**参数：** 2091 2092| 参数名 | 类型 | 必填 | 说明 | 2093| -------- | ---------------------------------------- | ---- | ------------------ | 2094| index | number | 是 | 要获取的文件的索引，从0开始。 | 2095| callback | AsyncCallback<T> | 是 | 异步返回指定索引的文件资产的回调。 | 2096 2097**错误码：** 2098 2099接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2100 2101| 错误码ID | 错误信息 | 2102| -------- | ---------------------------------------- | 2103| 401 | if parameter is invalid. | 2104| 13900020 | Invalid argument. | 2105| 14000011 | System inner fail. | 2106 2107**示例：** 2108 2109```ts 2110import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2111 2112async function example() { 2113 console.info('getObjectByPositionDemo'); 2114 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2115 let fetchOption: photoAccessHelper.FetchOptions = { 2116 fetchColumns: [], 2117 predicates: predicates 2118 }; 2119 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2120 fetchResult.getObjectByPosition(0, (err, photoAsset) => { 2121 if (photoAsset !== undefined) { 2122 console.info('photoAsset displayName: ', photoAsset.displayName); 2123 } else { 2124 console.error(`photoAsset failed with err: ${err.code}, ${err.message}`); 2125 } 2126 }); 2127} 2128``` 2129 2130### getObjectByPosition 2131 2132getObjectByPosition(index: number): Promise<T> 2133 2134获取文件检索结果中具有指定索引的文件资产。此方法使用Promise形式返回文件Asset。 2135 2136**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2137 2138**参数：** 2139 2140| 参数名 | 类型 | 必填 | 说明 | 2141| ----- | ------ | ---- | -------------- | 2142| index | number | 是 | 要获取的文件的索引，从0开始。 | 2143 2144**返回值：** 2145 2146| 类型 | 说明 | 2147| --------------------------------------- | ----------------- | 2148| Promise<T> | Promise对象，返回结果集中指定索引的一个对象。 | 2149 2150**错误码：** 2151 2152接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2153 2154| 错误码ID | 错误信息 | 2155| -------- | ---------------------------------------- | 2156| 401 | if parameter is invalid. | 2157| 13900020 | Invalid argument. | 2158| 14000011 | System inner fail. | 2159 2160**示例：** 2161 2162```ts 2163import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2164 2165async function example() { 2166 console.info('getObjectByPositionDemo'); 2167 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2168 let fetchOption: photoAccessHelper.FetchOptions = { 2169 fetchColumns: [], 2170 predicates: predicates 2171 }; 2172 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2173 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getObjectByPosition(0); 2174 console.info('photoAsset displayName: ', photoAsset.displayName); 2175} 2176``` 2177 2178### getAllObjects 2179 2180getAllObjects(callback: AsyncCallback<Array<T>>): void 2181 2182获取文件检索结果中的所有文件资产。此方法使用callback形式返回结果。 2183 2184**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2185 2186**参数：** 2187 2188| 参数名 | 类型 | 必填 | 说明 | 2189| -------- | --------------------------------------------- | ---- | ------------------------------------------- | 2190| callback | AsyncCallback<Array<T>> | 是 | 异步获取结果集中的所有文件资产完成后的回调。 | 2191 2192**错误码：** 2193 2194接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2195 2196| 错误码ID | 错误信息 | 2197| -------- | ---------------------------------------- | 2198| 401 | if parameter is invalid. | 2199| 13900020 | Invalid argument. | 2200| 14000011 | System inner fail. | 2201 2202**示例：** 2203 2204```ts 2205import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2206 2207async function example() { 2208 console.info('getAllObjectDemo'); 2209 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2210 let fetchOption: photoAccessHelper.FetchOptions = { 2211 fetchColumns: [], 2212 predicates: predicates 2213 }; 2214 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2215 fetchResult.getAllObjects((err, photoAssetList) => { 2216 if (photoAssetList !== undefined) { 2217 console.info('photoAssetList length: ', photoAssetList.length); 2218 } else { 2219 console.error(`photoAssetList failed with err:${err.code}, ${err.message}`); 2220 } 2221 }); 2222} 2223``` 2224 2225### getAllObjects 2226 2227getAllObjects(): Promise<Array<T>> 2228 2229获取文件检索结果中的所有文件资产。此方法使用promise方式来异步返回。 2230 2231**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2232 2233**返回值：** 2234 2235| 类型 | 说明 | 2236| --------------------------------------- | -------------------------- | 2237| Promise<Array<T>> | Promise对象，返回结果集中所有文件资产数组。 | 2238 2239**错误码：** 2240 2241接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2242 2243| 错误码ID | 错误信息 | 2244| -------- | ---------------------------------------- | 2245| 401 | if parameter is invalid. | 2246| 13900020 | Invalid argument. | 2247| 14000011 | System inner fail. | 2248 2249**示例：** 2250 2251```ts 2252import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2253 2254async function example() { 2255 console.info('getAllObjectDemo'); 2256 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2257 let fetchOption: photoAccessHelper.FetchOptions = { 2258 fetchColumns: [], 2259 predicates: predicates 2260 }; 2261 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2262 let photoAssetList: Array<photoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 2263 console.info('photoAssetList length: ', photoAssetList.length); 2264} 2265``` 2266 2267## Album 2268 2269实体相册 2270 2271### 属性 2272 2273**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2274 2275| 名称 | 类型 | 可读 | 可写 | 说明 | 2276| ------------ | ------ | ---- | ---- | ------- | 2277| albumType | [AlbumType]( #albumtype) | 是 | 否 | 相册类型。 | 2278| albumSubtype | [AlbumSubtype]( #albumsubtype) | 是 | 否 | 相册子类型。 | 2279| albumName | string | 是 | 用户相册可写，预置相册不可写 | 相册名称。 | 2280| albumUri | string | 是 | 否 | 相册Uri。 | 2281| count | number | 是 | 否 | 相册中文件数量。 | 2282| coverUri | string | 是 | 否 | 封面文件Uri。 | 2283| imageCount<sup>11+</sup> | number | 是 | 否 | 相册中图片数量。| 2284| videoCount<sup>11+</sup> | number | 是 | 否 | 相册中视频数量。| 2285 2286### getAssets 2287 2288getAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<PhotoAsset>>): void 2289 2290获取相册中的文件。该方法使用callback形式来返回文件。 2291 2292**需要权限**：ohos.permission.READ_IMAGEVIDEO 2293 2294**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2295 2296**参数：** 2297 2298| 参数名 | 类型 | 必填 | 说明 | 2299| -------- | ------------------------- | ---- | ---------- | 2300| options | [FetchOptions](#fetchoptions) | 是 | 检索选项。 | 2301| callback | AsyncCallback<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | 是 | callback返回图片和视频数据结果集。 | 2302 2303**错误码：** 2304 2305接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2306 2307| 错误码ID | 错误信息 | 2308| -------- | ---------------------------------------- | 2309| 401 | if parameter is invalid. | 2310| 13900012 | Permission denied. | 2311| 13900020 | Invalid argument. | 2312| 14000011 | System inner fail. | 2313 2314**示例：** 2315 2316```ts 2317import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2318 2319async function example() { 2320 console.info('albumGetAssetsDemoCallback'); 2321 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2322 let albumFetchOptions: photoAccessHelper.FetchOptions = { 2323 fetchColumns: [], 2324 predicates: predicates 2325 }; 2326 let fetchOption: photoAccessHelper.FetchOptions = { 2327 fetchColumns: [], 2328 predicates: predicates 2329 }; 2330 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 2331 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 2332 album.getAssets(fetchOption, (err, albumFetchResult) => { 2333 if (albumFetchResult !== undefined) { 2334 console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount()); 2335 } else { 2336 console.error(`album getAssets failed with error: ${err.code}, ${err.message}`); 2337 } 2338 }); 2339} 2340``` 2341 2342### getAssets 2343 2344getAssets(options: FetchOptions): Promise<FetchResult<PhotoAsset>> 2345 2346获取相册中的文件。该方法使用Promise来返回文件。 2347 2348**需要权限**：ohos.permission.READ_IMAGEVIDEO 2349 2350**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2351 2352**参数：** 2353 2354| 参数名 | 类型 | 必填 | 说明 | 2355| -------- | ------------------------- | ---- | ---------- | 2356| options | [FetchOptions](#fetchoptions) | 是 | 检索选项。 | 2357 2358**返回值：** 2359 2360| 类型 | 说明 | 2361| --------------------------------------- | ----------------- | 2362| Promise<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Promise对象，返回图片和视频数据结果集。 | 2363 2364**错误码：** 2365 2366接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2367 2368| 错误码ID | 错误信息 | 2369| -------- | ---------------------------------------- | 2370| 401 | if parameter is invalid. | 2371| 13900012 | Permission denied. | 2372| 13900020 | Invalid argument. | 2373| 14000011 | System inner fail. | 2374 2375**示例：** 2376 2377```ts 2378import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2379import { BusinessError } from '@ohos.base'; 2380 2381async function example() { 2382 console.info('albumGetAssetsDemoPromise'); 2383 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2384 let albumFetchOptions: photoAccessHelper.FetchOptions = { 2385 fetchColumns: [], 2386 predicates: predicates 2387 }; 2388 let fetchOption: photoAccessHelper.FetchOptions = { 2389 fetchColumns: [], 2390 predicates: predicates 2391 }; 2392 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 2393 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 2394 album.getAssets(fetchOption).then((albumFetchResult) => { 2395 console.info('album getAssets successfully, getCount: ' + albumFetchResult.getCount()); 2396 }).catch((err: BusinessError) => { 2397 console.error(`album getAssets failed with error: ${err.code}, ${err.message}`); 2398 }); 2399} 2400``` 2401 2402### commitModify 2403 2404commitModify(callback: AsyncCallback<void>): void 2405 2406更新相册属性修改到数据库中。该方法使用callback形式来返回结果。 2407 2408**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2409 2410**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2411 2412**参数：** 2413 2414| 参数名 | 类型 | 必填 | 说明 | 2415| -------- | ------------------------- | ---- | ---------- | 2416| callback | AsyncCallback<void> | 是 | callback返回void。 | 2417 2418**错误码：** 2419 2420接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2421 2422| 错误码ID | 错误信息 | 2423| -------- | ---------------------------------------- | 2424| 401 | if parameter is invalid. | 2425| 13900012 | Permission denied. | 2426| 13900020 | Invalid argument. | 2427| 14000011 | System inner fail. | 2428 2429**示例：** 2430 2431```ts 2432import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2433 2434async function example() { 2435 console.info('albumCommitModifyDemo'); 2436 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2437 let albumFetchOptions: photoAccessHelper.FetchOptions = { 2438 fetchColumns: [], 2439 predicates: predicates 2440 }; 2441 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 2442 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 2443 album.albumName = 'hello'; 2444 album.commitModify((err) => { 2445 if (err !== undefined) { 2446 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 2447 } else { 2448 console.info('commitModify successfully'); 2449 } 2450 }); 2451} 2452``` 2453 2454### commitModify 2455 2456commitModify(): Promise<void> 2457 2458更新相册属性修改到数据库中。该方法使用Promise来返回结果。 2459 2460**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2461 2462**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2463 2464**返回值：** 2465 2466| 类型 | 说明 | 2467| ------------------- | ------------ | 2468| Promise<void> | Promise对象，返回void。 | 2469 2470**错误码：** 2471 2472接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2473 2474| 错误码ID | 错误信息 | 2475| -------- | ---------------------------------------- | 2476| 401 | if parameter is invalid. | 2477| 13900012 | Permission denied. | 2478| 13900020 | Invalid argument. | 2479| 14000011 | System inner fail. | 2480 2481**示例：** 2482 2483```ts 2484import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2485import { BusinessError } from '@ohos.base'; 2486 2487async function example() { 2488 console.info('albumCommitModifyDemo'); 2489 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2490 let albumFetchOptions: photoAccessHelper.FetchOptions = { 2491 fetchColumns: [], 2492 predicates: predicates 2493 }; 2494 let albumList: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); 2495 let album: photoAccessHelper.Album = await albumList.getFirstObject(); 2496 album.albumName = 'hello'; 2497 album.commitModify().then(() => { 2498 console.info('commitModify successfully'); 2499 }).catch((err: BusinessError) => { 2500 console.error(`commitModify failed with error: ${err.code}, ${err.message}`); 2501 }); 2502} 2503``` 2504 2505### addAssets<sup>(deprecated)</sup> 2506 2507addAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void 2508 2509往相册中添加图片或者视频，需要先预置相册和文件资源。该方法使用callback形式来返回结果。 2510 2511> **说明：** 2512> 2513> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.addAssets](#addassets11)替代。 2514 2515**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2516 2517**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2518 2519**参数：** 2520 2521| 参数名 | 类型 | 必填 | 说明 | 2522| -------- | ------------------------- | ---- | ---------- | 2523| assets | Array<[PhotoAsset](#photoasset)> | 是 | 待添加到相册中的图片或视频数组。 | 2524| callback | AsyncCallback<void> | 是 | callback返回void。 | 2525 2526**错误码：** 2527 2528接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2529 2530| 错误码ID | 错误信息 | 2531| -------- | ---------------------------------------- | 2532| 401 | if parameter is invalid. | 2533| 13900012 | Permission denied. | 2534| 13900020 | Invalid argument. | 2535| 14000011 | System inner fail. | 2536 2537**示例：** 2538 2539```ts 2540import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2541 2542async function example() { 2543 try { 2544 console.info('addAssetsDemoCallback'); 2545 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2546 let fetchOption: photoAccessHelper.FetchOptions = { 2547 fetchColumns: [], 2548 predicates: predicates 2549 }; 2550 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 2551 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 2552 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2553 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 2554 album.addAssets([asset], (err) => { 2555 if (err === undefined) { 2556 console.info('album addAssets successfully'); 2557 } else { 2558 console.error(`album addAssets failed with error: ${err.code}, ${err.message}`); 2559 } 2560 }); 2561 } catch (err) { 2562 console.error(`addAssetsDemoCallback failed with error: ${err.code}, ${err.message}`); 2563 } 2564} 2565``` 2566 2567### addAssets<sup>(deprecated)</sup> 2568 2569addAssets(assets: Array<PhotoAsset>): Promise<void> 2570 2571往相册中添加图片或者视频，需要先预置相册和文件资源。该方法使用Promise来返回结果。 2572 2573> **说明：** 2574> 2575> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.addAssets](#addassets11)替代。 2576 2577**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2578 2579**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2580 2581**参数：** 2582 2583| 参数名 | 类型 | 必填 | 说明 | 2584| -------- | ------------------------- | ---- | ---------- | 2585| assets | Array<[PhotoAsset](#photoasset)> | 是 | 待添加到相册中的图片或视频数组。 | 2586 2587**返回值：** 2588 2589| 类型 | 说明 | 2590| --------------------------------------- | ----------------- | 2591|Promise<void> | Promise对象，返回void。 | 2592 2593**错误码：** 2594 2595接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2596 2597| 错误码ID | 错误信息 | 2598| -------- | ---------------------------------------- | 2599| 401 | if parameter is invalid. | 2600| 13900012 | Permission denied. | 2601| 13900020 | Invalid argument. | 2602| 14000011 | System inner fail. | 2603 2604**示例：** 2605 2606```ts 2607import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2608import { BusinessError } from '@ohos.base'; 2609 2610async function example() { 2611 try { 2612 console.info('addAssetsDemoPromise'); 2613 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2614 let fetchOption: photoAccessHelper.FetchOptions = { 2615 fetchColumns: [], 2616 predicates: predicates 2617 }; 2618 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 2619 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 2620 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 2621 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 2622 album.addAssets([asset]).then(() => { 2623 console.info('album addAssets successfully'); 2624 }).catch((err: BusinessError) => { 2625 console.error(`album addAssets failed with error: ${err.code}, ${err.message}`); 2626 }); 2627 } catch (err) { 2628 console.error(`addAssetsDemoPromise failed with error: ${err.code}, ${err.message}`); 2629 } 2630} 2631``` 2632 2633### removeAssets<sup>(deprecated)</sup> 2634 2635removeAssets(assets: Array<PhotoAsset>, callback: AsyncCallback<void>): void 2636 2637从相册中移除图片或者视频，需要先预置相册和文件资源。该方法使用callback形式来返回结果。 2638 2639> **说明：** 2640> 2641> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.removeAssets](#removeassets11)替代。 2642 2643**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2644 2645**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2646 2647**参数：** 2648 2649| 参数名 | 类型 | 必填 | 说明 | 2650| -------- | ------------------------- | ---- | ---------- | 2651| assets | Array<[PhotoAsset](#photoasset)> | 是 | 相册中待移除的图片或视频数组。 | 2652| callback | AsyncCallback<void> | 是 | callback返回void。 | 2653 2654**错误码：** 2655 2656接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2657 2658| 错误码ID | 错误信息 | 2659| -------- | ---------------------------------------- | 2660| 401 | if parameter is invalid. | 2661| 13900012 | Permission denied. | 2662| 13900020 | Invalid argument. | 2663| 14000011 | System inner fail. | 2664 2665**示例：** 2666 2667```ts 2668import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2669 2670async function example() { 2671 try { 2672 console.info('removeAssetsDemoCallback'); 2673 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2674 let fetchOption: photoAccessHelper.FetchOptions = { 2675 fetchColumns: [], 2676 predicates: predicates 2677 }; 2678 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 2679 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 2680 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption); 2681 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 2682 album.removeAssets([asset], (err) => { 2683 if (err === undefined) { 2684 console.info('album removeAssets successfully'); 2685 } else { 2686 console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`); 2687 } 2688 }); 2689 } catch (err) { 2690 console.error(`removeAssetsDemoCallback failed with error: ${err.code}, ${err.message}`); 2691 } 2692} 2693``` 2694 2695### removeAssets<sup>(deprecated)</sup> 2696 2697removeAssets(assets: Array<PhotoAsset>): Promise<void> 2698 2699从相册中移除图片或者视频，需要先预置相册和文件资源。该方法使用Promise来返回结果。 2700 2701> **说明：** 2702> 2703> 从API version 10开始支持，从API version 11开始废弃。建议使用[MediaAlbumChangeRequest.removeAssets](#removeassets11)替代。 2704 2705**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2706 2707**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2708 2709**参数：** 2710 2711| 参数名 | 类型 | 必填 | 说明 | 2712| -------- | ------------------------- | ---- | ---------- | 2713| assets | Array<[PhotoAsset](#photoasset)> | 是 | 相册中待移除的图片或视频数组。 | 2714 2715**返回值：** 2716 2717| 类型 | 说明 | 2718| --------------------------------------- | ----------------- | 2719|Promise<void> | Promise对象，返回void。 | 2720 2721**错误码：** 2722 2723接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2724 2725| 错误码ID | 错误信息 | 2726| -------- | ---------------------------------------- | 2727| 401 | if parameter is invalid. | 2728| 13900012 | Permission denied. | 2729| 13900020 | Invalid argument. | 2730| 14000011 | System inner fail. | 2731 2732**示例：** 2733 2734```ts 2735import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2736import { BusinessError } from '@ohos.base'; 2737 2738async function example() { 2739 try { 2740 console.info('removeAssetsDemoPromise'); 2741 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2742 let fetchOption: photoAccessHelper.FetchOptions = { 2743 fetchColumns: [], 2744 predicates: predicates 2745 }; 2746 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 2747 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 2748 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOption); 2749 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 2750 album.removeAssets([asset]).then(() => { 2751 console.info('album removeAssets successfully'); 2752 }).catch((err: BusinessError) => { 2753 console.error(`album removeAssets failed with error: ${err.code}, ${err.message}`); 2754 }); 2755 } catch (err) { 2756 console.error(`removeAssetsDemoPromise failed with error: ${err.code}, ${err.message}`); 2757 } 2758} 2759``` 2760 2761## MediaAssetChangeRequest<sup>11+</sup> 2762 2763资产变更请求。 2764 2765**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2766 2767### constructor<sup>11+</sup> 2768 2769constructor(asset: PhotoAsset) 2770 2771构造函数。 2772 2773**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2774 2775**参数：** 2776 2777| 参数名 | 类型 | 必填 | 说明 | 2778| -------- | ------------------------- | ---- | ---------- | 2779| asset | [PhotoAsset](#photoasset) | 是 | 需要变更的资产。 | 2780 2781**错误码：** 2782 2783接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2784 2785| 错误码ID | 错误信息 | 2786| -------- | ---------------------------------------- | 2787| 401 | if parameter is invalid. | 2788| 14000011 | System inner fail. | 2789 2790**示例：** 2791 2792```ts 2793import dataSharePredicates from '@ohos.data.dataSharePredicates'; 2794 2795async function example() { 2796 console.info('MediaAssetChangeRequest constructorDemo'); 2797 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 2798 let fetchOptions: photoAccessHelper.FetchOptions = { 2799 fetchColumns: [], 2800 predicates: predicates 2801 }; 2802 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 2803 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 2804 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset); 2805} 2806``` 2807 2808### createImageAssetRequest<sup>11+</sup> 2809 2810static createImageAssetRequest(context: Context, fileUri: string): MediaAssetChangeRequest 2811 2812创建图片资产变更请求。 2813 2814通过fileUri指定待创建资产的数据来源，可参考[FileUri](../apis-core-file-kit/js-apis-file-fileuri.md)。 2815 2816**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2817 2818**参数：** 2819 2820| 参数名 | 类型 | 必填 | 说明 | 2821| ------- | ------- | ---- | -------------------------- | 2822| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 2823| fileUri | string | 是 | 图片资产的数据来源，在应用沙箱下的uri。 | 2824 2825**返回值：** 2826 2827| 类型 | 说明 | 2828| --------------------------------------- | ----------------- | 2829| [MediaAssetChangeRequest](#mediaassetchangerequest11) | 返回创建资产的变更请求。 | 2830 2831**错误码：** 2832 2833接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2834 2835| 错误码ID | 错误信息 | 2836| -------- | ---------------------------------------- | 2837| 401 | if parameter is invalid. | 2838| 13900002 | No such file. | 2839| 14000011 | System inner fail. | 2840 2841**示例：** 2842 2843```ts 2844async function example() { 2845 console.info('createImageAssetRequestDemo'); 2846 try { 2847 // 需要确保fileUri对应的资源存在 2848 let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'; 2849 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createImageAssetRequest(context, fileUri); 2850 await phAccessHelper.applyChanges(assetChangeRequest); 2851 console.info('apply createImageAssetRequest successfully'); 2852 } catch (err) { 2853 console.error(`createImageAssetRequestDemo failed with error: ${err.code}, ${err.message}`); 2854 } 2855} 2856``` 2857 2858### createVideoAssetRequest<sup>11+</sup> 2859 2860static createVideoAssetRequest(context: Context, fileUri: string): MediaAssetChangeRequest 2861 2862创建视频资产变更请求。 2863 2864通过fileUri指定待创建资产的数据来源，可参考[FileUri](../apis-core-file-kit/js-apis-file-fileuri.md)。 2865 2866**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2867 2868**参数：** 2869 2870| 参数名 | 类型 | 必填 | 说明 | 2871| ------- | ------- | ---- | -------------------------- | 2872| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 2873| fileUri | string | 是 | 视频资产的数据来源，在应用沙箱下的uri。 | 2874 2875**返回值：** 2876 2877| 类型 | 说明 | 2878| --------------------------------------- | ----------------- | 2879| [MediaAssetChangeRequest](#mediaassetchangerequest11) | 返回创建资产的变更请求。 | 2880 2881**错误码：** 2882 2883接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2884 2885| 错误码ID | 错误信息 | 2886| -------- | ---------------------------------------- | 2887| 401 | if parameter is invalid. | 2888| 13900002 | No such file. | 2889| 14000011 | System inner fail. | 2890 2891**示例：** 2892 2893```ts 2894async function example() { 2895 console.info('createVideoAssetRequestDemo'); 2896 try { 2897 // 需要确保fileUri对应的资源存在 2898 let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.mp4'; 2899 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createVideoAssetRequest(context, fileUri); 2900 await phAccessHelper.applyChanges(assetChangeRequest); 2901 console.info('apply createVideoAssetRequest successfully'); 2902 } catch (err) { 2903 console.error(`createVideoAssetRequestDemo failed with error: ${err.code}, ${err.message}`); 2904 } 2905} 2906``` 2907 2908### createAssetRequest<sup>11+</sup> 2909 2910static createAssetRequest(context: Context, photoType: PhotoType, extension: string, options?: CreateOptions): MediaAssetChangeRequest 2911 2912指定待创建的文件类型和扩展名，创建资产变更请求。 2913 2914**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2915 2916**参数：** 2917 2918| 参数名 | 类型 | 必填 | 说明 | 2919| ------- | ------- | ---- | -------------------------- | 2920| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 2921| photoType | [PhotoType](#phototype) | 是 | 待创建的文件类型，IMAGE或者VIDEO类型。 | 2922| extension | string | 是 | 文件扩展名，例如：'jpg'。 | 2923| options | [CreateOptions](#createoptions) | 否 | 创建选项，例如：{title: 'testPhoto'}。 | 2924 2925**返回值：** 2926 2927| 类型 | 说明 | 2928| --------------------------------------- | ----------------- | 2929| [MediaAssetChangeRequest](#mediaassetchangerequest11) | 返回创建资产的变更请求。 | 2930 2931**错误码：** 2932 2933接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2934 2935| 错误码ID | 错误信息 | 2936| -------- | ---------------------------------------- | 2937| 401 | if parameter is invalid. | 2938| 14000011 | System inner fail. | 2939 2940**示例：** 2941 2942```ts 2943async function example() { 2944 console.info('createAssetRequestDemo'); 2945 try { 2946 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 2947 let extension: string = 'jpg'; 2948 let options: photoAccessHelper.CreateOptions = { 2949 title: 'testPhoto' 2950 } 2951 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension, options); 2952 // 需要确保fileUri对应的资源存在 2953 let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'; 2954 assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, fileUri); 2955 await phAccessHelper.applyChanges(assetChangeRequest); 2956 console.info('apply createAssetRequest successfully'); 2957 } catch (err) { 2958 console.error(`createAssetRequestDemo failed with error: ${err.code}, ${err.message}`); 2959 } 2960} 2961``` 2962 2963### deleteAssets<sup>11+</sup> 2964 2965static deleteAssets(context: Context, assets: Array<PhotoAsset>): Promise<void> 2966 2967删除媒体文件，删除的文件进入到回收站，使用Promise方式返回结果。 2968 2969**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 2970 2971**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 2972 2973**参数：** 2974 2975| 参数名 | 类型 | 必填 | 说明 | 2976| ------- | ------- | ---- | -------------------------- | 2977| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 2978| assets | Array<[PhotoAsset](#photoasset)> | 是 | 待删除的媒体文件数组。 | 2979 2980**返回值：** 2981 2982| 类型 | 说明 | 2983| --------------------------------------- | ----------------- | 2984| Promise<void>| Promise对象，返回void。 | 2985 2986**错误码：** 2987 2988接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 2989 2990| 错误码ID | 错误信息 | 2991| -------- | ---------------------------------------- | 2992| 201 | Permission denied. | 2993| 401 | if parameter is invalid. | 2994| 14000011 | System inner fail. | 2995 2996**示例：** 2997 2998```ts 2999import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3000 3001async function example() { 3002 console.info('deleteAssetsDemo'); 3003 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3004 let fetchOptions: photoAccessHelper.FetchOptions = { 3005 fetchColumns: [], 3006 predicates: predicates 3007 }; 3008 try { 3009 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 3010 let photoAssetList: Array<photoAccessHelper.PhotoAsset> = await fetchResult.getAllObjects(); 3011 await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, photoAssetList); 3012 console.info('deleteAssets successfully'); 3013 } catch (err) { 3014 console.error(`deleteAssetsDemo failed with error: ${err.code}, ${err.message}`); 3015 } 3016} 3017``` 3018 3019### deleteAssets<sup>11+</sup> 3020 3021static deleteAssets(context: Context, uriList: Array<string>): Promise<void> 3022 3023删除媒体文件，删除的文件进入到回收站，使用Promise方式返回结果。 3024 3025**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 3026 3027**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3028 3029**参数：** 3030 3031| 参数名 | 类型 | 必填 | 说明 | 3032| ------- | ------- | ---- | -------------------------- | 3033| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 3034| uriList | Array<string> | 是 | 待删除的媒体文件uri数组。 | 3035 3036**返回值：** 3037 3038| 类型 | 说明 | 3039| --------------------------------------- | ----------------- | 3040| Promise<void>| Promise对象，返回void。 | 3041 3042**错误码：** 3043 3044接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3045 3046| 错误码ID | 错误信息 | 3047| -------- | ---------------------------------------- | 3048| 201 | Permission denied. | 3049| 401 | if parameter is invalid. | 3050| 14000002 | Invalid asset uri. | 3051| 14000011 | System inner fail. | 3052 3053**示例：** 3054 3055```ts 3056import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3057 3058async function example() { 3059 console.info('deleteAssetsDemo'); 3060 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3061 let fetchOptions: photoAccessHelper.FetchOptions = { 3062 fetchColumns: [], 3063 predicates: predicates 3064 }; 3065 try { 3066 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 3067 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 3068 await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [asset.uri]); 3069 console.info('deleteAssets successfully'); 3070 } catch (err) { 3071 console.error(`deleteAssetsDemo failed with error: ${err.code}, ${err.message}`); 3072 } 3073} 3074``` 3075 3076### getAsset<sup>11+</sup> 3077 3078getAsset(): PhotoAsset 3079 3080获取当前资产变更请求中的资产。 3081 3082**注意**：对于创建资产的变更请求，在调用[applyChanges](#applychanges11)提交生效之前，该接口返回null。 3083 3084**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3085 3086**返回值：** 3087 3088| 类型 | 说明 | 3089| --------------------------------------- | ----------------- | 3090| [PhotoAsset](#photoasset) | 返回当前资产变更请求中的资产。 | 3091 3092**错误码：** 3093 3094接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3095 3096| 错误码ID | 错误信息 | 3097| -------- | ---------------------------------------- | 3098| 401 | if parameter is invalid. | 3099| 14000011 | System inner fail. | 3100 3101**示例：** 3102 3103```ts 3104async function example() { 3105 console.info('getAssetDemo'); 3106 try { 3107 // 需要确保fileUri对应的资源存在 3108 let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'; 3109 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createImageAssetRequest(context, fileUri); 3110 await phAccessHelper.applyChanges(assetChangeRequest); 3111 let asset: photoAccessHelper.PhotoAsset = assetChangeRequest.getAsset(); 3112 console.info('create asset successfully with uri = ' + asset.uri); 3113 } catch (err) { 3114 console.error(`getAssetDemo failed with error: ${err.code}, ${err.message}`); 3115 } 3116} 3117``` 3118 3119### setTitle<sup>11+</sup> 3120 3121setTitle(title: string): void 3122 3123修改媒体资产的标题。 3124 3125**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3126 3127**参数：** 3128 3129| 参数名 | 类型 | 必填 | 说明 | 3130| ---------- | ------- | ---- | ---------------------------------- | 3131| title | string | 是 | 待修改的资产标题。 | 3132 3133title参数规格为： 3134- 不应包含扩展名。 3135- 文件名字符串长度为1~255。 3136- 不允许出现非法字符，包括：<br> . .. \ / : * ? " ' ` < > | { } [ ] 3137 3138**错误码：** 3139 3140接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3141 3142| 错误码ID | 错误信息 | 3143| -------- | ---------------------------------------- | 3144| 401 | if parameter is invalid. | 3145| 14000011 | System inner fail. | 3146 3147**示例：** 3148 3149```ts 3150import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3151import { BusinessError } from '@ohos.base'; 3152 3153async function example() { 3154 console.info('setTitleDemo'); 3155 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3156 let fetchOption: photoAccessHelper.FetchOptions = { 3157 fetchColumns: [], 3158 predicates: predicates 3159 }; 3160 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 3161 let asset = await fetchResult.getFirstObject(); 3162 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset); 3163 let newTitle: string = 'newTitle'; 3164 assetChangeRequest.setTitle(newTitle); 3165 phAccessHelper.applyChanges(assetChangeRequest).then(() => { 3166 console.info('apply setTitle successfully'); 3167 }).catch((err: BusinessError) => { 3168 console.error(`apply setTitle failed with error: ${err.code}, ${err.message}`); 3169 }); 3170} 3171``` 3172 3173### getWriteCacheHandler<sup>11+</sup> 3174 3175getWriteCacheHandler(): Promise<number> 3176 3177获取临时文件写句柄。 3178 3179**注意**：对于同一个资产变更请求，不支持在成功获取临时文件写句柄后，重复调用该接口。 3180 3181**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3182 3183**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 3184 3185**返回值：** 3186 3187| 类型 | 说明 | 3188| --------------------------------------- | ----------------- | 3189| Promise<number> | Promise对象，返回临时文件写句柄。 | 3190 3191**错误码：** 3192 3193接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3194 3195| 错误码ID | 错误信息 | 3196| -------- | ---------------------------------------- | 3197| 201 | Permission denied. | 3198| 401 | if parameter is invalid. | 3199| 14000011 | System inner fail. | 3200| 14000016 | Operation Not Support. | 3201 3202**示例：** 3203 3204```ts 3205import fs from '@ohos.file.fs'; 3206 3207async function example() { 3208 console.info('getWriteCacheHandlerDemo'); 3209 try { 3210 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.VIDEO; 3211 let extension: string = 'mp4'; 3212 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension); 3213 let fd: number = await assetChangeRequest.getWriteCacheHandler(); 3214 console.info('getWriteCacheHandler successfully'); 3215 // write date into fd 3216 await fs.close(fd); 3217 await phAccessHelper.applyChanges(assetChangeRequest); 3218 } catch (err) { 3219 console.error(`getWriteCacheHandlerDemo failed with error: ${err.code}, ${err.message}`); 3220 } 3221} 3222``` 3223 3224### addResource<sup>11+</sup> 3225 3226addResource(type: ResourceType, fileUri: string): void 3227 3228通过fileUri从应用沙箱添加资源。 3229 3230**注意**：对于同一个资产变更请求，不支持在成功添加资源后，重复调用该接口。 3231 3232**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3233 3234**参数：** 3235 3236| 参数名 | 类型 | 必填 | 说明 | 3237| ------- | ------- | ---- | -------------------------- | 3238| type | [ResourceType](#resourcetype11) | 是 | 待添加资源的类型。 | 3239| fileUri | string | 是 | 待添加资源的数据来源，在应用沙箱下的uri。 | 3240 3241**错误码：** 3242 3243接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3244 3245| 错误码ID | 错误信息 | 3246| -------- | ---------------------------------------- | 3247| 401 | if parameter is invalid. | 3248| 13900002 | No such file. | 3249| 14000011 | System inner fail. | 3250| 14000016 | Operation Not Support. | 3251 3252**示例：** 3253 3254```ts 3255async function example() { 3256 console.info('addResourceByFileUriDemo'); 3257 try { 3258 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 3259 let extension: string = 'jpg'; 3260 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension); 3261 // 需要确保fileUri对应的资源存在 3262 let fileUri = 'file://com.example.temptest/data/storage/el2/base/haps/entry/files/test.jpg'; 3263 assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, fileUri); 3264 await phAccessHelper.applyChanges(assetChangeRequest); 3265 console.info('addResourceByFileUri successfully'); 3266 } catch (err) { 3267 console.error(`addResourceByFileUriDemo failed with error: ${err.code}, ${err.message}`); 3268 } 3269} 3270``` 3271 3272### addResource<sup>11+</sup> 3273 3274addResource(type: ResourceType, data: ArrayBuffer): void 3275 3276通过ArrayBuffer数据添加资源。 3277 3278**注意**：对于同一个资产变更请求，不支持在成功添加资源后，重复调用该接口。 3279 3280**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3281 3282**参数：** 3283 3284| 参数名 | 类型 | 必填 | 说明 | 3285| ------- | ------- | ---- | -------------------------- | 3286| type | [ResourceType](#resourcetype11) | 是 | 待添加资源的类型。 | 3287| data | ArrayBuffer | 是 | 待添加资源的数据。 | 3288 3289**错误码：** 3290 3291接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3292 3293| 错误码ID | 错误信息 | 3294| -------- | ---------------------------------------- | 3295| 401 | if parameter is invalid. | 3296| 14000011 | System inner fail. | 3297| 14000016 | Operation Not Support. | 3298 3299**示例：** 3300 3301```ts 3302async function example() { 3303 console.info('addResourceByArrayBufferDemo'); 3304 try { 3305 let photoType: photoAccessHelper.PhotoType = photoAccessHelper.PhotoType.IMAGE; 3306 let extension: string = 'jpg'; 3307 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoType, extension); 3308 let buffer: ArrayBuffer = new ArrayBuffer(2048); 3309 assetChangeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, buffer); 3310 await phAccessHelper.applyChanges(assetChangeRequest); 3311 console.info('addResourceByArrayBuffer successfully'); 3312 } catch (err) { 3313 console.error(`addResourceByArrayBufferDemo failed with error: ${err.code}, ${err.message}`); 3314 } 3315} 3316``` 3317 3318## MediaAlbumChangeRequest<sup>11+</sup> 3319 3320相册变更请求。 3321 3322**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3323 3324### constructor<sup>11+</sup> 3325 3326constructor(album: Album) 3327 3328构造函数。 3329 3330**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3331 3332**参数：** 3333 3334| 参数名 | 类型 | 必填 | 说明 | 3335| -------- | ------------------------- | ---- | ---------- | 3336| album | [Album](#album) | 是 | 需要变更的相册。 | 3337 3338**错误码：** 3339 3340接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3341 3342| 错误码ID | 错误信息 | 3343| -------- | ---------------------------------------- | 3344| 401 | if parameter is invalid. | 3345| 14000011 | System inner fail. | 3346 3347**示例：** 3348 3349```ts 3350import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3351 3352async function example() { 3353 console.info('MediaAlbumChangeRequest constructorDemo'); 3354 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3355 let fetchOptions: photoAccessHelper.FetchOptions = { 3356 fetchColumns: [], 3357 predicates: predicates 3358 }; 3359 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, fetchOptions); 3360 let album: photoAccessHelper.Album = await fetchResult.getFirstObject(); 3361 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 3362} 3363``` 3364 3365### getAlbum<sup>11+</sup> 3366 3367getAlbum(): Album 3368 3369获取当前相册变更请求中的相册。 3370 3371**注意**：对于创建相册的变更请求，在调用[applyChanges](#applychanges11)提交生效之前，该接口返回null。 3372 3373**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3374 3375**返回值：** 3376 3377| 类型 | 说明 | 3378| --------------------------------------- | ----------------- | 3379| [Album](#album) | 返回当前相册变更请求中的相册。 | 3380 3381**错误码：** 3382 3383接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3384 3385| 错误码ID | 错误信息 | 3386| -------- | ---------------------------------------- | 3387| 401 | if parameter is invalid. | 3388| 14000011 | System inner fail. | 3389 3390**示例：** 3391 3392```ts 3393async function example() { 3394 console.info('getAlbumDemo'); 3395 try { 3396 let albumName: string = 'newAlbumName' + new Date().getTime(); 3397 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName); 3398 await phAccessHelper.applyChanges(albumChangeRequest); 3399 let album: photoAccessHelper.Album = albumChangeRequest.getAlbum(); 3400 console.info('create album successfully with uri = ' + album.albumUri); 3401 } catch (err) { 3402 console.error(`getAlbumDemo failed with error: ${err.code}, ${err.message}`); 3403 } 3404} 3405``` 3406 3407### setAlbumName<sup>11+</sup> 3408 3409setAlbumName(name: string): void 3410 3411设置相册名称。 3412 3413相册名的参数规格为： 3414- 相册名字符串长度为1~255。 3415- 不允许出现非法字符，包括：<br> . .. \ / : * ? " ' ` < > | { } [ ] 3416- 英文字符大小写不敏感。 3417- 相册名不允许重名。 3418 3419**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3420 3421**参数：** 3422 3423| 参数名 | 类型 | 必填 | 说明 | 3424| ---------- | ------- | ---- | ---------------------------------- | 3425| name | string | 是 | 待设置的相册名称。| 3426 3427**错误码：** 3428 3429接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3430 3431| 错误码ID | 错误信息 | 3432| -------- | ---------------------------------------- | 3433| 401 | if parameter is invalid. | 3434| 14000011 | System inner fail. | 3435 3436**示例：** 3437 3438```ts 3439async function example() { 3440 console.info('setAlbumNameDemo'); 3441 try { 3442 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 3443 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 3444 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 3445 let newAlbumName: string = 'newAlbumName' + new Date().getTime(); 3446 albumChangeRequest.setAlbumName(newAlbumName); 3447 await phAccessHelper.applyChanges(albumChangeRequest); 3448 console.info('setAlbumName successfully'); 3449 } catch (err) { 3450 console.error(`setAlbumNameDemo failed with error: ${err.code}, ${err.message}`); 3451 } 3452} 3453``` 3454 3455### addAssets<sup>11+</sup> 3456 3457addAssets(assets: Array<PhotoAsset>): void 3458 3459向相册中添加资产。 3460 3461**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3462 3463**参数：** 3464 3465| 参数名 | 类型 | 必填 | 说明 | 3466| ---------- | ------- | ---- | ---------------------------------- | 3467| assets | Array<[PhotoAsset](#photoasset)> | 是 | 待添加到相册中的资产数组。 | 3468 3469**错误码：** 3470 3471接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3472 3473| 错误码ID | 错误信息 | 3474| -------- | ---------------------------------------- | 3475| 401 | if parameter is invalid. | 3476| 14000011 | System inner fail. | 3477| 14000016 | Operation Not Support. | 3478 3479**示例：** 3480 3481```ts 3482import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3483 3484async function example() { 3485 console.info('addAssetsDemo'); 3486 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3487 let fetchOptions: photoAccessHelper.FetchOptions = { 3488 fetchColumns: [], 3489 predicates: predicates 3490 }; 3491 try { 3492 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 3493 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 3494 let albumName: string = 'newAlbumName' + new Date().getTime(); 3495 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = photoAccessHelper.MediaAlbumChangeRequest.createAlbumRequest(context, albumName); 3496 albumChangeRequest.addAssets([asset]); 3497 await phAccessHelper.applyChanges(albumChangeRequest); 3498 console.info('addAssets successfully'); 3499 } catch (err) { 3500 console.error(`addAssetsDemo failed with error: ${err.code}, ${err.message}`); 3501 } 3502} 3503``` 3504 3505### removeAssets<sup>11+</sup> 3506 3507removeAssets(assets: Array<PhotoAsset>): void 3508 3509从相册中移除资产。 3510 3511**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3512 3513**参数：** 3514 3515| 参数名 | 类型 | 必填 | 说明 | 3516| ---------- | ------- | ---- | ---------------------------------- | 3517| assets | Array<[PhotoAsset](#photoasset)> | 是 | 待从相册中移除的资产数组。 | 3518 3519**错误码：** 3520 3521接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3522 3523| 错误码ID | 错误信息 | 3524| -------- | ---------------------------------------- | 3525| 401 | if parameter is invalid. | 3526| 14000011 | System inner fail. | 3527| 14000016 | Operation Not Support. | 3528 3529**示例：** 3530 3531```ts 3532import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3533 3534async function example() { 3535 console.info('removeAssetsDemo'); 3536 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3537 let fetchOptions: photoAccessHelper.FetchOptions = { 3538 fetchColumns: [], 3539 predicates: predicates 3540 }; 3541 try { 3542 let albumFetchResult: photoAccessHelper.FetchResult<photoAccessHelper.Album> = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); 3543 let album: photoAccessHelper.Album = await albumFetchResult.getFirstObject(); 3544 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await album.getAssets(fetchOptions); 3545 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 3546 3547 let albumChangeRequest: photoAccessHelper.MediaAlbumChangeRequest = new photoAccessHelper.MediaAlbumChangeRequest(album); 3548 albumChangeRequest.removeAssets([asset]); 3549 await phAccessHelper.applyChanges(albumChangeRequest); 3550 console.info('removeAssets successfully'); 3551 } catch (err) { 3552 console.error(`removeAssetsDemo failed with error: ${err.code}, ${err.message}`); 3553 } 3554} 3555``` 3556 3557## MediaAssetManager<sup>11+</sup> 3558 3559### requestImage<sup>11+</sup> 3560 3561static requestImage(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler<image.ImageSource>): Promise<string> 3562 3563根据不同的策略模式，请求图片资源。 3564 3565**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3566 3567**需要权限**：ohos.permission.READ_IMAGEVIDEO 3568 3569**参数：** 3570 3571| 参数名 | 类型 | 必填 | 说明 | 3572|----------------|-----------------------------------------------------------------------------------------------------------| ---- | ------------------------- | 3573| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 3574| asset | [PhotoAsset](#photoasset) | 是 | 待请求的的媒体文件对象。 | 3575| requestOptions | [RequestOptions](#requestoptions11) | 是 | 图片请求策略模式配置项。 3576| dataHandler | [MediaAssetDataHandler](#mediaassetdatahandler11)<[image.ImageSource](../apis-image-kit/js-apis-image.md#imagesource)> | 是 | 媒体资源处理器，当所请求的图片资源准备完成时会触发回调。 3577 3578**错误码：** 3579 3580接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3581 3582| 错误码ID | 错误信息 | 3583| -------- | ---------------------------------------- | 3584| 201 | Permission denied | 3585| 401 | if parameter is invalid. | 3586| 14000011 | System inner fail. | 3587 3588**示例：** 3589 3590```ts 3591import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3592import image from '@ohos.multimedia.image' 3593 3594class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> { 3595 onDataPrepared(data: image.ImageSource) { 3596 console.info('on image data prepared'); 3597 } 3598} 3599 3600async function example() { 3601 console.info('requestImage'); 3602 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3603 let fetchOptions: photoAccessHelper.FetchOptions = { 3604 fetchColumns: [], 3605 predicates: predicates 3606 }; 3607 let requestOptions: photoAccessHelper.RequestOptions = { 3608 deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE, 3609 sourceMode: photoAccessHelper.SourceMode.ORIGINAL_MODE 3610 } 3611 const handler = new MediaHandler(); 3612 3613 phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => { 3614 console.info('fetchResult success'); 3615 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 3616 await photoAccessHelper.MediaAssetManager.requestImage(context, photoAsset, requestOptions, handler); 3617 console.info('requestImage successfully'); 3618 }); 3619} 3620``` 3621 3622### requestImageData<sup>11+</sup> 3623 3624static requestImageData(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler<ArrayBuffer>): Promise<string> 3625 3626根据不同的策略模式，请求图片资源数据。 3627 3628**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3629 3630**需要权限**：ohos.permission.READ_IMAGEVIDEO 3631 3632**参数：** 3633 3634| 参数名 | 类型 | 必填 | 说明 | 3635| -------- |----------------------------------------------------------------------| ---- | ------------------------- | 3636| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 传入Ability实例的Context。 | 3637| asset | [PhotoAsset](#photoasset) | 是 | 待请求的的媒体文件对象。 | 3638| requestOptions | [RequestOptions](#requestoptions11) | 是 | 图片请求策略模式配置项。 3639| dataHandler | [MediaAssetDataHandler](#mediaassetdatahandler11)<ArrayBuffer> | 是 | 媒体资源处理器，当所请求的图片资源准备完成时会触发回调。 3640 3641**错误码：** 3642 3643接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 3644 3645| 错误码ID | 错误信息 | 3646| -------- | ---------------------------------------- | 3647| 201 | Permission denied | 3648| 401 | if parameter is invalid. | 3649| 14000011 | System inner fail. | 3650 3651**示例：** 3652 3653```ts 3654import dataSharePredicates from '@ohos.data.dataSharePredicates'; 3655class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> { 3656 onDataPrepared(data: ArrayBuffer) { 3657 console.info('on image data prepared'); 3658 } 3659} 3660 3661async function example() { 3662 console.info('requestImageData'); 3663 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 3664 let fetchOptions: photoAccessHelper.FetchOptions = { 3665 fetchColumns: [], 3666 predicates: predicates 3667 }; 3668 let requestOptions: photoAccessHelper.RequestOptions = { 3669 deliveryMode: photoAccessHelper.DeliveryMode.HIGH_QUALITY_MODE, 3670 sourceMode: photoAccessHelper.SourceMode.ORIGINAL_MODE 3671 } 3672 const handler = new MediaDataHandler(); 3673 3674 phAccessHelper.getAssets(fetchOptions, async (err, fetchResult) => { 3675 console.info('fetchResult success'); 3676 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 3677 await photoAccessHelper.MediaAssetManager.requestImageData(context, photoAsset, requestOptions, handler); 3678 console.info('requestImageData successfully'); 3679 }); 3680} 3681``` 3682 3683## MediaAssetDataHandler<sup>11+</sup> 3684 3685媒体资源处理器，应用在onDataPrepared方法中可自定义媒体资源处理逻辑。 3686 3687**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3688 3689### onDataPrepared<sup>11+</sup> 3690 3691onDataPrepared(data: T): void 3692 3693媒体资源就绪通知，当所请求的图片资源准备就绪时系统会回调此方法。 3694T支持ArrayBuffer与[ImageSource](../apis-image-kit/js-apis-image.md#imagesource)两种数据类型。 3695 3696**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3697 3698**参数：** 3699 3700| 参数名 | 类型 | 必填 | 说明 | 3701|------|---| ---- |-------------------------------------------------------------------------------| 3702| data | T | 是 | 泛型，支持ArrayBuffer与[ImageSource](../apis-image-kit/js-apis-image.md#imagesource)两种数据类型。 | 3703 3704**示例** 3705```ts 3706import image from '@ohos.multimedia.image' 3707 3708class MediaHandler implements photoAccessHelper.MediaAssetDataHandler<image.ImageSource> { 3709 onDataPrepared(data: image.ImageSource) { 3710 // 自定义对ImageSource的处理逻辑 3711 console.info('on image data prepared'); 3712 } 3713} 3714 3715class MediaDataHandler implements photoAccessHelper.MediaAssetDataHandler<ArrayBuffer> { 3716 onDataPrepared(data: ArrayBuffer) { 3717 // 自定义对ArrayBuffer的处理逻辑 3718 console.info('on image data prepared'); 3719 } 3720} 3721``` 3722 3723## MemberType 3724 3725成员类型。 3726 3727**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3728 3729| 名称 | 类型 | 可读 | 可写 | 说明 | 3730| ----- | ---- | ---- | ---- | ---- | 3731| number | number | 是 | 是 | number类型。 | 3732| string | string | 是 | 是 | string类型。| 3733| boolean | boolean | 是 | 是 | boolean类型。 | 3734 3735## PhotoType 3736 3737枚举，媒体文件类型。 3738 3739**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3740 3741| 名称 | 值 | 说明 | 3742| ----- | ---- | ---- | 3743| IMAGE | 1 | 图片。 | 3744| VIDEO | 2 | 视频。 | 3745 3746## AlbumType 3747 3748枚举，相册类型，表示是用户相册还是系统预置相册。 3749 3750**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3751 3752| 名称 | 值 | 说明 | 3753| ------------------- | ---- | ------------------------- | 3754| USER | 0 | 用户相册。 | 3755| SYSTEM | 1024 | 系统预置相册。 | 3756 3757## AlbumSubtype 3758 3759枚举，相册子类型，表示具体的相册类型。 3760 3761**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3762 3763| 名称 | 值 | 说明 | 3764| --------------------------------- | ---------- | ------------------------------- | 3765| USER\_GENERIC | 1 | 用户相册。 | 3766| FAVORITE | 1025 | 收藏夹。 | 3767| VIDEO | 1026 | 视频相册。 | 3768| ANY | 2147483647 | 任意相册。 | 3769 3770## PhotoKeys 3771 3772枚举，图片和视频文件关键信息。 3773 3774**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3775 3776| 名称 | 值 | 说明 | 3777| ------------- | ------------------- | ---------------------------------------------------------- | 3778| URI | 'uri' | 文件uri。 | 3779| PHOTO_TYPE | 'media_type' | 媒体文件类型。 | 3780| DISPLAY_NAME | 'display_name' | 显示名字。 | 3781| SIZE | 'size' | 文件大小。 | 3782| DATE_ADDED | 'date_added' | 添加日期（添加文件时间距1970年1月1日的秒数值）。 | 3783| DATE_MODIFIED | 'date_modified' | 修改日期（修改文件时间距1970年1月1日的秒数值，修改文件名不会改变此值，当文件内容发生修改时才会更新）。 | 3784| DURATION | 'duration' | 持续时间（单位：毫秒）。 | 3785| WIDTH | 'width' | 图片宽度（单位：像素）。 | 3786| HEIGHT | 'height' | 图片高度（单位：像素）。 | 3787| DATE_TAKEN | 'date_taken' | 拍摄日期（文件拍照时间距1970年1月1日的秒数值）。 | 3788| ORIENTATION | 'orientation' | 图片文件的方向。 | 3789| FAVORITE | 'is_favorite' | 收藏。 | 3790| TITLE | 'title' | 文件标题。 | 3791 3792## AlbumKeys 3793 3794枚举，相册关键信息。 3795 3796**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3797 3798| 名称 | 值 | 说明 | 3799| ------------- | ------------------- | ---------------------------------------------------------- | 3800| URI | 'uri' | 相册uri。 | 3801| ALBUM_NAME | 'album_name' | 相册名字。 | 3802 3803## CreateOptions 3804 3805图片或视频的创建选项。 3806 3807title参数规格为： 3808- 不应包含扩展名。 3809- 文件名字符串长度为1~255。 3810- 文件名中不允许出现的非法英文字符，包括：<br> . .. \ / : * ? " ' ` < > | { } [ ] 3811 3812**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3813 3814| 名称 | 类型 | 必填 | 说明 | 3815| ---------------------- | ------------------- | ---- | ------------------------------------------------ | 3816| title | string | 否 | 图片或者视频的标题。 | 3817 3818 3819## FetchOptions 3820 3821检索条件。 3822 3823**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3824 3825| 名称 | 类型 | 可读 | 可写 | 说明 | 3826| ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ | 3827| fetchColumns | Array<string> | 是 | 是 | 检索条件，指定列名查询，如果该参数为空时默认查询uri、name、photoType（具体字段名称以检索对象定义为准）且使用[get](#get)接口去获取当前对象的其他属性时将会报错。示例：<br />fetchColumns: ['uri', 'title']。 | 3828| predicates | [dataSharePredicates.DataSharePredicates](../apis-arkdata/js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 是 | 谓词查询，显示过滤条件。 | 3829 3830## RequestOptions<sup>11+</sup> 3831 3832请求策略。 3833 3834**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3835 3836| 名称 | 类型 | 可读 | 可写 | 说明 | 3837| ---------------------- |---------------------------------| ---- |---- | ------------------------------------------------ | 3838| deliveryMode | [DeliveryMode](#deliverymode11) | 是 | 是 | 请求资源分发模式，可以指定对于该资源的请求策略，可被配置为快速模式，高质量模式，均衡模式 三种策略。 | 3839 3840## PhotoProxy<sup>11+</sup> 3841 3842照片代理，相机应用通过该对象写入图片数据。 3843 3844**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3845 3846## MediaChangeRequest<sup>11+</sup> 3847 3848媒体变更请求，资产变更请求和相册变更请求的父类型。 3849 3850**注意**：媒体变更请求需要在调用[applyChanges](#applychanges11)后才会提交生效。 3851 3852**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3853 3854## ResourceType<sup>11+</sup> 3855 3856枚举，写入资源的类型。 3857 3858**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3859 3860| 名称 | 值 | 说明 | 3861| ----- | ---- | ---- | 3862| IMAGE_RESOURCE | 1 | 表示图片资源。 | 3863| VIDEO_RESOURCE | 2 | 表示视频资源。 | 3864 3865## ChangeData 3866 3867监听器回调函数的值。 3868 3869**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3870 3871| 名称 | 类型 | 可读 | 可写 | 说明 | 3872| ------- | --------------------------- | ---- | ---- | ------------------------------------------------------------ | 3873| type | [NotifyType](#notifytype) | 是 | 否 | ChangeData的通知类型。 | 3874| uris | Array<string> | 是 | 否 | 相同[NotifyType](#notifytype)的所有uri，可以是PhotoAsset或Album。 | 3875| extraUris | Array<string> | 是 | 否 | 相册中变动文件的uri数组。 | 3876 3877## NotifyType 3878 3879枚举，通知事件的类型。 3880 3881**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3882 3883| 名称 | 值 | 说明 | 3884| ------------------------- | ---- | -------------------------------- | 3885| NOTIFY_ADD | 0 | 添加文件集或相册通知的类型。 | 3886| NOTIFY_UPDATE | 1 | 文件集或相册的更新通知类型。 | 3887| NOTIFY_REMOVE | 2 | 删除文件集或相册的通知类型。 | 3888| NOTIFY_ALBUM_ADD_ASSET | 3 | 在相册中添加的文件集的通知类型。 | 3889| NOTIFY_ALBUM_REMOVE_ASSET | 4 | 在相册中删除的文件集的通知类型。 | 3890 3891## DefaultChangeUri 3892 3893枚举，DefaultChangeUri子类型。 3894 3895**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3896 3897| 名称 | 值 | 说明 | 3898| ----------------- | ----------------------- | ------------------------------------------------------------ | 3899| DEFAULT_PHOTO_URI | 'file://media/Photo' | 默认PhotoAsset的Uri，与forSubUri{true}一起使用，将接收所有PhotoAsset的更改通知。 | 3900| DEFAULT_ALBUM_URI | 'file://media/PhotoAlbum' | 默认相册的Uri，与forSubUri{true}一起使用，将接收所有相册的更改通知。 | 3901 3902## PhotoViewMIMETypes 3903 3904枚举，可选择的媒体文件类型。 3905 3906**系统能力：** SystemCapability.FileManagement.PhotoAccessHelper.Core 3907 3908| 名称 | 值 | 说明 | 3909| ----- | ---- | ---- | 3910| IMAGE_TYPE | 'image/*' | 图片类型。 | 3911| VIDEO_TYPE | 'video/*' | 视频类型。 | 3912| IMAGE_VIDEO_TYPE | '\*/*' | 图片和视频类型。 | 3913 3914## RecommendationType<sup>11+</sup> 3915 3916枚举，推荐的照片类型。 3917 3918**系统能力：** SystemCapability.FileManagement.PhotoAccessHelper.Core 3919 3920| 名称 | 值 | 说明 | 3921| ----- | ---- | ---- | 3922| QR_OR_BAR_CODE | 1 | 二维码或条码。 | 3923| QR_CODE | 2 | 二维码。 | 3924| BAR_CODE | 3 | 条码。 | 3925| ID_CARD | 4 | 身份证。 | 3926| PROFILE_PICTURE | 5 | 头像。 | 3927 3928## RecommendationOptions<sup>11+</sup> 3929 3930照片推荐选项(基于照片数据分析结果，依赖设备适配)。 3931 3932**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3933 3934| 名称 | 类型 | 必填 | 说明 | 3935| ----------------------- | ------------------- | ---- | -------------------------------- | 3936| recommendationType | [RecommendationType](#recommendationtype11) | 否 | 可选择的照片推荐类型，若无此参数，则默认为不推荐照片。 | 3937 3938## PhotoSelectOptions 3939 3940图库选择选项。 3941 3942**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3943 3944| 名称 | 类型 | 必填 | 说明 | 3945| ----------------------- | ------------------- | ---- | -------------------------------- | 3946| MIMEType | [PhotoViewMIMETypes](#photoviewmimetypes) | 否 | 可选择的媒体文件类型，若无此参数，则默认为图片和视频类型。 | 3947| maxSelectNumber | number | 否 | 选择媒体文件数量的最大值(默认值为50，最大值为500)。 | 3948| isPhotoTakingSupported<sup>11+</sup> | boolean | 否 | 支持拍照。 | 3949| isEditSupported<sup>11+</sup> | boolean | 否 | 支持编辑照片。 | 3950| isSearchSupported<sup>11+</sup> | boolean | 否 | 支持搜索。 | 3951| recommendationOptions<sup>11+</sup> | [RecommendationOptions](#recommendationoptions11) | 否 | 支持照片推荐。 | 3952| preselectedUris<sup>11+</sup> | Array<string> | 否 | 预选择图片的uri数据。 | 3953 3954## PhotoSelectResult 3955 3956返回图库选择后的结果集。 3957 3958**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3959 3960| 名称 | 类型 | 可读 | 可写 | 说明 | 3961| ----------------------- | ------------------- | ---- | ---- | ------------------------------ | 3962| photoUris | Array<string> | 是 | 是 | 返回图库选择后的媒体文件的uri数组，此uri数组只能通过临时授权的方式调用[photoAccessHelper.getAssets接口](#getassets)去使用，具体使用方式参见用户文件uri介绍中的[媒体文件uri的使用方式](../../file-management/user-file-uri-intro.md#媒体文件uri的使用方式)。 | 3963| isOriginalPhoto | boolean | 是 | 是 | 返回图库选择后的媒体文件是否为原图。 | 3964 3965 3966## DeliveryMode<sup>11+</sup> 3967 3968枚举，请求图片分发模式。 3969 3970**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 3971 3972| 名称 | 值 | 说明 | 3973| ----- | ---- | ---- | 3974| FAST_MODE | 0 | 快速模式。 | 3975| HIGH_QUALITY_MODE | 1 | 高质量模式。 | 3976| BALANCE_MODE | 2 | 均衡模式。 | 3977
