1# @ohos.inputMethodEngine (Input Method Service) 2 3The **inputMethodEngine** module streamlines the interactions between input methods and applications. By calling APIs of this module, applications can be bound to input method services to accept text input, request the keyboard to display or hide, listen for the input method status, and much more. 4 5> **NOTE** 6> 7>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. 8 9## Modules to Import 10 11``` 12import inputMethodEngine from '@ohos.inputMethodEngine'; 13``` 14 15## Constants 16 17Provides the constant values of function keys, edit boxes, and the cursor. 18 19**System capability**: SystemCapability.MiscServices.InputMethodFramework 20 21| Name| Type| Value| Description| 22| -------- | -------- | -------- | -------- | 23| ENTER_KEY_TYPE_UNSPECIFIED | number | 0 | No function is specified for the Enter key.| 24| ENTER_KEY_TYPE_GO | number | 2 | The Enter key takes the user to the target.| 25| ENTER_KEY_TYPE_SEARCH | number | 3 | The Enter key takes the user to the results of their searching.| 26| ENTER_KEY_TYPE_SEND | number | 4 | The Enter key sends the text to its target.| 27| ENTER_KEY_TYPE_NEXT | number | 5 | The Enter key takes the user to the next field.| 28| ENTER_KEY_TYPE_DONE | number | 6 | The Enter key takes the user to the next line.| 29| ENTER_KEY_TYPE_PREVIOUS | number | 7 | The Enter key takes the user to the previous field.| 30| PATTERN_NULL | number | -1 | Any type of edit box.| 31| PATTERN_TEXT | number | 0 | Text edit box.| 32| PATTERN_NUMBER | number | 2 | Number edit box.| 33| PATTERN_PHONE | number | 3 | Phone number edit box.| 34| PATTERN_DATETIME | number | 4 | Date edit box.| 35| PATTERN_EMAIL | number | 5 | Email edit box.| 36| PATTERN_URI | number | 6 | URI edit box.| 37| PATTERN_PASSWORD | number | 7 | Password edit box.| 38| OPTION_ASCII | number | 20 | ASCII values are allowed.| 39| OPTION_NONE | number | 0 | No input attribute is specified.| 40| OPTION_AUTO_CAP_CHARACTERS | number | 2 | Characters are allowed.| 41| OPTION_AUTO_CAP_SENTENCES | number | 8 | Sentences are allowed.| 42| OPTION_AUTO_WORDS | number | 4 | Words are allowed.| 43| OPTION_MULTI_LINE | number | 1 | Multiple lines are allowed.| 44| OPTION_NO_FULLSCREEN | number | 10 | Half-screen style.| 45| FLAG_SELECTING | number | 2 | The edit box is being selected.| 46| FLAG_SINGLE_LINE | number | 1 | The edit box allows only single-line input.| 47| DISPLAY_MODE_PART | number | 0 | The edit box is displayed in half-screen mode.| 48| DISPLAY_MODE_FULL | number | 1 | The edit box is displayed in full screen.| 49| CURSOR_UP<sup>9+</sup> | number | 1 | The caret moves upward.| 50| CURSOR_DOWN<sup>9+</sup> | number | 2 | The caret moves downward.| 51| CURSOR_LEFT<sup>9+</sup> | number | 3 | The caret moves leftward.| 52| CURSOR_RIGHT<sup>9+</sup> | number | 4 | The caret moves rightward.| 53| WINDOW_TYPE_INPUT_METHOD_FLOAT<sup>9+</sup> | number | 2105 | The input method is displayed in a floating window.| 54 55## inputMethodEngine.getInputMethodAbility<sup>9+</sup> 56 57getInputMethodAbility(): InputMethodAbility 58 59Obtains an **InputMethodEngine** instance. 60 61**System capability**: SystemCapability.MiscServices.InputMethodFramework 62 63**Return value** 64 65| Type | Description | 66| --------------------------------------- | ------------ | 67| [InputMethodAbility](#inputmethodability) | **InputMethodEngine** instance obtained.| 68 69**Example** 70 71```js 72let InputMethodAbility = inputMethodEngine.getInputMethodAbility(); 73``` 74 75## inputMethodEngine.getKeyboardDelegate<sup>9+</sup> 76 77getKeyboardDelegate(): KeyboardDelegate 78 79Obtains a **KeyboardDelegate** instance. 80 81**System capability**: SystemCapability.MiscServices.InputMethodFramework 82 83**Return value** 84 85| Type | Description | 86| ------------------------------------- | ---------------- | 87| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance obtained.| 88 89**Example** 90 91```js 92let KeyboardDelegate = inputMethodEngine.getKeyboardDelegate(); 93``` 94 95## inputMethodEngine.getInputMethodEngine<sup>(deprecated)</sup> 96 97getInputMethodEngine(): InputMethodEngine 98 99Obtains an **InputMethodEngine** instance. 100 101> **NOTE** 102> 103> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getInputMethodAbility()](#inputmethodenginegetinputmethodability9). 104 105**System capability**: SystemCapability.MiscServices.InputMethodFramework 106 107**Return value** 108 109| Type | Description | 110| --------------------------------------- | ------------ | 111| [InputMethodEngine](#inputmethodengine-1) | **InputMethodEngine** instance obtained.| 112 113**Example** 114 115```js 116let InputMethodEngine = inputMethodEngine.getInputMethodEngine(); 117``` 118 119## inputMethodEngine.createKeyboardDelegate<sup>(deprecated)</sup> 120 121createKeyboardDelegate(): KeyboardDelegate 122 123Obtains a **KeyboardDelegate** instance. 124 125> **NOTE** 126> 127>This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getKeyboardDelegate()](#inputmethodenginegetkeyboarddelegate9). 128 129**System capability**: SystemCapability.MiscServices.InputMethodFramework 130 131**Return value** 132 133| Type | Description | 134| ------------------------------------- | ---------------- | 135| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance obtained.| 136 137**Example** 138 139```js 140let keyboardDelegate = inputMethodEngine.createKeyboardDelegate(); 141``` 142 143## InputMethodEngine 144 145In the following API examples, you must first use **[getInputMethodEngine](#inputmethodenginegetinputmethodenginedeprecated)** to obtain an **InputMethodEngine** instance, and then call the APIs using the obtained instance. 146 147### on('inputStart') 148 149on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void 150 151Enables listening for the input method binding event. This API uses an asynchronous callback to return the result. 152 153**System capability**: SystemCapability.MiscServices.InputMethodFramework 154 155**Parameters** 156 157| Name | Type | Mandatory| Description | 158| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 159| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.| 160| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | Yes| Callback used to return the **KeyboardController** and **TextInputClient** instances.| 161 162**Example** 163 164```js 165inputMethodEngine.getInputMethodEngine().on('inputStart', (kbController, textClient) => { 166 let keyboardController = kbController; 167 let textInputClient = textClient; 168}); 169``` 170 171### off('inputStart') 172 173off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void 174 175Cancels listening for the input method binding event. 176 177**System capability**: SystemCapability.MiscServices.InputMethodFramework 178 179**Parameters** 180 181| Name | Type | Mandatory| Description | 182| -------- | -------------------- | ---- | ------------------------ | 183| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.| 184| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | No| Callback used to return the **KeyboardController** and **TextInputClient** instances.| 185 186**Example** 187 188```js 189inputMethodEngine.getInputMethodEngine().off('inputStart', (kbController, textInputClient) => { 190 console.log('delete inputStart notification.'); 191}); 192``` 193 194### on('keyboardShow'|'keyboardHide') 195 196on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void 197 198Enables listening for a keyboard event. This API uses an asynchronous callback to return the result. 199 200**System capability**: SystemCapability.MiscServices.InputMethodFramework 201 202**Parameters** 203 204| Name | Type | Mandatory| Description | 205| -------- | ------ | ---- | ------------------------------------------------------------ | 206| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.| 207| callback | () => void | Yes | Callback used to return the result. | 208 209**Example** 210 211```js 212inputMethodEngine.getInputMethodEngine().on('keyboardShow', () => { 213 console.log('inputMethodEngine keyboardShow.'); 214}); 215inputMethodEngine.getInputMethodEngine().on('keyboardHide', () => { 216 console.log('inputMethodEngine keyboardHide.'); 217}); 218``` 219 220### off('keyboardShow'|'keyboardHide') 221 222off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void 223 224Disables listening for a keyboard event. This API uses an asynchronous callback to return the result. 225 226**System capability**: SystemCapability.MiscServices.InputMethodFramework 227 228**Parameters** 229 230| Name | Type | Mandatory| Description | 231| -------- | ------ | ---- | ------------------------------------------------------------ | 232| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.| 233| callback | () => void | No | Callback used to return the result.| 234 235**Example** 236 237```js 238inputMethodEngine.getInputMethodEngine().off('keyboardShow'); 239inputMethodEngine.getInputMethodEngine().off('keyboardHide'); 240``` 241 242## InputMethodAbility 243 244In the following API examples, you must first use **[getInputMethodAbility](#inputmethodenginegetinputmethodability9)** to obtain an **InputMethodAbility** instance, and then call the APIs using the obtained instance. 245 246### on('inputStart')<sup>9+</sup> 247 248on(type: 'inputStart', callback: (kbController: KeyboardController, inputClient: InputClient) => void): void 249 250Enables listening for the input method binding event. This API uses an asynchronous callback to return the result. 251 252**System capability**: SystemCapability.MiscServices.InputMethodFramework 253 254**Parameters** 255 256| Name | Type | Mandatory| Description | 257| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 258| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.| 259| callback | (kbController: [KeyboardController](#keyboardcontroller), inputClient: [InputClient](#inputclient9)) => void | Yes| Callback used to return the result.| 260 261**Example** 262 263```js 264inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, client) => { 265 let keyboardController = kbController; 266 let inputClient = client; 267}); 268``` 269 270### off('inputStart')<sup>9+</sup> 271 272off(type: 'inputStart', callback?: (kbController: KeyboardController, inputClient: InputClient) => void): void 273 274Cancels listening for the input method binding event. This API uses an asynchronous callback to return the result. 275 276**System capability**: SystemCapability.MiscServices.InputMethodFramework 277 278**Parameters** 279 280| Name | Type | Mandatory| Description | 281| -------- | -------------------- | ---- | ------------------------ | 282| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.| 283| callback | (kbController: [KeyboardController](#keyboardcontroller), inputClient: [InputClient](#inputclient9)) => void | No| Callback used to return the result.| 284 285**Example** 286 287```js 288inputMethodEngine.getInputMethodAbility().off('inputStart'); 289``` 290 291### on('inputStop')<sup>9+</sup> 292 293on(type: 'inputStop', callback: () => void): void 294 295Enables listening for the input method unbinding event. This API uses an asynchronous callback to return the result. 296 297**System capability**: SystemCapability.MiscServices.InputMethodFramework 298 299**Parameters** 300 301| Name | Type | Mandatory| Description | 302| -------- | ------ | ---- | ------------------------------------------------------------ | 303| type | string | Yes | Listening type.<br>The value **'inputStop'** indicates the input method unbinding event.| 304| callback | () => void | Yes | Callback used to return the result. | 305 306**Example** 307 308```js 309inputMethodEngine.getInputMethodAbility().on('inputStop', () => { 310 console.log('inputMethodAbility inputStop'); 311}); 312``` 313 314### off('inputStop')<sup>9+</sup> 315 316off(type: 'inputStop', callback: () => void): void 317 318Cancels listening for the input method stop event. This API uses an asynchronous callback to return the result. 319 320**System capability**: SystemCapability.MiscServices.InputMethodFramework 321 322**Parameters** 323 324| Name | Type | Mandatory| Description | 325| -------- | ------ | ---- | ------------------------------------------------------------ | 326| type | string | Yes | Listening type.<br>The value **'inputStop'** indicates the input method unbinding event.| 327| callback | () => void | Yes | Callback used to return the result. | 328 329**Example** 330 331```js 332inputMethodEngine.getInputMethodAbility().off('inputStop', () => { 333 console.log('inputMethodAbility delete inputStop notification.'); 334}); 335``` 336 337### on('setCallingWindow')<sup>9+</sup> 338 339on(type: 'setCallingWindow', callback: (wid: number) => void): void 340 341Enables listening for the window invocation setting event. This API uses an asynchronous callback to return the result. 342 343**System capability**: SystemCapability.MiscServices.InputMethodFramework 344 345**Parameters** 346 347| Name | Type | Mandatory| Description | 348| -------- | ------ | ---- | ------------------------------------------------------------ | 349| type | string | Yes | Listening type.<br>The value **'setCallingWindow'** indicates the window invocation setting event.| 350| callback | (wid: number) => void | Yes | Callback used to return the window ID of the caller. | 351 352**Example** 353 354```js 355inputMethodEngine.getInputMethodAbility().on('setCallingWindow', (wid) => { 356 console.log('inputMethodAbility setCallingWindow'); 357}); 358``` 359 360### off('setCallingWindow')<sup>9+</sup> 361 362off(type: 'setCallingWindow', callback: (wid:number) => void): void 363 364Disables listening for the window invocation setting event. This API uses an asynchronous callback to return the result. 365 366**System capability**: SystemCapability.MiscServices.InputMethodFramework 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| -------- | ------ | ---- | ------------------------------------------------------------ | 372| type | string | Yes | Listening type.<br>The value **'setCallingWindow'** indicates the window invocation setting event.| 373| callback | (wid:number) => void | Yes | Callback used to return the window ID of the caller. | 374 375**Example** 376 377```js 378inputMethodEngine.getInputMethodAbility().off('setCallingWindow', () => { 379 console.log('inputMethodAbility delete setCallingWindow notification.'); 380}); 381``` 382 383### on('keyboardShow'|'keyboardHide')<sup>9+</sup> 384 385on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void 386 387Enables listening for a keyboard event. This API uses an asynchronous callback to return the result. 388 389**System capability**: SystemCapability.MiscServices.InputMethodFramework 390 391**Parameters** 392 393| Name | Type | Mandatory| Description | 394| -------- | ------ | ---- | ------------------------------------------------------------ | 395| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.| 396| callback | () => void | Yes | Callback used to return the result. | 397 398**Example** 399 400```js 401inputMethodEngine.getInputMethodAbility().on('keyboardShow', () => { 402 console.log('InputMethodAbility keyboardShow.'); 403}); 404inputMethodEngine.getInputMethodAbility().on('keyboardHide', () => { 405 console.log('InputMethodAbility keyboardHide.'); 406}); 407``` 408 409### off('keyboardShow'|'keyboardHide')<sup>9+</sup> 410 411off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void 412 413Disables listening for a keyboard event. This API uses an asynchronous callback to return the result. 414 415**System capability**: SystemCapability.MiscServices.InputMethodFramework 416 417**Parameters** 418 419| Name | Type | Mandatory| Description | 420| -------- | ------ | ---- | ------------------------------------------------------------ | 421| type | string | Yes | Listening type.<br>- The value **'keyboardShow'** indicates the keyboard display event.<br>- The value **'keyboardHide'** indicates the keyboard hiding event.| 422| callback | () => void | No | Callback used to return the result. | 423 424**Example** 425 426```js 427inputMethodEngine.getInputMethodAbility().off('keyboardShow', () => { 428 console.log('InputMethodAbility delete keyboardShow notification.'); 429}); 430inputMethodEngine.getInputMethodAbility().off('keyboardHide', () => { 431 console.log('InputMethodAbility delete keyboardHide notification.'); 432}); 433``` 434 435### on('setSubtype')<sup>9+</sup> 436 437on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void 438 439Enables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result. 440 441**System capability**: SystemCapability.MiscServices.InputMethodFramework 442 443**Parameters** 444 445| Name | Type | Mandatory| Description | 446| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 447| type | string | Yes | Listening type.<br>The value **'setSubtype'** indicates the input method subtype setting event.| 448| callback | (inputMethodSubtype: [InputMethodSubtype](js-apis-inputmethod-subtype.md)) => void | Yes | Callback used to return the input method subtype. | 449 450**Example** 451 452```js 453inputMethodEngine.getInputMethodAbility().on('setSubtype', (inputMethodSubtype) => { 454 console.log('InputMethodAbility setSubtype.'); 455}); 456``` 457 458### off('setSubtype')<sup>9+</sup> 459 460off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void 461 462Disables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result. 463 464**System capability**: SystemCapability.MiscServices.InputMethodFramework 465 466**Parameters** 467 468| Name | Type | Mandatory| Description | 469| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 470| type | string | Yes | Listening type.<br>The value **'setSubtype'** indicates the input method subtype setting event.| 471| callback | (inputMethodSubtype: [InputMethodSubtype](js-apis-inputmethod-subtype.md)) => void | No | Callback used to return the input method subtype. | 472 473**Example** 474 475```js 476inputMethodEngine.getInputMethodAbility().off('setSubtype', () => { 477 console.log('InputMethodAbility delete setSubtype notification.'); 478}); 479``` 480 481## KeyboardDelegate 482 483In the following API examples, you must first use **[getKeyboardDelegate](#inputmethodenginegetkeyboarddelegate9)** to obtain a **KeyboardDelegate** instance, and then call the APIs using the obtained instance. 484 485### on('keyDown'|'keyUp') 486 487on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void 488 489Enables listening for a keyboard event. This API uses an asynchronous callback to return the result. 490 491**System capability**: SystemCapability.MiscServices.InputMethodFramework 492 493**Parameters** 494 495| Name | Type | Mandatory| Description | 496| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 497| type | string | Yes | Listening type.<br>The value **'keyDown'** indicates the keydown event.<br>The value **'keyUp'** indicates the keyup event.| 498| callback | (event: [KeyEvent](#keyevent)) => boolean | Yes| Callback used to return the key information.| 499 500**Example** 501 502```js 503inputMethodEngine.getKeyboardDelegate().on('keyUp', (keyEvent) => { 504 console.info('inputMethodEngine keyCode.(keyUp):' + JSON.stringify(keyEvent.keyCode)); 505 console.info('inputMethodEngine keyAction.(keyUp):' + JSON.stringify(keyEvent.keyAction)); 506 return true; 507}); 508inputMethodEngine.getKeyboardDelegate().on('keyDown', (keyEvent) => { 509 console.info('inputMethodEngine keyCode.(keyDown):' + JSON.stringify(keyEvent.keyCode)); 510 console.info('inputMethodEngine keyAction.(keyDown):' + JSON.stringify(keyEvent.keyAction)); 511 return true; 512}); 513``` 514 515### off('keyDown'|'keyUp') 516 517off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void 518 519Disables listening for a keyboard event. This API uses an asynchronous callback to return the result. 520 521**System capability**: SystemCapability.MiscServices.InputMethodFramework 522 523**Parameters** 524 525| Name | Type | Mandatory| Description | 526| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 527| type | string | Yes | Listening type.<br>The value **'keyDown'** indicates the keydown event.<br>The value **'keyUp'** indicates the keyup event.| 528| callback | (event: [KeyEvent](#keyevent)) => boolean | No | Callback used to return the key information. | 529 530**Example** 531 532```js 533inputMethodEngine.getKeyboardDelegate().off('keyUp', (keyEvent) => { 534 console.log('delete keyUp notification.'); 535 return true; 536}); 537inputMethodEngine.getKeyboardDelegate().off('keyDown', (keyEvent) => { 538 console.log('delete keyDown notification.'); 539 return true; 540}); 541``` 542 543### on('cursorContextChange') 544 545on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void 546 547Enables listening for the cursor change event. This API uses an asynchronous callback to return the result. 548 549**System capability**: SystemCapability.MiscServices.InputMethodFramework 550 551**Parameters** 552 553| Name | Type | Mandatory| Description | 554| -------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | 555| type | string | Yes | Listening type.<br>The value **'cursorContextChange'** indicates the cursor change event.| 556| callback | (x: number, y: number, height: number) => void | Yes | Callback used to return the cursor information.<br>- **x**: x coordinate of the top of the cursor.<br>- **y**: x coordinate of the bottom of the cursor.<br>- **height**: height of the cursor.| 557 558**Example** 559 560```js 561inputMethodEngine.getKeyboardDelegate().on('cursorContextChange', (x, y, height) => { 562 console.log('inputMethodEngine cursorContextChange x:' + x); 563 console.log('inputMethodEngine cursorContextChange y:' + y); 564 console.log('inputMethodEngine cursorContextChange height:' + height); 565}); 566``` 567 568### off('cursorContextChange') 569 570off(type: 'cursorContextChange', callback?: (x: number, y: number, height: number) => void): void 571 572Cancels listening for cursor context changes. This API uses an asynchronous callback to return the result. 573 574**System capability**: SystemCapability.MiscServices.InputMethodFramework 575 576 **Parameters** 577 578| Name | Type | Mandatory| Description | 579| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 580| type | string | Yes | Listening type.<br>The value **'cursorContextChange'** indicates the cursor change event.| 581| callback | (x: number, y:number, height:number) => void | No | Callback used to return the cursor information.<br>- **x**: x coordinate of the top of the cursor.<br>- **y**: x coordinate of the bottom of the cursor.<br>- **height**: height of the cursor.<br>| 582 583 584 **Example** 585 586```js 587inputMethodEngine.getKeyboardDelegate().off('cursorContextChange', (x, y, height) => { 588 console.log('delete cursorContextChange notification.'); 589}); 590``` 591### on('selectionChange') 592 593on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void 594 595Enables listening for the text selection change event. This API uses an asynchronous callback to return the result. 596 597**System capability**: SystemCapability.MiscServices.InputMethodFramework 598 599**Parameters** 600 601| Name | Type | Mandatory| Description | 602| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 603| type | string | Yes | Listening type.<br>The value **'selectionChange'** indicates the text selection change event.| 604| callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | Yes | Callback used to return the text selection information.<br>- **oldBegin**: start of the selected text before the change.<br>- **oldEnd**: end of the selected text before the change.<br>- **newBegin**: start of the selected text after the change.<br>- **newEnd**: end of the selected text after the change.| 605 606**Example** 607 608```js 609inputMethodEngine.getKeyboardDelegate().on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { 610 console.log('inputMethodEngine beforeEach selectionChange oldBegin:' + oldBegin); 611 console.log('inputMethodEngine beforeEach selectionChange oldEnd:' + oldEnd); 612 console.log('inputMethodEngine beforeEach selectionChange newBegin:' + newBegin); 613 console.log('inputMethodEngine beforeEach selectionChange newEnd:' + newEnd); 614}); 615``` 616 617### off('selectionChange') 618 619off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void 620 621Cancels listening for text selection changes. This API uses an asynchronous callback to return the result. 622 623**System capability**: SystemCapability.MiscServices.InputMethodFramework 624 625**Parameters** 626 627| Name | Type | Mandatory| Description | 628| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 629| type | string | Yes | Listening type.<br>The value **'selectionChange'** indicates the text selection change event.| 630| callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | No | Callback used to return the text selection information.<br>- **oldBegin**: start of the selected text before the change.<br>- **oldEnd**: end of the selected text before the change.<br>- **newBegin**: start of the selected text after the change.<br>- **newEnd**: end of the selected text after the change.<br>| 631 632**Example** 633 634```js 635inputMethodEngine.getKeyboardDelegate().off('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { 636 console.log('delete selectionChange notification.'); 637}); 638``` 639 640 641### on('textChange') 642 643on(type: 'textChange', callback: (text: string) => void): void 644 645Enables listening for the text change event. This API uses an asynchronous callback to return the result. 646 647**System capability**: SystemCapability.MiscServices.InputMethodFramework 648 649**Parameters** 650 651| Name | Type | Mandatory| Description | 652| -------- | ------ | ---- | ------------------------------------------------------------ | 653| type | string | Yes | Listening type.<br>The value **'textChange'** indicates the text change event.| 654| callback | (text: string) => void | Yes | Callback used to return the text content. | 655 656**Example** 657 658```js 659inputMethodEngine.getKeyboardDelegate().on('textChange', (text) => { 660 console.log('inputMethodEngine textChange. text:' + text); 661}); 662``` 663 664### off('textChange') 665 666off(type: 'textChange', callback?: (text: string) => void): void 667 668Cancels listening for text changes. This API uses an asynchronous callback to return the result. 669 670**System capability**: SystemCapability.MiscServices.InputMethodFramework 671 672**Parameters** 673 674| Name | Type | Mandatory| Description | 675| -------- | ------ | ---- | ------------------------------------------------------------ | 676| type | string | Yes | Listening type.<br>The value **'textChange'** indicates the text change event.| 677| callback | (text: string) => void | No | Callback used to return the text content.| 678 679**Example** 680 681```js 682inputMethodEngine.getKeyboardDelegate().off('textChange', (text) => { 683 console.log('delete textChange notification. text:' + text); 684}); 685``` 686 687## KeyboardController 688 689In the following API examples, you must first use **[on('inputStart')](#oninputstart9)** to obtain a **KeyboardController** instance, and then call the APIs using the obtained instance. 690 691### hide<sup>9+</sup> 692 693hide(callback: AsyncCallback<void>): void 694 695Hides the keyboard. This API uses an asynchronous callback to return the result. 696 697**System capability**: SystemCapability.MiscServices.InputMethodFramework 698 699**Parameters** 700 701| Name | Type | Mandatory| Description | 702| -------- | ---------------------- | ---- | -------- | 703| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 704 705**Error codes** 706 707For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 708 709| Error Code ID| Error Message | 710| -------- | -------------------------- | 711| 12800003 | input method client error. | 712 713**Example** 714 715```js 716keyboardController.hide((err) => { 717 if (err !== undefined) { 718 console.error('Failed to hide keyboard: ' + JSON.stringify(err)); 719 return; 720 } 721 console.log('Succeeded in hiding keyboard.'); 722}); 723``` 724 725### hide<sup>9+</sup> 726 727hide(): Promise<void> 728 729Hides the keyboard. This API uses a promise to return the result. 730 731**System capability**: SystemCapability.MiscServices.InputMethodFramework 732 733**Return value** 734 735| Type | Description | 736| ---------------- | ------------------------- | 737| Promise<void> | Promise that returns no value.| 738 739**Error codes** 740 741For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 742 743| Error Code ID| Error Message | 744| -------- | -------------------------- | 745| 12800003 | input method client error. | 746 747**Example** 748 749```js 750keyboardController.hide().then(() => { 751 console.info('Succeeded in hiding keyboard.'); 752}).catch((err) => { 753 console.info('Failed to hide keyboard: ' + JSON.stringify(err)); 754}); 755``` 756 757### hideKeyboard<sup>(deprecated)</sup> 758 759hideKeyboard(callback: AsyncCallback<void>): void 760 761Hides the keyboard. This API uses an asynchronous callback to return the result. 762 763> **NOTE** 764> 765> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [hide](#hide9). 766 767**System capability**: SystemCapability.MiscServices.InputMethodFramework 768 769**Parameters** 770 771| Name | Type | Mandatory| Description | 772| -------- | ---------------------- | ---- | -------- | 773| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 774 775**Example** 776 777```js 778keyboardController.hideKeyboard((err) => { 779 if (err !== undefined) { 780 console.error('Failed to hide Keyboard: ' + JSON.stringify(err)); 781 return; 782 } 783 console.log('Succeeded in hiding keyboard.'); 784}); 785``` 786 787### hideKeyboard<sup>(deprecated)</sup> 788 789hideKeyboard(): Promise<void> 790 791Hides the keyboard. This API uses a promise to return the result. 792 793> **NOTE** 794> 795> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [hide](#hide9-1). 796 797**System capability**: SystemCapability.MiscServices.InputMethodFramework 798 799**Return value** 800 801| Type | Description | 802| ---------------- | ------------------------- | 803| Promise<void> | Promise that returns no value.| 804 805**Example** 806 807```js 808keyboardController.hideKeyboard().then(() => { 809 console.info('Succeeded in hiding keyboard.'); 810}).catch((err) => { 811 console.info('Failed to hide Keyboard: ' + JSON.stringify(err)); 812}); 813``` 814 815## InputClient<sup>9+</sup> 816 817In the following API examples, you must first use **[on('inputStart')](#oninputstart9)** to obtain an **InputClient** instance, and then call the APIs using the obtained instance. 818 819### sendKeyFunction<sup>9+</sup> 820 821sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void 822 823Sends the function key. This API uses an asynchronous callback to return the result. 824 825**System capability**: SystemCapability.MiscServices.InputMethodFramework 826 827 **Parameters** 828 829| Name| Type| Mandatory| Description| 830| -------- | -------- | -------- | -------- | 831| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).| 832| 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.| 833 834**Error codes** 835 836For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 837 838| Error Code ID| Error Message | 839| -------- | -------------------------- | 840| 12800003 | input method client error. | 841 842 **Example** 843 844```js 845let action = 1; 846try { 847 inputClient.sendKeyFunction(action, (err, result) => { 848 if (err !== undefined) { 849 console.error('Failed to sendKeyFunction: ' + JSON.stringify(err)); 850 return; 851 } 852 if (result) { 853 console.info('Succeeded in sending key function. '); 854 } else { 855 console.error('Failed to sendKeyFunction. '); 856 } 857 }); 858} catch (err) { 859 console.error('sendKeyFunction err: ' + JSON.stringify(err)); 860} 861``` 862 863### sendKeyFunction<sup>9+</sup> 864 865sendKeyFunction(action: number): Promise<boolean> 866 867Sends the function key. This API uses a promise to return the result. 868 869**System capability**: SystemCapability.MiscServices.InputMethodFramework 870 871**Parameters** 872 873| Name| Type| Mandatory| Description| 874| -------- | -------- | -------- | -------- | 875| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).| 876 877**Return value** 878 879| Type | Description | 880| ------------------------------- | ------------------------------------------------------------ | 881| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.| 882 883**Error codes** 884 885For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 886 887| Error Code ID| Error Message | 888| -------- | -------------------------- | 889| 12800003 | input method client error. | 890 891**Example** 892 893```js 894let action = 1; 895try { 896 inputClient.sendKeyFunction(action).then((result) => { 897 if (result) { 898 console.info('Succeeded in sending key function. '); 899 } else { 900 console.error('Failed to sendKeyFunction. '); 901 } 902 }).catch((err) => { 903 console.error('Failed to sendKeyFunction:' + JSON.stringify(err)); 904 }); 905} catch (err) { 906 console.error('Failed to sendKeyFunction: ' + JSON.stringify(err)); 907} 908``` 909 910### getForward<sup>9+</sup> 911 912getForward(length:number, callback: AsyncCallback<string>): void 913 914Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. 915 916**System capability**: SystemCapability.MiscServices.InputMethodFramework 917 918**Parameters** 919 920| Name| Type| Mandatory| Description| 921| -------- | -------- | -------- | -------- | 922| length | number | Yes| Text length.| 923| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.| 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| 12800003 | input method client error. | 932| 12800006 | Input method controller error. | 933 934**Example** 935 936```js 937let length = 1; 938try { 939 inputClient.getForward(length, (err, text) => { 940 if (err !== undefined) { 941 console.error('Failed to getForward: ' + JSON.stringify(err)); 942 return; 943 } 944 console.log('Succeeded in getting forward, text: ' + text); 945 }); 946} catch (err) { 947 console.error('Failed to getForward: ' + JSON.stringify(err)); 948} 949``` 950 951### getForward<sup>9+</sup> 952 953getForward(length:number): Promise<string> 954 955Obtains the specific-length text before the cursor. This API uses a promise to return the result. 956 957**System capability**: SystemCapability.MiscServices.InputMethodFramework 958 959**Parameters** 960 961| Name| Type| Mandatory| Description| 962| -------- | -------- | -------- | -------- | 963| length | number | Yes| Text length.| 964 965**Return value** 966 967| Type | Description | 968| ------------------------------- | ------------------------------------------------------------ | 969| Promise<string> | Promise used to return the specific-length text before the cursor. | 970 971**Error codes** 972 973For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 974 975| Error Code ID| Error Message | 976| -------- | ------------------------------ | 977| 12800003 | input method client error. | 978| 12800006 | Input method controller error. | 979 980**Example** 981 982```js 983let length = 1; 984try { 985 inputClient.getForward(length).then((text) => { 986 console.info('Succeeded in getting forward, text: ' + text); 987 }).catch((err) => { 988 console.error('Failed to getForward: ' + JSON.stringify(err)); 989 }); 990} catch (err) { 991 console.error('Failed to getForward: ' + JSON.stringify(err)); 992} 993``` 994 995### getBackward<sup>9+</sup> 996 997getBackward(length:number, callback: AsyncCallback<string>): void 998 999Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. 1000 1001**System capability**: SystemCapability.MiscServices.InputMethodFramework 1002 1003**Parameters** 1004 1005| Name| Type| Mandatory| Description| 1006| -------- | -------- | -------- | -------- | 1007| length | number | Yes| Text length.| 1008| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.| 1009 1010**Error codes** 1011 1012For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1013 1014| Error Code ID| Error Message | 1015| -------- | ------------------------------ | 1016| 12800003 | input method client error. | 1017| 12800006 | Input method controller error. | 1018 1019**Example** 1020 1021```js 1022let length = 1; 1023try { 1024 inputClient.getBackward(length, (err, text) => { 1025 if (err !== undefined) { 1026 console.error('Failed to getForward: ' + JSON.stringify(err)); 1027 return; 1028 } 1029 console.log('Succeeded in getting backward, text: ' + text); 1030 }); 1031} catch (err) { 1032 console.error('Failed to getForward: ' + JSON.stringify(err)); 1033} 1034``` 1035 1036### getBackward<sup>9+</sup> 1037 1038getBackward(length:number): Promise<string> 1039 1040Obtains the specific-length text after the cursor. This API uses a promise to return the result. 1041 1042**System capability**: SystemCapability.MiscServices.InputMethodFramework 1043 1044**Parameters** 1045 1046| Name| Type| Mandatory| Description| 1047| -------- | -------- | -------- | -------- | 1048| length | number | Yes| Text length.| 1049 1050**Return value** 1051 1052| Type | Description | 1053| ------------------------------- | ------------------------------------------------------------ | 1054| Promise<string> | Promise used to return the specific-length text after the cursor. | 1055 1056**Error codes** 1057 1058For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1059 1060| Error Code ID| Error Message | 1061| -------- | ------------------------------ | 1062| 12800003 | input method client error. | 1063| 12800006 | Input method controller error. | 1064 1065**Example** 1066 1067```js 1068let length = 1; 1069try { 1070 inputClient.getBackward(length).then((text) => { 1071 console.info('Succeeded in getting backward, text: ' + text); 1072 }).catch((err) => { 1073 console.error('Failed to getForward: ' + JSON.stringify(err)); 1074 }); 1075} catch (err) { 1076 console.error('Failed to getForward: ' + JSON.stringify(err)); 1077} 1078``` 1079 1080### deleteForward<sup>9+</sup> 1081 1082deleteForward(length:number, callback: AsyncCallback<boolean>): void 1083 1084Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. 1085 1086**System capability**: SystemCapability.MiscServices.InputMethodFramework 1087 1088**Parameters** 1089 1090| Name| Type| Mandatory| Description| 1091| -------- | -------- | -------- | -------- | 1092| length | number | Yes| Text length.| 1093| 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.| 1094 1095**Error codes** 1096 1097For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1098 1099| Error Code ID| Error Message | 1100| -------- | -------------------------- | 1101| 12800002 | Input method engine error. | 1102| 12800003 | input method client error. | 1103 1104**Example** 1105 1106```js 1107let length = 1; 1108try { 1109 inputClient.deleteForward(length, (err, result) => { 1110 if (err !== undefined) { 1111 console.error('Failed to delete forward: ' + JSON.stringify(err)); 1112 return; 1113 } 1114 if (result) { 1115 console.info('Succeeded in deleting forward. '); 1116 } else { 1117 console.error('Failed to delete forward: ' + JSON.stringify(err)); 1118 } 1119 }); 1120} catch (err) { 1121 console.error('Failed to delete forward: ' + JSON.stringify(err)); 1122} 1123``` 1124 1125### deleteForward<sup>9+</sup> 1126 1127deleteForward(length:number): Promise<boolean> 1128 1129Deletes the fixed-length text before the cursor. This API uses a promise to return the result. 1130 1131**System capability**: SystemCapability.MiscServices.InputMethodFramework 1132 1133**Parameters** 1134 1135| Name| Type | Mandatory| Description | 1136| ------ | ------ | ---- | ---------- | 1137| length | number | Yes | Text length.| 1138 1139**Return value** 1140 1141| Type | Description | 1142| ---------------------- | -------------- | 1143| Promise<boolean> | Promise used to return the result. The value **true** means that the operation is successful, and **false** means the opposite.| 1144 1145**Error codes** 1146 1147For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1148 1149| Error Code ID| Error Message | 1150| -------- | -------------------------- | 1151| 12800002 | Input method engine error. | 1152| 12800003 | input method client error. | 1153 1154**Example** 1155 1156```js 1157let length = 1; 1158try { 1159 inputClient.deleteForward(length).then((result) => { 1160 if (result) { 1161 console.info('Succeeded in deleting forward. '); 1162 } else { 1163 console.error('Failed to delete Forward. '); 1164 } 1165 }).catch((err) => { 1166 console.error('Failed to delete Forward: ' + JSON.stringify(err)); 1167 }); 1168} catch (err) { 1169 console.error('Failed to delete Forward: ' + JSON.stringify(err)); 1170} 1171``` 1172 1173### deleteBackward<sup>9+</sup> 1174 1175deleteBackward(length:number, callback: AsyncCallback<boolean>): void 1176 1177Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. 1178 1179**System capability**: SystemCapability.MiscServices.InputMethodFramework 1180 1181**Parameters** 1182 1183| Name | Type | Mandatory| Description | 1184| -------- | ---------------------------- | ---- | -------------- | 1185| length | number | Yes | Text length. | 1186| 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.| 1187 1188**Error codes** 1189 1190For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1191 1192| Error Code ID| Error Message | 1193| -------- | -------------------------- | 1194| 12800002 | Input method engine error. | 1195| 12800003 | input method client error. | 1196 1197**Example** 1198 1199```js 1200let length = 1; 1201try { 1202 inputClient.deleteBackward(length, (err, result) => { 1203 if (err !== undefined) { 1204 console.error('Failed to delete Backward: ' + JSON.stringify(err)); 1205 return; 1206 } 1207 if (result) { 1208 console.info('Succeeded in deleting backward. '); 1209 } else { 1210 console.error('Failed to delete Backward: ' + JSON.stringify(err)); 1211 } 1212 }); 1213} catch (err) { 1214 console.error('deleteBackward err: ' + JSON.stringify(err)); 1215} 1216``` 1217 1218### deleteBackward<sup>9+</sup> 1219 1220deleteBackward(length:number): Promise<boolean> 1221 1222Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. 1223 1224**System capability**: SystemCapability.MiscServices.InputMethodFramework 1225 1226**Parameters** 1227 1228| Name| Type| Mandatory| Description| 1229| -------- | -------- | -------- | -------- | 1230| length | number | Yes| Text length.| 1231 1232**Return value** 1233 1234| Type | Description | 1235| ------------------------------- | ------------------------------------------------------------ | 1236| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.| 1237 1238**Error codes** 1239 1240For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1241 1242| Error Code ID| Error Message | 1243| -------- | -------------------------- | 1244| 12800002 | Input method engine error. | 1245| 12800003 | input method client error. | 1246 1247**Example** 1248 1249```js 1250let length = 1; 1251inputClient.deleteBackward(length).then((result) => { 1252 if (result) { 1253 console.info('Succeeded in deleting backward. '); 1254 } else { 1255 console.error('Failed to deleteBackward. '); 1256 } 1257}).catch((err) => { 1258 console.error('Failed to deleteBackward: ' + JSON.stringify(err)); 1259}); 1260``` 1261 1262### insertText<sup>9+</sup> 1263 1264insertText(text:string, callback: AsyncCallback<boolean>): void 1265 1266Inserts text. This API uses an asynchronous callback to return the result. 1267 1268**System capability**: SystemCapability.MiscServices.InputMethodFramework 1269 1270**Parameters** 1271 1272| Name| Type| Mandatory| Description| 1273| -------- | -------- | -------- | -------- | 1274| text | string | Yes| Text to insert.| 1275| 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.| 1276 1277**Error codes** 1278 1279For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1280 1281| Error Code ID| Error Message | 1282| -------- | -------------------------- | 1283| 12800002 | Input method engine error. | 1284| 12800003 | input method client error. | 1285 1286**Example** 1287 1288```js 1289inputClient.insertText('test', (err, result) => { 1290 if (err !== undefined) { 1291 console.error('Failed to insertText: ' + JSON.stringify(err)); 1292 return; 1293 } 1294 if (result) { 1295 console.info('Succeeded in inserting text. '); 1296 } else { 1297 console.error('Failed to insertText. '); 1298 } 1299}); 1300``` 1301 1302### insertText<sup>9+</sup> 1303 1304insertText(text:string): Promise<boolean> 1305 1306Inserts text. This API uses a promise to return the result. 1307 1308**System capability**: SystemCapability.MiscServices.InputMethodFramework 1309 1310**Parameters** 1311 1312| Name| Type| Mandatory| Description| 1313| -------- | -------- | -------- | -------- | 1314| text | string | Yes| Text to insert.| 1315 1316**Return value** 1317 1318| Type | Description | 1319| ------------------------------- | ------------------------------------------------------------ | 1320| Promise<boolean> | Promise used to return the result. The value **true** means that the insertion is successful, and **false** means the opposite. | 1321 1322**Error codes** 1323 1324For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1325 1326| Error Code ID| Error Message | 1327| -------- | -------------------------- | 1328| 12800002 | Input method engine error. | 1329| 12800003 | input method client error. | 1330 1331**Example** 1332 1333```js 1334try { 1335 inputClient.insertText('test').then((result) => { 1336 if (result) { 1337 console.info('Succeeded in inserting text. '); 1338 } else { 1339 console.error('Failed to insertText. '); 1340 } 1341 }).catch((err) => { 1342 console.error('Failed to insertText: ' + JSON.stringify(err)); 1343 }); 1344} catch (err) { 1345 console.error('Failed to insertText: ' + JSON.stringify(err)); 1346} 1347``` 1348 1349### getEditorAttribute<sup>9+</sup> 1350 1351getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void 1352 1353Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. 1354 1355**System capability**: SystemCapability.MiscServices.InputMethodFramework 1356 1357**Parameters** 1358 1359| Name | Type | Mandatory | Description | 1360| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 1361| callback | AsyncCallback<[EditorAttribute](#editorattribute)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the attribute of the edit box. Otherwise, **err** is an error object.| 1362 1363**Error codes** 1364 1365For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1366 1367| Error Code ID| Error Message | 1368| -------- | -------------------------- | 1369| 12800003 | input method client error. | 1370 1371**Example** 1372 1373```js 1374inputClient.getEditorAttribute((err, editorAttribute) => { 1375 if (err !== undefined) { 1376 console.error('Failed to getEditorAttribute: ' + JSON.stringify(err)); 1377 return; 1378 } 1379 console.log('editorAttribute.inputPattern: ' + JSON.stringify(editorAttribute.inputPattern)); 1380 console.log('editorAttribute.enterKeyType: ' + JSON.stringify(editorAttribute.enterKeyType)); 1381}); 1382``` 1383 1384### getEditorAttribute<sup>9+</sup> 1385 1386getEditorAttribute(): Promise<EditorAttribute> 1387 1388Obtains the attribute of the edit box. This API uses a promise to return the result. 1389 1390**System capability**: SystemCapability.MiscServices.InputMethodFramework 1391 1392**Return value** 1393 1394| Type | Description | 1395| ------------------------------- | ------------------------------------------------------------ | 1396| Promise<[EditorAttribute](#editorattribute)> | Promise used to return the attribute of the edit box. | 1397 1398**Error codes** 1399 1400For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1401 1402| Error Code ID| Error Message | 1403| -------- | -------------------------- | 1404| 12800003 | input method client error. | 1405 1406**Example** 1407 1408```js 1409inputClient.getEditorAttribute().then((editorAttribute) => { 1410 console.info('editorAttribute.inputPattern: ' + JSON.stringify(editorAttribute.inputPattern)); 1411 console.info('editorAttribute.enterKeyType: ' + JSON.stringify(editorAttribute.enterKeyType)); 1412}).catch((err) => { 1413 console.error('Failed to getEditorAttribute: ' + JSON.stringify(err)); 1414}); 1415``` 1416 1417### moveCursor<sup>9+</sup> 1418 1419moveCursor(direction: number, callback: AsyncCallback<void>): void 1420 1421Moves the cursor. This API uses an asynchronous callback to return the result. 1422 1423**System capability**: SystemCapability.MiscServices.InputMethodFramework 1424 1425**Parameters** 1426 1427| Name | Type | Mandatory| Description | 1428| --------- | ------------------------- | ---- | -------------- | 1429| direction | number | Yes | Direction in which the cursor moves.| 1430| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 1431 1432**Error codes** 1433 1434For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1435 1436| Error Code ID| Error Message | 1437| -------- | -------------------------- | 1438| 12800003 | input method client error. | 1439 1440**Example** 1441 1442```js 1443try { 1444 inputClient.moveCursor(inputMethodEngine.CURSOR_UP, (err) => { 1445 if (err !== undefined) { 1446 console.error('Failed to moveCursor: ' + JSON.stringify(err)); 1447 return; 1448 } 1449 console.info('Succeeded in moving cursor.'); 1450 }); 1451} catch (err) { 1452 console.error('Failed to moveCursor: ' + JSON.stringify(err)); 1453} 1454``` 1455 1456### moveCursor<sup>9+</sup> 1457 1458moveCursor(direction: number): Promise<void> 1459 1460Moves the cursor. This API uses a promise to return the result. 1461 1462**System capability**: SystemCapability.MiscServices.InputMethodFramework 1463 1464**Parameters** 1465 1466| Name | Type | Mandatory| Description | 1467| --------- | ------ | ---- | -------------- | 1468| direction | number | Yes | Direction in which the cursor moves.| 1469 1470**Return value** 1471 1472| Type | Description | 1473| ------------------- | ------------------------- | 1474| Promise<void> | Promise that returns no value.| 1475 1476**Error codes** 1477 1478For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). 1479 1480| Error Code ID| Error Message | 1481| -------- | -------------------------- | 1482| 12800003 | input method client error. | 1483 1484**Example** 1485 1486```js 1487try { 1488 inputClient.moveCursor(inputMethodEngine.CURSOR_UP).then(() => { 1489 console.log('Succeeded in moving cursor.'); 1490 }).catch((err) => { 1491 console.error('Failed to moveCursor: ' + JSON.stringify(err)); 1492 }); 1493} catch (err) { 1494 console.log('Failed to moveCursor: ' + JSON.stringify(err)); 1495} 1496``` 1497 1498## EditorAttribute 1499 1500Attribute of the edit box. 1501 1502**System capability**: SystemCapability.MiscServices.InputMethodFramework 1503 1504| Name | Type| Readable| Writable| Description | 1505| ------------ | -------- | ---- | ---- | ------------------ | 1506| enterKeyType | number | Yes | No | Function attribute of the edit box.| 1507| inputPattern | number | Yes | No | Text attribute of the edit box.| 1508 1509## KeyEvent 1510 1511Describes the attribute of a key. 1512 1513**System capability**: SystemCapability.MiscServices.InputMethodFramework 1514 1515| Name | Type| Readable| Writable| Description | 1516| --------- | -------- | ---- | ---- | ------------ | 1517| keyCode | number | Yes | No | Key value.| 1518| keyAction | number | Yes | No | Key status.| 1519 1520## TextInputClient<sup>(deprecated)</sup> 1521 1522> **NOTE** 1523> 1524> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [InputClient](#inputclient9). 1525 1526In the following API examples, you must first use **[on('inputStart')](#oninputstart)** to obtain a **TextInputClient** instance, and then call the APIs using the obtained instance. 1527 1528### getForward<sup>(deprecated)</sup> 1529 1530getForward(length:number, callback: AsyncCallback<string>): void 1531 1532Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. 1533 1534> **NOTE** 1535> 1536> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getForward](#getforward9). 1537 1538**System capability**: SystemCapability.MiscServices.InputMethodFramework 1539 1540**Parameters** 1541 1542| Name| Type| Mandatory| Description| 1543| -------- | -------- | -------- | -------- | 1544| length | number | Yes| Text length.| 1545| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.| 1546 1547**Example** 1548 1549```js 1550let length = 1; 1551textInputClient.getForward(length, (err, text) => { 1552 if (err !== undefined) { 1553 console.error('Failed to getForward: ' + JSON.stringify(err)); 1554 return; 1555 } 1556 console.log('Succeeded in getting forward, text: ' + text); 1557}); 1558``` 1559 1560### getForward<sup>(deprecated)</sup> 1561 1562getForward(length:number): Promise<string> 1563 1564Obtains the specific-length text before the cursor. This API uses a promise to return the result. 1565 1566> **NOTE** 1567> 1568> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getForward](#getforward9). 1569 1570**System capability**: SystemCapability.MiscServices.InputMethodFramework 1571 1572**Parameters** 1573 1574| Name| Type| Mandatory| Description| 1575| -------- | -------- | -------- | -------- | 1576| length | number | Yes| Text length.| 1577 1578**Return value** 1579 1580| Type | Description | 1581| ------------------------------- | ------------------------------------------------------------ | 1582| Promise<string> | Promise used to return the specific-length text before the cursor. | 1583 1584**Example** 1585 1586```js 1587let length = 1; 1588textInputClient.getForward(length).then((text) => { 1589 console.info('Succeeded in getting forward, text: ' + text); 1590}).catch((err) => { 1591 console.error('Failed to getForward: ' + JSON.stringify(err)); 1592}); 1593``` 1594 1595### getBackward<sup>(deprecated)</sup> 1596 1597getBackward(length:number, callback: AsyncCallback<string>): void 1598 1599Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. 1600 1601> **NOTE** 1602> 1603> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getBackward](#getbackward9). 1604 1605**System capability**: SystemCapability.MiscServices.InputMethodFramework 1606 1607**Parameters** 1608 1609| Name| Type| Mandatory| Description| 1610| -------- | -------- | -------- | -------- | 1611| length | number | Yes| Text length.| 1612| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the obtained text. Otherwise, **err** is an error object.| 1613 1614**Example** 1615 1616```js 1617let length = 1; 1618textInputClient.getBackward(length, (err, text) => { 1619 if (err !== undefined) { 1620 console.error('Failed to getBackward: ' + JSON.stringify(err)); 1621 return; 1622 } 1623 console.log('Succeeded in getting borward, text: ' + text); 1624}); 1625``` 1626 1627### getBackward<sup>(deprecated)</sup> 1628 1629getBackward(length:number): Promise<string> 1630 1631Obtains the specific-length text after the cursor. This API uses a promise to return the result. 1632 1633> **NOTE** 1634> 1635> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getBackward](#getbackward9). 1636 1637**System capability**: SystemCapability.MiscServices.InputMethodFramework 1638 1639**Parameters** 1640 1641| Name| Type| Mandatory| Description| 1642| -------- | -------- | -------- | -------- | 1643| length | number | Yes| Text length.| 1644 1645**Return value** 1646 1647| Type | Description | 1648| ------------------------------- | ------------------------------------------------------------ | 1649| Promise<string> | Promise used to return the specific-length text after the cursor. | 1650 1651**Example** 1652 1653```js 1654let length = 1; 1655textInputClient.getBackward(length).then((text) => { 1656 console.info('Succeeded in getting backward: ' + JSON.stringify(text)); 1657}).catch((err) => { 1658 console.error('Failed to getBackward: ' + JSON.stringify(err)); 1659}); 1660``` 1661 1662### deleteForward<sup>(deprecated)</sup> 1663 1664deleteForward(length:number, callback: AsyncCallback<boolean>): void 1665 1666Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. 1667 1668> **NOTE** 1669> 1670> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [deleteForward](#deleteforward9). 1671 1672**System capability**: SystemCapability.MiscServices.InputMethodFramework 1673 1674**Parameters** 1675 1676| Name| Type| Mandatory| Description| 1677| -------- | -------- | -------- | -------- | 1678| length | number | Yes| Text length.| 1679| 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.| 1680 1681**Example** 1682 1683```js 1684let length = 1; 1685textInputClient.deleteForward(length, (err, result) => { 1686 if (err !== undefined) { 1687 console.error('Failed to deleteForward: ' + JSON.stringify(err)); 1688 return; 1689 } 1690 if (result) { 1691 console.info('Succeeded in deleting forward. '); 1692 } else { 1693 console.error('Failed to deleteForward. '); 1694 } 1695}); 1696``` 1697 1698### deleteForward<sup>(deprecated)</sup> 1699 1700deleteForward(length:number): Promise<boolean> 1701 1702Deletes the fixed-length text before the cursor. This API uses a promise to return the result. 1703 1704> **NOTE** 1705> 1706> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [deleteForward](#deleteforward9). 1707 1708**System capability**: SystemCapability.MiscServices.InputMethodFramework 1709 1710**Parameters** 1711 1712| Name| Type | Mandatory| Description | 1713| ------ | ------ | ---- | ---------- | 1714| length | number | Yes | Text length.| 1715 1716**Return value** 1717 1718| Type | Description | 1719| ---------------------- | -------------- | 1720| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.| 1721 1722**Example** 1723 1724```js 1725let length = 1; 1726textInputClient.deleteForward(length).then((result) => { 1727 if (result) { 1728 console.info('Succeeded in deleting forward. '); 1729 } else { 1730 console.error('Failed to delete forward. '); 1731 } 1732}).catch((err) => { 1733 console.error('Failed to delete forward: ' + JSON.stringify(err)); 1734}); 1735``` 1736 1737### deleteBackward<sup>(deprecated)</sup> 1738 1739deleteBackward(length:number, callback: AsyncCallback<boolean>): void 1740 1741Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. 1742 1743> **NOTE** 1744> 1745> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [deleteBackward](#deletebackward9). 1746 1747**System capability**: SystemCapability.MiscServices.InputMethodFramework 1748 1749 **Parameters** 1750 1751| Name | Type | Mandatory| Description | 1752| -------- | ---------------------------- | ---- | -------------- | 1753| length | number | Yes | Text length. | 1754| 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.| 1755 1756 **Example** 1757 1758```js 1759let length = 1; 1760textInputClient.deleteBackward(length, (err, result) => { 1761 if (err !== undefined) { 1762 console.error('Failed to delete backward: ' + JSON.stringify(err)); 1763 return; 1764 } 1765 if (result) { 1766 console.info('Succeeded in deleting backward. '); 1767 } else { 1768 console.error('Failed to deleteBackward. '); 1769 } 1770}); 1771``` 1772 1773### deleteBackward<sup>(deprecated)</sup> 1774 1775deleteBackward(length:number): Promise<boolean> 1776 1777Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. 1778 1779> **NOTE** 1780> 1781> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [deleteBackward](#deletebackward9). 1782 1783**System capability**: SystemCapability.MiscServices.InputMethodFramework 1784 1785**Parameters** 1786 1787| Name| Type| Mandatory| Description| 1788| -------- | -------- | -------- | -------- | 1789| length | number | Yes| Text length.| 1790 1791**Return value** 1792 1793| Type | Description | 1794| ------------------------------- | ------------------------------------------------------------ | 1795| Promise<boolean> | Promise used to return the result. The value **true** means that the deletion is successful, and **false** means the opposite.| 1796 1797**Example** 1798 1799```js 1800let length = 1; 1801textInputClient.deleteBackward(length).then((result) => { 1802 if (result) { 1803 console.info('Succeeded in deleting backward. '); 1804 } else { 1805 console.error('Failed to deleteBackward. '); 1806 } 1807}).catch((err) => { 1808 console.error('Failed to deleteBackward: ' + JSON.stringify(err)); 1809}); 1810``` 1811### sendKeyFunction<sup>(deprecated)</sup> 1812 1813sendKeyFunction(action: number, callback: AsyncCallback<boolean>): void 1814 1815Sends the function key. This API uses an asynchronous callback to return the result. 1816 1817> **NOTE** 1818> 1819> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [sendKeyFunction](#sendkeyfunction9). 1820 1821**System capability**: SystemCapability.MiscServices.InputMethodFramework 1822 1823 **Parameters** 1824 1825| Name| Type| Mandatory| Description| 1826| -------- | -------- | -------- | -------- | 1827| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).| 1828| 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.| 1829 1830 **Example** 1831 1832```js 1833let action = 1; 1834textInputClient.sendKeyFunction(action, (err, result) => { 1835 if (err !== undefined) { 1836 console.error('Failed to sendKeyFunction: ' + JSON.stringify(err)); 1837 return; 1838 } 1839 if (result) { 1840 console.info('Succeeded in sending key function. '); 1841 } else { 1842 console.error('Failed to sendKeyFunction. '); 1843 } 1844}); 1845``` 1846 1847### sendKeyFunction<sup>(deprecated)</sup> 1848 1849sendKeyFunction(action: number): Promise<boolean> 1850 1851Sends the function key. This API uses a promise to return the result. 1852 1853> **NOTE** 1854> 1855> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [sendKeyFunction](#sendkeyfunction9). 1856 1857**System capability**: SystemCapability.MiscServices.InputMethodFramework 1858 1859**Parameters** 1860 1861| Name| Type| Mandatory| Description| 1862| -------- | -------- | -------- | -------- | 1863| action | number | Yes| Action of the function key.<br>**0**: invalid key.<br>**1**: confirm key (Enter key).| 1864 1865**Return value** 1866 1867| Type | Description | 1868| ------------------------------- | ------------------------------------------------------------ | 1869| Promise<boolean> | Promise used to return the result. The value **true** means that the setting is successful, and **false** means the opposite.| 1870 1871**Example** 1872 1873```js 1874let action = 1; 1875textInputClient.sendKeyFunction(action).then((result) => { 1876 if (result) { 1877 console.info('Succeeded in sending key function. '); 1878 } else { 1879 console.error('Failed to sendKeyFunction. '); 1880 } 1881}).catch((err) => { 1882 console.error('Failed to sendKeyFunction:' + JSON.stringify(err)); 1883}); 1884``` 1885 1886### insertText<sup>(deprecated)</sup> 1887 1888insertText(text:string, callback: AsyncCallback<boolean>): void 1889 1890Inserts text. This API uses an asynchronous callback to return the result. 1891 1892> **NOTE** 1893> 1894> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [insertText](#inserttext9). 1895 1896**System capability**: SystemCapability.MiscServices.InputMethodFramework 1897 1898**Parameters** 1899 1900| Name| Type| Mandatory| Description| 1901| -------- | -------- | -------- | -------- | 1902| text | string | Yes| Text to insert.| 1903| 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.| 1904 1905**Example** 1906 1907```js 1908textInputClient.insertText('test', (err, result) => { 1909 if (err !== undefined) { 1910 console.error('Failed to insertText: ' + JSON.stringify(err)); 1911 return; 1912 } 1913 if (result) { 1914 console.info('Succeeded in inserting text. '); 1915 } else { 1916 console.error('Failed to insertText. '); 1917 } 1918}); 1919``` 1920 1921### insertText<sup>(deprecated)</sup> 1922 1923insertText(text:string): Promise<boolean> 1924 1925Inserts text. This API uses a promise to return the result. 1926 1927> **NOTE** 1928> 1929> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [insertText](#inserttext9). 1930 1931**System capability**: SystemCapability.MiscServices.InputMethodFramework 1932 1933**Parameters** 1934 1935| Name| Type| Mandatory| Description| 1936| -------- | -------- | -------- | -------- | 1937| text | string | Yes| Text to insert.| 1938 1939**Return value** 1940 1941| Type | Description | 1942| ------------------------------- | ------------------------------------------------------------ | 1943| Promise<boolean> | Promise used to return the result. The value **true** means that the insertion is successful, and **false** means the opposite.| 1944 1945**Example** 1946 1947```js 1948textInputClient.insertText('test').then((result) => { 1949 if (result) { 1950 console.info('Succeeded in inserting text. '); 1951 } else { 1952 console.error('Failed to insertText. '); 1953 } 1954}).catch((err) => { 1955 console.error('Failed to insertText: ' + JSON.stringify(err)); 1956}); 1957``` 1958 1959### getEditorAttribute<sup>(deprecated)</sup> 1960 1961getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void 1962 1963Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. 1964 1965> **NOTE** 1966> 1967> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getEditorAttribute](#geteditorattribute9). 1968 1969**System capability**: SystemCapability.MiscServices.InputMethodFramework 1970 1971**Parameters** 1972 1973| Name | Type | Mandatory | Description | 1974| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 1975| callback | AsyncCallback<[EditorAttribute](#editorattribute)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the attribute of the edit box. Otherwise, **err** is an error object.| 1976 1977**Example** 1978 1979```js 1980textInputClient.getEditorAttribute((err, editorAttribute) => { 1981 if (err !== undefined) { 1982 console.error('Failed to getEditorAttribute: ' + JSON.stringify(err)); 1983 return; 1984 } 1985 console.log('editorAttribute.inputPattern: ' + JSON.stringify(editorAttribute.inputPattern)); 1986 console.log('editorAttribute.enterKeyType: ' + JSON.stringify(editorAttribute.enterKeyType)); 1987}); 1988``` 1989 1990### getEditorAttribute<sup>(deprecated)</sup> 1991 1992getEditorAttribute(): Promise<EditorAttribute> 1993 1994Obtains the attribute of the edit box. This API uses a promise to return the result. 1995 1996> **NOTE** 1997> 1998> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getEditorAttribute](#geteditorattribute9). 1999 2000**System capability**: SystemCapability.MiscServices.InputMethodFramework 2001 2002**Return value** 2003 2004| Type | Description | 2005| ------------------------------- | ------------------------------------------------------------ | 2006| Promise<[EditorAttribute](#editorattribute)> | Promise used to return the attribute of the edit box. | 2007 2008**Example** 2009 2010```js 2011textInputClient.getEditorAttribute().then((editorAttribute) => { 2012 console.info('editorAttribute.inputPattern: ' + JSON.stringify(editorAttribute.inputPattern)); 2013 console.info('editorAttribute.enterKeyType: ' + JSON.stringify(editorAttribute.enterKeyType)); 2014}).catch((err) => { 2015 console.error('Failed to getEditorAttribute: ' + JSON.stringify(err)); 2016}); 2017``` 2018