1# 用户文件uri介绍
2
3用户文件uri是文件的唯一标识，在对用户文件进行访问与修改等操作时往往都会使用到uri，不建议开发者解析uri中的片段用于业务代码开发，不同类型的uri使用方式将在下文详细介绍。
4
5## uri的类型
6
7uri类型可以归纳为文档类uri和媒体文件uri两类
8
9- 文档类uri：由picker拉起文件管理器选择或保存返回，以及通过fileAccess模块获取。具体获取方式参见[文档类uri获取方式](#文档类uri获取方式)。
10- 媒体文件uri：由picker通过拉起图库选择图片或者视频返回，通过photoAccessHelper模块获取图片或者视频文件的uri，以及通过userFileManager模块获取图片、视频或者音频文件的uri。具体获取方式参见[媒体文件uri获取方式](#媒体文件uri获取方式)。
11
12![user-file-uri-intro](figures/user-file-uri-intro.png)
13
14## 文档类uri
15
16### 文档类uri介绍
17
18**文档类uri的格式类型为：**
19
20'file://docs/storage/Users/currentUser/\<relative_path\>/test.txt'
21
22**其中各个字段表示的含义为：**
23
24| uri字段          | 说明        |
25| ------------- | ------------------- |
26| 'file://docs/storage/Users/currentUser/' | 文件管理器的根目录。|
27| '\<relative_path\>/' | 文件在根目录下的相对路径。例如：'Download/'和'Documents/'。|
28| 'test.txt' | 用户文件系统中存储的文件名，支持的文件类型为文件管理器支持的所有类型，以文件管理器为准。例如txt、jpg、mp4和mp3等格式的文件。|
29
30### 文档类uri获取方式
31
321. 通过[DocumentViewPicker接口](../reference/apis-core-file-kit/js-apis-file-picker.md#documentviewpicker)选择或保存文件，返回选择或保存的文件uri。
33
342. 通过[AudioViewPicker接口](../reference/apis-core-file-kit/js-apis-file-picker.md#audioviewpicker)选择或保存文件，返回选择或保存的文件uri。<!--Del-->
35
363. 通过[fileAccess模块](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md)获取文档类目录下的文件得到对应文件的[FileInfo](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#fileinfo)对象，此对象中就包含对应文件或者目录的uri属性，此模块中的接口为系统接口，使用此模块需要注意应用是否为系统应用。支持获取文件uri的目录有：
37   - 外部存储目录
38   - Docs目录
39   - Download目录
40   - Desktop目录
41   - Documents目录
42   - Share共享盘目录
43<!--DelEnd-->
44
45### 文档类uri的使用方式
46
47normal等级的应用使用此类uri的方式只能通过[fs模块](../reference/apis-core-file-kit/js-apis-file-fs.md)进行进一步处理，其他模块使用此uri是会报没有权限的错误。示例代码参见picker中的[选择文档类文件](./select-user-file.md#选择文档类文件)和[保存文档类文件](./save-user-file.md#保存文档类文件)。<!--Del-->
48
49system_basic等级及以上的应用使用此类uri的方式除了上述通过fs模块外还可以通过[fileAccess模块](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md)进行进一步处理，使用此模块需要在配置文件module.json5中声明ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 权限，此权限为system_basic权限，仅供系统应用使用。其他模块使用此uri会报没有权限的错误。下面示例为使用fileAccess模块创建文件得到uri后对其进行重命名操作：
50
511. 通过[fileAccess模块](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md)获取文件uri。
522. 使用获取到的文件uri进行重命名操作。
53
54```ts
55import { BusinessError } from '@kit.BasicServicesKit';
56import { Want } from '@kit.AbilityKit';
57import { common } from '@kit.AbilityKit';
58import { fileAccess } from '@kit.CoreFileKit';
59// context 是EntryAbility 传过来的context
60let context = getContext(this) as common.UIAbilityContext;
61
62async function example() {
63    let fileAccessHelper: fileAccess.FileAccessHelper;
64    // wantInfos 从getFileAccessAbilityInfo()获取
65    let wantInfos: Array<Want> = [
66      {
67        bundleName: "com.ohos.UserFile.ExternalFileManager",
68        abilityName: "FileExtensionAbility",
69      },
70    ]
71    try {
72      fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos);
73      if (!fileAccessHelper) {
74        console.error("createFileAccessHelper interface returns an undefined object");
75      }
76      // 以内置存储目录为例
77      // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri
78      // 开发者应根据自己实际获取的uri进行开发
79      let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
80      let displayName: string = "file1.txt";
81      let fileUri: string;
82      try {
83        // 创建文件返回该文件的uri
84        fileUri = await fileAccessHelper.createFile(sourceUri, displayName);
85        if (!fileUri) {
86          console.error("createFile return undefined object");
87        }
88        console.log("createFile success, fileUri: " + JSON.stringify(fileUri));
89        // 将刚创建的文件进行重命名，返回新文件的uri
90        let renameUri = await fileAccessHelper.rename(fileUri, "renameFile.txt");
91        console.log("rename success, renameUri: " + JSON.stringify(renameUri));
92      } catch (err) {
93        let error: BusinessError = err as BusinessError;
94        console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message);
95      }
96    } catch (err) {
97      let error: BusinessError = err as BusinessError;
98      console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message);
99    }
100  }
101```
102<!--DelEnd-->
103
104## 媒体文件uri
105
106### 媒体文件uri介绍
107
108**媒体文件uri的格式类型为：**
109
110图片uri格式：
111
112- 'file://media/Photo/\<id\>/IMG_datetime_0001/displayName.jpg'
113
114视频uri格式：
115
116- 'file://media/Photo/\<id>/VID_datetime_0001/displayName.mp4'
117
118音频uri格式：
119
120- 'file://media/Audio/\<id>/AUD_datetime_0001/displayName.mp3'
121
122**其中各个字段表示的含义为：**
123
124| uri字段          | 说明        |
125| ------------- | ------------------- |
126| 'file://media' | 表示这个uri是媒体文件。 |
127| 'Photo' | Photo表示这个uri是媒体文件中的图片或者视频类文件。 |
128| 'Audio' | 表示这个uri是媒体文件中的音频类文件。 |
129| '\<id>' | 表示在数据库中多个表中处理后的值，并不是指表中的file_id列，注意请不要使用此id去数据库中查询具体文件。 |
130| 'IMG_datetime_0001' | 表示图片文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |
131| 'VID_datetime_0001' | 表示视频文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |
132| 'AUD_datetime_0001' | 表示音频文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |
133|<!--DelRow--> 'displayName.jpg' | 表示图片文件对外展示的displayName，使用[userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify)接口重命名修改的就是这个值，需要注意这个值修改后uri也会发生改变。 |
134|<!--DelRow--> 'displayName.mp4' | 表示视频文件对外展示的displayName，使用[userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify)接口重命名修改的就是这个值，需要注意这个值修改后uri也会发生改变。 |
135|<!--DelRow--> 'displayName.mp3' | 表示音频文件对外展示的displayName，使用[userFileManager.commitModify](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#commitmodify)接口重命名修改的就是这个值，需要注意这个值修改后uri也会发生改变。 |
136
137### 媒体文件uri获取方式
138
1391. 通过[PhotoAccessHelper的PhotoViewPicker](../media/medialibrary/photoAccessHelper-photoviewpicker.md)选择媒体文件，返回选择的媒体文件文件的uri。
140
1412. 通过[photoAccessHelper模块](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md)中的[getAssets](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets)或[createAsset](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#createasset)接口获取媒体文件对应文件的uri。<!--Del-->
142
1433. 通过[userFileManager模块](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md)中的[getPhotoAssets](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#getphotoassets)、[getAudioAssets](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#getaudioassets)、[createAudioAsset](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#createaudioasset10)或[createPhotoAsset](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md#createphotoasset)接口获取媒体文件对应文件的uri。
144<!--DelEnd-->
145
146### 媒体文件uri的使用方式
147
148normal等级的应用使用此类uri可以通过[photoAccessHelper模块](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md)进行进一步处理。示例代码参见媒体资源使用指导中的[指定URI获取图片或视频资源](../media/medialibrary/photoAccessHelper-photoviewpicker.md#指定uri获取图片或视频资源)。此接口需要申请相册管理模块读权限'ohos.permission.READ_IMAGEVIDEO'，在使用中需要注意应用是否有此权限。<!--Del-->
149
150system_basic等级及以上的应用使用此类uri的方式除了上述通过photoAccessHelper模块外还可以通过[userFileManager模块](../reference/apis-core-file-kit/js-apis-userFileManager-sys.md)进行进一步处理，接口详细使用方式见接口文档。
151<!--DelEnd-->
152
153若normal等级的应用不想申请权限也可以通过临时授权的方式使用[PhotoAccessHelper的PhotoViewPicker](../media/medialibrary/photoAccessHelper-photoviewpicker.md)得到的uri使用[photoAccessHelper.getAssets接口](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getassets)获取对应uri的PhotoAsset对象。这种方式获取的对象可以调用[getThumbnail](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#getthumbnail)获取缩略图和使用[get接口](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#get)读取[PhotoKeys](../reference/apis-media-library-kit/js-apis-photoAccessHelper.md#photokeys)中的部分信息。
154
155以下为PhotoKeys中支持临时授权方式可以读取的信息：
156
157| 名称          | 值              | 说明                                                       |
158| ------------- | ------------------- | ---------------------------------------------------------- |
159| URI           | 'uri'                 | 文件uri。                                                   |
160| PHOTO_TYPE    | 'media_type'           | 媒体文件类型。                                              |
161| DISPLAY_NAME  | 'display_name'        | 显示名字。                                                   |
162| SIZE          | 'size'                | 文件大小。                                                   |
163| DATE_ADDED    | 'date_added'          | 添加日期（添加文件时间距1970年1月1日的秒数值）。             |
164| DATE_MODIFIED | 'date_modified'       | 修改日期（修改文件时间距1970年1月1日的秒数值，修改文件名不会改变此值，当文件内容发生修改时才会更新）。 |
165| DURATION      | 'duration'            | 持续时间（单位：毫秒）。                                    |
166| WIDTH         | 'width'               | 图片宽度（单位：像素）。                                    |
167| HEIGHT        | 'height'              | 图片高度（单位：像素）。                                      |
168| DATE_TAKEN    | 'date_taken'          | 拍摄日期（文件拍照时间距1970年1月1日的秒数值）。                |
169| ORIENTATION   | 'orientation'         | 图片文件的方向。                                             |
170| TITLE         | 'title'               | 文件标题。                                                   |
171
172下面为通过临时授权方式使用媒体文件uri进行获取缩略图和读取文件部分信息的示例代码：
173
174```ts
175import { photoAccessHelper } from '@kit.MediaLibraryKit';
176import { BusinessError } from '@kit.BasicServicesKit';
177import { dataSharePredicates } from '@kit.ArkData';
178
179// 定义一个uri数组，用于接收PhotoViewPicker选择图片返回的uri
180let uris: Array<string> = [];
181const context = getContext(this);
182
183// 调用PhotoViewPicker.select选择图片
184async function photoPickerGetUri() {
185  try {
186    let PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
187    PhotoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
188    PhotoSelectOptions.maxSelectNumber = 1;
189    let photoPicker = new photoAccessHelper.PhotoViewPicker();
190    photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult: photoAccessHelper.PhotoSelectResult) => {
191      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
192      uris = PhotoSelectResult.photoUris;
193    }).catch((err: BusinessError) => {
194      console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err));
195    });
196  } catch (error) {
197    let err: BusinessError = error as BusinessError;
198    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
199  }
200}
201
202async function uriGetAssets() {
203try {
204    let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
205    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
206    // 配置查询条件，使用PhotoViewPicker选择图片返回的uri进行查询
207    predicates.equalTo('uri', uris[0]);
208    let fetchOption: photoAccessHelper.FetchOptions = {
209      fetchColumns: [photoAccessHelper.PhotoKeys.WIDTH, photoAccessHelper.PhotoKeys.HEIGHT, photoAccessHelper.PhotoKeys.TITLE, photoAccessHelper.PhotoKeys.DURATION],
210      predicates: predicates
211    };
212    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
213    // 得到uri对应的PhotoAsset对象，读取文件的部分信息
214    const asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
215    console.info('asset displayName: ', asset.displayName);
216    console.info('asset uri: ', asset.uri);
217    console.info('asset photoType: ', asset.photoType);
218    console.info('asset width: ', asset.get(photoAccessHelper.PhotoKeys.WIDTH));
219    console.info('asset height: ', asset.get(photoAccessHelper.PhotoKeys.HEIGHT));
220    console.info('asset title: ' + asset.get(photoAccessHelper.PhotoKeys.TITLE));
221    // 获取缩略图
222    asset.getThumbnail((err, pixelMap) => {
223      if (err == undefined) {
224        console.info('getThumbnail successful ' + JSON.stringify(pixelMap));
225      } else {
226        console.error('getThumbnail fail', err);
227      }
228    });
229  } catch (error){
230    console.error('uriGetAssets failed with err: ' + JSON.stringify(error));
231  }
232}
233```
234<!--Del-->
235## 通过uri复制文件（仅对系统应用开放）
236
237用户复制文件到指定目录
238
2391. 通过[createFileAccessHelper](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#fileaccesscreatefileaccesshelper)创建fileAccessHelper helper。
240
2412. 获取源文件的srcUri。
242
2433. 获取目的路径的destUri。
244
2454. 获取备用名 fileName。
246
2475. 使用helper.[copyFile](../reference/apis-core-file-kit/js-apis-fileAccess-sys.md#copyfile11)(srcUri, destUri, fileName) 进行文件操作。
248
249复制文件代码示例：
250
251```
252import { BusinessError } from '@kit.BasicServicesKit';
253import { Want } from '@kit.AbilityKit';
254import { common } from '@kit.AbilityKit';
255import { fileAccess } from '@kit.CoreFileKit';
256
257// context 是EntryAbility 传过来的context
258let context = getContext(this) as common.UIAbilityContext;
259async function example() {
260    let fileAccessHelper: fileAccess.FileAccessHelper;
261    // wantInfos 从getFileAccessAbilityInfo()获取
262    let wantInfos: Array<Want> = [
263      {
264        bundleName: "com.ohos.UserFile.ExternalFileManager",
265        abilityName: "FileExtensionAbility",
266      },
267    ]
268    try {
269      fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos);
270      if (!fileAccessHelper) {
271        console.error("createFileAccessHelper interface returns an undefined object");
272      }
273      // 以内置存储目录为例
274      // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri
275      // 开发者应根据自己实际获取的uri进行开发
276      let sourceUri: string = "file://docs/storage/Users/currentUser/Download/one.txt";
277      // 将文件复制到的位置uri
278      let destUri: string = "file://docs/storage/Users/currentUser/Documents";
279      // 如果文件名冲突，要使用的文件名
280      let displayName: string = "file1.txt";
281      // 存放返回的uri
282      let fileUri: string;
283      try {
284        // 复制文件返回该文件的uri
285        fileUri = await fileAccessHelper.copyFile(sourceUri, destUri, displayName);
286        if (!fileUri) {
287          console.error("copyFile return undefined object");
288        }
289        console.log("copyFile success, fileUri: " + JSON.stringify(fileUri));
290      } catch (err) {
291        let error: BusinessError = err as BusinessError;
292        console.error("copyFile failed, errCode:" + error.code + ", errMessage:" + error.message);
293      }
294    } catch (err) {
295      let error: BusinessError = err as BusinessError;
296      console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message);
297    }
298  }
299```
300<!--DelEnd-->