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