拉起文件处理类应用（startAbility）

使用场景

开发者可以通过调用startAbility接口，由系统从已安装的应用中寻找符合要求的应用，打开特定文件。

例如，浏览器下应用下载PDF文件，可以调用此接口选择文件处理应用打开此PDF文件。开发者需要在请求中设置待打开文件的URI路径（uri）、文件格式（type）等字段，以便系统能够识别，直接拉起文件打开应用或弹出一个选择框，让用户选择合适的应用来打开文件，效果示意如下图所示。

图1 效果示意图

接口关键参数说明

开发者通过调用startAbility接口即可实现由已安装的垂域应用来打开文件。

表1 startAbility请求中want相关参数说明

表2 parameters相关参数说明

表3 flags相关参数说明

接入步骤

调用方接入步骤

1. 导入相关模块。

   // xxx.ets
   import { fileUri } from '@kit.CoreFileKit';
   import { UIAbility, Want, common, wantConstant } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { window } from '@kit.ArkUI';
   

2. 获取应用文件路径。

   // xxx.ets
   // 假设应用bundleName值为com.example.demo
   export default class EntryAbility extends UIAbility {
       onWindowStageCreate(windowStage: window.WindowStage) {
           // 获取文件沙箱路径
           let filePath = this.context.filesDir + '/test1.txt';
           // 将沙箱路径转换为uri
           let uri = fileUri.getUriFromPath(filePath);
           // 获取的uri为"file://com.example.demo/data/storage/el2/base/files/test.txt"
       }
       // ...
   }
   

3. 构造请求数据。

   // xxx.ets
   export default class EntryAbility extends UIAbility {
       onWindowStageCreate(windowStage: window.WindowStage) {
           // 获取文件沙箱路径
           let filePath = this.context.filesDir + '/test.txt';
           // 将沙箱路径转换为uri
           let uri = fileUri.getUriFromPath(filePath);
           // 构造请求数据
           let want: Want = {
           action: 'ohos.want.action.viewData', // 表示查看数据的操作，文件打开场景固定为此值
           uri: uri,
           type: 'general.plain-text', // 表示待打开文件的类型
           // 配置被分享文件的读写权限，例如对文件打开应用进行读写授权
           flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
           };
       }
       // ...
   }
   

4. 调用接口启动。

   // xxx.ets
   export default class EntryAbility extends UIAbility {
       onWindowStageCreate(windowStage: window.WindowStage) {
           // 获取文件沙箱路径
           let filePath = this.context.filesDir + '/test.txt';
           // 将沙箱路径转换为uri
           let uri = fileUri.getUriFromPath(filePath);
           // 构造请求数据
           let want: Want = {
           action: 'ohos.want.action.viewData', // 表示查看数据的操作，文件打开场景固定为此值
           uri: uri,
           type: 'general.plain-text', // 表示待打开文件的类型
           // 配置被分享文件的读写权限，例如对文件打开应用进行读写授权
           flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
           };
           // 调用接口启动
           this.context.startAbility(want)
           .then(() => {
               console.info('Succeed to invoke startAbility.');
           })
           .catch((err: BusinessError) => {
               console.error(`Failed to invoke startAbility, code: ${err.code}, message: ${err.message}`);
           });
       }
       // ...
   }
   

目标方接入步骤

1. 声明文件打开能力。

   支持打开文件的应用需要在module.json5配置文件中声明文件打开能力。其中uris字段表示接收URI的类型，其中scheme固定为file。type字段表示支持打开的文件类型（参见UTD类型（推荐）或MIME type类型），如下举例中类型为txt文件。

   {
   "module": {
       // ...
       "abilities": [
       {
           // ...
           "skills": [
           {
               "actions": [
               "ohos.want.action.viewData" // 必填，声明数据处理能力
               ],
               "uris": [
               {
                   // 允许打开uri中以file://协议开头标识的本地文件
                   "scheme": "file", // 必填，声明协议类型为文件
                   "type": "general.plain-text", // 必填，表示支持打开的文件类型
                   "linkFeature": "FileOpen" // 必填且大小写敏感，表示此URI的功能为文件打开
               }
               // ...
               ]
               // ...
           }
           ]
       }
       ]
   }
   }
   

2. 应用处理待打开文件。

   声明了文件打开的应用在被拉起后，获取传入的Want参数信息，从中获取待打开文件的URI，在打开文件并获取对应的file对象后，可对文件进行读写操作。

   // xxx.ets
   import fs from '@ohos.file.fs';
   import { Want, AbilityConstant } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   export default class EntryAbility extends UIAbility {
       onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
           // 从want信息中获取uri字段
           let uri = want.uri;
           if (uri == null || uri == undefined) {
               console.info('uri is invalid');
               return;
           }
           try {
               // 根据待打开文件的URI进行相应操作。例如同步读写的方式打开URI获取file对象
               let file = fs.openSync(uri, fs.OpenMode.READ_WRITE);
               console.info('Succeed to open file.');
           } catch (err) {
               let error: BusinessError = err as BusinessError;
               console.error(`Failed to open file openSync, code: ${error.code}, message: ${error.message}`);
           }
       }
   }