1# 拉起文件处理类应用（startAbility）
2
3## 使用场景
4
5开发者可以通过调用[startAbility](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)接口，由系统从已安装的应用中寻找符合要求的应用，打开特定文件。
6
7例如，浏览器下应用下载PDF文件，可以调用此接口选择文件处理应用打开此PDF文件。开发者需要在请求中设置待打开文件的URI路径（[uri](#接口关键参数说明)）、文件格式（[type](#接口关键参数说明)）等字段，以便系统能够识别，直接拉起文件打开应用或弹出一个选择框，让用户选择合适的应用来打开文件，效果示意如下图所示。
8
9图1 效果示意图<br>
10![](figures/file-open.jpeg)
11
12## 接口关键参数说明
13
14开发者通过调用[startAbility](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)接口即可实现由已安装的垂域应用来打开文件。
15
16表1 startAbility请求中[want](../reference/apis-ability-kit/js-apis-app-ability-want.md)相关参数说明
17
18| 参数名称 | 类型   | 是否必填 | 说明                                                                                                                                                                                   |
19|----------|--------|----------|----------|
20| uri      | string | 是       | 表示待打开文件的URI路径，一般配合type使用。<br />uri格式为：file:\/\/bundleName\/path<br />- file：文件URI的标志。<br />- bundleName：该文件资源的属主。<br />- path：文件资源在应用沙箱中的路径。 |
21| type     | string | 否       | 表示打开文件的类型，推荐使用[UTD类型](../database/uniform-data-type-descriptors.md)，比如：'general.plain-text'、'general.image'。目前也可以兼容使用[MIME type类型](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com)，如：'text/xml' 、 'image/*'等。<br>**说明：** <br>1. type为可选字段，如果不传type，系统会尝试根据uri后缀名判断文件类型进行匹配；如果传入type，必须确保与uri的文件类型一致，否则会导致无法匹配到合适的应用。文件后缀与文件类型的映射关系参见[Uniform Type Descriptor(UTD)预置列表](../database/uniform-data-type-list.md)。<br>2. 不支持传\*/\*。
22| parameters | Record<string, Object>       | 否         | 表示由系统定义，由开发者按需赋值的自定义参数，文件打开场景请参考表2。                                                                                                                                                                                       |
23| flags | number | 否 | 表示处理方式，文件打开场景请参考表3。                                                                                                                                                                                       |
24
25
26**表2** [parameters](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params)相关参数说明
27
28
29| 参数名称                              | 类型    | 说明                                                                                                                                                                |
30|---------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
31| ability.params.stream                 | string  | 指示携带的文件URI要授权给目标方，用于待打开的文件存在其他文件依赖的场景。例如打开本地html文件依赖本地其余资源文件的场景等。对应的value必须是string类型的文件URI数组。文件URI的获取参考表1中uri参数。 |
32| ohos.ability.params.showDefaultPicker | boolean | 表示是否强制展示文件打开方式的选择弹框，缺省为false。<br>- false：表示由系统策略或默认应用设置决定直接拉起文件打开应用还是展示弹框。<br>- true：表示始终展示弹框。                                                                            |
33| showCaller                            | boolean | 表示调用方本身是否作为目标方应用之一参与匹配，缺省为false。<br>- false：不参与匹配。<br>- true：参与匹配。                                                                            |
34
35**表3** [flags](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#flags)相关参数说明
36
37| 参数名称                       | 值         | 说明                       |
38|--------------------------------|------------|----------------------------|
39| FLAG_AUTH_READ_URI_PERMISSION  | 0x00000001 | 指对URI执行读取操作的授权。 |
40| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 指对URI执行写入操作的授权。 |
41
42## 接入步骤
43
44### 调用方接入步骤
45
461. 导入相关模块。
47
48    ```ts
49    // xxx.ets
50    import { fileUri } from '@kit.CoreFileKit';
51    import { UIAbility, Want, common, wantConstant } from '@kit.AbilityKit';
52    import { BusinessError } from '@kit.BasicServicesKit';
53    import { window } from '@kit.ArkUI';
54    ```
55
562. 获取[应用文件路径](application-context-stage.md#获取应用文件路径)。
57
58    ```ts
59    // xxx.ets
60    // 假设应用bundleName值为com.example.demo
61    export default class EntryAbility extends UIAbility {
62        onWindowStageCreate(windowStage: window.WindowStage) {
63            // 获取文件沙箱路径
64            let filePath = this.context.filesDir + '/test1.txt';
65            // 将沙箱路径转换为uri
66            let uri = fileUri.getUriFromPath(filePath);
67            // 获取的uri为"file://com.example.demo/data/storage/el2/base/files/test.txt"
68        }
69        // ...
70    }
71    ```
72
733. 构造请求数据。
74
75    ```ts
76    // xxx.ets
77    export default class EntryAbility extends UIAbility {
78        onWindowStageCreate(windowStage: window.WindowStage) {
79            // 获取文件沙箱路径
80            let filePath = this.context.filesDir + '/test.txt';
81            // 将沙箱路径转换为uri
82            let uri = fileUri.getUriFromPath(filePath);
83            // 构造请求数据
84            let want: Want = {
85            action: 'ohos.want.action.viewData', // 表示查看数据的操作，文件打开场景固定为此值
86            uri: uri,
87            type: 'general.plain-text', // 表示待打开文件的类型
88            // 配置被分享文件的读写权限，例如对文件打开应用进行读写授权
89            flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
90            };
91        }
92        // ...
93    }
94    ```
95
964. 调用接口启动。
97
98    ```ts
99    // xxx.ets
100    export default class EntryAbility extends UIAbility {
101        onWindowStageCreate(windowStage: window.WindowStage) {
102            // 获取文件沙箱路径
103            let filePath = this.context.filesDir + '/test.txt';
104            // 将沙箱路径转换为uri
105            let uri = fileUri.getUriFromPath(filePath);
106            // 构造请求数据
107            let want: Want = {
108            action: 'ohos.want.action.viewData', // 表示查看数据的操作，文件打开场景固定为此值
109            uri: uri,
110            type: 'general.plain-text', // 表示待打开文件的类型
111            // 配置被分享文件的读写权限，例如对文件打开应用进行读写授权
112            flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
113            };
114            // 调用接口启动
115            this.context.startAbility(want)
116            .then(() => {
117                console.info('Succeed to invoke startAbility.');
118            })
119            .catch((err: BusinessError) => {
120                console.error(`Failed to invoke startAbility, code: ${err.code}, message: ${err.message}`);
121            });
122        }
123        // ...
124    }
125    ```
126
127### 目标方接入步骤
128
1291. 声明文件打开能力。
130
131    支持打开文件的应用需要在[module.json5](../quick-start/module-configuration-file.md)配置文件中声明文件打开能力。其中uris字段表示接收URI的类型，其中scheme固定为file。type字段表示支持打开的文件类型（参见[UTD类型](../database/uniform-data-type-descriptors.md)（推荐）或[MIME type类型](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com)），如下举例中类型为txt文件。
132
133    ```json
134    {
135    "module": {
136        // ...
137        "abilities": [
138        {
139            // ...
140            "skills": [
141            {
142                "actions": [
143                "ohos.want.action.viewData" // 必填，声明数据处理能力
144                ],
145                "uris": [
146                {
147                    // 允许打开uri中以file://协议开头标识的本地文件
148                    "scheme": "file", // 必填，声明协议类型为文件
149                    "type": "general.plain-text", // 必填，表示支持打开的文件类型
150                    "linkFeature": "FileOpen" // 必填且大小写敏感，表示此URI的功能为文件打开
151                }
152                // ...
153                ]
154                // ...
155            }
156            ]
157        }
158        ]
159    }
160    }
161    ```
162
163
1642. 应用处理待打开文件。
165
166    声明了文件打开的应用在被拉起后，获取传入的[Want](../reference/apis-ability-kit/js-apis-app-ability-want.md)参数信息，从中获取待打开文件的URI，在打开文件并获取对应的file对象后，可对文件进行读写操作。
167
168    ```ts
169    // xxx.ets
170    import fs from '@ohos.file.fs';
171    import { Want, AbilityConstant } from '@kit.AbilityKit';
172    import { BusinessError } from '@kit.BasicServicesKit';
173
174    export default class EntryAbility extends UIAbility {
175        onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
176            // 从want信息中获取uri字段
177            let uri = want.uri;
178            if (uri == null || uri == undefined) {
179                console.info('uri is invalid');
180                return;
181            }
182            try {
183                // 根据待打开文件的URI进行相应操作。例如同步读写的方式打开URI获取file对象
184                let file = fs.openSync(uri, fs.OpenMode.READ_WRITE);
185                console.info('Succeed to open file.');
186            } catch (err) {
187                let error: BusinessError = err as BusinessError;
188                console.error(`Failed to open file openSync, code: ${error.code}, message: ${error.message}`);
189            }
190        }
191    }
192    ```
193
194
195