用户文件uri介绍

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

uri的类型

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

• 文档类uri：由picker拉起文件管理器选择或保存返回，以及通过fileAccess模块获取。具体获取方式参见文档类uri获取方式。
• 媒体文件uri：由picker通过拉起图库选择图片或者视频返回，通过photoAccessHelper模块获取图片或者视频文件的uri，以及通过userFileManager模块获取图片、视频或者音频文件的uri。具体获取方式参见媒体文件uri获取方式。

文档类uri

文档类uri介绍

文档类uri的格式类型为：

'file://docs/storage/Users/currentUser/<relative_path>/test.txt'

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

文档类uri获取方式

1. 通过DocumentViewPicker接口选择或保存文件，返回选择或保存的文件uri。

2. 通过AudioViewPicker接口选择或保存文件，返回选择或保存的文件uri。

3. 通过PhotoViewPicker.save接口保存文件，返回保存的文件uri。

4. 通过fileAccess模块获取文档类目录下的文件得到对应文件的FileInfo对象，此对象中就包含对应文件或者目录的uri属性，此模块中的接口为系统接口，使用此模块需要注意应用是否为系统应用。支持获取文件uri的目录有：

   • 外部存储目录
   • Docs目录
   • Download目录
   • Desktop目录
   • Documents目录
   • Share共享盘目录

文档类uri的使用方式

normal等级的应用使用此类uri的方式只能通过fs模块进行进一步处理，其他模块使用此uri是会报没有权限的错误。示例代码参见picker中的选择文档类文件和保存文档类文件。

system_basic等级及以上的应用使用此类uri的方式除了上述通过fs模块外还可以通过fileAccess模块进行进一步处理，使用此模块需要在配置文件module.json5中声明ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 权限，此权限为system_basic权限，仅供系统应用使用。其他模块使用此uri会报没有权限的错误。下面示例为使用fileAccess模块创建文件得到uri后对其进行重命名操作：

1. 通过fileAccess模块获取文件uri。
2. 使用获取到的文件uri进行重命名操作。

import { BusinessError } from '@ohos.base';
import Want from '@ohos.app.ability.Want';
import common from '@ohos.app.ability.common';
import fileAccess from '@ohos.file.fileAccess';
// context 是EntryAbility 传过来的context
let context = getContext(this) as common.UIAbilityContext;

async function example() {
    let fileAccessHelper: fileAccess.FileAccessHelper;
    // wantInfos 从getFileAccessAbilityInfo()获取
    let wantInfos: Array<Want> = [
      {
        bundleName: "com.ohos.UserFile.ExternalFileManager",
        abilityName: "FileExtensionAbility",
      },
    ]
    try {
      fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos);
      if (!fileAccessHelper) {
        console.error("createFileAccessHelper interface returns an undefined object");
      }
      // 以内置存储目录为例
      // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri
      // 开发者应根据自己实际获取的uri进行开发
      let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
      let displayName: string = "file1.txt";
      let fileUri: string;
      try {
        // 创建文件返回该文件的uri
        fileUri = await fileAccessHelper.createFile(sourceUri, displayName);
        if (!fileUri) {
          console.error("createFile return undefined object");
        }
        console.log("createFile success, fileUri: " + JSON.stringify(fileUri));
        // 将刚创建的文件进行重命名，返回新文件的uri
        let renameUri = await fileAccessHelper.rename(fileUri, "renameFile.txt");
        console.log("rename success, renameUri: " + JSON.stringify(renameUri));
      } catch (err) {
        let error: BusinessError = err as BusinessError;
        console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message);
      }
    } catch (err) {
      let error: BusinessError = err as BusinessError;
      console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message);
    }
  }

媒体文件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获取方式

1. 通过PhotoViewPicker.select接口选择媒体文件，返回选择的媒体文件文件的uri。

2. 通过photoAccessHelper模块中的getAssets或createAsset接口获取媒体文件对应文件的uri。

3. 通过userFileManager模块中的getPhotoAssets、getAudioAssets、createAudioAsset或createPhotoAsset接口获取媒体文件对应文件的uri。

媒体文件uri的使用方式

normal等级的应用使用此类uri可以通过photoAccessHelper模块进行进一步处理。示例代码参见媒体资源使用指导中的指定URI获取图片或视频资源。此接口需要申请相册管理模块读权限'ohos.permission.READ_IMAGEVIDEO'，在使用中需要注意应用是否有此权限。

system_basic等级及以上的应用使用此类uri的方式除了上述通过photoAccessHelper模块外还可以通过userFileManager模块进行进一步处理，接口详细使用方式见接口文档。

若normal等级的应用不想申请权限也可以通过临时授权的方式使用PhotoViewPicker.select接口得到的uri使用photoAccessHelper.getAssets接口获取对应uri的PhotoAsset对象。这种方式获取的对象可以调用getThumbnail获取缩略图和使用get接口读取PhotoKeys中的部分信息。

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

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

import picker from '@ohos.file.picker';
import photoAccessHelper from '@ohos.file.photoAccessHelper';
import { BusinessError } from '@ohos.base';
import dataSharePredicates from '@ohos.data.dataSharePredicates';

// 定义一个uri数组，用于接收PhotoViewPicker选择图片返回的uri
let uris: Array<string> = [];
const context = getContext(this);

// 调用PhotoViewPicker.select选择图片
async function photoPickerGetUri() {
  try {  
    let PhotoSelectOptions = new picker.PhotoSelectOptions();
    PhotoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
    PhotoSelectOptions.maxSelectNumber = 1;
    let photoPicker = new picker.PhotoViewPicker();
    photoPicker.select(PhotoSelectOptions).then((PhotoSelectResult: picker.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(PhotoSelectResult));
      uris = PhotoSelectResult.photoUris;
    }).catch((err: BusinessError) => {
      console.error('PhotoViewPicker.select failed with err: ' + JSON.stringify(err));
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('PhotoViewPicker failed with err: ' + JSON.stringify(err));
  }
}

async function uriGetAssets() {
try {
    let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    // 配置查询条件，使用PhotoViewPicker选择图片返回的uri进行查询
    predicates.equalTo('uri', uris[0]);
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);
    // 得到uri对应的PhotoAsset对象，读取文件的部分信息
    const asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    console.info('asset displayName: ', asset.displayName);
    console.info('asset uri: ', asset.uri);
    console.info('asset photoType: ', asset.photoType);
    console.info('asset width: ', asset.get(photoAccessHelper.PhotoKeys.WIDTH));
    console.info('asset height: ', asset.get(photoAccessHelper.PhotoKeys.HEIGHT));
    console.info('asset title: ' + asset.get(photoAccessHelper.PhotoKeys.TITLE));
    // 获取缩略图
    asset.getThumbnail((err, pixelMap) => {
      if (err == undefined) {
        console.info('getThumbnail successful ' + JSON.stringify(pixelMap));
      } else {
        console.error('getThumbnail fail', err);
      }
    });
  } catch (error){
    console.error('uriGetAssets failed with err: ' + JSON.stringify(error));
  }
}