1# @ohos.inputMethod (Input Method Framework) (System API) 2<!--Kit: IME Kit--> 3<!--Subsystem: MiscServices--> 4<!--Owner: @illybyy--> 5<!--Designer: @andeszhang--> 6<!--Tester: @murphy1984--> 7<!--Adviser: @zhang_yixin13--> 8 9The **inputMethod** module is oriented to common foreground applications (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. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15 16## Modules to Import 17 18```ts 19import { inputMethod } from '@kit.IMEKit'; 20``` 21 22## inputMethod.switchInputMethod<sup>11+</sup> 23switchInputMethod(bundleName: string, subtypeId?: string): Promise<void> 24 25Switches to another input method. This API uses a promise to return the result. 26 27**Required permissions**: ohos.permission.CONNECT_IME_ABILITY 28 29**System capability**: SystemCapability.MiscServices.InputMethodFramework 30 31**System API**: This is a system API. 32 33**Parameters** 34 35 | Name| Type| Mandatory| Description| 36 | -------- | -------- | -------- | -------- | 37 |bundleName | string| Yes| Bundle name of the target input method.| 38 |subtypeId | string| No| Input method subtype.| 39 40**Return value** 41 42 | Type | Description | 43 | -------------- | ----------------------- | 44 | Promise\<void> | Promise that returns no value.| 45 46**Error codes** 47 48For details about the error codes, see [Input Method Framework Error Codes](errorcode-inputmethod-framework.md) and [Universal Error Codes](../errorcode-universal.md). 49 50| ID| Error Message | 51| -------- | -------------------------------------- | 52| 201 | permissions check fails. | 53| 202 | not system application. | 54| 401 | parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 55| 12800005 | configuration persistence error. | 56| 12800008 | input method manager service error. Possible cause: a system error, such as null pointer, IPC exception. | 57 58**Example** 59 60```ts 61import { BusinessError } from '@kit.BasicServicesKit'; 62 63async function switchInputMethodWithSubtype() { 64 // 1. Obtain the current input method. 65 const currentIme = inputMethod.getCurrentInputMethod(); 66 if (!currentIme) { 67 console.error("Failed to get current input method"); 68 return; 69 } 70 // 2. Switch the input method. 71 try { 72 await inputMethod.switchInputMethod(currentIme.name); 73 console.info('Succeeded in switching inputmethod.'); 74 } catch (err) { 75 console.error(`Failed to switch input method: Code: ${err.code}, Message: ${err.message}`); 76 return; 77 } 78 // 3. Obtain the current input method subtype. 79 const currentSubtype = inputMethod.getCurrentInputMethodSubtype(); 80 if (!currentSubtype) { 81 console.error("Failed to get current input subtype"); 82 return; 83 } 84 // 4. Switch the input method subtype. 85 try { 86 await inputMethod.switchInputMethod(currentIme.name, currentSubtype.id); 87 console.info('Succeeded in switching inputmethod.'); 88 } catch (err) { 89 console.error(`Failed to switch input subtype: Code: ${err.code}, Message: ${err.message}`); 90 } 91} 92switchInputMethodWithSubtype(); 93``` 94 95## InputMethodSetting<sup>8+</sup> 96 97In 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. 98 99### on('imeShow')<sup>10+</sup> 100 101on(type: 'imeShow', callback: (info: Array\<InputWindowInfo>) => void): void 102 103Subscribes 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. 104 105**System API**: This is a system API. 106 107**System capability**: SystemCapability.MiscServices.InputMethodFramework 108 109**Parameters** 110 111| Name | Type| Mandatory| Description| 112| -------- | ---- | ---- | ---- | 113| type | string | Yes| Event type, which is **'imeShow'**.| 114| 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.| 115 116**Error codes** 117 118For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 119 120| ID| Error Message | 121| -------- | -------------------------------------- | 122| 202 | not system application. | 123 124**Example** 125 126```ts 127try { 128 inputMethodSetting.on('imeShow', (info: Array<inputMethod.InputWindowInfo>) => { 129 console.info('Succeeded in subscribing imeShow event.'); 130 }); 131} catch(err) { 132 console.error(`Failed to subscribing imeShow. Code: ${err.code}, Message: ${err.message}`); 133} 134``` 135 136### on('imeHide')<sup>10+</sup> 137 138on(type: 'imeHide', callback: (info: Array\<InputWindowInfo>) => void): void 139 140Subscribes 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. 141 142**System API**: This is a system API. 143 144**System capability**: SystemCapability.MiscServices.InputMethodFramework 145 146**Parameters** 147 148| Name | Type| Mandatory| Description| 149| -------- | ---- | ---- | ---- | 150| type | string | Yes| Event type, which is **'imeHide'**.| 151| 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.| 152 153**Error codes** 154 155For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 156 157| ID| Error Message | 158| -------- | -------------------------------------- | 159| 202 | not system application. | 160 161 162**Example** 163 164```ts 165try { 166 inputMethodSetting.on('imeHide', (info: Array<inputMethod.InputWindowInfo>) => { 167 console.info('Succeeded in subscribing imeHide event.'); 168 }); 169} catch(err) { 170 console.error(`Failed to subscribing imeHide. Code: ${err.code}, Message: ${err.message}`); 171} 172``` 173 174### off('imeShow')<sup>10+</sup> 175 176off(type: 'imeShow', callback?: (info: Array\<InputWindowInfo>) => void): void 177 178Unsubscribes from the soft keyboard show event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state. 179 180**System API**: This is a system API. 181 182**System capability**: SystemCapability.MiscServices.InputMethodFramework 183 184**Parameters** 185 186| Name | Type| Mandatory| Description | 187| -------- | ---- | ---- | ------ | 188| type | string | Yes| Event type, which is **'imeShow'**.| 189| 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.| 190 191**Example** 192 193```ts 194try { 195 inputMethodSetting.off('imeShow'); 196} catch(err) { 197 console.error(`Failed to unsubscribing imeShow. Code: ${err.code}, Message: ${err.message}`); 198} 199``` 200 201### off('imeHide')<sup>10+</sup> 202 203off(type: 'imeHide', callback?: (info: Array\<InputWindowInfo>) => void): void 204 205Unsubscribes from the soft keyboard hide event of the [input method panel](js-apis-inputmethodengine.md#panel10) in the fixed state. 206 207**System API**: This is a system API. 208 209**System capability**: SystemCapability.MiscServices.InputMethodFramework 210 211**Parameters** 212 213| Name | Type| Mandatory| Description | 214| -------- | ---- | ---- | ------ | 215| type | string | Yes| Event type, which is **'imeHide'**.| 216| 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.| 217 218**Example** 219 220```ts 221try { 222 inputMethodSetting.off('imeHide'); 223} catch(err) { 224 console.error(`Failed to unsubscribing imeHide. Code: ${err.code}, Message: ${err.message}`); 225} 226``` 227 228### isPanelShown<sup>11+</sup> 229 230isPanelShown(panelInfo: PanelInfo): boolean 231 232Checks whether the input method panel of a specified type is shown. 233 234**System API**: This is a system API. 235 236**System capability**: SystemCapability.MiscServices.InputMethodFramework 237 238**Parameters** 239 240| Name | Type | Mandatory| Description | 241| --------- | ----------------------------------------------------- | ---- | ------------------ | 242| panelInfo | [PanelInfo](./js-apis-inputmethod-panel.md#panelinfo) | Yes | Information about the input method panel.| 243 244**Return value** 245 246| Type | Description | 247| ------- | ------------------------------------------------------------ | 248| 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.| 249 250**Error codes** 251 252For details about the error codes, see [Input Method Framework Error Codes](errorcode-inputmethod-framework.md) and [Universal Error Codes](../errorcode-universal.md). 253 254| ID| Error Message | 255| -------- | ----------------------------------- | 256| 202 | not system application. | 257| 401 | parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 258| 12800008 | input method manager service error. Possible cause: a system error, such as null pointer, IPC exception. | 259 260**Example** 261 262```ts 263import { PanelInfo, PanelType, PanelFlag } from '@kit.IMEKit'; 264 265let info: PanelInfo = { 266 type: PanelType.SOFT_KEYBOARD, 267 flag: PanelFlag.FLAG_FIXED 268} 269try { 270 let result = inputMethodSetting.isPanelShown(info); 271 console.info('Succeeded in querying isPanelShown, result: ' + result); 272} catch (err) { 273 console.error(`Failed to query isPanelShown: ${JSON.stringify(err)}`); 274} 275``` 276 277### enableInputMethod<sup>20+</sup> 278 279enableInputMethod(bundleName: string, extensionName: string, enabledState: EnabledState): Promise<void> 280 281Enables or disables an input method. This API uses a promise to return the result. 282 283**Required permissions**: ohos.permission.CONNECT_IME_ABILITY 284 285**System capability**: SystemCapability.MiscServices.InputMethodFramework 286 287**System API**: This is a system API. 288 289**Parameters** 290 291 | Name| Type| Mandatory| Description| 292 | -------- | -------- | -------- | -------- | 293 | bundleName | string | Yes| Bundle name of the input method.| 294 | extensionName | string | Yes| Extension name of the input method.| 295 | enabledState | [EnabledState](js-apis-inputmethod.md#enabledstate15) | Yes| Whether the input method is enabled.| 296 297**Return value** 298 299 | Type | Description | 300 | -------------- | ----------------------- | 301 | Promise\<void> | Promise that returns no value.| 302 303**Error codes** 304 305For details about the error codes, see [Input Method Framework Error Codes](errorcode-inputmethod-framework.md) and [Universal Error Codes](../errorcode-universal.md). 306 307| ID| Error Message | 308| -------- | -------------------------------------- | 309| 201 | permissions check fails. | 310| 202 | not system application. | 311| 12800008 | input method manager service error. Possible cause: a system error, such as null pointer, IPC exception. | 312| 12800018 | the input method is not found. | 313| 12800019 | current operation cannot be applied to the preconfigured default input method. | 314 315**Example** 316 317```ts 318import { BusinessError } from '@kit.BasicServicesKit'; 319 320function enableInputMethodSafely() { 321 const currentIme = inputMethod.getCurrentInputMethod(); 322 if (!currentIme) { 323 console.error("Failed to get current input method"); 324 return; 325 } 326 327 inputMethodSetting.enableInputMethod(currentIme.name, currentIme.id, inputMethod.EnabledState.BASIC_MODE).then(() => { 328 console.info('Succeeded in enable inputmethod.'); 329 }).catch((err: BusinessError) => { 330 console.error(`Failed to enableInputMethod. Code: ${err.code}, message: ${err.message}`); 331 }); 332} 333enableInputMethodSafely(); 334``` 335