1# @ohos.inputMethod (Input Method Framework) 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``` 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 (for system applications only) 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 (for system applications only) 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 (for system applications only) 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)| 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: "ServiceExtAbility", 260 label: "", 261 name: "com.example.kikakeyboard", 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 (for system applications only) 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)| 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: "ServiceExtAbility", 321 label: "", 322 name: "com.example.kikakeyboard", 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) | 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 (for system applications only) 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)| 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 imSubType = inputMethod.getCurrentInputMethodSubtype(); 395try { 396 inputMethod.switchCurrentInputMethodAndSubtype(im, imSubType, (err,result) => { 397 if (err !== undefined) { 398 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 399 return; 400 } 401 if (result) { 402 console.info('Succeeded in switching currentInputMethodAndSubtype.'); 403 } else { 404 console.error('Failed to switchCurrentInputMethodAndSubtype.'); 405 } 406 }); 407} catch (err) { 408 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 409} 410``` 411 412## inputMethod.switchCurrentInputMethodAndSubtype<sup>9+</sup> 413 414switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean> 415 416Switches to a specified subtype of a specified input method. This API uses a promise to return the result. 417 418**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (for system applications only) 419 420**System capability**: SystemCapability.MiscServices.InputMethodFramework 421 422**Parameters** 423 424| Name| Type| Mandatory| Description| 425| -------- | -------- | -------- | -------- | 426|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| 427|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md)| Yes| Input method subtype to switch to.| 428 429**Return value** 430 431| Type | Description | 432| ----------------------------------------- | ---------------------------- | 433| Promise\<boolean> | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| 434 435**Error codes** 436 437For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 438 439| Error Code ID| Error Message | 440| -------- | -------------------------------------- | 441| 12800005 | configuration persisting error. | 442| 12800008 | input method manager service error. | 443 444**Example** 445 446```js 447let im = inputMethod.getCurrentInputMethod(); 448let imSubType = inputMethod.getCurrentInputMethodSubtype(); 449try { 450 inputMethod.switchCurrentInputMethodAndSubtype(im, imSubType).then((result) => { 451 if (result) { 452 console.info('Succeeded in switching currentInputMethodAndSubtype.'); 453 } else { 454 console.error('Failed to switchCurrentInputMethodAndSubtype.'); 455 } 456 }).catch((err) => { 457 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 458 }) 459} catch(err) { 460 console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err)); 461} 462``` 463 464## inputMethod.getInputMethodController<sup>(deprecated)</sup> 465 466getInputMethodController(): InputMethodController 467 468Obtains an **[InputMethodController](#inputmethodcontroller)** instance. 469 470> **NOTE** 471> 472> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getController()](#inputmethodgetcontroller9). 473 474**System capability**: SystemCapability.MiscServices.InputMethodFramework 475 476**Return value** 477 478| Type | Description | 479| ----------------------------------------------- | ------------------------ | 480| [InputMethodController](#inputmethodcontroller) | Current **InputMethodController** instance.| 481 482**Example** 483 484```js 485let inputMethodController = inputMethod.getInputMethodController(); 486``` 487 488## inputMethod.getInputMethodSetting<sup>(deprecated)</sup> 489 490getInputMethodSetting(): InputMethodSetting 491 492Obtains an **[InputMethodSetting](#inputmethodsetting8)** instance. 493 494> **NOTE** 495> 496> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getSetting()](#inputmethodgetsetting9). 497 498**System capability**: SystemCapability.MiscServices.InputMethodFramework 499 500**Return value** 501 502| Type | Description | 503| ----------------------------------------- | ---------------------------- | 504| [InputMethodSetting](#inputmethodsetting8) | Current **InputMethodSetting** instance.| 505 506**Example** 507 508```js 509let inputMethodSetting = inputMethod.getInputMethodSetting(); 510``` 511 512## InputMethodController 513 514In the following API examples, you must first use [getController](#inputmethodgetcontroller9) to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance. 515 516### stopInputSession<sup>9+</sup> 517 518stopInputSession(callback: AsyncCallback<boolean>): void 519 520Ends 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. 521 522**System capability**: SystemCapability.MiscServices.InputMethodFramework 523 524**Parameters** 525 526| Name| Type| Mandatory| Description| 527| -------- | -------- | -------- | -------- | 528| 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.| 529 530**Error codes** 531 532For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 533 534| Error Code ID| Error Message | 535| -------- | -------------------------------------- | 536| 12800003 | input method client error. | 537| 12800008 | input method manager service error. | 538 539**Example** 540 541```js 542try { 543 inputMethodController.stopInputSession((error, result) => { 544 if (error !== undefined) { 545 console.error('Failed to stopInputSession: ' + JSON.stringify(error)); 546 return; 547 } 548 if (result) { 549 console.info('Succeeded in stopping inputSession.'); 550 } else { 551 console.error('Failed to stopInputSession.'); 552 } 553 }); 554} catch(error) { 555 console.error('Failed to stopInputSession: ' + JSON.stringify(error)); 556} 557``` 558 559### stopInputSession<sup>9+</sup> 560 561stopInputSession(): Promise<boolean> 562 563Ends 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. 564 565**System capability**: SystemCapability.MiscServices.InputMethodFramework 566 567**Return value** 568 569| Type| Description| 570| -------- | -------- | 571| Promise<boolean> | Promise used to return the result. The value **true** means that the ending is successful, and **false** means the opposite.| 572 573**Error codes** 574 575For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 576 577| Error Code ID| Error Message | 578| -------- | -------------------------------------- | 579| 12800003 | input method client error. | 580| 12800008 | input method manager service error. | 581 582**Example** 583 584```js 585try { 586 inputMethodController.stopInputSession().then((result) => { 587 if (result) { 588 console.info('Succeeded in stopping inputSession.'); 589 } else { 590 console.error('Failed to stopInputSession.'); 591 } 592 }).catch((err) => { 593 console.error('Failed to stopInputSession: ' + JSON.stringify(err)); 594 }) 595} catch(err) { 596 console.error('Failed to stopInputSession: ' + JSON.stringify(err)); 597} 598``` 599 600### showSoftKeyboard<sup>9+</sup> 601 602showSoftKeyboard(callback: AsyncCallback<void>): void 603 604Shows 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. 605 606**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (for system applications only) 607 608**System capability**: SystemCapability.MiscServices.InputMethodFramework 609 610**Parameters** 611 612| Name | Type | Mandatory| Description | 613| -------- | ------------------------- | ---- | ---------- | 614| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 615 616**Error codes** 617 618For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 619 620| Error Code ID| Error Message | 621| -------- | -------------------------------------- | 622| 12800003 | input method client error. | 623| 12800008 | input method manager service error. | 624 625**Example** 626 627```js 628inputMethodController.showSoftKeyboard((err) => { 629 if (err === undefined) { 630 console.info('Succeeded in showing softKeyboard.'); 631 } else { 632 console.error('Failed to showSoftKeyboard: ' + JSON.stringify(err)); 633 } 634}) 635``` 636 637### showSoftKeyboard<sup>9+</sup> 638 639showSoftKeyboard(): Promise<void> 640 641Shows 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. 642 643**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (for system applications only) 644 645**System capability**: SystemCapability.MiscServices.InputMethodFramework 646 647**Return value** 648 649| Type | Description | 650| ------------------- | ------------------------- | 651| Promise<void> | Promise that returns no value.| 652 653**Error codes** 654 655For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 656 657| Error Code ID| Error Message | 658| -------- | -------------------------------------- | 659| 12800003 | input method client error. | 660| 12800008 | input method manager service error. | 661 662**Example** 663 664```js 665inputMethodController.showSoftKeyboard().then(() => { 666 console.log('Succeeded in showing softKeyboard.'); 667}).catch((err) => { 668 console.error('Failed to showSoftKeyboard: ' + JSON.stringify(err)); 669}); 670``` 671 672### hideSoftKeyboard<sup>9+</sup> 673 674hideSoftKeyboard(callback: AsyncCallback<void>): void 675 676Hides 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. 677 678**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (for system applications only) 679 680**System capability**: SystemCapability.MiscServices.InputMethodFramework 681 682**Parameters** 683 684| Name | Type | Mandatory| Description | 685| -------- | ------------------------- | ---- | ---------- | 686| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 687 688**Error codes** 689 690For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 691 692| Error Code ID| Error Message | 693| -------- | -------------------------------------- | 694| 12800003 | input method client error. | 695| 12800008 | input method manager service error. | 696 697**Example** 698 699```js 700inputMethodController.hideSoftKeyboard((err) => { 701 if (err === undefined) { 702 console.info('Succeeded in hiding softKeyboard.'); 703 } else { 704 console.error('Failed to hideSoftKeyboard: ' + JSON.stringify(err)); 705 } 706}) 707``` 708 709### hideSoftKeyboard<sup>9+</sup> 710 711hideSoftKeyboard(): Promise<void> 712 713Hides 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. 714 715**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (for system applications only) 716 717**System capability**: SystemCapability.MiscServices.InputMethodFramework 718 719**Return value** 720 721| Type | Description | 722| ------------------- | ------------------------- | 723| Promise<void> | Promise that returns no value.| 724 725**Error codes** 726 727For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 728 729| Error Code ID| Error Message | 730| -------- | -------------------------------------- | 731| 12800003 | input method client error. | 732| 12800008 | input method manager service error. | 733 734**Example** 735 736```js 737inputMethodController.hideSoftKeyboard().then(() => { 738 console.log('Succeeded in hiding softKeyboard.'); 739}).catch((err) => { 740 console.error('Failed to hideSoftKeyboard: ' + JSON.stringify(err)); 741}); 742``` 743 744### stopInput<sup>(deprecated)</sup> 745 746stopInput(callback: AsyncCallback<boolean>): void 747 748Ends 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. 749 750> **NOTE** 751> 752> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9). 753 754**System capability**: SystemCapability.MiscServices.InputMethodFramework 755 756**Parameters** 757 758| Name| Type| Mandatory| Description| 759| -------- | -------- | -------- | -------- | 760| 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.| 761 762**Example** 763 764```js 765inputMethodController.stopInput((error, result) => { 766 if (error !== undefined) { 767 console.error('Failed to stopInput: ' + JSON.stringify(error)); 768 return; 769 } 770 if (result) { 771 console.info('Succeeded in stopping input.'); 772 } else { 773 console.error('Failed to stopInput.'); 774 } 775}); 776``` 777 778### stopInput<sup>(deprecated)</sup> 779 780stopInput(): Promise<boolean> 781 782Ends 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. 783 784> **NOTE** 785> 786> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [stopInputSession()](#stopinputsession9). 787 788**System capability**: SystemCapability.MiscServices.InputMethodFramework 789 790**Return value** 791 792| Type| Description| 793| -------- | -------- | 794| Promise<boolean> | Promise used to return the result. The value **true** means that the hiding is successful, and **false** means the opposite.| 795 796**Example** 797 798```js 799inputMethodController.stopInput().then((result) => { 800 if (result) { 801 console.info('Succeeded in stopping input.'); 802 } else { 803 console.error('Failed to stopInput.'); 804 } 805}).catch((err) => { 806 console.error('Failed to stopInput: ' + err); 807}) 808``` 809 810## InputMethodSetting<sup>8+</sup> 811 812In the following API examples, you must first use [getSetting](#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance. 813 814### on('imeChange')<sup>9+</sup> 815 816on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void 817 818Enables listening for the input method and subtype change event. This API uses an asynchronous callback to return the result. 819 820**System capability**: SystemCapability.MiscServices.InputMethodFramework 821 822**Parameters** 823 824| Name | Type | Mandatory| Description | 825| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 826| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.| 827| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md)) => void | Yes| Callback used to return the input method attributes and subtype.| 828 829**Example** 830 831```js 832inputMethodSetting.on('imeChange', (inputMethodProperty, inputMethodSubtype) => { 833 console.info('Succeeded in subscribing imeChange: inputMethodProperty: ' + JSON.stringify(inputMethodProperty) + " , inputMethodSubtype: " + JSON.stringify(inputMethodSubtype)); 834}); 835``` 836 837### off('imeChange')<sup>9+</sup> 838 839off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void 840 841Disables listening for the input method and subtype change event. This API uses an asynchronous callback to return the result. 842 843**System capability**: SystemCapability.MiscServices.InputMethodFramework 844 845**Parameters** 846 847| Name | Type | Mandatory| Description | 848| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 849| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.| 850| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md)) => void | No| Callback used to return the input method attributes and subtype.| 851 852**Example** 853 854```js 855inputMethodSetting.off('imeChange'); 856``` 857 858### listInputMethodSubtype<sup>9+</sup> 859 860listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void 861 862Obtains all subtypes of a specified input method. This API uses an asynchronous callback to return the result. 863 864**System capability**: SystemCapability.MiscServices.InputMethodFramework 865 866**Parameters** 867 868| Name | Type | Mandatory| Description | 869| -------- | -------------------------------------------------- | ---- | ---------------------- | 870| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.| 871| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Yes| Callback used to return all subtypes of the specified input method.| 872 873**Error codes** 874 875For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 876 877| Error Code ID| Error Message | 878| -------- | -------------------------------------- | 879| 12800001 | package manager error. | 880| 12800008 | input method manager service error. | 881 882**Example** 883 884```js 885let inputMethodProperty = { 886 packageName: 'com.example.kikakeyboard', 887 methodId: 'com.example.kikakeyboard', 888 name: 'com.example.kikakeyboard', 889 id: 'com.example.kikakeyboard', 890 extra:{} 891} 892try { 893 inputMethodSetting.listInputMethodSubtype(inputMethodProperty, (err,data) => { 894 if (err !== undefined) { 895 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 896 return; 897 } 898 console.log('Succeeded in listing inputMethodSubtype.'); 899 }); 900} catch (err) { 901 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 902} 903``` 904 905### listInputMethodSubtype<sup>9+</sup> 906 907listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>> 908 909Obtains all subtypes of a specified input method. This API uses a promise to return the result. 910 911**System capability**: SystemCapability.MiscServices.InputMethodFramework 912 913**Parameters** 914 915| Name | Type | Mandatory| Description | 916| -------- | -------------------------------------------------- | ---- | ---------------------- | 917| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.| 918 919**Return value** 920 921| Type | Description | 922| ----------------------------------------------------------- | ---------------------- | 923| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Promise used to return all subtypes of the specified input method.| 924 925**Error codes** 926 927For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 928 929| Error Code ID| Error Message | 930| -------- | -------------------------------------- | 931| 12800001 | package manager error. | 932| 12800008 | input method manager service error. | 933 934**Example** 935 936```js 937let inputMethodProperty = { 938 packageName: 'com.example.kikakeyboard', 939 methodId: 'com.example.kikakeyboard', 940 name: 'com.example.kikakeyboard', 941 id: 'com.example.kikakeyboard', 942 extra:{} 943} 944try { 945 inputMethodSetting.listInputMethodSubtype(inputMethodProperty).then((data) => { 946 console.info('Succeeded in listing inputMethodSubtype.'); 947 }).catch((err) => { 948 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 949 }) 950} catch(err) { 951 console.error('Failed to listInputMethodSubtype: ' + JSON.stringify(err)); 952} 953``` 954 955### listCurrentInputMethodSubtype<sup>9+</sup> 956 957listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void 958 959Obtains all subtypes of this input method. This API uses an asynchronous callback to return the result. 960 961**System capability**: SystemCapability.MiscServices.InputMethodFramework 962 963**Parameters** 964 965| Name | Type | Mandatory| Description | 966| -------- | -------------------------------------------------- | ---- | ---------------------- | 967| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Yes | Callback used to return all subtypes of the current input method.| 968 969**Error codes** 970 971For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 972 973| Error Code ID| Error Message | 974| -------- | -------------------------------------- | 975| 12800001 | package manager error. | 976| 12800008 | input method manager service error. | 977 978**Example** 979 980```js 981try { 982 inputMethodSetting.listCurrentInputMethodSubtype((err, data) => { 983 if (err !== undefined) { 984 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 985 return; 986 } 987 console.log('Succeeded in listing currentInputMethodSubtype.'); 988 }); 989} catch(err) { 990 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 991} 992``` 993 994### listCurrentInputMethodSubtype<sup>9+</sup> 995 996listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>> 997 998Obtains all subtypes of this input method. This API uses a promise to return the result. 999 1000**System capability**: SystemCapability.MiscServices.InputMethodFramework 1001 1002**Return value** 1003 1004| Type | Description | 1005| ----------------------------------------------------------- | ---------------------- | 1006| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Promise used to return all subtypes of the current input method.| 1007 1008**Error codes** 1009 1010For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1011 1012| Error Code ID| Error Message | 1013| -------- | -------------------------------------- | 1014| 12800001 | package manager error. | 1015| 12800008 | input method manager service error. | 1016 1017**Example** 1018 1019```js 1020try { 1021 inputMethodSetting.listCurrentInputMethodSubtype().then((data) => { 1022 console.info('Succeeded in listing currentInputMethodSubtype.'); 1023 }).catch((err) => { 1024 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1025 }) 1026} catch(err) { 1027 console.error('Failed to listCurrentInputMethodSubtype: ' + JSON.stringify(err)); 1028} 1029``` 1030 1031### getInputMethods<sup>9+</sup> 1032 1033getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void 1034 1035Obtains 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. 1036 1037**System capability**: SystemCapability.MiscServices.InputMethodFramework 1038 1039**Parameters** 1040 1041| Name | Type | Mandatory| Description | 1042| -------- | --------------------------------------------------- | ---- | ----------------------------- | 1043| 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. | 1044| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return a list of activated or deactivated input methods.| 1045 1046**Error codes** 1047 1048For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1049 1050| Error Code ID| Error Message | 1051| -------- | -------------------------------------- | 1052| 12800001 | package manager error. | 1053| 12800008 | input method manager service error. | 1054 1055**Example** 1056 1057```js 1058try { 1059 inputMethodSetting.getInputMethods(true, (err,data) => { 1060 if (err !== undefined) { 1061 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1062 return; 1063 } 1064 console.log('Succeeded in getting inputMethods.'); 1065 }); 1066} catch (err) { 1067 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1068} 1069``` 1070 1071### getInputMethods<sup>9+</sup> 1072 1073getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>> 1074 1075Obtains 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. 1076 1077**System capability**: SystemCapability.MiscServices.InputMethodFramework 1078 1079**Parameters** 1080 1081| Name| Type | Mandatory| Description | 1082| ------ | ------- | ---- | ----------------------- | 1083| 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.| 1084 1085**Error codes** 1086 1087For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1088 1089| Error Code ID| Error Message | 1090| -------- | -------------------------------------- | 1091| 12800001 | package manager error. | 1092| 12800008 | input method manager service error. | 1093 1094**Return value** 1095 1096| Type | Description | 1097| ------------------------------------------------------------ | ----------------------------- | 1098| Promise<Array<[InputMethodProperty](#inputmethodproperty8)>> | Promise used to return a list of activated or deactivated input methods.| 1099 1100**Example** 1101 1102```js 1103try { 1104 inputMethodSetting.getInputMethods(true).then((data) => { 1105 console.info('Succeeded in getting inputMethods.'); 1106 }).catch((err) => { 1107 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1108 }) 1109} catch(err) { 1110 console.error('Failed to getInputMethods: ' + JSON.stringify(err)); 1111} 1112``` 1113 1114### showOptionalInputMethods<sup>9+</sup> 1115 1116showOptionalInputMethods(callback: AsyncCallback<boolean>): void 1117 1118Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. 1119 1120**System capability**: SystemCapability.MiscServices.InputMethodFramework 1121 1122**Parameters** 1123 1124| Name| Type| Mandatory| Description| 1125| -------- | -------- | -------- | -------- | 1126| 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.| 1127 1128**Error codes** 1129 1130For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1131 1132| Error Code ID| Error Message | 1133| -------- | -------------------------------------- | 1134| 12800008 | input method manager service error. | 1135 1136**Example** 1137 1138```js 1139try { 1140 inputMethodSetting.showOptionalInputMethods((err, data) => { 1141 if (err !== undefined) { 1142 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1143 return; 1144 } 1145 console.info('Succeeded in showing optionalInputMethods.'); 1146 }); 1147} catch (err) { 1148 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1149} 1150``` 1151 1152### showOptionalInputMethods<sup>9+</sup> 1153 1154showOptionalInputMethods(): Promise<boolean> 1155 1156Displays a dialog box for selecting an input method. This API uses a promise to return the result. 1157 1158**System capability**: SystemCapability.MiscServices.InputMethodFramework 1159 1160**Return value** 1161 1162| Type| Description| 1163| -------- | -------- | 1164| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.| 1165 1166**Error codes** 1167 1168For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1169 1170| Error Code ID| Error Message | 1171| -------- | -------------------------------------- | 1172| 12800008 | input method manager service error. | 1173 1174**Example** 1175 1176```js 1177inputMethodSetting.showOptionalInputMethods().then((data) => { 1178 console.info('Succeeded in showing optionalInputMethods.'); 1179}).catch((err) => { 1180 console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err)); 1181}) 1182``` 1183 1184### listInputMethod<sup>(deprecated)</sup> 1185 1186listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void 1187 1188Obtains a list of installed input methods. This API uses an asynchronous callback to return the result. 1189 1190> **NOTE** 1191> 1192> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethods](#getinputmethods9). 1193 1194**System capability**: SystemCapability.MiscServices.InputMethodFramework 1195 1196**Parameters** 1197 1198| Name | Type | Mandatory| Description | 1199| -------- | -------------------------------------------------- | ---- | ---------------------- | 1200| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | Yes | Callback used to return the list of installed input methods.| 1201 1202**Example** 1203 1204```js 1205inputMethodSetting.listInputMethod((err,data) => { 1206 if (err !== undefined) { 1207 console.error('Failed to listInputMethod: ' + JSON.stringify(err)); 1208 return; 1209 } 1210 console.log('Succeeded in listing inputMethod.'); 1211 }); 1212``` 1213 1214### listInputMethod<sup>(deprecated)</sup> 1215 1216listInputMethod(): Promise<Array<InputMethodProperty>> 1217 1218Obtains a list of installed input methods. This API uses a promise to return the result. 1219 1220> **NOTE** 1221> 1222> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethods](#getinputmethods9-1). 1223 1224**System capability**: SystemCapability.MiscServices.InputMethodFramework 1225 1226**Return value** 1227 1228| Type | Description | 1229| ----------------------------------------------------------- | ---------------------- | 1230| Promise<Array<[InputMethodProperty](#inputmethodproperty8)>> | Promise used to return the list of installed input methods.| 1231 1232**Example** 1233 1234```js 1235inputMethodSetting.listInputMethod().then((data) => { 1236 console.info('Succeeded in listing inputMethod.'); 1237}).catch((err) => { 1238 console.error('Failed to listInputMethod: ' + JSON.stringify(err)); 1239}) 1240``` 1241 1242### displayOptionalInputMethod<sup>(deprecated)</sup> 1243 1244displayOptionalInputMethod(callback: AsyncCallback<void>): void 1245 1246Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. 1247 1248> **NOTE** 1249> 1250> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [showOptionalInputMethods()](#showoptionalinputmethods9). 1251 1252**System capability**: SystemCapability.MiscServices.InputMethodFramework 1253 1254**Parameters** 1255 1256| Name| Type| Mandatory| Description| 1257| -------- | -------- | -------- | -------- | 1258| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 1259 1260**Example** 1261 1262```js 1263inputMethodSetting.displayOptionalInputMethod((err) => { 1264 if (err !== undefined) { 1265 console.error('Failed to displayOptionalInputMethod: ' + JSON.stringify(err)); 1266 return; 1267 } 1268 console.info('Succeeded in displaying optionalInputMethod.'); 1269}); 1270``` 1271 1272### displayOptionalInputMethod<sup>(deprecated)</sup> 1273 1274displayOptionalInputMethod(): Promise<void> 1275 1276Displays a dialog box for selecting an input method. This API uses a promise to return the result. 1277 1278> **NOTE** 1279> 1280> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [showOptionalInputMethods()](#showoptionalinputmethods9-1). 1281 1282**System capability**: SystemCapability.MiscServices.InputMethodFramework 1283 1284**Return value** 1285 1286| Type| Description| 1287| -------- | -------- | 1288| Promise<void> | Promise that returns no value.| 1289 1290**Example** 1291 1292```js 1293inputMethodSetting.displayOptionalInputMethod().then(() => { 1294 console.info('Succeeded in displaying optionalInputMethod.'); 1295}).catch((err) => { 1296 console.error('Failed to displayOptionalInputMethod: ' + JSON.stringify(err)); 1297}) 1298``` 1299