用户文件URI是文件的唯一标识，在对用户文件进行访问与修改等操作时往往都会使用到URI，不建议开发者解析URI中的片段用于业务代码开发，不同类型的URI使用方式将在下文详细介绍。

## URI的类型

URI类型可以归纳为文档类URI和媒体文件URI两类

* 文档类URI：由picker拉起文件管理器选择或保存返回，以及通过fileAccess模块获取。具体获取方式参见[文档类URI获取方式](/consumer/cn/doc/harmonyos-guides/user-file-uri-intro#文档类uri获取方式)。
* 媒体文件URI：由picker通过拉起图库选择图片或者视频返回，通过photoAccessHelper模块获取图片或者视频文件的URI，以及通过userFileManager模块获取图片、视频或者音频文件的URI。具体获取方式参见[媒体文件URI获取方式](/consumer/cn/doc/harmonyos-guides/user-file-uri-intro#媒体文件uri获取方式)。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/42/v3/tJxibGCZQ12cWUGYpqEy8A/zh-cn_image_0000002540771544.png?HW-CC-KV=V1&HW-CC-Date=20260414T041131Z&HW-CC-Expire=86400&HW-CC-Sign=253EF579C180B2471BF868CA5A65FEA456C1A1E9AD49F0CDFABDFEB83BDF22CE)

## 文档类URI

### 文档类URI介绍

**文档类URI的格式类型为：**

'file://docs/storage/Users/currentUser/<relative\_path>/test.txt'

**其中各个字段表示的含义为：**

展开

| URI字段 | 说明 |
| --- | --- |
| 'file://docs/storage/Users/currentUser/' | 文件管理器的根目录。 |
| '<relative\_path>/' | 文件在根目录下的相对路径。例如：'Download/'和'Documents/'。 |
| 'test.txt' | 用户文件系统中存储的文件名，支持的文件类型为文件管理器支持的所有类型，以文件管理器为准。例如txt、jpg、mp4和mp3等格式的文件。 |

### 文档类URI获取方式

1. 通过[DocumentViewPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-picker#documentviewpicker)接口选择或保存文件，返回选择或保存的文件URI。
2. 通过[AudioViewPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-picker#audioviewpicker)接口选择或保存文件，返回选择或保存的文件URI。

### 文档类URI的使用方式

normal等级的应用使用此类URI的方式只能通过[文件管理](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-fs)进行进一步处理。示例代码参见picker中的[选择文档类文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/select-user-file#选择文档类文件)和[保存文档类文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/save-user-file#保存文档类文件)。

## 媒体文件URI

### 媒体文件URI介绍

**媒体文件URI的格式类型为：**

图片URI格式：

* 'file://media/Photo/<id>/IMG\_datetime\_0001/displayName.jpg'

视频URI格式：

* 'file://media/Photo/<id>/VID\_datetime\_0001/displayName.mp4'

音频URI格式：

* 'file://media/Audio/<id>/AUD\_datetime\_0001/displayName.mp3'

**其中各个字段表示的含义为：**

展开

| URI字段 | 说明 |
| --- | --- |
| 'file://media' | 表示这个URI是媒体文件。 |
| 'Photo' | 表示这个URI是媒体文件中的图片或者视频类文件。 |
| 'Audio' | 表示这个URI是媒体文件中的音频类文件。 |
| '<id>' | 表示在数据库中多个表中处理后的值，并不是指表中的file\_id列，注意请不要使用此id去数据库中查询具体文件。 |
| 'IMG\_datetime\_0001' | 表示图片文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |
| 'VID\_datetime\_0001' | 表示视频文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |
| 'AUD\_datetime\_0001' | 表示音频文件在用户文件系统中存储的文件名去掉后缀剩下的部分。 |

### 媒体文件URI获取方式

1. 通过PhotoAccessHelper的[PhotoViewPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoviewpicker)选择媒体文件，返回选择的媒体文件的URI。
2. 通过[photoAccessHelper](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper)模块中的[getAssets](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoaccesshelper#getassets)或[createAsset](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoaccesshelper#createasset)接口获取媒体文件对应文件的URI。

### 媒体文件URI的使用方式

normal等级的应用使用此类URI可以通过[photoAccessHelper](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper)模块进行进一步处理。示例代码参见媒体资源使用指导中的[指定URI获取图片或视频资源](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/photoaccesshelper-photoviewpicker#指定uri获取图片或视频资源)。此接口需要申请相册管理模块读权限（[ohos.permission.READ\_IMAGEVIDEO](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/photoaccesshelper-overview#能力范围)），在使用中需要注意应用是否有此权限。

若normal等级的应用不想申请权限也可以通过临时授权的方式使用PhotoAccessHelper的[PhotoViewPicker](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoviewpicker)得到的URI使用[photoAccessHelper.getAssets](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoaccesshelper#getassets)接口获取对应URI的PhotoAsset对象。通过此方式获取的PhotoAsset对象可调用[getThumbnail](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoasset#getthumbnail)方法获取缩略图，并通过[get](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-photoasset#get)接口方法读取[PhotoKeys](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-photoaccesshelper-e#photokeys)中的部分信息。

以下为PhotoKeys中支持临时授权方式可以读取的信息：

展开

| 名称 | 值 | 说明 |
| --- | --- | --- |
| URI | 'uri' | 文件URI。 |
| PHOTO\_TYPE | 'media\_type' | 媒体文件类型。 |
| DISPLAY\_NAME | 'display\_name' | 显示名字。 |
| SIZE | 'size' | 文件大小。 |
| DATE\_ADDED | 'date\_added' | 文件创建时的Unix时间戳（单位：秒）。 |
| DATE\_MODIFIED | 'date\_modified' | 文件修改时的Unix时间戳（单位：秒）。修改文件名不会改变此值，当文件内容发生修改时才会更新。 |
| DURATION | 'duration' | 持续时间（单位：毫秒）。 |
| WIDTH | 'width' | 图片宽度（单位：像素）。 |
| HEIGHT | 'height' | 图片高度（单位：像素）。 |
| DATE\_TAKEN | 'date\_taken' | 拍摄时的Unix时间戳（单位：秒）。 |
| ORIENTATION | 'orientation' | 图片文件的方向。 |
| TITLE | 'title' | 文件标题。 |

下面为通过临时授权方式使用媒体文件URI进行获取缩略图和读取文件部分信息的示例代码：

收起

自动换行

深色代码主题

复制

```
1. import { BusinessError } from '@kit.BasicServicesKit';
2. // ···
3. import { common } from '@kit.AbilityKit';
4. // ···
5. import { dataSharePredicates } from '@kit.ArkData';
6. // ···
7. import { photoAccessHelper } from '@kit.MediaLibraryKit';

9. // 定义一个uri数组，用于接收PhotoViewPicker选择图片返回的uri
10. let uris: string[] = [];

12. // context 是EntryAbility 传过来的context
13. let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
14. // ···

16. // 调用PhotoViewPicker.select选择图片
17. async function photoPickerGetUri() {
18. try {
19. let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
20. photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
21. // 设置最多可以选择的图片数量为1
22. photoSelectOptions.maxSelectNumber = 1;
23. let photoPicker = new photoAccessHelper.PhotoViewPicker();
24. // 等待用户选择图片
25. let photoSelectResult: photoAccessHelper.PhotoSelectResult = await photoPicker.select(photoSelectOptions);
26. console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(photoSelectResult));
27. uris = photoSelectResult.photoUris;
28. } catch (err) {
29. let err: BusinessError = error as BusinessError;
30. console.error(`PhotoViewPicker failed with err, code is ${err.code}, message is ${err.message}`);
31. }
32. }

34. async function uriGetAssets(): Promise<string> {
35. // 检查uris数组是否为空
36. if (uris.length === 0) {
37. throw new Error('No URIs available');
38. }
39. try {
40. let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
41. let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
42. // 配置查询条件，使用PhotoViewPicker选择图片返回的uri进行查询
43. predicates.equalTo('uri', uris[0]);
44. let fetchOption: photoAccessHelper.FetchOptions = {
45. fetchColumns: [photoAccessHelper.PhotoKeys.WIDTH, photoAccessHelper.PhotoKeys.HEIGHT,
46. photoAccessHelper.PhotoKeys.TITLE, photoAccessHelper.PhotoKeys.DURATION],
47. predicates: predicates
48. };
49. let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> =
50. await phAccessHelper.getAssets(fetchOption);
51. // 得到uri对应的PhotoAsset对象，读取文件的部分信息
52. const asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
53. console.info('asset displayName: ', asset.displayName);
54. console.info('asset uri: ', asset.uri);
55. console.info('asset photoType: ', asset.photoType);
56. console.info('asset width: ', asset.get(photoAccessHelper.PhotoKeys.WIDTH));
57. console.info('asset height: ', asset.get(photoAccessHelper.PhotoKeys.HEIGHT));
58. console.info('asset title: ' + asset.get(photoAccessHelper.PhotoKeys.TITLE));
59. // 获取缩略图
60. asset.getThumbnail((err, pixelMap) => {
61. if (err == undefined) {
62. console.info('getThumbnail successful ' + JSON.stringify(pixelMap));
63. } else {
64. console.error('getThumbnail fail', err);
65. }
66. });
67. // ···
68. } catch (error) {
69. console.error(`uriGetAssets failed with err, code is ${error.code}, message is ${error.message}`);
70. return 'ReadMediaUriFail';
71. }
72. return 'ReadMediaUriFail';
73. }
```

[Index.ets](https://gitcode.com/HarmonyOS_Samples/guide-snippets/blob/HarmonyOS-feature-20251117/CoreFile/UserFile/UserFileURI/entry/src/main/ets/pages/Index.ets#L16-L87)