1# @ohos.inputMethod (输入法框架) (系统接口)
2
3本模块主要面向普通前台应用(备忘录、信息、设置等系统应用与三方应用),提供对输入法(输入法应用)的控制、管理能力,包括显示/隐藏输入法软键盘、切换输入法、获取所有输入法列表等等。
4
5> **说明:**
6>
7> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12```ts
13import { inputMethod } from '@kit.IMEKit';
14```
15
16## inputMethod.switchInputMethod<sup>11+</sup>
17switchInputMethod(bundleName: string, subtypeId?: string): Promise&lt;void&gt;
18
19切换输入法,使用promise异步回调。
20
21**需要权限:** ohos.permission.CONNECT_IME_ABILITY
22
23**系统能力:** SystemCapability.MiscServices.InputMethodFramework
24
25**系统接口:** 此接口为系统接口。
26
27**参数:**
28
29  | 参数名 | 类型 | 必填 | 说明 |
30  | -------- | -------- | -------- | -------- |
31  |bundleName |  string| 是 | 目标输入法包名。 |
32  |subtypeId |  string| 否 | 输入法子类型。 |
33
34**返回值:**
35
36  | 类型           | 说明                     |
37  | -------------- | ----------------------- |
38  | Promise\<void> | 无返回结果的Promise对象。 |
39
40**错误码:**
41
42以下错误码的详细介绍请参见[输入法框架错误码](errorcode-inputmethod-framework.md),[通用错误码说明文档](../errorcode-universal.md)。
43
44| 错误码ID | 错误信息                             |
45| -------- | -------------------------------------- |
46| 201      | permissions check fails.  |
47| 202      | not system application.  |
48| 401      | parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.           |
49| 12800005 | configuration persistence error.        |
50| 12800008 | input method manager service error. |
51
52**示例:**
53
54```ts
55import { BusinessError } from '@kit.BasicServicesKit';
56
57let currentIme = inputMethod.getCurrentInputMethod();
58try {
59  inputMethod.switchInputMethod(currentIme.name).then(() => {
60    console.log('Succeeded in switching inputmethod.');
61  }).catch((err: BusinessError) => {
62    console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
63  })
64} catch (err) {
65  console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
66}
67let currentImeSubType = inputMethod.getCurrentInputMethodSubtype();
68try {
69  inputMethod.switchInputMethod(currentIme.name, currentImeSubType.id).then(() => {
70    console.log('Succeeded in switching inputmethod.');
71  }).catch((err: BusinessError) => {
72    console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
73  })
74} catch (err) {
75  console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
76}
77```
78
79## InputMethodSetting<sup>8+</sup>
80
81下列API均需使用[getSetting](./js-apis-inputmethod.md#inputmethodgetsetting9)获取到InputMethodSetting实例后,通过实例调用。
82
83### on('imeShow')<sup>10+</sup>
84
85on(type: 'imeShow', callback: (info: Array\<InputWindowInfo>) => void): void
86
87订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘显示事件。使用callback异步回调。
88
89**系统接口**:此接口为系统接口。
90
91**系统能力:** SystemCapability.MiscServices.InputMethodFramework
92
93**参数:**
94
95| 参数名   | 类型 | 必填 | 说明 |
96| -------- | ---- | ---- | ---- |
97| type     | string | 是 | 设置监听类型,固定取值为'imeShow'。 |
98| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | 是 | 回调函数,返回输入法固定态软键盘信息。 |
99
100**错误码:**
101
102以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
103
104| 错误码ID | 错误信息                             |
105| -------- | -------------------------------------- |
106| 202      | not system application.  |
107
108**示例:**
109
110```ts
111try {
112  inputMethodSetting.on('imeShow', (info: Array<inputMethod.InputWindowInfo>) => {
113    console.info('Succeeded in subscribing imeShow event.');
114  });
115} catch(err) {
116  console.error(`Failed to unsubscribing imeShow. err: ${JSON.stringify(err)}`);
117}
118```
119
120### on('imeHide')<sup>10+</sup>
121
122on(type: 'imeHide', callback: (info: Array\<InputWindowInfo>) => void): void
123
124订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘隐藏事件。使用callback异步回调。
125
126**系统接口**:此接口为系统接口。
127
128**系统能力:** SystemCapability.MiscServices.InputMethodFramework
129
130**参数:**
131
132| 参数名   | 类型 | 必填 | 说明 |
133| -------- | ---- | ---- | ---- |
134| type     | string | 是 | 设置监听类型,固定取值为'imeHide'。 |
135| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | 是 | 回调函数,返回输入法固定态软键盘信息。 |
136
137**错误码:**
138
139以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
140
141| 错误码ID | 错误信息                             |
142| -------- | -------------------------------------- |
143| 202      | not system application.  |
144
145
146**示例:**
147
148```ts
149try {
150  inputMethodSetting.on('imeHide', (info: Array<inputMethod.InputWindowInfo>) => {
151    console.info('Succeeded in subscribing imeHide event.');
152  });
153} catch(err) {
154  console.error(`Failed to unsubscribing imeHide. err: ${JSON.stringify(err)}`);
155}
156```
157
158### off('imeShow')<sup>10+</sup>
159
160off(type: 'imeShow', callback?: (info: Array\<InputWindowInfo>) => void): void
161
162取消订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘显示事件。
163
164**系统接口**:此接口为系统接口。
165
166**系统能力:** SystemCapability.MiscServices.InputMethodFramework
167
168**参数:**
169
170| 参数名   | 类型 | 必填 | 说明   |
171| -------- | ---- | ---- | ------ |
172| type     | string | 是 | 设置监听类型,固定取值`imeShow`。 |
173| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void  | 否 | 取消订阅的回调函数。<br>参数不填写时,取消订阅type对应的所有回调事件。 |
174
175**示例:**
176
177```ts
178try {
179  inputMethodSetting.off('imeShow');
180} catch(err) {
181  console.error(`Failed to unsubscribing imeShow. err: ${JSON.stringify(err)}`);
182}
183```
184
185### off('imeHide')<sup>10+</sup>
186
187off(type: 'imeHide', callback?: (info: Array\<InputWindowInfo>) => void): void
188
189取消订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘隐藏事件。
190
191**系统接口**:此接口为系统接口。
192
193**系统能力:** SystemCapability.MiscServices.InputMethodFramework
194
195**参数:**
196
197| 参数名   | 类型 | 必填 | 说明   |
198| -------- | ---- | ---- | ------ |
199| type     | string | 是 | 设置监听类型,固定取值'imeHide'。 |
200| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void  | 否 | 取消订阅的回调函数。<br>参数不填写时,取消订阅type对应的所有回调事件。 |
201
202**示例:**
203
204```ts
205try {
206  inputMethodSetting.off('imeHide');
207} catch(err) {
208  console.error(`Failed to unsubscribing imeHide. err: ${JSON.stringify(err)}`);
209}
210```
211
212### isPanelShown<sup>11+</sup>
213
214isPanelShown(panelInfo: PanelInfo): boolean
215
216查询指定类型的输入法面板是否处于显示状态。
217
218**系统接口**:此接口为系统接口。
219
220**系统能力:** SystemCapability.MiscServices.InputMethodFramework
221
222**参数:**
223
224| 参数名    | 类型                                                  | 必填 | 说明               |
225| --------- | ----------------------------------------------------- | ---- | ------------------ |
226| panelInfo | [PanelInfo](./js-apis-inputmethod-panel.md#panelinfo) | 是   | 输入法面板的属性。 |
227
228**返回值:**
229
230| 类型    | 说明                                                         |
231| ------- | ------------------------------------------------------------ |
232| boolean | 面板显隐状态查询结果。<br/>- true表示被查询的输入法面板处于显示状态。<br/>- false表示被查询的输入法面板处于隐藏状态。 |
233
234**错误码:**
235
236以下错误码的详细介绍请参见[输入法框架错误码](errorcode-inputmethod-framework.md),[通用错误码说明文档](../errorcode-universal.md)。
237
238| 错误码ID | 错误信息                            |
239| -------- | ----------------------------------- |
240| 202      | not system application.  |
241| 401      | parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
242| 12800008 | input method manager service error. |
243
244**示例:**
245
246```ts
247import { PanelInfo, PanelType, PanelFlag } from '@kit.IMEKit';
248
249let info: PanelInfo = {
250  type: PanelType.SOFT_KEYBOARD,
251  flag: PanelFlag.FLAG_FIXED
252}
253try {
254  let result = inputMethodSetting.isPanelShown(info);
255  console.log('Succeeded in querying isPanelShown, result: ' + result);
256} catch (err) {
257  console.error(`Failed to query isPanelShown: ${JSON.stringify(err)}`);
258}
259```
260