1# Interface (PhotoAsset) 2<!--Kit: Media Library Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yixiaoff--> 5<!--Designer: @liweilu1--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13提供封装文件属性的方法。 14 15## 导入模块 16 17```ts 18import { photoAccessHelper } from '@kit.MediaLibraryKit'; 19``` 20 21## 属性 22 23**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 24 25| 名称 | 类型 | 可读 | 可写 | 说明 | 26| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | 27| uri | string | 是 | 否 | 媒体文件资源uri（如：file://media/Photo/1/IMG_datetime_0001/displayName.jpg），详情参见用户文件uri介绍中的[媒体文件uri](../../file-management/user-file-uri-intro.md#媒体文件uri)<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 28| photoType | [PhotoType](arkts-apis-photoAccessHelper-e.md#phototype) | 是 | 否 | 媒体文件类型。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 29| displayName | string | 是 | 否 | 显示文件名，包含后缀名。字符串长度为1~255。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 30 31## get 32 33get(member: string): MemberType 34 35获取PhotoAsset成员参数的值。 36 37**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 38 39**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| -------- | ------------------------- | ---- | ----- | 45| member | string | 是 | 成员参数名称，在get时，除了'uri'、'media_type'、'subtype'和'display_name'四个属性之外，其他的属性都需要在fetchColumns中填入需要获取的[PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys)，例如：get title属性fetchColumns: ['title']。 | 46 47**返回值：** 48 49| 类型 | 说明 | 50| ------------------- | --------------------------------- | 51| [MemberType](arkts-apis-photoAccessHelper-t.md#membertype) | 获取PhotoAsset成员参数的值。 | 52 53**错误码：** 54 55接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 56 57| 错误码ID | 错误信息 | 58| -------- | ---------------------------------------- | 59| 13900020 | Invalid argument. | 60| 14000014 | The provided member must be a property name of PhotoKey. | 61 62**示例：** 63 64phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 65 66```ts 67import { dataSharePredicates } from '@kit.ArkData'; 68 69async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 70 console.info('photoAssetGetDemo'); 71 try { 72 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 73 let fetchOption: photoAccessHelper.FetchOptions = { 74 fetchColumns: ['title'], 75 predicates: predicates 76 }; 77 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 78 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 79 let title: photoAccessHelper.PhotoKeys = photoAccessHelper.PhotoKeys.TITLE; 80 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title.toString()); 81 console.info('photoAsset Get photoAssetTitle = ', photoAssetTitle); 82 } catch (err) { 83 console.error(`release failed. error: ${err.code}, ${err.message}`); 84 } 85} 86``` 87 88## set 89 90set(member: string, value: string): void 91 92设置PhotoAsset成员参数。 93 94**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| -------- | ------------------------- | ---- | ----- | 100| member | string | 是 | 成员参数名称例如：[PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE。字符串长度为1~255。 | 101| value | string | 是 | 设置成员参数名称，只能修改[PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys).TITLE的值。title的参数规格为：<br>- 不应包含扩展名。<br>- 文件名字符串长度为1~255（资产文件名为标题+扩展名）。<br>- 不允许出现的非法英文字符，包括：. \ / : * ? " ' ` < > \| { } [ ] | 102 103**错误码：** 104 105接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 106 107| 错误码ID | 错误信息 | 108| -------- | ---------------------------------------- | 109| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 110| 13900020 | Invalid argument. | 111| 14000014 | The provided member must be a property name of PhotoKey. | 112 113**示例：** 114 115phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 116 117```ts 118import { dataSharePredicates } from '@kit.ArkData'; 119 120async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 121 console.info('photoAssetSetDemo'); 122 try { 123 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 124 let fetchOption: photoAccessHelper.FetchOptions = { 125 fetchColumns: ['title'], 126 predicates: predicates 127 }; 128 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 129 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 130 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 131 photoAsset.set(title, 'newTitle'); 132 } catch (err) { 133 console.error(`release failed. error: ${err.code}, ${err.message}`); 134 } 135} 136``` 137 138## commitModify 139 140commitModify(callback: AsyncCallback<void>): void 141 142修改文件的元数据，使用callback方式返回异步结果。 143 144**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 145 146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 147 148**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| -------- | ------------------------- | ---- | ----- | 154| callback | AsyncCallback<void> | 是 | callback返回void。 | 155 156**错误码：** 157 158接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 159 160错误码14000001，请参考 [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys)获取有关文件名的格式和长度要求。 161 162错误码13900012，请参考[开发准备](../../media/medialibrary/photoAccessHelper-preparation.md)。 163 164| 错误码ID | 错误信息 | 165| -------- | ---------------------------------------- | 166| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 167| 201 | Permission denied. | 168| 13900020 | Invalid argument. | 169| 14000001 | Invalid display name. | 170| 14000011 | System inner fail. | 171 172**示例：** 173 174phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 175 176```ts 177import { dataSharePredicates } from '@kit.ArkData'; 178 179async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 180 console.info('commitModifyDemo'); 181 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 182 let fetchOption: photoAccessHelper.FetchOptions = { 183 fetchColumns: ['title'], 184 predicates: predicates 185 }; 186 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 187 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 188 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 189 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 190 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 191 photoAsset.set(title, 'newTitle2'); 192 photoAsset.commitModify((err) => { 193 if (err === undefined) { 194 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 195 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 196 } else { 197 console.error(`commitModify failed, error: ${err.code}, ${err.message}`); 198 } 199 }); 200} 201``` 202 203## commitModify 204 205commitModify(): Promise<void> 206 207修改文件的元数据，使用promise方式返回异步结果。 208 209**需要权限**：ohos.permission.WRITE_IMAGEVIDEO 210 211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 212 213**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 214 215**返回值：** 216 217| 类型 | 说明 | 218| ------------------- | ---------- | 219| Promise<void> | Promise对象，返回void。 | 220 221**错误码：** 222 223接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 224 225错误码14000001，请参考 [PhotoKeys](arkts-apis-photoAccessHelper-e.md#photokeys)获取有关文件名的格式和长度要求。 226 227在API 13及之前的版本，无相关权限返回错误码13900012；从API 14开始，无相关权限返回错误码201。 228 229| 错误码ID | 错误信息 | 230| -------- | ---------------------------------------- | 231| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 232| 201 | Permission denied. | 233| 13900020 | Invalid argument. | 234| 14000001 | Invalid display name. | 235| 14000011 | System inner fail. | 236 237**示例：** 238 239phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 240 241```ts 242import { dataSharePredicates } from '@kit.ArkData'; 243 244async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 245 console.info('commitModifyDemo'); 246 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 247 let fetchOption: photoAccessHelper.FetchOptions = { 248 fetchColumns: ['title'], 249 predicates: predicates 250 }; 251 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 252 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 253 let title: string = photoAccessHelper.PhotoKeys.TITLE.toString(); 254 let photoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 255 console.info('photoAsset get photoAssetTitle = ', photoAssetTitle); 256 photoAsset.set(title, 'newTitle3'); 257 try { 258 await photoAsset.commitModify(); 259 let newPhotoAssetTitle: photoAccessHelper.MemberType = photoAsset.get(title); 260 console.info('photoAsset get newPhotoAssetTitle = ', newPhotoAssetTitle); 261 } catch (err) { 262 console.error(`release failed. error: ${err.code}, ${err.message}`); 263 } 264} 265``` 266 267## close<sup>(deprecated)</sup> 268 269close(fd: number, callback: AsyncCallback<void>): void 270 271关闭当前文件，使用callback方式返回异步结果。 272 273> **说明：** 274> 275> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。 276 277**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| -------- | ------------------------- | ---- | ----- | 283| fd | number | 是 | 文件描述符。 | 284| callback | AsyncCallback<void> | 是 | callback返回void。 | 285 286**错误码：** 287 288接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 289 290| 错误码ID | 错误信息 | 291| -------- | ---------------------------------------- | 292| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 293| 13900020 | Invalid argument. | 294| 14000011 | System inner fail. | 295 296**示例：** 297 298phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 299 300```ts 301import { dataSharePredicates } from '@kit.ArkData'; 302 303async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 304 console.info('closeDemo'); 305 try { 306 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 307 let fetchOption: photoAccessHelper.FetchOptions = { 308 fetchColumns: [], 309 predicates: predicates 310 }; 311 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 312 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 313 let fd: number = await photoAsset.open('rw'); 314 console.info('file fd', fd); 315 photoAsset.close(fd, (err) => { 316 if (err === undefined) { 317 console.info('asset close succeed.'); 318 } else { 319 console.error(`close failed, error: ${err.code}, ${err.message}`); 320 } 321 }); 322 } catch (err) { 323 console.error(`close failed, error: ${err.code}, ${err.message}`); 324 } 325} 326``` 327 328## close<sup>(deprecated)</sup> 329 330close(fd: number): Promise<void> 331 332关闭当前文件，使用promise方式返回异步结果。 333 334> **说明：** 335> 336> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。对应的close接口一并废弃。 337 338**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| ---- | ------ | ---- | ----- | 344| fd | number | 是 | 文件描述符。 | 345 346**返回值：** 347 348| 类型 | 说明 | 349| ------------------- | ---------- | 350| Promise<void> | Promise对象，返回void。 | 351 352**错误码：** 353 354接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 355 356| 错误码ID | 错误信息 | 357| -------- | ---------------------------------------- | 358| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 359| 13900020 | Invalid argument. | 360| 14000011 | System inner fail. | 361 362**示例：** 363 364phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 365 366```ts 367import { dataSharePredicates } from '@kit.ArkData'; 368 369async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 370 console.info('closeDemo'); 371 try { 372 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 373 let fetchOption: photoAccessHelper.FetchOptions = { 374 fetchColumns: [], 375 predicates: predicates 376 }; 377 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 378 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 379 let fd = await asset.open('rw'); 380 console.info('file fd', fd); 381 await asset.close(fd); 382 console.info('asset close succeed.'); 383 } catch (err) { 384 console.error(`close failed, error: ${err.code}, ${err.message}`); 385 } 386} 387``` 388 389## getThumbnail 390 391getThumbnail(callback: AsyncCallback<image.PixelMap>): void 392 393获取文件的缩略图，使用callback方式返回异步结果。 394 395**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 396 397**需要权限**：ohos.permission.READ_IMAGEVIDEO 398 399**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404| -------- | ----------------------------------- | ---- | ---------------- | 405| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | callback返回缩略图的PixelMap。 | 406 407**错误码：** 408 409接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 410 411错误码13900012，请参考[开发准备](../../media/medialibrary/photoAccessHelper-preparation.md)。 412 413| 错误码ID | 错误信息 | 414| -------- | ---------------------------------------- | 415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 416| 13900012 | Permission denied. | 417| 13900020 | Invalid argument. | 418| 14000011 | System inner fail. | 419 420**示例：** 421 422phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 423 424```ts 425import { dataSharePredicates } from '@kit.ArkData'; 426 427async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 428 console.info('getThumbnailDemo'); 429 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 430 let fetchOption: photoAccessHelper.FetchOptions = { 431 fetchColumns: [], 432 predicates: predicates 433 }; 434 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 435 let asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 436 console.info('asset displayName = ', asset.displayName); 437 asset.getThumbnail((err, pixelMap) => { 438 if (err === undefined) { 439 console.info('getThumbnail successful ' + pixelMap); 440 } else { 441 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 442 } 443 }); 444} 445``` 446 447## getThumbnail 448 449getThumbnail(size: image.Size, callback: AsyncCallback<image.PixelMap>): void 450 451获取文件的缩略图，传入缩略图尺寸，使用callback方式返回异步结果。 452 453**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 454 455**需要权限**：ohos.permission.READ_IMAGEVIDEO 456 457**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 458 459**参数：** 460 461| 参数名 | 类型 | 必填 | 说明 | 462| -------- | ----------------------------------- | ---- | ---------------- | 463| size | [image.Size](../apis-image-kit/arkts-apis-image-i.md#size) | 是 | 缩略图尺寸。 | 464| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | callback返回缩略图的PixelMap。 | 465 466**错误码：** 467 468接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 469 470错误码13900012，请参考[开发准备](../../media/medialibrary/photoAccessHelper-preparation.md)。 471 472| 错误码ID | 错误信息 | 473| -------- | ---------------------------------------- | 474| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 475| 13900012 | Permission denied. | 476| 13900020 | Invalid argument. | 477| 14000011 | System inner fail. | 478 479**示例：** 480 481phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 482 483```ts 484import { dataSharePredicates } from '@kit.ArkData'; 485import { image } from '@kit.ImageKit'; 486 487async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 488 console.info('getThumbnailDemo'); 489 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 490 let fetchOption: photoAccessHelper.FetchOptions = { 491 fetchColumns: [], 492 predicates: predicates 493 }; 494 let size: image.Size = { width: 720, height: 720 }; 495 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 496 let asset = await fetchResult.getFirstObject(); 497 console.info('asset displayName = ', asset.displayName); 498 asset.getThumbnail(size, (err, pixelMap) => { 499 if (err === undefined) { 500 console.info('getThumbnail successful ' + pixelMap); 501 } else { 502 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 503 } 504 }); 505} 506``` 507 508## getThumbnail 509 510getThumbnail(size?: image.Size): Promise<image.PixelMap> 511 512获取文件的缩略图，传入缩略图尺寸，使用promise方式返回异步结果。 513 514**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 515 516**需要权限**：ohos.permission.READ_IMAGEVIDEO 517 518**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 519 520**参数：** 521 522| 参数名 | 类型 | 必填 | 说明 | 523| ---- | -------------- | ---- | ----- | 524| size | [image.Size](../apis-image-kit/arkts-apis-image-i.md#size) | 否 | 缩略图尺寸。 | 525 526**返回值：** 527 528| 类型 | 说明 | 529| ----------------------------- | --------------------- | 530| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象，返回缩略图的PixelMap。 | 531 532**错误码：** 533 534接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 535 536错误码13900012，请参考[开发准备](../../media/medialibrary/photoAccessHelper-preparation.md)。 537 538| 错误码ID | 错误信息 | 539| -------- | ---------------------------------------- | 540| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 541| 13900012 | Permission denied. | 542| 13900020 | Invalid argument. | 543| 14000011 | System inner fail. | 544 545**示例：** 546 547phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 548 549```ts 550import { dataSharePredicates } from '@kit.ArkData'; 551import { image } from '@kit.ImageKit'; 552import { BusinessError } from '@kit.BasicServicesKit'; 553 554async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 555 console.info('getThumbnailDemo'); 556 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 557 let fetchOption: photoAccessHelper.FetchOptions = { 558 fetchColumns: [], 559 predicates: predicates 560 }; 561 let size: image.Size = { width: 720, height: 720 }; 562 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption); 563 let asset = await fetchResult.getFirstObject(); 564 console.info('asset displayName = ', asset.displayName); 565 asset.getThumbnail(size).then((pixelMap) => { 566 console.info('getThumbnail successful ' + pixelMap); 567 }).catch((err: BusinessError) => { 568 console.error(`getThumbnail fail with error: ${err.code}, ${err.message}`); 569 }); 570} 571``` 572 573## clone<sup>14+</sup> 574 575clone(title: string): Promise<PhotoAsset> 576 577克隆资产。可设置文件名，但不支持修改文件类型。 578 579**需要权限**：ohos.permission.WRITE\_IMAGEVIDEO 580 581**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 582 583**参数：** 584 585| 参数名 | 类型 | 必填 | 说明 | 586| ---------- | ------- | ---- | ---------------------------------- | 587| title| string | 是 | 克隆后资产的标题。参数规格为：<br>- 不应包含扩展名。<br>- 文件名字符串长度为1~255（资产文件名为标题+扩展名）。<br>- 不允许出现的非法英文字符，包括：. \ / : * ? " ' ` < > \| { } [ ] | 588 589**返回值：** 590 591| 类型 | 说明 | 592| ------------------- | ----------------------- | 593| Promise<[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)> | Promise对象，返回[PhotoAsset](arkts-apis-photoAccessHelper-PhotoAsset.md)。 | 594 595**错误码：** 596 597接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 598 599| 错误码ID | 错误信息 | 600| :------- | :-------------------------------- | 601| 201 | Permission denied. | 602| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 603| 14000011 | Internal system error. It is recommended to retry and check the logs.Possible causes: 1. Database corrupted; 2. The file system is abnormal; 3. The IPC request timed out. | 604 605**示例：** 606 607phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 608 609```ts 610import { dataSharePredicates } from '@kit.ArkData'; 611import { systemDateTime } from '@kit.BasicServicesKit'; 612 613async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 614 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 615 let fetchOptions: photoAccessHelper.FetchOptions = { 616 fetchColumns: [], 617 predicates: predicates 618 }; 619 try { 620 let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 621 let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 622 let title: string = systemDateTime.getTime().toString(); 623 let newAsset: photoAccessHelper.PhotoAsset = await photoAsset.clone(title); 624 console.info('get new asset successfully'); 625 } catch (error) { 626 console.error(`failed to get new asset. message = ${error.code}, ${error.message}`); 627 } 628} 629``` 630 631## getReadOnlyFd<sup>(deprecated)</sup> 632 633getReadOnlyFd(callback: AsyncCallback<number>): void 634 635以只读方式打开当前文件，使用callback方式返回异步结果。 636 637> **说明：** 638> 639> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。 640 641**注意**：使用完毕后调用close释放文件描述符。 642 643**需要权限**：ohos.permission.READ_IMAGEVIDEO 644 645**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 646 647**参数：** 648 649| 参数名 | 类型 | 必填 | 说明 | 650| -------- | --------------------------- | ---- | ----------------------------------- | 651| callback | AsyncCallback<number> | 是 | callback返回文件描述符。 | 652 653**错误码：** 654 655接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 656 657在API 13及之前的版本，无相关权限返回错误码13900012；从API 14开始，无相关权限返回错误码201。 658 659| 错误码ID | 错误信息 | 660| -------- | ---------------------------------------- | 661| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 662| 201 | Permission denied. | 663| 13900020 | Invalid argument. | 664| 14000011 | System inner fail. | 665 666**示例：** 667 668phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 669 670```ts 671import { dataSharePredicates } from '@kit.ArkData'; 672 673async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 674 console.info('getReadOnlyFdDemo'); 675 // 需要保证设备中存在可读取图片视频文件。 676 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 677 let fetchOptions: photoAccessHelper.FetchOptions = { 678 fetchColumns: [], 679 predicates: predicates 680 }; 681 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 682 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 683 photoAsset.getReadOnlyFd((err, fd) => { 684 if (fd !== undefined) { 685 console.info('File fd' + fd); 686 photoAsset.close(fd); 687 } else { 688 console.error(`getReadOnlyFd err: ${err.code}, ${err.message}`); 689 } 690 }); 691} 692``` 693 694## getReadOnlyFd<sup>(deprecated)</sup> 695 696getReadOnlyFd(): Promise<number> 697 698以只读方式打开当前文件，使用promise方式返回异步结果。 699 700> **说明：** 701> 702> 从API version 10开始支持，从API version 11开始废弃。出于安全考量，不再提供获取正式媒体文件句柄的接口。 703 704**注意**：返回的文件描述符在使用完毕后需要调用close进行释放。 705 706**需要权限**：ohos.permission.READ_IMAGEVIDEO 707 708**系统能力**：SystemCapability.FileManagement.PhotoAccessHelper.Core 709 710**返回值：** 711 712| 类型 | 说明 | 713| --------------------- | ------------- | 714| Promise<number> | Promise对象，返回文件描述符。 | 715 716**错误码：** 717 718接口抛出错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[文件管理错误码](../apis-core-file-kit/errorcode-filemanagement.md)。 719 720在API 13及之前的版本，无相关权限返回错误码13900012；从API 14开始，无相关权限返回错误码201。 721 722| 错误码ID | 错误信息 | 723| -------- | ---------------------------------------- | 724| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 725| 201 | Permission denied. | 726| 13900020 | Invalid argument. | 727| 14000011 | System inner fail. | 728 729**示例：** 730 731phAccessHelper的创建请参考[photoAccessHelper.getPhotoAccessHelper](arkts-apis-photoAccessHelper-f.md#photoaccesshelpergetphotoaccesshelper)的示例使用。 732 733```ts 734import { dataSharePredicates } from '@kit.ArkData'; 735 736async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) { 737 console.info('getReadOnlyFdDemo'); 738 try { 739 // 需要保证设备中存在可读取图片视频文件。 740 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 741 let fetchOptions: photoAccessHelper.FetchOptions = { 742 fetchColumns: [], 743 predicates: predicates 744 }; 745 let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 746 let photoAsset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject(); 747 let fd: number = await photoAsset.getReadOnlyFd(); 748 if (fd !== undefined) { 749 console.info('File fd' + fd); 750 photoAsset.close(fd); 751 } else { 752 console.error('getReadOnlyFd fail'); 753 } 754 } catch (err) { 755 console.error(`getReadOnlyFd demo err: ${err.code}, ${err.message}`); 756 } 757} 758``` 759 760
