1# @ohos.inputMethod (输入法框架) (系统接口) 2<!--Kit: IME Kit--> 3<!--Subsystem: MiscServices--> 4<!--Owner: @illybyy--> 5<!--Designer: @andeszhang--> 6<!--Tester: @murphy1984--> 7<!--Adviser: @zhang_yixin13--> 8 9本模块主要面向普通前台应用（备忘录、信息、设置等系统应用），提供对输入法（输入法应用）的控制、管理能力，包括显示/隐藏输入法软键盘、切换输入法、获取所有输入法列表等等。 10 11> **说明：** 12> 13> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16## 导入模块 17 18```ts 19import { inputMethod } from '@kit.IMEKit'; 20``` 21 22## inputMethod.switchInputMethod<sup>11+</sup> 23switchInputMethod(bundleName: string, subtypeId?: string): Promise<void> 24 25切换输入法，使用promise异步回调。 26 27**需要权限：** ohos.permission.CONNECT_IME_ABILITY 28 29**系统能力：** SystemCapability.MiscServices.InputMethodFramework 30 31**系统接口：** 此接口为系统接口。 32 33**参数：** 34 35 | 参数名 | 类型 | 必填 | 说明 | 36 | -------- | -------- | -------- | -------- | 37 |bundleName | string| 是 | 目标输入法包名。 | 38 |subtypeId | string| 否 | 输入法子类型。 | 39 40**返回值：** 41 42 | 类型 | 说明 | 43 | -------------- | ----------------------- | 44 | Promise\<void> | 无返回结果的Promise对象。 | 45 46**错误码：** 47 48以下错误码的详细介绍请参见[输入法框架错误码](errorcode-inputmethod-framework.md)，[通用错误码说明文档](../errorcode-universal.md)。 49 50| 错误码ID | 错误信息 | 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**示例：** 59 60```ts 61import { InputMethodSubtype } from '@kit.IMEKit'; 62 63async function switchInputMethodWithSubtype() { 64 // 1. 获取当前输入法 65 const currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod(); 66 if (!currentIme) { 67 console.error("Failed to get current input method"); 68 return; 69 } 70 // 2. 切换输入法 71 await inputMethod.switchInputMethod(currentIme.name); 72 console.info('Succeeded in switching inputmethod.'); 73 // 3. 获取当前输入法子类型 74 const currentSubtype: InputMethodSubtype = inputMethod.getCurrentInputMethodSubtype(); 75 if (!currentSubtype) { 76 console.error("Failed to get current input subtype"); 77 return; 78 } 79 // 4. 切换输入法子类型 80 await inputMethod.switchInputMethod(currentIme.name, currentSubtype.id); 81 console.info('Succeeded in switching inputmethod.'); 82} 83 84switchInputMethodWithSubtype(); 85``` 86 87## InputMethodSetting<sup>8+</sup> 88 89下列API均需使用[getSetting](./js-apis-inputmethod.md#inputmethodgetsetting9)获取到InputMethodSetting实例后，通过实例调用。 90 91### on('imeShow')<sup>10+</sup> 92 93on(type: 'imeShow', callback: (info: Array\<InputWindowInfo>) => void): void 94 95订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘显示事件。使用callback异步回调。 96 97**系统接口**：此接口为系统接口。 98 99**系统能力：** SystemCapability.MiscServices.InputMethodFramework 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| -------- | ---- | ---- | ---- | 105| type | string | 是 | 设置监听类型，固定取值为'imeShow'。 | 106| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | 是 | 回调函数，返回输入法固定态软键盘信息。 | 107 108**错误码：** 109 110以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 111 112| 错误码ID | 错误信息 | 113| -------- | -------------------------------------- | 114| 202 | not system application. | 115 116**示例：** 117 118```ts 119inputMethod.getSetting().on('imeShow', (info: Array<inputMethod.InputWindowInfo>) => { 120 console.info('Succeeded in subscribing imeShow event.'); 121}); 122``` 123 124### on('imeHide')<sup>10+</sup> 125 126on(type: 'imeHide', callback: (info: Array\<InputWindowInfo>) => void): void 127 128订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘隐藏事件。使用callback异步回调。 129 130**系统接口**：此接口为系统接口。 131 132**系统能力：** SystemCapability.MiscServices.InputMethodFramework 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| -------- | ---- | ---- | ---- | 138| type | string | 是 | 设置监听类型，固定取值为'imeHide'。 | 139| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | 是 | 回调函数，返回输入法固定态软键盘信息。 | 140 141**错误码：** 142 143以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 144 145| 错误码ID | 错误信息 | 146| -------- | -------------------------------------- | 147| 202 | not system application. | 148 149 150**示例：** 151 152```ts 153inputMethod.getSetting().on('imeHide', (info: Array<inputMethod.InputWindowInfo>) => { 154 console.info('Succeeded in subscribing imeHide event.'); 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 178inputMethod.getSetting().off('imeShow'); 179``` 180 181### off('imeHide')<sup>10+</sup> 182 183off(type: 'imeHide', callback?: (info: Array\<InputWindowInfo>) => void): void 184 185取消订阅输入法[Panel](js-apis-inputmethodengine.md#panel10)固定态软键盘隐藏事件。 186 187**系统接口**：此接口为系统接口。 188 189**系统能力：** SystemCapability.MiscServices.InputMethodFramework 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | ---- | ---- | ------ | 195| type | string | 是 | 设置监听类型，固定取值'imeHide'。 | 196| callback | (info: Array<[InputWindowInfo](js-apis-inputmethod.md#inputwindowinfo10)>) => void | 否 | 取消订阅的回调函数。<br>参数不填写时，取消订阅type对应的所有回调事件。 | 197 198**示例：** 199 200```ts 201inputMethod.getSetting().off('imeHide'); 202``` 203 204### isPanelShown<sup>11+</sup> 205 206isPanelShown(panelInfo: PanelInfo): boolean 207 208查询指定类型的输入法面板是否处于显示状态。 209 210**系统接口**：此接口为系统接口。 211 212**系统能力：** SystemCapability.MiscServices.InputMethodFramework 213 214**参数：** 215 216| 参数名 | 类型 | 必填 | 说明 | 217| --------- | ----------------------------------------------------- | ---- | ------------------ | 218| panelInfo | [PanelInfo](./js-apis-inputmethod-panel.md#panelinfo) | 是 | 输入法面板的属性。 | 219 220**返回值：** 221 222| 类型 | 说明 | 223| ------- | ------------------------------------------------------------ | 224| boolean | 面板显隐状态查询结果。<br/>- true表示被查询的输入法面板处于显示状态。<br/>- false表示被查询的输入法面板处于隐藏状态。 | 225 226**错误码：** 227 228以下错误码的详细介绍请参见[输入法框架错误码](errorcode-inputmethod-framework.md)，[通用错误码说明文档](../errorcode-universal.md)。 229 230| 错误码ID | 错误信息 | 231| -------- | ----------------------------------- | 232| 202 | not system application. | 233| 401 | parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 234| 12800008 | input method manager service error. Possible cause: a system error, such as null pointer, IPC exception. | 235 236**示例：** 237 238```ts 239import { PanelInfo, PanelType, PanelFlag } from '@kit.IMEKit'; 240 241let info: PanelInfo = { 242 type: PanelType.SOFT_KEYBOARD, 243 flag: PanelFlag.FLAG_FIXED 244} 245 246let result: boolean = inputMethod.getSetting().isPanelShown(info); 247console.info('Succeeded in querying isPanelShown, result: ' + result); 248``` 249 250### enableInputMethod<sup>20+</sup> 251 252enableInputMethod(bundleName: string, extensionName: string, enabledState: EnabledState): Promise<void> 253 254修改输入法的启用状态。使用promise异步回调。 255 256**需要权限：** ohos.permission.CONNECT_IME_ABILITY 257 258**系统能力：** SystemCapability.MiscServices.InputMethodFramework 259 260**系统接口：** 此接口为系统接口。 261 262**参数：** 263 264 | 参数名 | 类型 | 必填 | 说明 | 265 | -------- | -------- | -------- | -------- | 266 | bundleName | string | 是 | 输入法包名。 | 267 | extensionName | string | 是 | 输入法扩展名。 | 268 | enabledState | [EnabledState](js-apis-inputmethod.md#enabledstate15) | 是 | 输入法启用状态。 | 269 270**返回值：** 271 272 | 类型 | 说明 | 273 | -------------- | ----------------------- | 274 | Promise\<void> | Promise对象。无返回结果的Promise对象。 | 275 276**错误码：** 277 278以下错误码的详细介绍请参见[输入法框架错误码](errorcode-inputmethod-framework.md)，[通用错误码说明文档](../errorcode-universal.md)。 279 280| 错误码ID | 错误信息 | 281| -------- | -------------------------------------- | 282| 201 | permissions check fails. | 283| 202 | not system application. | 284| 12800008 | input method manager service error. Possible cause: a system error, such as null pointer, IPC exception. | 285| 12800018 | the input method is not found. | 286| 12800019 | current operation cannot be applied to the preconfigured default input method. | 287 288**示例：** 289 290```ts 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293function enableInputMethodSafely() { 294 const currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod(); 295 if (!currentIme) { 296 console.error("Failed to get current input method"); 297 return; 298 } 299 300 inputMethod.getSetting() 301 .enableInputMethod(currentIme.name, currentIme.id, inputMethod.EnabledState.BASIC_MODE) 302 .then(() => { 303 console.info('Succeeded in enable inputmethod.'); 304 }) 305 .catch((err: BusinessError) => { 306 console.error(`Failed to enableInputMethod. Code: ${err.code}, message: ${err.message}`); 307 }); 308} 309 310enableInputMethodSafely(); 311``` 312