1# @ohos.inputMethod (Input Method Framework) 2 3The **inputMethod** module provides an input method framework, which can be used to hide the keyboard, obtain the list of installed input methods, display the dialog box for input method selection, and more. 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```js 13import inputMethod from '@ohos.inputMethod'; 14``` 15 16## Constants<sup>8+</sup> 17 18Provides the constants. 19 20**System capability**: SystemCapability.MiscServices.InputMethodFramework 21 22| Name| Type| Value| Description| 23| -------- | -------- | -------- | -------- | 24| MAX_TYPE_NUM | number | 128 | Maximum number of supported input methods.| 25 26## InputMethodProperty<sup>8+</sup> 27 28Describes the input method application attributes. 29 30**System capability**: SystemCapability.MiscServices.InputMethodFramework 31 32| Name| Type| Readable| Writable| Description| 33| -------- | -------- | -------- | -------- | -------- | 34| name<sup>9+</sup> | string | Yes| No| Internal name of the input method. Mandatory.| 35| id<sup>9+</sup> | string | Yes| No| Unique ID of the input method. Mandatory.| 36| label<sup>9+</sup> | string | Yes| No| External display name of the input method. Optional.| 37| icon<sup>9+</sup> | string | Yes| No| Icon of the input method. Optional.| 38| iconId<sup>9+</sup> | number | Yes| No| Icon ID of the input method. Optional.| 39| extra<sup>9+</sup> | object | Yes| Yes| Extra information about the input method. Mandatory.| 40| packageName<sup>(deprecated)</sup> | string | Yes| No| Name of the input method package. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **name**.| 41| methodId<sup>(deprecated)</sup> | string | Yes| No| Unique ID of the input method. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **id**.| 42 43## inputMethod.getController<sup>9+</sup> 44 45getController(): InputMethodController 46 47Obtains an **[InputMethodController](#inputmethodcontroller)** instance. 48 49**System capability**: SystemCapability.MiscServices.InputMethodFramework 50 51**Return value** 52 53| Type | Description | 54| ----------------------------------------------- | ------------------------ | 55| [InputMethodController](#inputmethodcontroller) | Current **InputMethodController** instance.| 56 57**Error codes** 58 59For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 60 61| Error Code ID| Error Message | 62| -------- | ------------------------------ | 63| 12800006 | Input method controller error. | 64 65**Example** 66 67```js 68let inputMethodController = inputMethod.getController(); 69``` 70 71## inputMethod.getSetting<sup>9+</sup> 72 73getSetting(): InputMethodSetting 74 75Obtains an **[InputMethodSetting](#inputmethodsetting8)** instance. 76 77**System capability**: SystemCapability.MiscServices.InputMethodFramework 78 79**Return value** 80 81| Type | Description | 82| ----------------------------------------- | ---------------------------- | 83| [InputMethodSetting](#inputmethodsetting8) | Current **InputMethodSetting** instance.| 84 85**Error codes** 86 87For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 88 89| Error Code ID| Error Message | 90| -------- | -------------------------------------- | 91| 12800007 | Input method settings extension error. | 92 93**Example** 94 95```js 96let inputMethodSetting = inputMethod.getSetting(); 97``` 98 99## inputMethod.switchInputMethod<sup>9+</sup> 100 101switchInputMethod(target: InputMethodProperty, callback: AsyncCallback<boolean>): void 102 103Switches to another input method. This API uses an asynchronous callback to return the result. 104 105**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 106 107**System capability**: SystemCapability.MiscServices.InputMethodFramework 108 109**Parameters** 110 111| Name| Type| Mandatory| Description| 112| -------- | -------- | -------- | -------- | 113| target | [InputMethodProperty](#inputmethodproperty8) | Yes| Input method to switch to.| 114| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 115 116**Error codes** 117 118For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 119 120| Error Code ID| Error Message | 121| -------- | -------------------------------------- | 122| 12800005 | Configuration persisting error. | 123| 12800008 | Input method manager service error. | 124 125**Example** 126 127```js 128let im = inputMethod.getCurrentInputMethod(); 129let prop = { 130 packageName: im.packageName, 131 methodId: im.methodId, 132 name: im.packageName, 133 id: im.methodId, 134 extra: {} 135} 136try{ 137 inputMethod.switchInputMethod(prop, (err, result) => { 138 if (err !== undefined) { 139 console.error('Failed to switchInputMethod: ' + JSON.stringify(err)); 140 return; 141 } 142 if (result) { 143 console.info('Succeeded in switching inputmethod.'); 144 } else { 145 console.error('Failed to switchInputMethod.'); 146 } 147 }); 148} catch(err) { 149 console.error('Failed to switchInputMethod: ' + JSON.stringify(err)); 150} 151``` 152## inputMethod.switchInputMethod<sup>9+</sup> 153switchInputMethod(target: InputMethodProperty): Promise<boolean> 154 155Switches to another input method. This API uses a promise to return the result. 156 157**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 158 159**System capability**: SystemCapability.MiscServices.InputMethodFramework 160 161**Parameters** 162 163 | Name| Type| Mandatory| Description| 164 | -------- | -------- | -------- | -------- | 165 |target | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| 166 167**Return value** 168 169 | Type | Description | 170 | ----------------------------------------- | ---------------------------- | 171 | Promise\<boolean> | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| 172 173**Error codes** 174 175For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 176 177| Error Code ID| Error Message | 178| -------- | -------------------------------------- | 179| 12800005 | Configuration persisting error. | 180| 12800008 | Input method manager service error. | 181 182**Example** 183 184```js 185let im = inputMethod.getCurrentInputMethod(); 186let prop = { 187 packageName: im.packageName, 188 methodId: im.methodId, 189 name: im.packageName, 190 id: im.methodId, 191 extra: {} 192} 193try { 194 inputMethod.switchInputMethod(prop).then((result) => { 195 if (result) { 196 console.info('Succeeded in switching inputmethod.'); 197 } else { 198 console.error('Failed to switchInputMethod.'); 199 } 200 }).catch((err) => { 201 console.error('Failed to switchInputMethod: ' + JSON.stringify(err)); 202 }) 203} catch(err) { 204 console.error('Failed to switchInputMethod: ' + JSON.stringify(err)); 205} 206``` 207 208## inputMethod.getCurrentInputMethod<sup>9+</sup> 209 210getCurrentInputMethod(): InputMethodProperty 211 212Obtains the current input method. This API synchronously returns the **InputmethodProperty** instance of the current input method. 213 214**System capability**: SystemCapability.MiscServices.InputMethodFramework 215 216**Return value** 217 218| Type | Description | 219| -------------------------------------------- | ------------------------ | 220| [InputMethodProperty](#inputmethodproperty8) | **InputmethodProperty** instance of the current input method.| 221 222**Example** 223 224```js 225let currentIme = inputMethod.getCurrentInputMethod(); 226``` 227 228## inputMethod.switchCurrentInputMethodSubtype<sup>9+</sup> 229 230switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback\<boolean>): void 231 232Switches to another subtype of the current input method. This API uses an asynchronous callback to return the result. 233 234**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 235 236**System capability**: SystemCapability.MiscServices.InputMethodFramework 237 238**Parameters** 239 240| Name| Type| Mandatory| Description| 241| -------- | -------- | -------- | -------- | 242| target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.| 243| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 244 245**Error codes** 246 247For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 248 249| Error Code ID| Error Message | 250| -------- | -------------------------------------- | 251| 12800005 | Configuration persisting error. | 252| 12800008 | Input method manager service error. | 253 254**Example** 255 256```js 257try { 258 inputMethod.switchCurrentInputMethodSubtype({ 259 id: "com.example.kikakeyboard", 260 label: "ServiceExtAbility", 261 name: "", 262 mode: "upper", 263 locale: "", 264 language: "", 265 icon: "", 266 iconId: 0, 267 extra: {} 268 }, (err, result) => { 269 if (err !== undefined) { 270 console.error('Failed to switchCurrentInputMethodSubtype: ' + JSON.stringify(err)); 271 return; 272 } 273 if (result) { 274 console.info('Succeeded in switching currentInputMethodSubtype.'); 275 } else { 276 console.error('Failed to switchCurrentInputMethodSubtype'); 277 } 278 }); 279} catch(err) { 280 console.error('Failed to switchCurrentInputMethodSubtype: ' + JSON.stringify(err)); 281} 282``` 283 284## inputMethod.switchCurrentInputMethodSubtype<sup>9+</sup> 285 286switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise<boolean> 287 288Switches to another subtype of the current input method. This API uses a promise to return the result. 289 290**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 291 292**System capability**: SystemCapability.MiscServices.InputMethodFramework 293 294**Parameters** 295 296| Name| Type| Mandatory| Description| 297| -------- | -------- | -------- | -------- | 298|target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.| 299 300**Return value** 301 302| Type | Description | 303| ----------------------------------------- | ---------------------------- | 304| Promise\<boolean> | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| 305 306**Error codes** 307 308For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 309 310| Error Code ID| Error Message | 311| -------- | -------------------------------------- | 312| 12800005 | Configuration persisting error. | 313| 12800008 | Input method manager service error. | 314 315**Example** 316 317```js 318try { 319 inputMethod.switchCurrentInputMethodSubtype({ 320 id: "com.example.kikakeyboard", 321 label: "ServiceExtAbility", 322 name: "", 323 mode: "upper", 324 locale: "", 325 language: "", 326 icon: "", 327 iconId: 0, 328 extra: {} 329 }).then((result) => { 330 if (result) { 331 console.info('Succeeded in switching currentInputMethodSubtype.'); 332 } else { 333 console.error('Failed to switchCurrentInputMethodSubtype.'); 334 } 335 }).catch((err) => { 336 console.error('Failed to switchCurrentInputMethodSubtype: ' + JSON.stringify(err)); 337 }) 338} catch(err) { 339 console.error('Failed to switchCurrentInputMethodSubtype: ' + JSON.stringify(err)); 340} 341``` 342 343## inputMethod.getCurrentInputMethodSubtype<sup>9+</sup> 344 345getCurrentInputMethodSubtype(): InputMethodSubtype 346 347Obtains the current input method subtype. 348 349**System capability**: SystemCapability.MiscServices.InputMethodFramework 350 351**Return value** 352 353| Type | Description | 354| -------------------------------------------- | ------------------------ | 355| [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype) | Current input method subtype.| 356 357**Example** 358 359```js 360let currentImeSubType = inputMethod.getCurrentInputMethodSubtype(); 361``` 362 363## inputMethod.switchCurrentInputMethodAndSubtype<sup>9+</sup> 364 365switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback\<boolean>): void 366 367Switches to a specified subtype of a specified input method. This API uses an asynchronous callback to return the result. 368 369**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 370 371**System capability**: SystemCapability.MiscServices.InputMethodFramework 372 373**Parameters** 374 375| Name| Type| Mandatory| Description| 376| -------- | -------- | -------- | -------- | 377|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| 378|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.| 379| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 380 381**Error codes** 382 383For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 384 385| Error Code ID| Error Message | 386| -------- | -------------------------------------- | 387| 12800005 | Configuration persisting error. | 388| 12800008 | Input method manager service error. | 389 390**Example** 391 392```js 393let im = inputMethod.getCurrentInputMethod(); 394let inputMethodProperty = { 395 packageName: im.packageName, 396 methodId: im.methodId, 397 name: im.packageName, 398 id: im.methodId, 399 extra: {} 400} 401try { 402 inputMethod.switchCurrentInputMethodAndSubtype(inputMethodProperty, { 403 id: "com.example.kikakeyboard", 404 label: "ServiceExtAbility", 405 name: "", 406 mode: "upper", 407 locale: "", 408 language: "", 409 icon: "", 410 iconId: 0, 411 extra: {} 412 }, (err,result) => { 413 if (err !== undefined) { 414 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 415 return; 416 } 417 if (result) { 418 console.info('Succeeded in switching currentInputMethodAndSubtype.'); 419 } else { 420 console.error('Failed to switchCurrentInputMethodAndSubtype.'); 421 } 422 }); 423} catch (err) { 424 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 425} 426``` 427 428## inputMethod.switchCurrentInputMethodAndSubtype<sup>9+</sup> 429 430switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean> 431 432Switches to a specified subtype of a specified input method. This API uses a promise to return the result. 433 434**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 435 436**System capability**: SystemCapability.MiscServices.InputMethodFramework 437 438**Parameters** 439 440| Name| Type| Mandatory| Description| 441| -------- | -------- | -------- | -------- | 442|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| 443|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.| 444 445**Return value** 446 447| Type | Description | 448| ----------------------------------------- | ---------------------------- | 449| Promise\<boolean> | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| 450 451**Error codes** 452 453For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 454 455| Error Code ID| Error Message | 456| -------- | -------------------------------------- | 457| 12800005 | Configuration persisting error. | 458| 12800008 | Input method manager service error. | 459 460**Example** 461 462```js 463let im = inputMethod.getCurrentInputMethod(); 464let inputMethodProperty = { 465 packageName: im.packageName, 466 methodId: im.methodId, 467 name: im.packageName, 468 id: im.methodId, 469 extra: {} 470} 471try { 472 inputMethod.switchCurrentInputMethodAndSubtype(inputMethodProperty, { 473 id: im.packageName, 474 label: im.methodId, 475 name: "", 476 mode: "upper", 477 locale: "", 478 language: "", 479 icon: "", 480 iconId: 0, 481 extra: {} 482 }).then((result) => { 483 if (result) { 484 console.info('Succeeded in switching currentInputMethodAndSubtype.'); 485 } else { 486 console.error('Failed to switchCurrentInputMethodAndSubtype.'); 487 } 488 }).catch((err) => { 489 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 490 }) 491} catch(err) { 492 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 493} 494``` 495 496## inputMethod.getInputMethodController<sup>(deprecated)</sup> 497 498getInputMethodController(): InputMethodController 499 500Obtains an **[InputMethodController](#inputmethodcontroller)** instance. 501 502> **NOTE** 503> 504> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getController()](#inputmethodgetcontroller9). 505 506**System capability**: SystemCapability.MiscServices.InputMethodFramework 507 508**Return value** 509 510| Type | Description | 511| ----------------------------------------------- | ------------------------ | 512| [InputMethodController](#inputmethodcontroller) | Current **InputMethodController** instance.| 513 514**Example** 515 516```js 517let inputMethodController = inputMethod.getInputMethodController(); 518``` 519 520## inputMethod.getInputMethodSetting<sup>(deprecated)</sup> 521 522getInputMethodSetting(): InputMethodSetting 523 524Obtains an **[InputMethodSetting](#inputmethodsetting8)** instance. 525 526> **NOTE** 527> 528> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getSetting()](#inputmethodgetsetting9). 529 530**System capability**: SystemCapability.MiscServices.InputMethodFramework 531 532**Return value** 533 534| Type | Description | 535| ----------------------------------------- | ---------------------------- | 536| [InputMethodSetting](#inputmethodsetting8) | Current **InputMethodSetting** instance.| 537 538**Example** 539 540```js 541let inputMethodSetting = inputMethod.getInputMethodSetting(); 542``` 543 544## InputMethodController 545 546In the following API examples, you must first use [getController](#inputmethodgetcontroller9) to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance. 547 548### stopInputSession<sup>9+</sup> 549 550stopInputSession(callback: AsyncCallback<boolean>): void 551 552Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses an asynchronous callback to return the result. 553 554**System capability**: SystemCapability.MiscServices.InputMethodFramework 555 556**Parameters** 557 558| Name| Type| Mandatory| Description| 559| -------- | -------- | -------- | -------- | 560| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 561 562**Error codes** 563 564For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 565 566| Error Code ID| Error Message | 567| -------- | -------------------------------------- | 568| 12800003 | Input method client error. | 569| 12800008 | Input method manager service error. | 570 571**Example** 572 573```js 574try { 575 inputMethodController.stopInputSession((error, result) => { 576 if (error !== undefined) { 577 console.error('Failed to stopInputSession: ' + JSON.stringify(error)); 578 return; 579 } 580 if (result) { 581 console.info('Succeeded in stopping inputSession.'); 582 } else { 583 console.error('Failed to stopInputSession.'); 584 } 585 }); 586} catch(error) { 587 console.error('Failed to stopInputSession: ' + JSON.stringify(error)); 588} 589``` 590 591### stopInputSession<sup>9+</sup> 592 593stopInputSession(): Promise<boolean> 594 595Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses a promise to return the result. 596 597**System capability**: SystemCapability.MiscServices.InputMethodFramework 598 599**Return value** 600 601| Type| Description| 602| -------- | -------- | 603| Promise<boolean> | Promise used to return the result. The value **true** means that the ending is successful, and **false** means the opposite.| 604 605**Error codes** 606 607For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 608 609| Error Code ID| Error Message | 610| -------- | -------------------------------------- | 611| 12800003 | Input method client error. | 612| 12800008 | Input method manager service error. | 613 614**Example** 615 616```js 617try { 618 inputMethodController.stopInputSession().then((result) => { 619 if (result) { 620 console.info('Succeeded in stopping inputSession.'); 621 } else { 622 console.error('Failed to stopInputSession.'); 623 } 624 }).catch((err) => { 625 console.error('Failed to stopInputSession: ' + JSON.stringify(err)); 626 }) 627} catch(err) { 628 console.error('Failed to stopInputSession: ' + JSON.stringify(err)); 629} 630``` 631 632### showSoftKeyboard<sup>9+</sup> 633 634showSoftKeyboard(callback: AsyncCallback<void>): void 635 636Shows this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses an asynchronous callback to return the result. 637 638**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 639 640**System capability**: SystemCapability.MiscServices.InputMethodFramework 641 642**Parameters** 643 644| Name | Type | Mandatory| Description | 645| -------- | ------------------------- | ---- | ---------- | 646| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 647 648**Error codes** 649 650For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 651 652| Error Code ID| Error Message | 653| -------- | -------------------------------------- | 654| 12800003 | Input method client error. | 655| 12800008 | Input method manager service error. | 656 657**Example** 658 659```js 660inputMethodController.showSoftKeyboard((err) => { 661 if (err === undefined) { 662 console.info('Succeeded in showing softKeyboard.'); 663 } else { 664 console.error('Failed to showSoftKeyboard: ' + JSON.stringify(err)); 665 } 666}) 667``` 668 669### showSoftKeyboard<sup>9+</sup> 670 671showSoftKeyboard(): Promise<void> 672 673Shows this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses a promise to return the result. 674 675**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 676 677**System capability**: SystemCapability.MiscServices.InputMethodFramework 678 679**Return value** 680 681| Type | Description | 682| ------------------- | ------------------------- | 683| Promise<void> | Promise that returns no value.| 684 685**Error codes** 686 687For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 688 689| Error Code ID| Error Message | 690| -------- | -------------------------------------- | 691| 12800003 | Input method client error. | 692| 12800008 | Input method manager service error. | 693 694**Example** 695 696```js 697inputMethodController.showSoftKeyboard().then(() => { 698 console.log('Succeeded in showing softKeyboard.'); 699}).catch((err) => { 700 console.error('Failed to showSoftKeyboard: ' + JSON.stringify(err)); 701}); 702``` 703 704### hideSoftKeyboard<sup>9+</sup> 705 706hideSoftKeyboard(callback: AsyncCallback<void>): void 707 708Hides this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses an asynchronous callback to return the result. 709 710**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 711 712**System capability**: SystemCapability.MiscServices.InputMethodFramework 713 714**Parameters** 715 716| Name | Type | Mandatory| Description | 717| -------- | ------------------------- | ---- | ---------- | 718| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 719 720**Error codes** 721 722For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 723 724| Error Code ID| Error Message | 725| -------- | -------------------------------------- | 726| 12800003 | Input method client error. | 727| 12800008 | Input method manager service error. | 728 729**Example** 730 731```js 732inputMethodController.hideSoftKeyboard((err) => { 733 if (err === undefined) { 734 console.info('Succeeded in hiding softKeyboard.'); 735 } else { 736 console.error('Failed to hideSoftKeyboard: ' + JSON.stringify(err)); 737 } 738}) 739``` 740 741### hideSoftKeyboard<sup>9+</sup> 742 743hideSoftKeyboard(): Promise<void> 744 745Hides this soft keyboard. This API must be used with the input text box and works only when the input text box is activated. This API uses a promise to return the result. 746 747**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) 748 749**System capability**: SystemCapability.MiscServices.InputMethodFramework 750 751**Return value** 752 753| Type | Description | 754| ------------------- | ------------------------- | 755| Promise<void> | Promise that returns no value.| 756 757**Error codes** 758 759For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 760 761| Error Code ID| Error Message | 762| -------- | -------------------------------------- | 763| 12800003 | Input method client error. | 764| 12800008 | Input method manager service error. | 765 766**Example** 767 768```js 769inputMethodController.hideSoftKeyboard().then(() => { 770 console.log('Succeeded in hiding softKeyboard.'); 771}).catch((err) => { 772 console.error('Failed to hideSoftKeyboard: ' + JSON.stringify(err)); 773}); 774``` 775 776### stopInput<sup>(deprecated)</sup> 777 778stopInput(callback: AsyncCallback<boolean>): void 779 780Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses an asynchronous callback to return the result. 781 782> **NOTE** 783> 784> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9). 785 786**System capability**: SystemCapability.MiscServices.InputMethodFramework 787 788**Parameters** 789 790| Name| Type| Mandatory| Description| 791| -------- | -------- | -------- | -------- | 792| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 793 794**Example** 795 796```js 797inputMethodController.stopInput((error, result) => { 798 if (error !== undefined) { 799 console.error('Failed to stopInput: ' + JSON.stringify(error)); 800 return; 801 } 802 if (result) { 803 console.info('Succeeded in stopping input.'); 804 } else { 805 console.error('Failed to stopInput.'); 806 } 807}); 808``` 809 810### stopInput<sup>(deprecated)</sup> 811 812stopInput(): Promise<boolean> 813 814Ends this input session. The invoking of this API takes effect only after the input session is enabled by clicking the text box. This API uses a promise to return the result. 815 816> **NOTE** 817> 818> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9). 819 820**System capability**: SystemCapability.MiscServices.InputMethodFramework 821 822**Return value** 823 824| Type| Description| 825| -------- | -------- | 826| Promise<boolean> | Promise used to return the result. The value **true** means that the hiding is successful, and **false** means the opposite.| 827 828**Example** 829 830```js 831inputMethodController.stopInput().then((result) => { 832 if (result) { 833 console.info('Succeeded in stopping input.'); 834 } else { 835 console.error('Failed to stopInput.'); 836 } 837}).catch((err) => { 838 console.error('Failed to stopInput: ' + err); 839}) 840``` 841 842## InputMethodSetting<sup>8+</sup> 843 844In the following API examples, you must first use [getSetting](#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance. 845 846### on('imeChange')<sup>9+</sup> 847 848on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void 849 850Enables listening for the input method and subtype change event. This API uses an asynchronous callback to return the result. 851 852**System capability**: SystemCapability.MiscServices.InputMethodFramework 853 854**Parameters** 855 856| Name | Type | Mandatory| Description | 857| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 858| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.| 859| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | Yes| Callback used to return the input method attributes and subtype.| 860 861**Example** 862 863```js 864inputMethodSetting.on('imeChange', (inputMethodProperty, inputMethodSubtype) => { 865 console.info('Succeeded in subscribing imeChange: inputMethodProperty: ' + JSON.stringify(inputMethodProperty) + " , inputMethodSubtype: " + JSON.stringify(inputMethodSubtype)); 866}); 867``` 868 869### off('imeChange')<sup>9+</sup> 870 871off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void 872 873Disables listening for the input method and subtype change event. This API uses an asynchronous callback to return the result. 874 875**System capability**: SystemCapability.MiscServices.InputMethodFramework 876 877**Parameters** 878 879| Name | Type | Mandatory| Description | 880| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 881| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.| 882| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | No| Callback used to return the input method attributes and subtype.| 883 884**Example** 885 886```js 887inputMethodSetting.off('imeChange'); 888``` 889 890### listInputMethodSubtype<sup>9+</sup> 891 892listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void 893 894Obtains all subtypes of a specified input method. This API uses an asynchronous callback to return the result. 895 896**System capability**: SystemCapability.MiscServices.InputMethodFramework 897 898**Parameters** 899 900| Name | Type | Mandatory| Description | 901| -------- | -------------------------------------------------- | ---- | ---------------------- | 902| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.| 903| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes| Callback used to return all subtypes of the specified input method.| 904 905**Error codes** 906 907For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 908 909| Error Code ID| Error Message | 910| -------- | -------------------------------------- | 911| 12800001 | Package manager error. | 912| 12800008 | Input method manager service error. | 913 914**Example** 915 916```js 917let inputMethodProperty = { 918 packageName: 'com.example.kikakeyboard', 919 methodId: 'com.example.kikakeyboard', 920 name: 'com.example.kikakeyboard', 921 id: 'com.example.kikakeyboard', 922 extra:{} 923} 924try { 925 inputMethodSetting.listInputMethodSubtype(inputMethodProperty, (err,data) => { 926 if (err !== undefined) { 927 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 928 return; 929 } 930 console.log('Succeeded in listing inputMethodSubtype.'); 931 }); 932} catch (err) { 933 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 934} 935``` 936 937### listInputMethodSubtype<sup>9+</sup> 938 939listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>> 940 941Obtains all subtypes of a specified input method. This API uses a promise to return the result. 942 943**System capability**: SystemCapability.MiscServices.InputMethodFramework 944 945**Parameters** 946 947| Name | Type | Mandatory| Description | 948| -------- | -------------------------------------------------- | ---- | ---------------------- | 949| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.| 950 951**Return value** 952 953| Type | Description | 954| ----------------------------------------------------------- | ---------------------- | 955| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the specified input method.| 956 957**Error codes** 958 959For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 960 961| Error Code ID| Error Message | 962| -------- | -------------------------------------- | 963| 12800001 | Package manager error. | 964| 12800008 | Input method manager service error. | 965 966**Example** 967 968```js 969let inputMethodProperty = { 970 packageName: 'com.example.kikakeyboard', 971 methodId: 'com.example.kikakeyboard', 972 name: 'com.example.kikakeyboard', 973 id: 'com.example.kikakeyboard', 974 extra:{} 975} 976try { 977 inputMethodSetting.listInputMethodSubtype(inputMethodProperty).then((data) => { 978 console.info('Succeeded in listing inputMethodSubtype.'); 979 }).catch((err) => { 980 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 981 }) 982} catch(err) { 983 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 984} 985``` 986 987### listCurrentInputMethodSubtype<sup>9+</sup> 988 989listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void 990 991Obtains all subtypes of this input method. This API uses an asynchronous callback to return the result. 992 993**System capability**: SystemCapability.MiscServices.InputMethodFramework 994 995**Parameters** 996 997| Name | Type | Mandatory| Description | 998| -------- | -------------------------------------------------- | ---- | ---------------------- | 999| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes | Callback used to return all subtypes of the current input method.| 1000 1001**Error codes** 1002 1003For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1004 1005| Error Code ID| Error Message | 1006| -------- | -------------------------------------- | 1007| 12800001 | Package manager error. | 1008| 12800008 | Input method manager service error. | 1009 1010**Example** 1011 1012```js 1013try { 1014 inputMethodSetting.listCurrentInputMethodSubtype((err, data) => { 1015 if (err !== undefined) { 1016 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1017 return; 1018 } 1019 console.log('Succeeded in listing currentInputMethodSubtype.'); 1020 }); 1021} catch(err) { 1022 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1023} 1024``` 1025 1026### listCurrentInputMethodSubtype<sup>9+</sup> 1027 1028listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>> 1029 1030Obtains all subtypes of this input method. This API uses a promise to return the result. 1031 1032**System capability**: SystemCapability.MiscServices.InputMethodFramework 1033 1034**Return value** 1035 1036| Type | Description | 1037| ----------------------------------------------------------- | ---------------------- | 1038| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the current input method.| 1039 1040**Error codes** 1041 1042For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1043 1044| Error Code ID| Error Message | 1045| -------- | -------------------------------------- | 1046| 12800001 | Package manager error. | 1047| 12800008 | Input method manager service error. | 1048 1049**Example** 1050 1051```js 1052try { 1053 inputMethodSetting.listCurrentInputMethodSubtype().then((data) => { 1054 console.info('Succeeded in listing currentInputMethodSubtype.'); 1055 }).catch((err) => { 1056 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1057 }) 1058} catch(err) { 1059 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1060} 1061``` 1062 1063### getInputMethods<sup>9+</sup> 1064 1065getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void 1066 1067Obtains a list of activated or deactivated input methods. In the current version, an activated input method is the input method in use, and a deactivated one is any of the installed input methods except the one in use. This API uses an asynchronous callback to return the result. 1068 1069**System capability**: SystemCapability.MiscServices.InputMethodFramework 1070 1071**Parameters** 1072 1073| Name | Type | Mandatory| Description | 1074| -------- | --------------------------------------------------- | ---- | ----------------------------- | 1075| enable | boolean | Yes | Whether to return a list of activated input methods. The value **true** means to return a list of activated input methods, and **false** means to return a list of deactivated input methods. | 1076| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return a list of activated or deactivated input methods.| 1077 1078**Error codes** 1079 1080For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1081 1082| Error Code ID| Error Message | 1083| -------- | -------------------------------------- | 1084| 12800001 | Package manager error. | 1085| 12800008 | Input method manager service error. | 1086 1087**Example** 1088 1089```js 1090try { 1091 inputMethodSetting.getInputMethods(true, (err,data) => { 1092 if (err !== undefined) { 1093 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1094 return; 1095 } 1096 console.log('Succeeded in getting inputMethods.'); 1097 }); 1098} catch (err) { 1099 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1100} 1101``` 1102 1103### getInputMethods<sup>9+</sup> 1104 1105getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>> 1106 1107Obtains a list of activated or deactivated input methods. In the current version, an activated input method is the input method in use, and a deactivated one is any of the installed input methods except the one in use. This API uses a promise to return the result. 1108 1109**System capability**: SystemCapability.MiscServices.InputMethodFramework 1110 1111**Parameters** 1112 1113| Name| Type | Mandatory| Description | 1114| ------ | ------- | ---- | ----------------------- | 1115| enable | boolean | Yes | Whether to return a list of activated input methods. The value **true** means to return a list of activated input methods, and **false** means to return a list of deactivated input methods.| 1116 1117**Error codes** 1118 1119For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1120 1121| Error Code ID| Error Message | 1122| -------- | -------------------------------------- | 1123| 12800001 | Package manager error. | 1124| 12800008 | Input method manager service error. | 1125 1126**Return value** 1127 1128| Type | Description | 1129| ------------------------------------------------------------ | ----------------------------- | 1130| Promise<Array<[InputMethodProperty](#inputmethodproperty8)>> | Promise used to return a list of activated or deactivated input methods.| 1131 1132**Example** 1133 1134```js 1135try { 1136 inputMethodSetting.getInputMethods(true).then((data) => { 1137 console.info('Succeeded in getting inputMethods.'); 1138 }).catch((err) => { 1139 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1140 }) 1141} catch(err) { 1142 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1143} 1144``` 1145 1146### showOptionalInputMethods<sup>9+</sup> 1147 1148showOptionalInputMethods(callback: AsyncCallback<boolean>): void 1149 1150Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. 1151 1152**System capability**: SystemCapability.MiscServices.InputMethodFramework 1153 1154**Parameters** 1155 1156| Name| Type| Mandatory| Description| 1157| -------- | -------- | -------- | -------- | 1158| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.| 1159 1160**Error codes** 1161 1162For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1163 1164| Error Code ID| Error Message | 1165| -------- | -------------------------------------- | 1166| 12800008 | Input method manager service error. | 1167 1168**Example** 1169 1170```js 1171try { 1172 inputMethodSetting.showOptionalInputMethods((err, data) => { 1173 if (err !== undefined) { 1174 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1175 return; 1176 } 1177 console.info('Succeeded in showing optionalInputMethods.'); 1178 }); 1179} catch (err) { 1180 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1181} 1182``` 1183 1184### showOptionalInputMethods<sup>9+</sup> 1185 1186showOptionalInputMethods(): Promise<boolean> 1187 1188Displays a dialog box for selecting an input method. This API uses a promise to return the result. 1189 1190**System capability**: SystemCapability.MiscServices.InputMethodFramework 1191 1192**Return value** 1193 1194| Type| Description| 1195| -------- | -------- | 1196| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.| 1197 1198**Error codes** 1199 1200For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1201 1202| Error Code ID| Error Message | 1203| -------- | -------------------------------------- | 1204| 12800008 | Input method manager service error. | 1205 1206**Example** 1207 1208```js 1209inputMethodSetting.showOptionalInputMethods().then((data) => { 1210 console.info('Succeeded in showing optionalInputMethods.'); 1211}).catch((err) => { 1212 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1213}) 1214``` 1215 1216### listInputMethod<sup>(deprecated)</sup> 1217 1218listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void 1219 1220Obtains a list of installed input methods. This API uses an asynchronous callback to return the result. 1221 1222> **NOTE** 1223> 1224> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethods](#getinputmethods9). 1225 1226**System capability**: SystemCapability.MiscServices.InputMethodFramework 1227 1228**Parameters** 1229 1230| Name | Type | Mandatory| Description | 1231| -------- | -------------------------------------------------- | ---- | ---------------------- | 1232| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return the list of installed input methods.| 1233 1234**Example** 1235 1236```js 1237inputMethodSetting.listInputMethod((err,data) => { 1238 if (err !== undefined) { 1239 console.error('Failed to listInputMethod: ' + JSON.stringify(err)); 1240 return; 1241 } 1242 console.log('Succeeded in listing inputMethod.'); 1243 }); 1244``` 1245 1246### listInputMethod<sup>(deprecated)</sup> 1247 1248listInputMethod(): Promise<Array<InputMethodProperty>> 1249 1250Obtains a list of installed input methods. This API uses a promise to return the result. 1251 1252> **NOTE** 1253> 1254> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethods](#getinputmethods9-1). 1255 1256**System capability**: SystemCapability.MiscServices.InputMethodFramework 1257 1258**Return value** 1259 1260| Type | Description | 1261| ----------------------------------------------------------- | ---------------------- | 1262| Promise<Array<[InputMethodProperty](#inputmethodproperty8)>> | Promise used to return the list of installed input methods.| 1263 1264**Example** 1265 1266```js 1267inputMethodSetting.listInputMethod().then((data) => { 1268 console.info('Succeeded in listing inputMethod.'); 1269}).catch((err) => { 1270 console.error('Failed to listInputMethod: ' + JSON.stringify(err)); 1271}) 1272``` 1273 1274### displayOptionalInputMethod<sup>(deprecated)</sup> 1275 1276displayOptionalInputMethod(callback: AsyncCallback<void>): void 1277 1278Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. 1279 1280> **NOTE** 1281> 1282> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [showOptionalInputMethods()](#showoptionalinputmethods9). 1283 1284**System capability**: SystemCapability.MiscServices.InputMethodFramework 1285 1286**Parameters** 1287 1288| Name| Type| Mandatory| Description| 1289| -------- | -------- | -------- | -------- | 1290| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 1291 1292**Example** 1293 1294```js 1295inputMethodSetting.displayOptionalInputMethod((err) => { 1296 if (err !== undefined) { 1297 console.error('Failed to displayOptionalInputMethod: ' + JSON.stringify(err)); 1298 return; 1299 } 1300 console.info('Succeeded in displaying optionalInputMethod.'); 1301}); 1302``` 1303 1304### displayOptionalInputMethod<sup>(deprecated)</sup> 1305 1306displayOptionalInputMethod(): Promise<void> 1307 1308Displays a dialog box for selecting an input method. This API uses a promise to return the result. 1309 1310> **NOTE** 1311> 1312> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [showOptionalInputMethods()](#showoptionalinputmethods9-1). 1313 1314**System capability**: SystemCapability.MiscServices.InputMethodFramework 1315 1316**Return value** 1317 1318| Type| Description| 1319| -------- | -------- | 1320| Promise<void> | Promise that returns no value.| 1321 1322**Example** 1323 1324```js 1325inputMethodSetting.displayOptionalInputMethod().then(() => { 1326 console.info('Succeeded in displaying optionalInputMethod.'); 1327}).catch((err) => { 1328 console.error('Failed to displayOptionalInputMethod: ' + JSON.stringify(err)); 1329}) 1330``` 1331