• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# FormExtensionContext
2
3FormExtensionContext模块是FormExtensionAbility的上下文环境，继承自ExtensionContext。
4
5FormExtensionContext模块提供FormExtensionAbility具有的接口和能力。
6
7> **说明：**
8>
9> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
10> 本模块接口仅可在Stage模型下使用。
11
12## 导入模块
13
14```ts
15import common from '@ohos.app.ability.common';
16```
17
18## FormExtensionContext.startAbility
19
20startAbility(want: Want, callback: AsyncCallback<void>): void
21
22拉起一个卡片所属应用的Ability。使用callback异步回调。
23
24**系统接口**：此接口为系统接口。
25
26**系统能力**：SystemCapability.Ability.Form
27
28**错误码：**
29
30| 错误码ID | 错误信息 |
31| -------- | -------- |
32| 202 | The application is not a system application. |
33| 401 | If the input parameter is not valid parameter. |
34| 16500050 | An IPC connection error happened. |
35| 16500100 | Failed to obtain the configuration information. |
36| 16500101 | The application is not a system application. |
37| 16501000 | An internal functional error occurred. |
38
39以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
40
41**参数：**
42
43| 参数名 |                类型               | 必填 |              说明               |
44| ------| --------------------------------- | ---- | -------------------------------------- |
45| want| [Want](js-apis-app-ability-want.md) | 是  | 包含bundleName，abilityName以及用户自定参数用于拉起Ability。 |
46| callback| AsyncCallback<void>       | 是  | 回调函数。当拉起一个卡片所属应用的Ability成功，err为undefined，否则为错误对象。 |
47
48**示例：**
49
50```ts
51import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
52import Want from '@ohos.app.ability.Want';
53import Base from '@ohos.base';
54
55export default class MyFormExtensionAbility extends FormExtensionAbility {
56  onFormEvent(formId: string, message: string) {
57    // 当触发卡片message事件时，执行startAbility
58    console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message:${message}`);
59    let want: Want = {
60      deviceId: '',
61      bundleName: 'com.example.formstartability',
62      abilityName: 'EntryAbility',
63      parameters: {
64        'message': message
65      }
66    };
67    this.context.startAbility(want, (error: Base.BusinessError) => {
68      if (error) {
69        console.error(`FormExtensionContext startAbility, error:${JSON.stringify(error)}`);
70      } else {
71        console.log('FormExtensionContext startAbility success');
72      }
73    });
74  }
75};
76```
77
78## FormExtensionContext.startAbility
79
80startAbility(want: Want): Promise<void>
81
82拉起一个卡片所属应用的Ability。使用Promise异步回调。
83
84**系统接口**：此接口为系统接口。
85
86**系统能力**：SystemCapability.Ability.Form
87
88**参数：**
89
90| 参数名 |                类型               | 必填 |              说明               |
91| ------| --------------------------------- | ---- | -------------------------------------- |
92| want| [Want](js-apis-app-ability-want.md) | 是  | 包含bundleName，abilityName以及用户自定参数用于拉起Ability。 |
93
94**返回值：**
95
96| 类型          | 说明                                |
97| ------------ | ---------------------------------- |
98| Promise<void> | 无返回结果的Promise对象。 |
99
100**错误码：**
101
102| 错误码ID | 错误信息 |
103| -------- | -------- |
104| 202 | The application is not a system application. |
105| 401 | If the input parameter is not valid parameter. |
106| 16500050 | An IPC connection error happened. |
107| 16500100 | Failed to obtain the configuration information. |
108| 16500101 | The application is not a system application. |
109| 16501000 | An internal functional error occurred. |
110
111以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。
112
113**示例：**
114
115```ts
116import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
117import Want from '@ohos.app.ability.Want';
118import Base from '@ohos.base';
119
120export default class MyFormExtensionAbility extends FormExtensionAbility {
121  onFormEvent(formId: string, message: string) {
122    // 当触发卡片message事件时，执行startAbility
123    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
124    let want: Want = {
125      deviceId: '',
126      bundleName: 'com.example.formstartability',
127      abilityName: 'EntryAbility',
128      parameters: {
129        'message': message
130      }
131    };
132    this.context.startAbility(want).then(() => {
133      console.info('StartAbility Success');
134    }).catch((error: Base.BusinessError) => {
135      console.error('StartAbility failed');
136    });
137  }
138};
139```
140
141## FormExtensionContext.connectServiceExtensionAbility<sup>10+</sup>
142
143connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
144
145将一个Ability与服务类型的Ability绑定。
146
147**系统能力**：SystemCapability.Ability.Form
148
149**系统API**: 此接口为系统接口，三方应用不支持调用。
150
151**参数：**
152
153| 参数名 | 类型 | 必填 | 说明 |
154| -------- | -------- | -------- | -------- |
155| want | [Want](js-apis-app-ability-want.md)  | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 |
156| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 |
157
158**返回值：**
159
160| 类型 | 说明 |
161| -------- | -------- |
162| number | 返回一个connectId，后续根据此connectId断开连接。 |
163
164**错误码：**
165
166| 错误码ID | 错误信息 |
167| ------- | -------------------------------- |
168| 16000001 | The specified ability does not exist. |
169| 16000002 | Incorrect ability type. |
170| 16000004 | Can not start invisible component. |
171| 16000005 | The specified process does not have the permission. |
172| 16000006 | Cross-user operations are not allowed. |
173| 16000008 | The crowdtesting application expires. |
174| 16000053 | The ability is not on the top of the UI. |
175| 16000055 | Installation-free timed out. |
176| 16000011 | The context does not exist.        |
177| 16000050 | Internal error. |
178
179以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
180
181**示例：**
182
183```ts
184import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
185import Want from '@ohos.app.ability.Want';
186import rpc from '@ohos.rpc';
187import common from '@ohos.app.ability.common';
188
189let commRemote: rpc.IRemoteObject | null = null;
190export default class MyFormExtensionAbility extends FormExtensionAbility {
191  onFormEvent(formId: string, message: string) {
192    // 当触发卡片message事件时，执行connectServiceExtensionAbility
193    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
194    let want: Want = {
195      deviceId: '',
196      bundleName: 'com.example.formstartability',
197      abilityName: 'EntryAbility',
198      parameters: {
199        'message': message
200      }
201    };
202    let options: common.ConnectOptions = {
203      onConnect(elementName, remote) {
204        commRemote = remote; // remote 用于与ServiceExtensionAbility进行通信
205        console.log('----------- onConnect -----------');
206      },
207      onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
208      onFailed(code) { console.error('----------- onFailed -----------') }
209    };
210
211    let connection: number | null = null;
212    try {
213      connection = this.context.connectServiceExtensionAbility(want, options);
214    } catch (paramError) {
215      // 处理入参错误异常
216      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
217    }
218  }
219};
220```
221
222## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
223
224disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback&lt;void&gt;): void;
225
226将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。
227
228**系统能力**：SystemCapability.Ability.Form
229
230**系统API**: 此接口为系统接口，三方应用不支持调用。
231
232**参数：**
233
234| 参数名 | 类型 | 必填 | 说明 |
235| -------- | -------- | -------- | -------- |
236| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 |
237| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，返回接口调用是否成功的结果。 |
238
239**错误码：**
240
241| 错误码ID | 错误信息 |
242| ------- | -------------------------------- |
243| 16000011 | The context does not exist.        |
244| 16000050 | Internal error. |
245
246以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
247
248**示例：**
249
250```ts
251import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
252import rpc from '@ohos.rpc';
253import common from '@ohos.app.ability.common';
254import Base from '@ohos.base';
255
256// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
257let commRemote: rpc.IRemoteObject | null = null;
258export default class MyFormExtensionAbility extends FormExtensionAbility {
259  onFormEvent(formId: string, message: string) {
260    // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
261    let connection: number = 1;
262
263    try {
264      this.context.disconnectServiceExtensionAbility(connection, (error: Base.BusinessError) => {
265        commRemote = null;
266        if (error.code) {
267          // 处理业务逻辑错误
268          console.error(
269            `disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
270          return;
271        }
272        // 执行正常业务
273        console.log('disconnectServiceExtensionAbility succeed');
274      });
275    } catch (paramError) {
276      commRemote = null;
277      // 处理入参错误异常
278      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
279    }
280  }
281};
282```
283
284## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
285
286disconnectServiceExtensionAbility(connection: number): Promise&lt;void&gt;;
287
288将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。
289
290**系统能力**：SystemCapability.Ability.Form
291
292**系统API**: 此接口为系统接口，三方应用不支持调用。
293
294**参数：**
295
296| 参数名 | 类型 | 必填 | 说明 |
297| -------- | -------- | -------- | -------- |
298| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 |
299
300**返回值：**
301
302| 类型 | 说明 |
303| -------- | -------- |
304| Promise&lt;void&gt; | 返回一个Promise，包含接口的结果。 |
305
306**错误码：**
307
308| 错误码ID | 错误信息 |
309| ------- | -------------------------------- |
310| 16000011 | The context does not exist.        |
311| 16000050 | Internal error. |
312
313以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
314
315**示例：**
316
317```ts
318import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
319import rpc from '@ohos.rpc';
320import common from '@ohos.app.ability.common';
321import Base from '@ohos.base';
322
323// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
324let commRemote: rpc.IRemoteObject | null = null;
325export default class MyFormExtensionAbility extends FormExtensionAbility {
326  onFormEvent(formId: string, message: string) {
327    // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
328    let connection: number = 1;
329
330    try {
331      this.context.disconnectServiceExtensionAbility(connection)
332        .then(() => {
333          commRemote = null;
334          // 执行正常业务
335          console.log('disconnectServiceExtensionAbility succeed');
336        })
337        .catch((error: Base.BusinessError) => {
338          commRemote = null;
339          // 处理业务逻辑错误
340          console.error(
341            `disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
342        });
343    } catch (paramError) {
344      commRemote = null;
345      // 处理入参错误异常
346      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
347    }
348  }
349};
350```
351