1# @ohos.inputMethod (Input Method Framework) (System API)
2
3The **inputMethod** module is oriented to common foreground applications (third-party applications and system applications such as Notes, Messaging, and Settings). It provides input method control and management capabilities, including displaying or hiding the soft keyboard, switching between input methods, and obtaining the list of all input methods.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
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
19Switches to another input method. This API uses a promise to return the result.
20
21**Required permissions**: ohos.permission.CONNECT_IME_ABILITY
22
23**System capability**: SystemCapability.MiscServices.InputMethodFramework
24
25**System API**: This is a system API.
26
27**Parameters**
28
29  | Name| Type| Mandatory| Description|
30  | -------- | -------- | -------- | -------- |
31  |bundleName |  string| Yes| Bundle name of the target input method.|
32  |subtypeId |  string| No| Input method subtype.|
33
34**Return value**
35
36  | Type          | Description                    |
37  | -------------- | ----------------------- |
38  | Promise\<void> | Promise that returns no value.|
39
40**Error codes**
41
42For details about the error codes, see [Input Method Framework Error Codes](errorcode-inputmethod-framework.md) and [Universal Error Codes](../errorcode-universal.md).
43
44| ID| Error Message                            |
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**Example**
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
81In the following API examples, you must first use [getSetting](./js-apis-inputmethod.md#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance.
82
83### on('imeShow')<sup>10+</sup>
84
85on(type: 'imeShow', callback: (info: Array\<InputWindowInfo>) => void): void
86
87Subscribes to the soft keyboard show event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state. This API uses an asynchronous callback to return the result.
88
89**System API**: This is a system API.
90
91**System capability**: SystemCapability.MiscServices.InputMethodFramework
92
93**Parameters**
94
95| Name  | Type| Mandatory| Description|
96| -------- | ---- | ---- | ---- |
97| type     | string | Yes| Event type, which is **'imeShow'**.|
98| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | Yes| Callback used to return the soft keyboard information of the input method panel in the fixed state.|
99
100**Error codes**
101
102For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
103
104| ID| Error Message                            |
105| -------- | -------------------------------------- |
106| 202      | not system application.  |
107
108**Example**
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
124Subscribes to the soft keyboard hide event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state. This API uses an asynchronous callback to return the result.
125
126**System API**: This is a system API.
127
128**System capability**: SystemCapability.MiscServices.InputMethodFramework
129
130**Parameters**
131
132| Name  | Type| Mandatory| Description|
133| -------- | ---- | ---- | ---- |
134| type     | string | Yes| Event type, which is **'imeHide'**.|
135| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | Yes| Callback used to return the soft keyboard information of the input method panel in the fixed state.|
136
137**Error codes**
138
139For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
140
141| ID| Error Message                            |
142| -------- | -------------------------------------- |
143| 202      | not system application.  |
144
145
146**Example**
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
162Unsubscribes from the soft keyboard show event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state.
163
164**System API**: This is a system API.
165
166**System capability**: SystemCapability.MiscServices.InputMethodFramework
167
168**Parameters**
169
170| Name  | Type| Mandatory| Description  |
171| -------- | ---- | ---- | ------ |
172| type     | string | Yes| Event type, which is **'imeShow'**.|
173| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void  | No| Callback to unregister.<br>If this parameter is not specified, this API unregisters all callbacks for the specified event type.|
174
175**Example**
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
189Unsubscribes from the soft keyboard hide event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state.
190
191**System API**: This is a system API.
192
193**System capability**: SystemCapability.MiscServices.InputMethodFramework
194
195**Parameters**
196
197| Name  | Type| Mandatory| Description  |
198| -------- | ---- | ---- | ------ |
199| type     | string | Yes| Event type, which is **'imeHide'**.|
200| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void  | No| Callback to unregister.<br>If this parameter is not specified, this API unregisters all callbacks for the specified event type.|
201
202**Example**
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
216Checks whether the input method panel of a specified type is shown.
217
218**System API**: This is a system API.
219
220**System capability**: SystemCapability.MiscServices.InputMethodFramework
221
222**Parameters**
223
224| Name   | Type                                                 | Mandatory| Description              |
225| --------- | ----------------------------------------------------- | ---- | ------------------ |
226| panelInfo | [PanelInfo](./js-apis-inputmethod-panel.md#panelinfo) | Yes  | Information about the input method panel.|
227
228**Return value**
229
230| Type   | Description                                                        |
231| ------- | ------------------------------------------------------------ |
232| boolean | Whether the input method panel is shown.<br>- The value **true** means that the input method panel is shown.<br>- The value **false** means that the input method panel is hidden.|
233
234**Error codes**
235
236For details about the error codes, see [Input Method Framework Error Codes](errorcode-inputmethod-framework.md) and [Universal Error Codes](../errorcode-universal.md).
237
238| ID| Error Message                           |
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**Example**
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