• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 媒体资源使用指导
2
3应用可以通过photoAccessHelper的接口，对媒体资源（图片、视频）进行相关操作。
4
5> **说明：**
6>
7> - 在进行功能开发前，请开发者查阅[开发准备](photoAccessHelper-preparation.md)，了解如何获取相册管理模块实例和如何申请相册管理模块功能开发相关权限。
8> - 文档中使用到photoAccessHelper的地方默认为使用开发准备中获取的对象，如未添加此段代码报photoAccessHelper未定义的错误请自行添加。
9
10为了保证应用的运行效率，大部分photoAccessHelper的接口调用都是异步的。以下异步调用的API示例均采用Promise函数，更多方式可以查阅[API参考](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md)。
11
12## 获取指定媒体资源
13
14开发者可以根据特定的条件查询媒体资源，如指定类型、指定日期、指定相册等。
15
16应用通过调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1)获取媒体资源，并传入[FetchOptions](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchoptions)对象指定检索条件。如无特别说明，文档中涉及的待获取的资源均视为已经预置且在数据库中存在相应数据。如出现按照示例代码执行出现获取资源为空的情况请确认文件是否已预置，数据库中是否存在该文件的数据。
17
18如果只想获取某个位置的对象（如第一个、最后一个、指定索引等），可以通过[FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult)中的接口获取对应位置的媒体资源对象。
19
20**前提条件**
21
22- 获取相册管理模块photoAccessHelper实例。
23- [申请相册管理模块读权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
24- 导入[dataSharePredicates](../../reference/apis-arkdata/js-apis-data-dataSharePredicates.md)模块。
25
26### 指定媒体文件名获取图片或视频资源
27
28下面以查询文件名为'test.jpg'的图片资源为例。
29
30```ts
31import { dataSharePredicates } from '@kit.ArkData';
32import { photoAccessHelper } from '@kit.MediaLibraryKit';
33import { common } from '@kit.AbilityKit';
34
35// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
36let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
37let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
38
39async function example() {
40  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
41  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
42  let fetchOptions: photoAccessHelper.FetchOptions = {
43    fetchColumns: [],
44    predicates: predicates
45  };
46  try {
47    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
48    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
49    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
50    fetchResult.close();
51  } catch (err) {
52    console.error('getAssets failed with err: ' + err);
53  }
54}
55```
56
57## 获取图片和视频缩略图
58
59通过接口[PhotoAsset.getThumbnail](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getthumbnail-2)，传入缩略图尺寸，可以获取图片和视频缩略图。缩略图常用于UI界面展示。
60
61**前提条件**
62
63- 获取相册管理模块photoAccessHelper实例。
64- [申请相册管理模块读权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.READ_IMAGEVIDEO'。
65- 导入[dataSharePredicates](../../reference/apis-arkdata/js-apis-data-dataSharePredicates.md)模块。
66
67### 获取某张图片的缩略图
68
69当需要在相册展示图片和视频、编辑预览，应用需要获取某张图片的缩略图。
70
71参考以下示例，获取图片的文件描述符fd后，需要解码为统一的PixelMap，方便在应用中进行图片显示或图片处理，具体请参考[图片解码](../image/image-decoding.md)。
72
73下面以获取一张图片的缩略图为例，缩略图尺寸为720*720。
74
75**开发步骤**
76
771. 建立检索条件，用于获取图片资源。
782. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1)接口获取图片资源。
793. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片。
804. 调用PhotoAsset.getThumbnail获取图片的缩略图的[PixelMap](../../reference/apis-image-kit/js-apis-image.md#pixelmap7)。
81
82```ts
83import { dataSharePredicates } from '@kit.ArkData';
84import { image } from '@kit.ImageKit';
85import { photoAccessHelper } from '@kit.MediaLibraryKit';
86import { common } from '@kit.AbilityKit';
87
88// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
89let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
90let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
91
92async function example() {
93  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
94  let fetchOptions: photoAccessHelper.FetchOptions = {
95    fetchColumns: [],
96    predicates: predicates
97  };
98
99  try {
100    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
101    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
102    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
103    let size: image.Size = { width: 720, height: 720 };
104    let pixelMap: image.PixelMap =  await photoAsset.getThumbnail(size);
105    let imageInfo: image.ImageInfo = await pixelMap.getImageInfo()
106    console.info('getThumbnail successful, pixelMap ImageInfo size: ' + JSON.stringify(imageInfo.size));
107    fetchResult.close();
108  } catch (err) {
109    console.error('getThumbnail failed with err: ' + err);
110  }
111}
112```
113
114<!--Del-->
115## 创建媒体资源
116
117创建[MediaAssetChangeRequest](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#mediaassetchangerequest11)媒体资产变更对象并写入媒体资源内容，然后调用[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口提交创建资产的变更请求。
118
119**前提条件**
120
121- 获取相册管理模块photoAccessHelper实例。
122- [申请相册管理模块读写权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.WRITE_IMAGEVIDEO'。
123
124### 创建图片或视频资源（仅向系统应用开放）
125
126下面以创建一张图片资源为例。
127
128**开发步骤**
129
1301. 定义文件名和创建选项，用于创建图片资源时设置属性。
1312. 调用MediaAssetChangeRequest.createAssetRequest接口创建资产变更请求。
1323. 调用MediaAssetChangeRequest.getWriteCacheHandler接口获取临时文件写句柄，并写入图片资源的内容。
1334. 调用PhotoAccessHelper.applyChanges接口提交资产变更请求。
134
135```ts
136import { photoAccessHelper } from '@kit.MediaLibraryKit';
137import { fileIo } from '@kit.CoreFileKit';
138import { common } from '@kit.AbilityKit';
139
140// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
141let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
142let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
143
144async function example() {
145  try {
146    let displayName: string = 'testPhoto' + Date.now() + '.jpg';
147    let createOption: photoAccessHelper.PhotoCreateOptions = {
148      subtype: photoAccessHelper.PhotoSubtype.DEFAULT
149    };
150    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, displayName, createOption);
151    let fd: number = await assetChangeRequest.getWriteCacheHandler();
152    // write date into fd.
153    await fileIoclose(fd);
154    await phAccessHelper.applyChanges(assetChangeRequest);
155  } catch (err) {
156    console.error(`create asset failed with error: ${err.code}, ${err.message}`);
157  }
158}
159```
160
161应用还可以调用MediaAssetChangeRequest.addResource接口指定媒体资源内容的数据来源，具体包括[应用沙箱](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addresource11)，[ArrayBuffer](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#addresource11-1)和[PhotoProxy](../../reference/apis-media-library-kit/js-apis-photoAccessHelper-sys.md#addresource11)。
162<!--DelEnd-->
163
164## 重命名媒体资源
165
166重命名修改的是文件的PhotoAsset.displayName属性，即文件的显示文件名，包含文件后缀。
167
168调用[MediaAssetChangeRequest.setTitle](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#settitle11)重命名后再通过[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)更新到数据库中完成修改。
169
170在重命名文件之前，需要先获取文件对象，可以通过[FetchResult](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#fetchresult)中的接口获取对应位置的文件。
171
172**前提条件**
173
174- 获取相册管理模块photoAccessHelper实例。
175- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.WRITE_IMAGEVIDEO'和'ohos.permission.READ_IMAGEVIDEO'。
176
177下面以将获取的图片资源中第一个文件重命名为例。
178
179**开发步骤**
180
1811. 建立检索条件，用于获取图片资源。
1822. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1)接口获取目标图片资源。
1833. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片，即要重命名的图片对象。
1844. 调用[MediaAssetChangeRequest.setTitle](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#settitle11)接口将图片重命名为新的名字。
1855. 调用[PhotoAccessHelper.applyChanges](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#applychanges11)接口将修改的图片属性更新到数据库中完成修改。
186
187```ts
188import { dataSharePredicates } from '@kit.ArkData';
189import { photoAccessHelper } from '@kit.MediaLibraryKit';
190import { common } from '@kit.AbilityKit';
191
192// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
193let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
194let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
195
196async function example() {
197  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
198  let fetchOptions: photoAccessHelper.FetchOptions = {
199    fetchColumns: ['title'],
200    predicates: predicates
201  };
202  let newTitle: string = 'newTestPhoto';
203
204  try {
205    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
206    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
207    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
208    assetChangeRequest.setTitle(newTitle);
209    await phAccessHelper.applyChanges(assetChangeRequest);
210    fetchResult.close();
211  } catch (err) {
212    console.error(`rename failed with error: ${err.code}, ${err.message}`);
213  }
214}
215```
216
217## 将文件放入回收站
218
219通过[MediaAssetChangeRequest.deleteAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#deleteassets11)可以将文件放入回收站。
220
221放入回收站的文件将会保存30天，30天后会自动彻底删除。在此期间，应用用户可以通过系统应用“文件管理”或“图库”恢复文件。
222
223**前提条件**
224
225- 获取相册管理模块photoAccessHelper实例。
226- [申请相册管理模块权限](photoAccessHelper-preparation.md#申请相册管理模块功能相关权限)'ohos.permission.WRITE_IMAGEVIDEO'和'ohos.permission.READ_IMAGEVIDEO'。
227
228下面以将文件检索结果中第一个文件放入回收站为例。
229
230**开发步骤**
231
2321. 建立检索条件，用于获取图片资源。
2332. 调用[PhotoAccessHelper.getAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets-1)接口获取目标图片资源。
2343. 调用[FetchResult.getFirstObject](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getfirstobject-1)接口获取第一张图片，即要放入回收站的图片对象。
2354. 调用[MediaAssetChangeRequest.deleteAssets](../../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#deleteassets11)接口将文件放入回收站。
236
237```ts
238import { dataSharePredicates } from '@kit.ArkData';
239import { photoAccessHelper } from '@kit.MediaLibraryKit';
240import { common } from '@kit.AbilityKit';
241
242// 请在组件内获取context，确保this.getUiContext().getHostContext()返回结果为UIAbilityContext
243let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
244let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
245
246async function example() {
247  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
248  let fetchOptions: photoAccessHelper.FetchOptions = {
249    fetchColumns: [],
250    predicates: predicates
251  };
252
253  try {
254    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
255    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
256    await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [photoAsset]);
257    fetchResult.close();
258  } catch (err) {
259    console.error(`deleteAssets failed with error: ${err.code}, ${err.message}`);
260  }
261}
262```
263