1# Input Method Engine 2 3> **NOTE**<br> 4> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 5 6## Modules to Import 7 8```js 9import inputMethodEngine from '@ohos.inputmethodengine'; 10``` 11 12## inputMethodEngine 13 14Defines constant values. 15 16**System capability**: SystemCapability.Miscservices.InputMethodFramework 17 18| Name| Type| Readable| Writable| Description| 19| -------------------- | -------- | ---- | ---- | ------------------- | 20| ENTER_KEY_TYPE_UNSPECIFIED | number | Yes | No | No function is specified for the Enter key.| 21| ENTER_KEY_TYPE_GO | number | Yes | No | The Enter key takes the user to the target.| 22| ENTER_KEY_TYPE_SEARCH | number | Yes | No | The Enter key takes the user to the results of their searching.| 23| ENTER_KEY_TYPE_SEND | number | Yes | No | The Enter key sends the text to its target.| 24| ENTER_KEY_TYPE_NEXT | number | Yes | No | The Enter key takes the user to the next field.| 25| ENTER_KEY_TYPE_DONE | number | Yes | No | The Enter key takes the user to the next line.| 26| ENTER_KEY_TYPE_PREVIOUS | number | Yes | No | The Enter key takes the user to the previous field.| 27| PATTERN_NULL | number | Yes | No | Any type of edit box.| 28| PATTERN_TEXT | number | Yes | No | Text edit box.| 29| PATTERN_NUMBER | number | Yes | No | Number edit box.| 30| PATTERN_PHONE | number | Yes | No | Phone number edit box.| 31| PATTERN_DATETIME | number | Yes | No | Date edit box.| 32| PATTERN_EMAIL | number | Yes | No | Email edit box.| 33| PATTERN_URI | number | Yes | No | URI edit box.| 34| PATTERN_PASSWORD | number | Yes | No | Password edit box.| 35| OPTION_ASCII | number | Yes | No | ASCII values are allowed.| 36| OPTION_NONE | number | Yes | No | No input attribute is specified.| 37| OPTION_AUTO_CAP_CHARACTERS | number | Yes | No | Characters are allowed.| 38| OPTION_AUTO_CAP_SENTENCES | number | Yes | No | Sentences are allowed.| 39| OPTION_AUTO_WORDS | number | Yes | No | Words are allowed.| 40| OPTION_MULTI_LINE | number | Yes | No | Multiple lines are allowed.| 41| OPTION_NO_FULLSCREEN | number | Yes | No | Half-screen style.| 42| FLAG_SELECTING | number | Yes | No | The edit box is being selected.| 43| FLAG_SINGLE_LINE | number | Yes | No | The edit box allows only single-line input.| 44| DISPLAY_MODE_PART | number | Yes | No | The edit box is displayed in half-screen mode.| 45| DISPLAY_MODE_FULL | number | Yes | No | The edit box is displayed in full screen.| 46 47## inputMethodEngine.getInputMethodEngine 48 49getInputMethodEngine(): InputMethodEngine 50 51Obtains an **InputMethodEngine** instance. 52 53**System capability**: SystemCapability.Miscservices.InputMethodFramework 54 55**Return value** 56 57| Type | Description | 58| --------------------------------------- | ------------ | 59| [InputMethodEngine](#InputMethodEngine) | **InputMethodEngine** instance obtained.| 60 61**Example** 62 63```js 64let InputMethodEngine = inputMethodEngine.getInputMethodEngine(); 65``` 66 67## inputMethodEngine.createKeyboardDelegate 68 69createKeyboardDelegate(): KeyboardDelegate 70 71Obtains a **KeyboardDelegate** instance. 72 73**System capability**: SystemCapability.Miscservices.InputMethodFramework 74 75**Return value** 76 77| Type | Description | 78| ------------------------------------- | ---------------- | 79| [KeyboardDelegate](#KeyboardDelegate) | **KeyboardDelegate** instance obtained.| 80 81**Example** 82 83```js 84let KeyboardDelegate = inputMethodEngine.createKeyboardDelegate(); 85``` 86 87## InputMethodEngine 88 89In the following API examples, you must first use [getInputMethodEngine](#getInputMethodEngine) to obtain an **InputMethodEngine** instance, and then call the APIs using the obtained instance. 90 91### on('inputStart') 92 93on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void 94 95Listens for the input method binding event. This API uses a callback to return the result. 96 97**System capability**: SystemCapability.Miscservices.InputMethodFramework 98 99**Parameters** 100 101| Name | Type | Mandatory| Description | 102| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 103| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.| 104| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | Yes| Callback used to return the result.| 105 106**Example** 107 108```js 109InputMethodEngine.on('inputStart', (kbController, textInputClient) => { 110 KeyboardController = kbController; 111 TextInputClient = textInputClient; 112}); 113``` 114 115### off('inputStart') 116 117off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void 118 119Cancels listening for the input method binding event. 120 121**System capability**: SystemCapability.Miscservices.InputMethodFramework 122 123**Parameters** 124 125| Name | Type | Mandatory| Description | 126| -------- | -------------------- | ---- | ------------------------ | 127| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.| 128| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | No| Callback used to return the result.| 129 130**Example** 131 132```js 133InputMethodEngine.off('inputStart'); 134``` 135 136### on('keyboardShow'|'keyboardHide') 137 138on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void 139 140Listens for an input method event. 141 142**System capability**: SystemCapability.Miscservices.InputMethodFramework 143 144**Parameters** 145 146| Name | Type | Mandatory| Description | 147| -------- | ------ | ---- | ------------------------------------------------------------ | 148| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** means to listen for displaying of the input method.<br>- The value **'keyboardHide'** means to listen for hiding of the input method.| 149| callback | void | No | Callback used to return the result. | 150 151**Example** 152 153```js 154InputMethodEngine.on('keyboardShow', (err) => { 155 console.info('keyboardShow'); 156}); 157``` 158 159### off('keyboardShow'|'keyboardHide') 160 161off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void 162 163Cancels listening for an input method event. 164 165**System capability**: SystemCapability.Miscservices.InputMethodFramework 166 167**Parameters** 168 169| Name | Type | Mandatory| Description | 170| -------- | ------ | ---- | ------------------------------------------------------------ | 171| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** means to listen for displaying of the input method.<br>- The value **'keyboardHide'** means to listen for hiding of the input method.| 172| callback | void | No | Callback used to return the result. | 173 174**Example** 175 176```js 177InputMethodEngine.off('keyboardShow'); 178``` 179 180## KeyboardDelegate 181 182In the following API examples, you must first use [createKeyboardDelegate](#createKeyboardDelegate) to obtain a **KeyboardDelegate** instance, and then call the APIs using the obtained instance. 183 184### on('keyDown'|'keyUp') 185 186on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void 187 188Listens for a hard keyboard even. This API uses a callback to return the key information. 189 190**System capability**: SystemCapability.Miscservices.InputMethodFramework 191 192**Parameters** 193 194| Name | Type | Mandatory| Description | 195| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 196| type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.| 197| callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.| 198 199**Example** 200 201```js 202KeyboardDelegate.on('keyDown', (event) => { 203 console.info('keyDown'); 204}); 205``` 206 207### off('keyDown'|'keyUp') 208 209off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void 210 211Cancels listening for a hard keyboard even. 212 213**System capability**: SystemCapability.Miscservices.InputMethodFramework 214 215**Parameters** 216 217| Name | Type | Mandatory| Description | 218| -------- | --------------------- | ---- | ------------------------------------------------------------ | 219| type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.| 220| callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. | 221 222**Example** 223 224```js 225KeyboardDelegate.off('keyDown'); 226``` 227 228### on('cursorContextChange') 229 230on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void 231 232Listens for cursor context changes. This API uses a callback to return the cursor information. 233 234**System capability**: SystemCapability.Miscservices.InputMethodFramework 235 236**Parameters** 237 238| Name | Type | Mandatory| Description | 239| -------- | ------ | ---- | ------------------------------------------------------------ | 240| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| 241| callback | number | Yes | Callback used to return the cursor information. | 242 243**Example** 244 245```js 246KeyboardDelegate.on('cursorContextChange', (x, y, height) => { 247 console.info('cursorContextChange'); 248}); 249``` 250 251### off('cursorContextChange') 252 253off(type: 'cursorContextChange', callback?: (x: number, y:number, height:number) => void): void 254 255Cancels listening for cursor context changes. 256 257**System capability**: SystemCapability.Miscservices.InputMethodFramework 258 259**Parameters** 260 261| Name | Type | Mandatory| Description | 262| -------- | -------------------- | ---- | ------------------------ | 263| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| 264| callback | number | No| Callback used to return the cursor information.| 265 266**Example** 267 268```js 269KeyboardDelegate.off('cursorContextChange'); 270``` 271 272### on('selectionChange') 273 274on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void 275 276Listens for text selection changes. This API uses a callback to return the text selection information. 277 278**System capability**: SystemCapability.Miscservices.InputMethodFramework 279 280**Parameters** 281 282| Name | Type | Mandatory| Description | 283| -------- | ------ | ---- | ------------------------------------------------------------ | 284| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.| 285| callback | number | Yes | Callback used to return the text selection information. | 286 287**Example** 288 289```js 290KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { 291 console.info('selectionChange'); 292}); 293``` 294 295### off('selectionChange') 296 297off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void 298 299Cancels listening for text selection changes. 300 301**System capability**: SystemCapability.Miscservices.InputMethodFramework 302 303**Parameters** 304 305| Name | Type | Mandatory| Description | 306| -------- | -------------------- | ---- | ------------------------ | 307| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.| 308| callback | number | No| Callback used to return the text selection information.| 309 310**Example** 311 312```js 313KeyboardDelegate.off('selectionChange'); 314``` 315 316 317### on('textChange') 318 319on(type: 'textChange', callback: (text: string) => void): void 320 321Listens for text changes. This API uses a callback to return the current text content. 322 323**System capability**: SystemCapability.Miscservices.InputMethodFramework 324 325**Parameters** 326 327| Name | Type | Mandatory| Description | 328| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 329| type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.| 330| callback | string | Yes| Callback used to return the current text content.| 331 332**Example** 333 334```js 335KeyboardDelegate.on('textChange', (text) => { 336 console.info('textChange'); 337}); 338``` 339 340### off('textChange') 341 342off(type: 'textChange', callback?: (text: string) => void): void 343 344Cancels listening for text changes. 345 346**System capability**: SystemCapability.MiscServices.InputMethodFramework 347 348**Parameters** 349 350| Name | Type | Mandatory| Description | 351| -------- | -------------------- | ---- | ------------------------ | 352| type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.| 353| callback | string | No| Callback used to return the current text content.| 354 355**Example** 356 357```js 358KeyboardDelegate.off('textChange'); 359``` 360 361## KeyboardController 362 363In the following API examples, you must first use [inputStart](#inputStart) to obtain a **KeyboardController** instance, and then call the APIs using the obtained instance. 364 365### hideKeyboard 366 367hideKeyboard(callback: AsyncCallback<void>): void 368 369Hides the keyboard. This API uses an asynchronous callback to return the result. 370 371**System capability**: SystemCapability.Miscservices.InputMethodFramework 372 373**Parameters** 374 375| Name | Type | Mandatory| Description | 376| -------- | ---------------------- | ---- | -------- | 377| callback | AsyncCallback<void> | No | Callback used to return the result.| 378 379**Example** 380 381```js 382KeyboardController.hideKeyboard(()=>{ 383}); 384``` 385 386### hideKeyboard 387 388hideKeyboard(): Promise<void> 389 390Hides the keyboard. This API uses a promise to return the result. 391 392**System capability**: SystemCapability.MiscServices.InputMethodFramework 393 394**Return value** 395 396| Type | Description | 397| ---------------- | -------- | 398| Promise<void> | Promise used to return the result.| 399 400**Example** 401 402```js 403KeyboardController.hideKeyboard(); 404``` 405 406## TextInputClient 407 408In the following API examples, you must first use [inputStart](#inputStart) to obtain a **TextInputClient** instance, and then call the APIs using the obtained instance. 409 410### getForward 411 412getForward(length:number, callback: AsyncCallback<string>): void 413 414Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. 415 416**System capability**: SystemCapability.Miscservices.InputMethodFramework 417 418**Parameters** 419 420| Name| Type| Mandatory| Description| 421| -------- | -------- | -------- | -------- | 422| length | number | Yes| Text length.| 423| callback | AsyncCallback<string> | Yes| Text returned.| 424 425**Example** 426 427```js 428TextInputClient.getForward(5,(text) =>{ 429 console.info("text = " + text); 430}); 431``` 432 433### getForward 434 435getForward(length:number): Promise<string> 436 437Obtains the specific-length text before the cursor. This API uses a promise to return the result. 438 439**System capability**: SystemCapability.Miscservices.InputMethodFramework 440 441**Parameters** 442 443| Name| Type| Mandatory| Description| 444| -------- | -------- | -------- | -------- | 445| length | number | Yes| Text length.| 446 447**Return value** 448 449| Type | Description | 450| ------------------------------- | ------------------------------------------------------------ | 451| Promise<string> | Text returned. | 452 453**Example** 454 455```js 456let text = TextInputClient.getForward(5); 457console.info("text = " + text); 458``` 459 460### getBackward 461 462getBackward(length:number, callback: AsyncCallback<string>): void 463 464Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. 465 466**System capability**: SystemCapability.Miscservices.InputMethodFramework 467 468**Parameters** 469 470| Name| Type| Mandatory| Description| 471| -------- | -------- | -------- | -------- | 472| length | number | Yes| Text length.| 473| callback | AsyncCallback<string> | Yes| Text returned.| 474 475**Example** 476 477```js 478TextInputClient.getBackward(5,(text)=>{ 479 console.info("text = " + text); 480}); 481``` 482 483### getBackward 484 485getBackward(length:number): Promise<string> 486 487Obtains the specific-length text after the cursor. This API uses a promise to return the result. 488 489**System capability**: SystemCapability.Miscservices.InputMethodFramework 490 491**Parameters** 492 493| Name| Type| Mandatory| Description| 494| -------- | -------- | -------- | -------- | 495| length | number | Yes| Text length.| 496 497**Return value** 498 499| Type | Description | 500| ------------------------------- | ------------------------------------------------------------ | 501| Promise<string> | Text returned. | 502 503**Example** 504 505```js 506let text = TextInputClient.getBackward(5); 507console.info("text = " + text); 508``` 509 510### deleteForward 511 512deleteForward(length:number, callback: AsyncCallback<boolean>): void 513 514Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. 515 516**System capability**: SystemCapability.Miscservices.InputMethodFramework 517 518**Parameters** 519 520| Name| Type| Mandatory| Description| 521| -------- | -------- | -------- | -------- | 522| length | number | Yes| Text length.| 523| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| 524 525**Example** 526 527```js 528TextInputClient.deleteForward(5,(isSuccess)=>{ 529 console.info("isSuccess = " + isSuccess); 530}); 531``` 532 533### deleteForward 534 535deleteForward(length:number): Promise<boolean> 536 537Deletes the fixed-length text before the cursor. This API uses a promise to return the result. 538 539**System capability**: SystemCapability.Miscservices.InputMethodFramework 540 541**Parameters** 542 543| Name| Type| Mandatory| Description| 544| -------- | -------- | -------- | -------- | 545| length | number | Yes| Text length.| 546 547**Return value** 548 549| Type | Description | 550| ------------------------------- | ------------------------------------------------------------ | 551| Promise<boolean> | Returns whether the operation is successful. | 552 553**Example** 554 555```js 556let isSuccess = TextInputClient.deleteForward(5); 557console.info("isSuccess = " + isSuccess); 558``` 559 560### deleteBackward 561 562deleteBackward(length:number, callback: AsyncCallback<boolean>): void 563 564Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. 565 566**System capability**: SystemCapability.Miscservices.InputMethodFramework 567 568**Parameters** 569 570| Name| Type| Mandatory| Description| 571| -------- | -------- | -------- | -------- | 572| length | number | Yes| Text length.| 573| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| 574 575**Example** 576 577```js 578TextInputClient.deleteBackward(5, (isSuccess)=>{ 579 console.info("isSuccess = " + isSuccess); 580}); 581``` 582 583### deleteBackward 584 585deleteBackward(length:number): Promise<boolean> 586 587Deletes the fixed-length text after the cursor. This API uses a promise to return the result. 588 589**System capability**: SystemCapability.MiscServices.InputMethodFramework 590 591**Parameters** 592 593| Name| Type| Mandatory| Description| 594| -------- | -------- | -------- | -------- | 595| length | number | Yes| Text length.| 596 597**Return value** 598 599| Type | Description | 600| ------------------------------- | ------------------------------------------------------------ | 601| Promise<boolean> | Returns whether the operation is successful. | 602 603**Example** 604 605```js 606let isSuccess = TextInputClient.deleteBackward(5); 607console.info("isSuccess = " + isSuccess); 608``` 609 610### sendKeyFunction 611 612sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void 613 614Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. 615 616**System capability**: SystemCapability.Miscservices.InputMethodFramework 617 618**Parameters** 619 620| Name| Type| Mandatory| Description| 621| -------- | -------- | -------- | -------- | 622| action | number | Yes| Edit box attribute.| 623| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| 624 625**Example** 626 627```js 628TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{ 629 console.info("isSuccess = " + isSuccess); 630}); 631``` 632 633### sendKeyFunction 634 635sendKeyFunction(action:number): Promise<boolean> 636 637Sets the Enter key to send the text to its target. This API uses a promise to return the result. 638 639**System capability**: SystemCapability.Miscservices.InputMethodFramework 640 641**Parameters** 642 643| Name| Type| Mandatory| Description| 644| -------- | -------- | -------- | -------- | 645| action | number | Yes| Edit box attribute.| 646 647**Return value** 648 649| Type | Description | 650| ------------------------------- | ------------------------------------------------------------ | 651| Promise<boolean> | Returns whether the operation is successful. | 652 653**Example** 654 655```js 656let isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT); 657console.info("isSuccess = " + isSuccess); 658``` 659 660### insertText 661 662insertText(text:string, callback: AsyncCallback<boolean>): void 663 664Inserts text. This API uses an asynchronous callback to return the result. 665 666**System capability**: SystemCapability.MiscServices.InputMethodFramework 667 668**Parameters** 669 670| Name| Type| Mandatory| Description| 671| -------- | -------- | -------- | -------- | 672| text | string | Yes| Text to insert.| 673| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| 674 675**Example** 676 677```js 678TextInputClient.insertText("test", (isSuccess)=>{ 679 console.info("isSuccess = " + isSuccess); 680}); 681``` 682 683### insertText 684 685insertText(text:string): Promise<boolean> 686 687Inserts text. This API uses a promise to return the result. 688 689**System capability**: SystemCapability.Miscservices.InputMethodFramework 690 691**Parameters** 692 693| Name| Type| Mandatory| Description| 694| -------- | -------- | -------- | -------- | 695| text | string | Yes| Text to insert.| 696 697**Return value** 698 699| Type | Description | 700| ------------------------------- | ------------------------------------------------------------ | 701| Promise<boolean> | Returns whether the operation is successful. | 702 703**Example** 704 705```js 706let isSuccess = TextInputClient.insertText("test"); 707console.info("isSuccess = " + isSuccess); 708``` 709 710### getEditorAttribute 711 712getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void 713 714Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. 715 716**System capability**: SystemCapability.Miscservices.InputMethodFramework 717 718**Parameters** 719 720| Name | Type | Mandatory | Description | 721| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 722| callback | AsyncCallback<[EditorAttribute](#EditorAttribute)> | Yes| Attribute of the edit box. | 723 724**Example** 725 726```js 727TextInputClient.getEditorAttribute((EditorAttribute)=>{ 728}); 729``` 730 731### getEditorAttribute 732 733getEditorAttribute(): Promise<EditorAttribute> 734 735Obtains the attribute of the edit box. This API uses a promise to return the result. 736 737**System capability**: SystemCapability.Miscservices.InputMethodFramework 738 739**Return value** 740 741| Type | Description | 742| ------------------------------- | ------------------------------------------------------------ | 743| Promise<[EditorAttribute](#EditorAttribute)> | Returns the attribute of the edit box. | 744 745**Example** 746 747```js 748let EditorAttribute = TextInputClient.getEditorAttribute(); 749``` 750 751## EditorAttribute 752 753Describes the attribute of the edit box. 754 755**System capability**: SystemCapability.Miscservices.InputMethodFramework 756 757| Name | Type| Readable| Writable| Description | 758| ------------ | -------- | ---- | ---- | ------------------ | 759| enterKeyType | number | Yes | No | Function attribute of the edit box.| 760| inputPattern | number | Yes | No | Text attribute of the edit box.| 761 762## KeyEvent 763 764Describes the attribute of a key. 765 766**System capability**: SystemCapability.Miscservices.InputMethodFramework 767 768| Name | Type| Readable| Writable| Description | 769| --------- | -------- | ---- | ---- | ------------ | 770| keyCode | number | Yes | No | Key value.| 771| keyAction | number | Yes | No | Key status.| 772