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<void> 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