目录

@ohos.inputMethodEngine (Input Method Service)

The @ohos.inputMethodEngine module is a server-side API module for input method apps (including system input methods and third-party input methods). It provides interaction capabilities between input method apps and the system input method framework.

This module contains server-side interfaces for input method apps, defining all open capabilities required while an input method app is running. The capabilities cover input method lifecycle management, creation and control of the soft keyboard panel, text editing operations (insertion, deletion, and selection), cursor control, physical keyboard event listening, secure mode management, and private data communication.

With this module, an input method app can:

- Subscribe to input method attach/detach events to perceive connection and disconnection with edit boxes.

- Create and manage soft keyboard panels (fixed mode, floating mode, and candidate mode) and status bar panels, and control panel visibility, size adjustment, position movement, immersive mode, and more.

- Use InputClient to perform operations on edit boxes, such as text insertion, text deletion, text selection, cursor movement, function key sending, and extended editing actions.

- Use KeyboardDelegate to listen for physical keyboard key events, cursor position changes, text selection region changes, text content changes, and edit box attribute changes.

- Manage security modes (basic mode and full access mode) and support privacy panel configuration.

- Exchange private data and custom messages with an edit box app.

This module is used during input method app development. It must be used within InputMethodExtensionAbility, and applies to scenarios such as system input method development, third-party input method development, and custom keyboard layout implementation.

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.

The core open capabilities of this module are implemented by the following key interfaces and classes:

Interface/Class Description
InputMethodAbility Input method capability object, which is a core entry for input method apps. Supports subscription to input method lifecycle events (attach/detach, keyboard showing/hiding, subtype switching, security mode changes, etc.), panel creation and destruction, and security mode query. The instance can be obtained via getInputMethodAbility().
KeyboardDelegate Keyboard delegate object. Supports listening for physical keyboard key events, cursor position changes, text selection region changes, text content changes, and edit box attribute changes. The instance can be obtained via getKeyboardDelegate().
InputClient Input client object. Provides capabilities to perform text operations on edit boxes, including inserting text, deleting text backward/forward, obtaining text before or after the cursor, moving the cursor, selecting text, sending function keys, and performing extended editing actions, setting preview text, transmitting private data, and exchanging custom messages. The instance can be obtained inside the callback for the subscribed inputStart event.
KeyboardController Keyboard controller object. Provides capabilities such as hiding the keyboard and exiting the current input type. The instance can be obtained inside the callback for the subscribed inputStart event.
Panel Input method panel object, which provides capabilities such as panel page content loading, resizing, repositioning, showing/hiding, panel state switching, privacy mode setting, immersive mode and effect setting, panel rectangle area presetting, and hot zone updating. Obtain the instance through createPanel().
MessageHandler Custom communication object. Receives custom communication data sent by edit box apps and provides the termination notification callback. It is registered via InputClient.recvMessage().

The typical usage workflow within an input method app involves combined calls of multiple APIs. The core workflow is as follows:

1. Obtain an InputMethodAbility instance.

2. Subscribe to the inputStart event.

3. Obtain KeyboardController and InputClient within the callback

4. Create a panel.

5. Load panel page content.

6. Perform operations on the text of the edit box via InputClient

7. Control keyboard visibility via KeyboardController.

// The following pseudocode illustrates the calling logic.

// 1. Obtain the input method ability object.
let inputMethodAbility = inputMethodEngine.getInputMethodAbility();

// 2. Obtain the keyboard delegate object to listen for physical keyboard and edit box change events.
let keyboardDelegate = inputMethodEngine.getKeyboardDelegate();
keyboardDelegate.on('keyDown', (event) => {
  return true;
});
keyboardDelegate.on('cursorContextChange', (x, y, height) => {
  // do something
});
keyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => {
  // do something
});

// 3. Subscribe to the input method attachment event to obtain **KeyboardController** and **InputClient**.
inputMethodAbility.on('inputStart', (kbController, inputClient) => {

  // 4. Create an input method panel.
  let panelInfo = { type: inputMethodEngine.PanelType.SOFT_KEYBOARD, flag: inputMethodEngine.PanelFlag.FLG_FIXED };
  let panel = inputMethodAbility.createPanel(context, panelInfo);

  // 5. Load panel page content.
  panel.setUiContent('pages/Index');

  // 6. Show the panel.
  panel.show();

  // 7. Perform operations on the edit box via **InputClient**.
  inputClient.insertText('Hello');
  inputClient.deleteForward(1);
  inputClient.moveCursor(inputMethodEngine.CURSOR_RIGHT);

  // 8. Hide the keyboard via **KeyboardController**.
  kbController.hide();
});

// 9. Subscribe to the input method detachment event.
inputMethodAbility.on('inputStop', () => {
  // Destroy the panel.
  inputMethodAbility.destroyPanel(panel);
});

Modules to Import

import { inputMethodEngine } from '@kit.IMEKit';

Constants

Provides the constant values of function keys, edit boxes, and cursors. These constants enable input method apps to identify attributes such as edit box types, Enter key functions, and cursor movement directions. Input method apps can adjust the keyboard layout and input behavior based on these constant values. For example, the app can switch between different keyboard layouts according to the edit box type (PATTERN_TEXT, PATTERN_NUMBER, etc.), and adjust the displayed text and icon of the Enter key according to the Enter key function (ENTER_KEY_TYPE_SEARCH, ENTER_KEY_TYPE_SEND, etc.).

The following constants are divided into three categories by function:

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Value Description
ENTER_KEY_TYPE_UNSPECIFIED number 0 No function is specified for the key.
ENTER_KEY_TYPE_GO number 2 Key that executes a command or navigates to a specific location.
ENTER_KEY_TYPE_SEARCH number 3 Key that initiates a search operation.
ENTER_KEY_TYPE_SEND number 4 Key that sends the text to its target.
ENTER_KEY_TYPE_NEXT number 5 Key that moves the focus to the next item in a sequence.
ENTER_KEY_TYPE_DONE number 6 Key that indicates that a task or input is complete.
ENTER_KEY_TYPE_PREVIOUS number 7 Key that moves the focus to the previous item in a sequence.
ENTER_KEY_TYPE_NEWLINE12+ number 8 Key that inserts a new line.
PATTERN_NULL number -1 Any type of edit box.
PATTERN_TEXT number 0 Text edit box.
PATTERN_NUMBER number 2 Number edit box.
PATTERN_PHONE number 3 Phone number edit box.
PATTERN_DATETIME number 4 Date edit box.
PATTERN_EMAIL number 5 Email edit box.
PATTERN_URI number 6 URI edit box.
PATTERN_PASSWORD number 7 Password edit box.
PATTERN_PASSWORD_NUMBER11+ number 8 Numeric password edit box.
PATTERN_PASSWORD_SCREEN_LOCK11+ number 9 Screen lock password edit box.
PATTERN_USER_NAME20+ number 10

User name edit box.

Model restriction: This parameter can be used only in the stage model.
PATTERN_NEW_PASSWORD20+ number 11

New password edit box.

Model restriction: This parameter can be used only in the stage model.
PATTERN_NUMBER_DECIMAL20+ number 12

Edit box for numbers with decimal points.

Model restriction: This parameter can be used only in the stage model.
PATTERN_ONE_TIME_CODE20+ number 13

Verification code edit box.

Model restriction: This parameter can be used only in the stage model.
OPTION_ASCII number 20 ASCII values are allowed.
OPTION_NONE number 0 No input attribute is specified.
OPTION_AUTO_CAP_CHARACTERS number 2 Characters are auto-capitalized.
OPTION_AUTO_CAP_SENTENCES number 8 Sentences are auto-capitalized.
OPTION_AUTO_WORDS number 4 Words are allowed.
OPTION_MULTI_LINE number 1 Multiple lines are allowed.
OPTION_NO_FULLSCREEN number 10 Half-screen style.
FLAG_SELECTING number 2 The edit box is being selected.
FLAG_SINGLE_LINE number 1 The edit box allows only single-line input.
DISPLAY_MODE_PART number 0 The edit box is displayed in half-screen mode.
DISPLAY_MODE_FULL number 1 The edit box is displayed in full screen.
CURSOR_UP9+ number 1 The cursor moves upward.
CURSOR_DOWN9+ number 2 The cursor moves downward.
CURSOR_LEFT9+ number 3 The cursor moves leftward.
CURSOR_RIGHT9+ number 4 The cursor moves rightward.
WINDOW_TYPE_INPUT_METHOD_FLOAT9+ number 2105 The input method is displayed in a floating window.

inputMethodEngine.getInputMethodAbility9+

getInputMethodAbility(): InputMethodAbility

Obtains an InputMethodAbility instance. This API can be called only by an input method app.

After obtaining the instance, the input method app can subscribe to soft keyboard showing/hiding request events, create/destroy the input method panel, and perform other related operations.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodAbility Input method ability object.

Example

// Obtain the input method app client instance.
let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();

inputMethodEngine.getKeyboardDelegate9+

getKeyboardDelegate(): KeyboardDelegate

Obtains a KeyboardDelegate instance (keyboard delegate object) for the input method app.

After this instance is obtained, the input method app can subscribe to physical keyboard key events, text selection change events, and more.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
KeyboardDelegate Delegate for listening to client edit events.

Example

// Obtain the delegate instance for listening to client edit events.
let keyboardDelegate: inputMethodEngine.KeyboardDelegate = inputMethodEngine.getKeyboardDelegate();

inputMethodEngine.getInputMethodEngine(deprecated)

getInputMethodEngine(): InputMethodEngine

Obtains an InputMethodEngine instance (input method engine) for the input method app.

After this instance is obtained, the input method app can subscribe to soft keyboard show/hide request events and other events.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.getInputMethodAbility() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodEngine Input method app client.

Example

// Obtain the input method app client instance (deprecated).
let InputMethodEngine: inputMethodEngine.InputMethodEngine = inputMethodEngine.getInputMethodEngine();

inputMethodEngine.createKeyboardDelegate(deprecated)

createKeyboardDelegate(): KeyboardDelegate

Obtains a KeyboardDelegate instance for the input method app. After this instance is obtained, the input method app can subscribe to a physical keyboard event, text selection change event, and more.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.getKeyboardDelegate() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
KeyboardDelegate Delegate for listening to client edit events.

Example

let keyboardDelegate: inputMethodEngine.KeyboardDelegate = inputMethodEngine.createKeyboardDelegate();

CommandDataType12+

type CommandDataType = number | string | boolean;

Defines the private data type, which varies depending on its function.

System capability: SystemCapability.MiscServices.InputMethodFramework

Type Description
number Number.
string String.
boolean Boolean.

SizeChangeCallback15+

type SizeChangeCallback = (size: window.Size, keyboardArea?: KeyboardArea) => void

Callback triggered when the size of the input method panel changes.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
size window.Size Yes Panel size.
keyboardArea KeyboardArea No Keyboard area within the current panel. Pass this parameter to obtain or listen for keyboard area changes. If omitted, the default value is undefined, and no keyboard area information will be returned.

InputMethodEngine(deprecated)

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility instead.

The following APIs must be called on an InputMethodEngine instance obtained through getInputMethodEngine.

[h2]on('inputStart')(deprecated)

on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void

Enables listening for the input method binding event. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 23. You are advised to use inputMethodEngine.InputMethodAbility.on instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStart'.
callback (kbController: KeyboardController, textInputClient: TextInputClient) => void Yes Callback used to return the KeyboardController and TextInputClient instances.

Example

inputMethodEngine.getInputMethodEngine()
  .on('inputStart',
    (keyboardController: inputMethodEngine.KeyboardController, textInputClient: inputMethodEngine.TextInputClient) => {
      // Use kbController and textClient to perform related operations.
    });

[h2]off('inputStart')(deprecated)

off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void

Disables listening for the input method binding event.

This API is supported since API version 8 and deprecated since API version 23. You are advised to use inputMethodEngine.InputMethodAbility.off instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStart'.
callback (kbController: KeyboardController, textInputClient: TextInputClient) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodEngine()
  .off('inputStart',
    (kbController: inputMethodEngine.KeyboardController, textClient: inputMethodEngine.TextInputClient) => {
      console.info('delete inputStart notification.');
    });

[h2]on('keyboardShow'|'keyboardHide')(deprecated)

on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void

Enables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 23. You are advised to use inputMethodEngine.InputMethodAbility.on instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyboardShow' indicates the keyboard display event.

- The value 'keyboardHide' indicates the keyboard hiding event.
callback () => void Yes Callback used to return the result.

Example

inputMethodEngine.getInputMethodEngine().on('keyboardShow', () => {
  console.info('inputMethodEngine keyboardShow.');
});
inputMethodEngine.getInputMethodEngine().on('keyboardHide', () => {
  console.info('inputMethodEngine keyboardHide.');
});

[h2]off('keyboardShow'|'keyboardHide')(deprecated)

off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void

Disables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 23. You are advised to use inputMethodEngine.InputMethodAbility.off instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyboardShow' indicates the keyboard showing event.

- The value 'keyboardHide' indicates the keyboard hiding event.
callback () => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodEngine().off('keyboardShow');
inputMethodEngine.getInputMethodEngine().off('keyboardHide');

InputMethodAbility

Represents the core capability object for input method apps. Provides capabilities including input method lifecycle management, panel creation and destruction, and event subscription. An input method app obtains this instance via getInputMethodAbility.

Core capability overview:

Typical calling sequence:

  1. The input method app calls getInputMethodAbility() in the onCreate lifecycle callback of InputMethodExtensionAbility to obtain the instance.

  2. Subscribe to the on('inputStart') event, and obtain KeyboardController and InputClient instances within the callback.

  3. Call createPanel() inside the on('inputStart') callback to create a panel, and call panel.setUiContent() to load the keyboard page.

  4. Subscribe to the on('keyboardShow'|'keyboardHide') event and call panel.show()/panel.hide() in the callback to show/hide the panel.

  5. Call destroyPanel() in the onDestroy lifecycle callback of InputMethodExtensionAbility to release resources, and unsubscribe from all events.

In the following API examples, you must first use getInputMethodAbility to obtain an InputMethodAbility instance, and then call the APIs using the obtained instance.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]on('inputStart')9+

on(type: 'inputStart', callback: (kbController: KeyboardController, inputClient: InputClient) => void): void

Enables listening for the input method binding event. This API uses an asynchronous callback to return the result.

Usage scenarios: When an edit box gains focus and attaches to the input method, the input method app needs to obtain KeyboardController and InputClient instances for subsequent keyboard operations and text interactions.

Use effect: When an edit box attaches to the input method app, the callback is triggered and returns KeyboardController and InputClient instances. Within the callback, the input method app can create panels, load keyboard pages, register listeners for KeyboardDelegate events, and perform other operations.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStart'.
callback (kbController: KeyboardController, inputClient: InputClient) => void Yes Callback used to return the instances related to input method operations. kbController is the keyboard controller instance, used to control keyboard display/hiding; inputClient is the input client instance, used for text interaction with the edit box.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (keyboardController: inputMethodEngine.KeyboardController, inputClient: inputMethodEngine.InputClient) => {
      // Use kbController and client to perform related operations.
    });

[h2]off('inputStart')9+

off(type: 'inputStart', callback?: (kbController: KeyboardController, inputClient: InputClient) => void): void

Disables listening for the input method binding event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStart'.
callback (kbController: KeyboardController, inputClient: InputClient) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('inputStart');

[h2]on('inputStop')9+

on(type: 'inputStop', callback: () => void): void

Enables listening for the input method unbinding event. This API uses an asynchronous callback to return the result.

Usage scenarios: The input method app needs to perform cleanup operations (such as hiding the panel and releasing resources) when the edit box loses focus or the user switches the input method.

Use effect: The callback is triggered when the attachment between the edit box and the input method app terminates. The input method app shall hide the panel, unsubscribe from events, and release resources related to InputClient within the callback.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStop'.
callback () => void Yes Callback function, with no return parameters.

Example

inputMethodEngine.getInputMethodAbility().on('inputStop', () => {
  console.info('inputMethodAbility inputStop');
});

[h2]off('inputStop')9+

off(type: 'inputStop', callback: () => void): void

Disables listening for the input method stop event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'inputStop'.
callback () => void Yes Callback used to unsubscribe.

Example

inputMethodEngine.getInputMethodAbility().off('inputStop', () => {
  console.info('inputMethodAbility delete inputStop notification.');
});

[h2]on('setCallingWindow')9+

on(type: 'setCallingWindow', callback: (wid: number) => void): void;

Enables listening for the window invocation setting event. This API uses an asynchronous callback to return the result.

Usage scenarios: The input method app needs to adjust the panel position or reposition the panel when the window of the attached app changes (for example, when the app switches windows or in multi-window scenarios).

Use effect: The callback is triggered when the calling window changes and returns the new window ID. The input method app can adjust the panel position based on this window ID.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'setCallingWindow'.
callback (wid: number) => void Yes Callback used to return the result. The parameter is the ID of the caller window.

Example

inputMethodEngine.getInputMethodAbility().on('setCallingWindow', (windowId: number) => {
  console.info('inputMethodAbility setCallingWindow');
});

[h2]off('setCallingWindow')9+

off(type: 'setCallingWindow', callback: (wid:number) => void): void

Disables listening for the window invocation setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'setCallingWindow'.
callback (wid:number) => void Yes Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('setCallingWindow', (windowId: number) => {
  console.info('inputMethodAbility delete setCallingWindow notification.');
});

[h2]on('keyboardShow'|'keyboardHide')9+

on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void

Enables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

Usage scenarios: The input method app needs to perform corresponding UI updates (such as adjusting the panel layout and updating the candidate word region) when the soft keyboard is shown or hidden.

Use effect: When a request to show the soft keyboard is triggered, the 'keyboardShow' callback is invoked, and the input method app shall call panel.show() to display the panel within the callback. When a request to hide the soft keyboard is triggered, the 'keyboardHide' callback is invoked, and the input method app shall call panel.hide() to hide the panel within the callback.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyboardShow' indicates the keyboard showing event.

- The value 'keyboardHide' indicates the keyboard hiding event.
callback () => void Yes Callback used to return the result.

Example

inputMethodEngine.getInputMethodAbility().on('keyboardShow', () => {
  console.info('InputMethodAbility keyboardShow.');
});
inputMethodEngine.getInputMethodAbility().on('keyboardHide', () => {
  console.info('InputMethodAbility keyboardHide.');
});

[h2]off('keyboardShow'|'keyboardHide')9+

off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void

Disables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyboardShow' indicates the keyboard display event.

- The value 'keyboardHide' indicates the keyboard hiding event.
callback () => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('keyboardShow', () => {
  console.info('InputMethodAbility delete keyboardShow notification.');
});
inputMethodEngine.getInputMethodAbility().off('keyboardHide', () => {
  console.info('InputMethodAbility delete keyboardHide notification.');
});

[h2]on('setSubtype')9+

on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void

Enables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result.

Usage scenarios: The input method app needs to switch to the corresponding keyboard layout or input logic when the subtype (such as language or input mode) changes.

Use effect: The callback is triggered when the input method subtype changes and returns information about the new input method subtype.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'setSubtype'.
callback (inputMethodSubtype: InputMethodSubtype) => void Yes Callback used to return the input method subtype InputMethodSubtype.

Example

import { InputMethodSubtype } from '@kit.IMEKit';

inputMethodEngine.getInputMethodAbility().on('setSubtype', (inputMethodSubtype: InputMethodSubtype) => {
  console.info('InputMethodAbility setSubtype.');
});

[h2]off('setSubtype')9+

off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void

Disables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'setSubtype'.
callback (inputMethodSubtype: InputMethodSubtype) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('setSubtype', () => {
  console.info('InputMethodAbility delete setSubtype notification.');
});

[h2]on('securityModeChange')11+

on(type: 'securityModeChange', callback: Callback< SecurityMode>): void

Enables listening for the security mode changes of the input method. This API uses an asynchronous callback to return the result.

Use scenarios: The input method app needs to adjust keyboard behaviors when the security mode changes (for example, when the edit box switches to password input mode or privacy mode), such as disabling screenshots and switching to a secure keyboard layout.

Use effect: The callback is triggered when the security mode changes and returns the current security mode value.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'securityModeChange'.
callback Callback<SecurityMode> Yes Callback used to return the current security mode.

Example

inputMethodEngine.getInputMethodAbility()
  .on('securityModeChange', (securityMode: inputMethodEngine.SecurityMode) => {
    console.info(`InputMethodAbility securityModeChange, security is ${securityMode}`);
  });

[h2]off('securityModeChange')11+

off(type: 'securityModeChange', callback?: Callback< SecurityMode>): void

Disables listening for the security mode changes of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'securityModeChange'.
callback Callback<SecurityMode> No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

let securityChangeCallback: (securityMode: inputMethodEngine.SecurityMode) => void =
  (securityMode: inputMethodEngine.SecurityMode) => {
    console.info(`InputMethodAbility securityModeChange, security is ${securityMode}`);
  };
let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();
inputMethodAbility.on('securityModeChange', securityChangeCallback);
inputMethodAbility.off('securityModeChange', securityChangeCallback);

[h2]on('privateCommand')12+

on(type: 'privateCommand', callback: Callback<Record<string, CommandDataType>>): void;

Enables listening for the private data event of the input method. This API uses an asynchronous callback to return the result.

Usage scenarios: This API is used when private data (such as custom commands and configuration information) needs to be transmitted between an app and the input method. Only the system default input method app can subscribe to this event.

Use effect: The callback is triggered when the attached app sends private data to the input method, returning the private data record.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'privateCommand'.
callback Callback<Record<string, CommandDataType>> Yes Callback used to return the private data sent to the input method app.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800010 not the preconfigured default input method.

Example

let privateCommandCallback: (record: Record<string, inputMethodEngine.CommandDataType>) => void =
  (record: Record<string, inputMethodEngine.CommandDataType>) => {
    for (const key in record) {
      console.info(`private command key: ${key}, value: ${record[key]}`);
    }
  }
inputMethodEngine.getInputMethodAbility().on('privateCommand', privateCommandCallback);

[h2]off('privateCommand')12+

off(type: 'privateCommand', callback?: Callback<Record<string, CommandDataType>>): void

Disables listening for the private data event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'privateCommand'.
callback Callback<Record<string, CommandDataType>> No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800010 not the preconfigured default input method.

Example

let privateCommandCallback: (record: Record<string, inputMethodEngine.CommandDataType>) => void =
  (record: Record<string, inputMethodEngine.CommandDataType>) => {
    for (const key in record) {
      console.info(`private command key: ${key}, value: ${record[key]}`);
    }
  }

inputMethodEngine.getInputMethodAbility().off('privateCommand', privateCommandCallback);

[h2]on('callingDisplayDidChange')18+

on(type: 'callingDisplayDidChange', callback: Callback<number>): void

Enables listening for changes of the screen ID of the window associated with the edit box. This API uses an asynchronous callback to return the result.

Usage scenarios: On multi-screen devices, when the edit box switches between different screens, the input method app needs to adjust the panel position and size based on the new screen ID.

Use effect: The callback is triggered when the screen ID where the edit box resides changes, returning the new screen ID.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'callingDisplayDidChange'.
callback Callback<number> Yes Callback used to return the screen ID of the window corresponding to the edit box.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
801 capability not supported.

Example

inputMethodEngine.getInputMethodAbility().on('callingDisplayDidChange', (displayId: number) => {
  console.info(`display id: ${displayId}`);
});
inputMethodEngine.getInputMethodAbility().on('callingDisplayDidChange', callingDisplayDidChangeCallback);

[h2]off('callingDisplayDidChange')18+

off(type: 'callingDisplayDidChange', callback?: Callback<number>): void

Disables listening for changes of the screen ID of the window associated with the edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'callingDisplayDidChange'.
callback Callback<number> No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('callingDisplayDidChange', (displayId: number) => {
  console.info('InputMethodAbility delete calling display notification.');
});

[h2]on('discardTypingText')20+

on(type: 'discardTypingText', callback: Callback<void> ): void

Subscribes to the event that the edit box app sends to the input method to discard candidate words. This API uses an asynchronous callback to return the result.

Usage scenarios: This API is used when the edit box app needs to notify the input method to discard the current candidate word list (such as when the user switches edit boxes or after form submission).

Use effect: The callback is triggered when the edit box app sends a request to discard candidate words. The input method app discards the candidate word list and pre-input text within the callback.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type, which is 'discardTypingText'.

'discardTypingText' indicates subscribing to the event in which the edit box app sends a request to discard candidate words to the input method.
callback Callback<void> Yes Callback used to return the result.

Example

inputMethodEngine.getInputMethodAbility().on('discardTypingText', () => {
  console.info('InputMethodAbility discard the typing text.');
});

[h2]off('discardTypingText')20+

off(type: 'discardTypingText', callback?: Callback<void> ): void

Unsubscribes from the event that the edit box app sends to the input method to discard candidate words. This API uses an asynchronous callback to return the result.

Usage scenario: Used when the edit box app needs to notify the input method to clear the current candidate word list (for example, when the user switches input boxes or submits a form).

Effect after use: When the edit box app sends a request to clear candidate words, the callback is triggered, and the input method app should clear the candidate word list and pre-input text in the callback.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type, which is 'discardTypingText'.

- 'discardTypingText': unsubscribes from the event that the editing box app sends to the input method to discard candidate words.
callback Callback<void> No Callback used to unsubscribe. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('discardTypingText', () => {
  console.info('InputMethodAbility discard the typing text.');
});

[h2]getSecurityMode11+

getSecurityMode(): SecurityMode

Obtains the current security mode of the input method app.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
SecurityMode Security mode.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800004 not an input method application.

Example

let security: inputMethodEngine.SecurityMode = inputMethodEngine.getInputMethodAbility().getSecurityMode();
console.info(`getSecurityMode, securityMode is : ${security}`);

[h2]createPanel10+

createPanel(ctx: BaseContext, info: PanelInfo, callback: AsyncCallback<Panel>): void

Creates an input method panel. This API can be called only by an input method app in the InputMethodExtensionAbility class. This API uses an asynchronous callback to return the result.

Paired calls:

A single input method app can create only one soft keyboard panel and one status bar panel.

The input method panel does not support the creation of child windows. For example, you cannot set an app child window by using window.createWindow, or create child window dialogs by using bindContextMenu, CustomDialog, or other APIs. You are advised to use non-child-window alternatives, such as dialogs, bindMenu, or setting showInSubwindow to false.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
ctx BaseContext Yes Context of the input method.
info PanelInfo Yes Information about the input method panel.
callback AsyncCallback<Panel> Yes Callback used to return the result. If the input method panel is created successfully, err is undefined and data is the obtained Panel object; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800004 not an input method application.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine, InputMethodExtensionAbility } from '@kit.IMEKit';
import { Want } from '@kit.AbilityKit';

// Create the panel information. Set the panel type to soft keyboard and the state to fixed.
let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

class InputMethodExt extends InputMethodExtensionAbility {
    onCreate(want: Want): void {
        console.info(`onCreate, want: ${want.abilityName}`);
        // context is the context object provided by the InputMethodExtensionAbility class and does not need to be obtained separately.
        if (this.context) {
            // Create the input method panel.
            inputMethodEngine.getInputMethodAbility()
            .createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
                if (err) {
                console.error(`Failed to createPanel. Code is ${err.code}, message is ${err.message}`);
                return;
              }
                console.info('Succeed in creating panel.');
            })
        }
    }
}

[h2]createPanel10+

createPanel(ctx: BaseContext, info: PanelInfo): Promise<Panel>

Creates an input method panel. This API can be called only by an input method app in the InputMethodExtensionAbility class. This API uses a promise to return the result.

A single input method app can create only one soft keyboard panel and one status bar panel.

The input method panel does not support the creation of child windows. For example, you cannot set an app child window by using window.createWindow, or create child window dialogs by using bindContextMenu, CustomDialog, or other APIs. You are advised to use non-child-window alternatives, such as dialogs, bindMenu, or setting showInSubwindow to false.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
ctx BaseContext Yes Current context of the input method.
info PanelInfo Yes Information about the input method panel.

Return value

Type Description
Promise<Panel> Promise used to return the Panel object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800004 not an input method application.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine, InputMethodExtensionAbility } from '@kit.IMEKit';
import { Want } from '@kit.AbilityKit';

// Create the panel information. Set the panel type to soft keyboard and the state to fixed.
let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

class InputMethodExt extends InputMethodExtensionAbility {
    onCreate(want: Want): void {
        console.info(`onCreate, want: ${want.abilityName}`);
        if (this.context) {
            inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo)
                .then((panel: inputMethodEngine.Panel) => {
                console.info('Succeed in creating panel.');
            }).catch((err: BusinessError) => {
                console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
            })
        }
    }
}

[h2]destroyPanel10+

destroyPanel(panel: Panel, callback: AsyncCallback<void> ): void

Destroys an input method panel. This API is called after the panel is created via createPanel. This API uses an asynchronous callback to return the result.

Paired calls:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
panel Panel Yes Input method panel to destroy.
callback AsyncCallback<void> Yes Callback used to return the result. If the input method panel is destroyed successfully, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Create the panel information. Set the panel type to soft keyboard and the state to fixed.
let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

// Used in the InputMethodExtensionAbility class.
let inputPanel: inputMethodEngine.Panel | undefined = undefined;
inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
  if (err) {
    console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  inputPanel = panel;
  console.info('Succeed in creating panel.');
  // Destroy the instance after it is created successfully.
  if (inputPanel) {
    inputMethodEngine.getInputMethodAbility().destroyPanel(inputPanel, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to destroy panel. Code is ${err.code}, message is ${err.message}`);
        return;
      }
      console.info('Succeed in destroying panel.');
    });
  }
});

[h2]destroyPanel10+

destroyPanel(panel: Panel): Promise<void>

Destroys the input method panel. This API uses a promise to return the result.

Paired calls:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
panel Panel Yes Input method panel to destroy.

Return value

Type Description
Promise<void> Promise that returns no result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Create the panel information. Set the panel type to soft keyboard and the state to fixed.
let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

let inputPanel: inputMethodEngine.Panel | undefined = undefined;
// context is the context object provided by the InputMethodExtensionAbility class and does not need to be obtained separately.
if (this.context) {
  inputMethodEngine.getInputMethodAbility()
    .createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
      if (err) {
        console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
        return;
      }
      inputPanel = panel;
      console.info('Succeed in creating panel.');
    })
}

if (inputPanel) {
  inputMethodEngine.getInputMethodAbility().destroyPanel(inputPanel).then(() => {
    console.info('Succeed in destroying panel.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to destroy panel. Code is ${err.code}, message is ${err.message}`);
  });
}

KeyboardDelegate

Provides a delegate object for listening to keyboard events. It is used by the input method app to listen for physical keyboard key events and edit box text/cursor/selection change events. The input method app obtains this instance through getKeyboardDelegate. Core capabilities include:

Usage scenarios:

In the following API examples, you must first use getKeyboardDelegate to obtain a KeyboardDelegate instance, and then call the APIs using the obtained instance.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]on('keyDown'|'keyUp')

on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void

Enables listening for a keyup or keydown event from a physical keyboard. This API uses an asynchronous callback to return the result.

Usage scenarios: Implement shortcut functions, intercept special keys, and handle function keys (such as Backspace and Enter), among others.

Use effect: The callback is triggered when a physical key is pressed or released, returning key information. If the key event is consumed by the event subscriber, the callback returns true; otherwise, it returns false. When true is returned, the key event will no longer be delivered to the edit box. When false is returned, the key event continues to be delivered to the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyDown' indicates the keydown event.

- The value 'keyUp' indicates the keyup event.
callback (event: KeyEvent) => boolean Yes Callback used to return the key information. If the event is consumed by the event subscriber, true is returned. Otherwise, false is returned.

Example

inputMethodEngine.getKeyboardDelegate().on('keyUp', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info(`inputMethodEngine keyCode.(keyUp): ${keyEvent.keyCode}`);
  console.info(`inputMethodEngine keyAction.(keyUp): ${keyEvent.keyAction}`);
  return true;
});
inputMethodEngine.getKeyboardDelegate().on('keyDown', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info(`inputMethodEngine keyCode.(keyDown): ${keyEvent.keyCode}`);
  console.info(`inputMethodEngine keyAction.(keyDown): ${keyEvent.keyAction}`);
  return true;
});

[h2]off('keyDown'|'keyUp')

off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void

Disables listening for a keyup or keydown event from a physical keyboard.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes

Event type.

- The value 'keyDown' indicates the keydown event.

- The value 'keyUp' indicates the keyup event.
callback (event: KeyEvent) => boolean No Callback used to unsubscribe from specific key events. Passing this parameter cancels the subscription for the specified callback. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('keyUp', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info('delete keyUp notification.');
  return true;
});
inputMethodEngine.getKeyboardDelegate().off('keyDown', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info('delete keyDown notification.');
  return true;
});

[h2]on('keyEvent')10+

on(type: 'keyEvent', callback: (event: InputKeyEvent) => boolean): void

Subscribes to physical keyboard events. This API uses an asynchronous callback to return the result. Compared with on('keyDown'|'keyUp'), on('keyEvent') provides more comprehensive key event information, including modifier key states for Ctrl/Shift/Alt and unicodeChar information. It applies to scenarios requiring processing of key combinations or access to detailed key event data.

Usage scenarios: Require handling key combinations (such as Ctrl+C and Shift+Enter) or obtaining more comprehensive key information (such as unicodeChar and ctrlKey).

Use effect: When a physical key event is triggered, the callback is invoked. If the key event is consumed by the event subscriber, the callback returns true; otherwise, it returns false.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'keyEvent'.
callback (event: InputKeyEvent) => boolean Yes

Callback used to return the result. The input parameter is the key event information and the return value is of the Boolean type.

- Input parameter: InputKeyEvent.

- If the event is consumed by the event subscriber, true is returned. Otherwise, false is returned.

Example

import type { KeyEvent } from '@kit.InputKit';

inputMethodEngine.getKeyboardDelegate().on('keyEvent', (keyEvent: KeyEvent) => {
  console.info(`inputMethodEngine keyEvent.action:${ keyEvent.action}`);
  console.info(`inputMethodEngine keyEvent.key.code: ${keyEvent.key.code}`);
  console.info(`inputMethodEngine keyEvent.ctrlKey: ${keyEvent.ctrlKey}`);
  console.info(`inputMethodEngine keyEvent.unicodeChar: ${keyEvent.unicodeChar}`);
  return true;
});

[h2]off('keyEvent')10+

off(type: 'keyEvent', callback?: (event: InputKeyEvent) => boolean): void

Unsubscribes from physical keyboard events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'keyEvent'.
callback (event: InputKeyEvent) => boolean No Callback used to unsubscribe from specific keyboard events. Passing this parameter cancels the subscription for the specified callback. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

import type { KeyEvent } from '@kit.InputKit';

inputMethodEngine.getKeyboardDelegate().off('keyEvent', (keyEvent: KeyEvent) => {
  console.info('This is a callback function which will be deregistered.');
  return true;
});
inputMethodEngine.getKeyboardDelegate().off('keyEvent');

[h2]on('cursorContextChange')

on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void

Enables listening for the cursor change event. This API uses an asynchronous callback to return the result.

Usage scenarios: Update the candidate word display position in real time, adjust the input method UI based on the cursor position, and implement a floating menu that follows the cursor, among others.

Use effect: This callback is triggered when the cursor position in the edit box changes, returning the x coordinate, y coordinate, and height of the cursor. The input method app can adjust the positioning of the candidate word window or panel accordingly.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'cursorContextChange'.
callback (x: number, y: number, height: number) => void Yes

Callback used to return the cursor information.

- x: x coordinate of the top of the cursor, in px. y: y coordinate of the top of the cursor, in px. height: height of the cursor, in px.

Example

inputMethodEngine.getKeyboardDelegate().on('cursorContextChange', (x: number, y: number, height: number) => {
  console.info('inputMethodEngine cursorContextChange x:' + x);
  console.info('inputMethodEngine cursorContextChange y:' + y);
  console.info('inputMethodEngine cursorContextChange height:' + height);
});

[h2]off('cursorContextChange')

off(type: 'cursorContextChange', callback?: (x: number, y: number, height: number) => void): void

Unsubscribes from cursor change events.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'cursorContextChange'.
callback (x: number, y:number, height:number) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('cursorContextChange');

[h2]on('selectionChange')

on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void

Enables listening for the text selection change event. This API uses an asynchronous callback to return the result.

Usage scenarios: Listen for user text selection to provide quick actions such as cut, copy, and paste, display relevant suggestions based on selected text, implement text editing assistance features, and more.

Use effect: This callback is triggered when the text selection range in the edit field changes, returning the start and end indices of the selection range before and after the change.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'selectionChange'.
callback (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void Yes

Callback used to return the text selection information.

- oldBegin: start of the selected text before the change.

- oldEnd: end of the selected text before the change.

- newBegin: start of the selected text after the change.

- newEnd: end of the selected text after the change.

Example

inputMethodEngine.getKeyboardDelegate()
  .on('selectionChange', (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => {
    console.info('selectionChange oldBegin:' + oldBegin);
    console.info('selectionChange oldEnd:' + oldEnd);
    console.info('selectionChange newBegin:' + newBegin);
    console.info('selectionChange newEnd:' + newEnd);
  });

[h2]off('selectionChange')

off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void

Unsubscribes from text selection change events.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'selectionChange'.
callback (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate()
  .off('selectionChange', (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => {
    console.info('delete selectionChange notification.');
  });

[h2]on('textChange')

on(type: 'textChange', callback: (text: string) => void): void

Enables listening for the text change event. This API uses an asynchronous callback to return the result.

Usage scenarios: Update candidate words, provide intelligent input suggestions, and implement predictive input based on text changes, among others.

Use effect: This callback is triggered when the text content in the edit box changes, returning the complete text content of the current edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'textChange'.
callback (text: string) => void Yes Callback used to return the text content.

Example

inputMethodEngine.getKeyboardDelegate().on('textChange', (text: string) => {
  console.info('inputMethodEngine textChange. text:' + text);
});

[h2]off('textChange')

off(type: 'textChange', callback?: (text: string) => void): void

Disables listening for the text change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'textChange'.
callback (text: string) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('textChange', (text: string) => {
  console.info('delete textChange notification. text:' + text);
});

[h2]on('editorAttributeChanged')10+

on(type: 'editorAttributeChanged', callback: (attr: EditorAttribute) => void): void

Enables listening for the edit box attribute change event. This API uses an asynchronous callback to return the result.

Usage scenarios: The input method app needs to dynamically adjust the keyboard layout in response to edit box attribute changes (for example, when the input type switches from text to numeric, or the Enter key type switches from "Search" to "Send").

Use effect: This callback is triggered when the edit box attributes change, returning updated edit box attribute information (including inputPattern and enterKeyType). The input method app can adjust the keyboard layout accordingly.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Edit box attribute change event. The value is fixed at 'editorAttributeChanged'.
callback (attr: EditorAttribute) => void Yes Callback used to return the updated edit box attributes.

Example

inputMethodEngine.getKeyboardDelegate()
  .on('editorAttributeChanged', (editorAttribute: inputMethodEngine.EditorAttribute) => {
    console.info(`Succeeded in receiving attribute of editor, inputPattern = ${editorAttribute.inputPattern}, enterKeyType = ${editorAttribute.enterKeyType}`);
  });

[h2]off('editorAttributeChanged')10+

off(type: 'editorAttributeChanged', callback?: (attr: EditorAttribute) => void): void

Disables listening for the edit box attribute change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Edit box attribute change event. The value is fixed at 'editorAttributeChanged'.
callback (attr: EditorAttribute) => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type by default.

Example

inputMethodEngine.getKeyboardDelegate().off('editorAttributeChanged');

Panel10+

Represents the input method panel object, offering capabilities including panel page loading, showing/hiding, size adjustment, position movement, and mode switching. A Panel instance is obtained through the createPanel API of InputMethodAbility, and destroyed via a call to destroyPanel to release resources after use. createPanel and destroyPanel must be called in pairs.

Core capability overview:

Panel lifecycle:

  1. Create a Panel instance via createPanel of InputMethodAbility, specifying the panel type and flags.

  2. Call setUiContent to load keyboard page content.

  3. Call show to display the panel for user interaction.

  4. Call APIs such as resize, moveTo, and changeFlag to dynamically adjust the panel as required.

  5. Call destroyPanel to destroy the panel after using the instance and release resources.

In the following API examples, you must first use createPanel to obtain a Panel instance, and then call the APIs using the obtained instance.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]setUiContent10+

setUiContent(path: string, callback: AsyncCallback<void> ): void

Loads content from a page to this input method panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
path string Yes Path of the target page. It is recommended that the path length does not exceed 1,024 characters.
callback AsyncCallback<void> Yes Callback used to return the result. If the panel page content is loaded successfully, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the input method panel content.
// The panel object is obtained via the createPanel API. For details, see the createPanel example.
panel.setUiContent('pages/page2/page2', (err: BusinessError) => {
  if (err) {
    console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the content.');
});

[h2]setUiContent10+

setUiContent(path: string): Promise<void>

Loads content from a page to this input method panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
path string Yes Path of the target page. It is recommended that the path length does not exceed 1,024 characters.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.setUiContent('pages/page2/page2').then(() => {
  console.info('Succeeded in setting the content.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
});

[h2]setUiContent10+

setUiContent(path: string, storage: LocalStorage, callback: AsyncCallback<void> ): void

Loads content from a page associated with LocalStorage to this input method panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
path string Yes Path of the page associated with LocalStorage. It is recommended that the path length does not exceed 1,024 characters.
storage LocalStorage Yes Storage unit that stores mutable and immutable state properties within the app scope.
callback AsyncCallback<void> Yes Callback used to return the result. If the panel page content is loaded successfully, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Create and initialize the LocalStorage object.
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
panel.setUiContent('pages/page2/page2', storage, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the content.');
});

[h2]setUiContent10+

setUiContent(path: string, storage: LocalStorage): Promise<void>

Loads content from a page associated with LocalStorage to this panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
path string Yes Path of the target page. It is recommended that the path length does not exceed 1,024 characters.
storage LocalStorage Yes Storage unit that stores mutable and immutable state properties within the app scope.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Create and initialize the LocalStorage object.
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
panel.setUiContent('pages/page2/page2', storage).then(() => {
  console.info('Succeeded in setting the content.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
});

[h2]resize10+

resize(width: number, height: number, callback: AsyncCallback<void> ): void

Resizes this input method panel. This API uses an asynchronous callback to return the result.

The panel width cannot exceed the screen width, and the panel height cannot exceed 0.7 times the screen height.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
width number Yes Width of the target panel, in px. The value must be an integer greater than or equal to 0 and must not exceed the screen width. If the value is out of range, error code 401 is returned.
height number Yes Height of the target panel, in px. The value must be an integer greater than or equal to 0 and must not exceed 0.7 times the screen height. If the value is out of range, error code 401 is returned.
callback AsyncCallback<void> Yes Callback used to return the result. If the panel size is changed successfully, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Change the input method panel size.
panel.resize(500, 1000, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to resize panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in changing the panel size.');
});

[h2]resize10+

resize(width: number, height: number): Promise<void>

Resizes this input method panel. This API uses a promise to return the result.

The panel width cannot exceed the screen width, and the panel height cannot exceed 0.7 times the screen height.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
width number Yes Width of the target panel, in px. The value must be an integer greater than or equal to 0 and must not exceed the screen width. If the value is out of range, error code 401 is returned.
height number Yes Height of the target panel, in px. The value must be an integer greater than or equal to 0 and must not exceed 0.7 times the screen height. If the value is out of range, error code 401 is returned.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Change the input method panel size.
panel.resize(500, 1000).then(() => {
  console.info('Succeeded in changing the panel size.');
}).catch((err: BusinessError) => {
  console.error(`Failed to resize panel. Code is ${err.code}, message is ${err.message}`);
});

[h2]moveTo10+

moveTo(x: number, y: number, callback: AsyncCallback<void> ): void

Moves this input method panel to the specified position. This API uses an asynchronous callback to return the result. This API does not work on panels in the FLG_FIXED state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
x number Yes Distance to move along the horizontal axis, in px. This parameter must be an integer. A value greater than 0 indicates moving right; a value less than 0 indicates moving left. Error code 401 is returned if the value is outside the screen bounds.
y number Yes Distance to move along the vertical axis, in px. This parameter must be an integer. A value greater than 0 indicates moving down; a value less than 0 indicates moving up. Error code 401 is returned if the value is outside the screen bounds.
callback AsyncCallback<void> Yes Callback used to return the result. If the panel is moved successfully, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Move the input method panel position.
panel.moveTo(300, 300, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to move panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in moving the panel.');
});

[h2]moveTo10+

moveTo(x: number, y: number): Promise<void>

Moves this input method panel to the specified position. This API uses a promise to return the result. This API does not work on panels in the FLG_FIXED state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
x number Yes Distance to move along the horizontal axis, in px. A positive value indicates moving rightwards. The value must be an integer.
y number Yes Distance to move along the vertical axis, in px. A positive value indicates moving downwards. The value must be an integer.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Move the input method panel position.
panel.moveTo(300, 300).then(() => {
  console.info('Succeeded in moving the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to move panel. Code is ${err.code}, message is ${err.message}`);
});

[h2]startMoving15+

startMoving(): void

Sends a move command to the window to put the panel into a draggable state. It does not produce an actual movement effect; the panel moves only when the user drags it with the mouse.

System capability: SystemCapability.MiscServices.InputMethodFramework

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
801 capability not supported. Applicable version: 18+
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013 window manager service error.
12800017 invalid panel type or panel flag.

Example

panel.startMoving();

[h2]getDisplayId15+

getDisplayId(): Promise<number>

Obtains the display Id of the current window. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<number> Promise used to return the display Id of the window.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013 window manager service error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.getDisplayId().then((result: number) => {
  console.info('get displayId:' + result);
}).catch((err: BusinessError) => {
  console.error(`Failed to get displayId. Code is ${err.code}, message is ${err.message}`);
});

[h2]show10+

show(callback: AsyncCallback<void> ): void

Shows this input method panel. This API uses an asynchronous callback to return the result. It can be called when the input method is bound to the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the panel is displayed successfully, err is undefined; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.show((err: BusinessError) => {
  if (err) {
    console.error(`Failed to show panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in showing the panel.');
});

[h2]show10+

show(): Promise<void>

Shows this input method panel. This API uses a promise to return the result. It can be called when the input method is bound to the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise object that returns no result.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.show().then(() => {
  console.info('Succeeded in showing the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show panel. Code is ${err.code}, message is ${err.message}`);
});

[h2]hide10+

hide(callback: AsyncCallback<void> ): void

Hides this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the panel is hidden successfully, err is undefined; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.hide((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hide panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding the panel.');
});

[h2]hide10+

hide(): Promise<void>

Hides this panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise object that returns no result.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.hide().then(() => {
  console.info('Succeeded in hiding the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide panel. Code is ${err.code}, message is ${err.message}`);
});

[h2]adjustPanelRect12+

adjustPanelRect(flag: PanelFlag, rect: PanelRect): void

Adjusts the panel rectangle. After the API is called, the adjust request is submitted to the input method framework, but the execution is not complete.

This API applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state.

This is a synchronous API. A successful return only indicates that the system has received the configuration request, not that the configuration is complete. To detect exceptions during execution, use updatePanelRect or updatePanelRectSync.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect PanelRect Yes Target panel's x coordinate, y coordinate, width, and height in both landscape and portrait orientations. In fixed mode, the height cannot exceed 70% of the screen height, and the width cannot exceed the screen width. In floating mode, the height cannot exceed the screen height, and the width cannot exceed the screen width. Error code 401 is returned when the value is out of range.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013 window manager service error.

Example

import { window } from '@kit.ArkUI';

// Define the rectangular area of the panel in landscape mode.
let landscapeRect: window.Rect = {
  left: 100,
  top: 100,
  width: 400,
  height: 400
};

// Define the rectangular area of the panel in portrait mode.
let portraitRect: window.Rect = {
  left: 200,
  top: 200,
  width: 300,
  height: 300
};

// Set the panel state to fixed.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// Configure the rectangular areas of the panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.PanelRect = {
  landscapeRect: landscapeRect,
  portraitRect: portraitRect
};
// Preset the landscape and portrait dimensions of the input method app panel.
panel.adjustPanelRect(panelFlag, panelRect);

[h2]adjustPanelRect15+

adjustPanelRect(flag: PanelFlag, rect: EnhancedPanelRect): void

Presets the size, position, custom avoidance area, and hot zone of the input method app panel for landscape and portrait orientations.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state. This API is compatible with the calling method of adjustPanelRect. If the input parameter rect contains only the landscapeRect and portraitRect properties, adjustPanelRect is called by default.

This is a synchronous API. A successful return only indicates that the system has received the configuration request, not that the configuration is complete. To detect exceptions during execution, use updatePanelRect or updatePanelRectSync.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

When the com.ohos.sceneboard process does not exist, the effective range of the input method hot zone remains consistent with the soft keyboard area.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect EnhancedPanelRect Yes Position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013 window manager service error.
12800017 invalid panel type or panel flag.

Example:

import { window } from '@kit.ArkUI';

let landscapeRect1: window.Rect = {
  left: 300,
  top: 650,
  width: 2000,
  height: 500
};
let landscapeInputRegion: Array<window.Rect> = [landscapeRect1];

let portraitRect1: window.Rect = {
  left: 0,
  top: 1800,
  width: 1200,
  height: 800
}
let portraitInputRegion: Array<window.Rect> = [portraitRect1];
// Target panel state type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// The position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.EnhancedPanelRect = {
  landscapeAvoidY: 650,
  landscapeInputRegion: landscapeInputRegion,
  portraitAvoidY: 1800,
  portraitInputRegion: portraitInputRegion,
  fullScreenMode: true
};
panel.adjustPanelRect(panelFlag, panelRect);

[h2]updatePanelRect

updatePanelRect(flag: PanelFlag, rect: PanelRect): Promise<void>

Presets the landscape and portrait dimensions of the input method app. This API uses a promise to return the result.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state.

This is an asynchronous API. A successful return only indicates that the system has received the configuration request, not that the configuration is complete.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect PanelRect Yes Target panel's x coordinate, y coordinate, width, and height in both landscape and portrait orientations. In fixed mode, the height cannot exceed 70% of the screen height, and the width cannot exceed the screen width. In floating mode, the height cannot exceed the screen height, and the width cannot exceed the screen width. Error code 401 is returned when the value is out of range.

Return value

Type Description
Promise<void> Promise object that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
12800013 window manager service error.

Example

import { window } from '@kit.ArkUI';

let landscapeRect: window.Rect = {
  left: 100,
  top: 100,
  width: 400,
  height: 400
};

let portraitRect: window.Rect = {
  left: 200,
  top: 200,
  width: 300,
  height: 300
};

// Target panel state type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// The x coordinate, y coordinate, width, and height of the target panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.PanelRect = {
  landscapeRect: landscapeRect,
  portraitRect: portraitRect
};
panel.updatePanelRect(panelFlag, panelRect);

[h2]updatePanelRect

updatePanelRect(flag: PanelFlag, rect: EnhancedPanelRect): Promise<void>

Presets the size, position, custom avoidance area, and hot zone of the input method app panel for landscape and portrait orientations. This API uses a promise to return the result.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state. This API is compatible with the calling method of adjustPanelRect. If the input parameter rect contains only the landscapeRect and portraitRect properties, adjustPanelRect is called by default.

This is an asynchronous API. A successful return only indicates that the system has received the configuration request, not that the configuration is complete.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

When the com.ohos.sceneboard process does not exist, the effective range of the input method hot zone remains consistent with the soft keyboard area.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect EnhancedPanelRect Yes Position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
12800013 window manager service error.
12800017 invalid panel type or panel flag.

Example

import { window } from '@kit.ArkUI';

let landscapeRect1: window.Rect = {
  left: 300,
  top: 650,
  width: 2000,
  height: 500
};
let landscapeInputRegion: Array<window.Rect> = [landscapeRect1];

let portraitRect1: window.Rect = {
  left: 0,
  top: 1800,
  width: 1200,
  height: 800
}
let portraitInputRegion: Array<window.Rect> = [portraitRect1];
// Target panel state type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// The position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.EnhancedPanelRect = {
  landscapeAvoidY: 650,
  landscapeInputRegion: landscapeInputRegion,
  portraitAvoidY: 1800,
  portraitInputRegion: portraitInputRegion,
  fullScreenMode: true
};
panel.updatePanelRect(panelFlag, panelRect);

[h2]updatePanelRectSync

updatePanelRectSync(flag: PanelFlag, rect: PanelRect): void

Presets the landscape and portrait sizes of the input method app.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API updatePanelRect instead.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state.

This is a synchronous API. A successful return indicates that the system has received the configuration request and the configuration is complete.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect PanelRect Yes Target panel's x coordinate, y coordinate, width, and height in both landscape and portrait orientations. In fixed mode, the height cannot exceed 70% of the screen height, and the width cannot exceed the screen width. In floating mode, the height cannot exceed the screen height, and the width cannot exceed the screen width. Error code 401 is returned when the value is out of range.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
12800013 window manager service error.

Example

import { window } from '@kit.ArkUI';

let landscapeRect: window.Rect = {
  left: 100,
  top: 100,
  width: 400,
  height: 400
};

let portraitRect: window.Rect = {
  left: 200,
  top: 200,
  width: 300,
  height: 300
};

// Target panel state type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// The x coordinate, y coordinate, width, and height of the target panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.PanelRect = {
  landscapeRect: landscapeRect,
  portraitRect: portraitRect
};
panel.updatePanelRectSync(panelFlag, panelRect);

[h2]updatePanelRectSync

updatePanelRectSync(flag: PanelFlag, rect: EnhancedPanelRect): void

Presets the size, position, custom avoidance area, and hot zone of the input method app panel for landscape and portrait orientations.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API updatePanelRect instead.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state. This API is compatible with the calling method of adjustPanelRect. If the input parameter rect contains only the landscapeRect and portraitRect properties, adjustPanelRect is called by default.

This is a synchronous API. A successful return indicates that the system has received the configuration request and the configuration is complete.

On mobile devices, when PanelFlag is set to FLG_FLOATING and the panel width ranges from 0 to 288 vp, the function keys at the bottom of the panel are resized dynamically according to panel width. For optimal user experience, it is recommended that the panel width be no less than 90 vp.

When the com.ohos.sceneboard process does not exist, the effective range of the input method hot zone remains consistent with the soft keyboard area.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Target panel state type. The value can be FLG_FIXED or FLG_FLOATING.
rect EnhancedPanelRect Yes Position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
12800013 window manager service error.
12800017 invalid panel type or panel flag.

Example

import { window } from '@kit.ArkUI';

let landscapeRect1: window.Rect = {
  left: 300,
  top: 650,
  width: 2000,
  height: 500
};
let landscapeInputRegion: Array<window.Rect> = [landscapeRect1];

let portraitRect1: window.Rect = {
  left: 0,
  top: 1800,
  width: 1200,
  height: 800
}
let portraitInputRegion: Array<window.Rect> = [portraitRect1];
// Target panel state type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// The position, size, avoidance area, and hot zone of the target panel for landscape and portrait orientations.
let panelRect: inputMethodEngine.EnhancedPanelRect = {
  landscapeAvoidY: 650,
  landscapeInputRegion: landscapeInputRegion,
  portraitAvoidY: 1800,
  portraitInputRegion: portraitInputRegion,
  fullScreenMode: true
};
panel.updatePanelRectSync(panelFlag, panelRect);

[h2]updateRegion15+

updateRegion(inputRegion: Array<window.Rect>): void

Updates the hot zone on the input method panel in the current state.

This applies only to panels of the SOFT_KEYBOARD type with the FLG_FIXED or FLG_FLOATING state.

This is a synchronous API. A successful return only indicates that the system has received the request to update the hot zone, not that the hot zone update is complete.

When the com.ohos.sceneboard process does not exist, the effective range of the input method hot zone remains consistent with the soft keyboard area.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
inputRegion Array<window.Rect> Yes

Region for receiving input events.

- The array size is limited to [1, 4].

- The input hot zone is relative to the left vertex of the input method panel window.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013 window manager service error.
12800017 invalid panel type or panel flag.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

let inputRegion: Array<window.Rect> = [{
  left: 300,
  top: 650,
  width: 2000,
  height: 500
}];
panel.updateRegion(inputRegion);

[h2]on('show')10+

on(type: 'show', callback: () => void): void

Listens for the display state of the current panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'show'.
callback () => void Yes Callback used to return the result.

Example

panel.on('show', () => {
  console.info('Panel is showing.');
});

[h2]on('hide')10+

on(type: 'hide', callback: () => void): void

Enables listening for the hide event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'hide'.
callback () => void Yes Callback used to return the result.

Example

panel.on('hide', () => {
  console.info('Panel is hiding.');
});

[h2]on('sizeChange')12+

on(type: 'sizeChange', callback: SizeChangeCallback): void

Enables listening for the panel size change. This API uses an asynchronous callback to return the result.

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state. When the input method calls APIs like adjustPanelRect to adjust the panel size, the system calculates the final value based on certain rules (for example, whether the panel size exceeds the screen). This callback can be used to obtain the actual panel size to refresh the panel layout.

  • This API is supported from API version 12 to 14. The callback function of this API contains only mandatory parameters of the window.Size type.
  • Since API version 15, after the adjustPanelRect API is called, an optional parameter of the KeyboardArea type is added to the callback function of this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'sizeChange'.
callback SizeChangeCallback Yes Callback used to return the size of the soft keyboard panel, including the width and height.

Example

import { window } from '@kit.ArkUI';

// Listen for panel size change events.
panel.on('sizeChange', (windowSize: window.Size) => {
  console.info(`panel size changed, width: ${windowSize.width}, height: ${windowSize.height}`);
});

// Listen for panel size change events (with keyboard area parameters).
panel.on('sizeChange', (windowSize: window.Size, keyboardArea: inputMethodEngine.KeyboardArea) => {
  console.info(`panel size changed, windowSize: ${windowSize.width}, ${windowSize.height}, ` +
    `keyboardArea: ${keyboardArea.top}, ${keyboardArea.bottom}, ${keyboardArea.left}, ${keyboardArea.right}`);
});

[h2]off('show')10+

off(type: 'show', callback?: () => void): void

Disables listening for the show event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'show'.
callback () => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

panel.off('show');

[h2]off('hide')10+

off(type: 'hide', callback?: () => void): void

Disables listening for the hide event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'hide'.
callback () => void No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

panel.off('hide');

[h2]off('sizeChange')12+

off(type: 'sizeChange', callback?: SizeChangeCallback): void

Disables listening for the panel size change. This API uses an asynchronous callback to return the result.

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state. When you call adjustPanelRect to adjust the panel size, the system calculates the final value based on certain rules (for example, whether the panel size exceeds the screen). This callback can be used to obtain the actual panel size to refresh the panel layout.

  • This API is supported from API version 12 to 14. The callback function of this API contains only mandatory parameters of the window.Size type.
  • Since API version 15, after the adjustPanelRect API is called, an optional parameter of the KeyboardArea type is added to the callback function of this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'sizeChange'.
callback SizeChangeCallback No Callback used to return the current soft keyboard panel size, including the width and height. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

import { window } from '@kit.ArkUI';

panel.off('sizeChange', (windowSize: window.Size) => {
  console.info(`panel size changed, width: ${windowSize.width}, height: ${windowSize.height}`);
});

[h2]changeFlag10+

changeFlag(flag: PanelFlag): void

Changes the state type (PanelFlag) of this input method panel. This API only works for SOFT_KEYBOARD panels.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
flag PanelFlag Yes Type of the state of the target panel.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
panel.changeFlag(panelFlag);

[h2]setPrivacyMode11+

setPrivacyMode(isPrivacyMode: boolean): void

Sets the input method panel to privacy mode. In privacy mode, screenshot and screen recording are blocked.

Required permissions: ohos.permission.PRIVACY_WINDOW

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
isPrivacyMode boolean Yes

Whether to set the input method panel to privacy mode.

- true: privacy mode.

- false: non-privacy mode.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
201 permissions check fails.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

let isPrivacyMode: boolean = true;
panel.setPrivacyMode(isPrivacyMode);

[h2]setImmersiveMode15+

setImmersiveMode(mode: ImmersiveMode): void

Sets the immersive mode of the input method app. The mode can only be set to NONE_IMMERSIVE, LIGHT_IMMERSIVE, or DARK_IMMERSIVE.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
mode ImmersiveMode Yes Immersive mode.

Error codes

For details about the error codes, see Universal Error Codes and Input Method Framework Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013 window manager service error.

Example

panel.setImmersiveMode(inputMethodEngine.ImmersiveMode.LIGHT_IMMERSIVE);

[h2]getImmersiveMode15+

getImmersiveMode(): ImmersiveMode

Obtains the immersive mode of the input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
ImmersiveMode Immersive mode.

Example

let mode: inputMethodEngine.ImmersiveMode = panel.getImmersiveMode();

[h2]setImmersiveEffect20+

setImmersiveEffect(effect: ImmersiveEffect): void

Sets the immersive effect of the input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Device behavior difference: This API can be called normally only on phone and tablet devices. On other devices, error code 801 is returned.

Parameters

Name Type Mandatory Description
effect ImmersiveEffect Yes Immersive effect.

Error codes

For details about the error codes, see Universal Error Codes and Input Method Framework Error Codes.

ID Error Message
801 capability not supported.
12800002 input method engine error. Possible causes:1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013 window manager service error.
12800020 invalid immersive effect. 1.The gradient mode and the fluid light mode can only be used when the immersive mode is enabled. 2.The fluid light mode can only be used when the gradient mode is enabled. 3.When the gradient mode is not enabled, the gradient height can only be 0.
12800021 this operation is allowed only after adjustPanelRect or resize is called.

Example

let effect: inputMethodEngine.ImmersiveEffect = {
  gradientHeight: 100,
  gradientMode: inputMethodEngine.GradientMode.LINEAR_GRADIENT
}
panel.setImmersiveEffect(effect);

[h2]setKeepScreenOn20+

setKeepScreenOn(isKeepScreenOn: boolean): Promise<void>

Sets to keep the screen always on. This API uses a promise to return the result.

  • When the keyboard is displayed, the screen stays on. When the keyboard is hidden, the screen turns off.
  • You need to use this API properly. Set the attribute to true in necessary scenarios (for example, voice input) and reset this attribute to false after exiting necessary scenarios. In other scenarios, do not use this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
isKeepScreenOn boolean Yes Whether to keep the screen always on. The value true means that the screen is always on; the value false means the opposite.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800013 window manager service error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

panel.setKeepScreenOn(true).then(() => {
  console.info(`setKeepScreenOn success.`);
}).catch((error: BusinessError) => {
  console.error(`setKeepScreenOn failed, code: ${error.code}, message: ${error.message}`);
})

[h2]getSystemPanelCurrentInsets21+

getSystemPanelCurrentInsets(displayId: number): Promise<SystemPanelInsets>

Obtains the offset area of the soft keyboard relative to the system panel under the current state of the specified screen (for example, folded or unfolded) and the current state of the input method keyboard (for example, floating or fixed). This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
displayId number Yes Display ID of the screen where the input method keyboard is located. It can be obtained by calling getDisplayId.

Return value

Type Description
Promise<SystemPanelInsets> Promise used to return the result. The offset area between the input method keyboard and the system panel.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800013 window manager service error.
12800017 invalid panel type or panel flag. Possible causes: 1. Current panel's type is not SOFT_KEYBOARD. 2. Panel's flag is not FLG_FIXED or FLG_FLOATING.
12800022 invalid displayId.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine } from '@kit.IMEKit';

let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();
let panelConfig: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}
// The following logic needs to be executed in InputMethodExtensionAbility. this.context is the context of InputMethodExtensionAbility.
// Create the input method panel.
inputMethodAbility.createPanel(this.context, panelConfig).then((panel: inputMethodEngine.Panel) => {
  panel.getDisplayId().then((displayId: number) => {
    panel.getSystemPanelCurrentInsets(displayId).then((insets: inputMethodEngine.SystemPanelInsets) => {
      console.info(`getSystemPanelCurrentInsets success, insets is { left: ${insets.left}, right: ${insets.right}, bottom: ${insets.bottom} }`);
    }).catch((error: BusinessError) => {
      console.error(`getSystemPanelCurrentInsets failed, code: ${error.code}, message: ${error.message}`);
    });
  }).catch((error: BusinessError) => {
    console.error(`getDisplayId failed, code: ${error.code}, message: ${error.message}`);
  });
}).catch((error: BusinessError) => {
  console.error(`createPanel failed, code: ${error.code}, message: ${error.message}`);
});

[h2]setSystemPanelButtonColor22+

setSystemPanelButtonColor(fillColor: string | undefined, backgroundColor: string | undefined): Promise<void>

Sets the color of the function buttons and their background color on the current panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
fillColor string|undefined Yes Color of the function buttons. The value can be [#01000000, #FFFFFFFF] or [#000000, #FFFFFF]. The value of the fully transparent alpha channel (#00xxxxxx) is not supported.
backgroundColor string|undefined Yes Background color of the function buttons. The value can be [#01000000, #FFFFFFFF] or [#000000, #FFFFFF]. The value of the fully transparent alpha channel (#00xxxxxx) is not supported.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Ensure that a panel instance exists. You can use inputMethodEngine.getInputMethodAbility().createPanel(...) to create a panel instance.
try {
  let fillColor = "#FFFF00";
  let backgroundColor = "#0000FF";
  panel.setSystemPanelButtonColor(fillColor, backgroundColor).then(() => {
    console.info(`setSystemPanelButtonColor success.`);
  }).catch((error: BusinessError) => {
    console.error(`setSystemPanelButtonColor failed, code: ${error.code}, message: ${error.message}`);
  })
} catch (err) {
  let error = err as BusinessError;
  console.error(`setSystemPanelButtonColor failed, code: ${error.code}, message: ${error.message}`);
}

KeyboardController

You must first use on('inputStart') to obtain a KeyboardController instance, and then use this instance to call the following APIs.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]hide9+

hide(callback: AsyncCallback<void>): void

Hides the keyboard. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.hide((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hide. Code:${err.code}, message:${err.message}`);
    return;
  }
  console.info('Succeeded in hiding keyboard.');
});

[h2]hide9+

hide(): Promise<void>

Hides the keyboard. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.hide().then(() => {
  console.info('Succeeded in hiding keyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide. Code:${err.code}, message:${err.message}`);
});

[h2]hideKeyboard(deprecated)

hideKeyboard(callback: AsyncCallback<void>): void

Hides the keyboard. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.KeyboardController.hide instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.hideKeyboard((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hideKeyboard. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding keyboard.');
});

[h2]hideKeyboard(deprecated)

hideKeyboard(): Promise<void>

Hides the keyboard. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.KeyboardController.hide instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.hideKeyboard().then(() => {
  console.info('Succeeded in hiding keyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hideKeyboard. Code is ${err.code}, message is ${err.message}`);
});

[h2]exitCurrentInputType11+

exitCurrentInputType(callback: AsyncCallback<void>): void

Exits this input type. This API can be called only by the preconfigured default input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800010 not the preconfigured default input method.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.exitCurrentInputType((err: BusinessError) => {
  if (err) {
    console.error(`Failed to exit current input type. Code:${err.code}, message:${err.message}`);
    return;
  }
  console.info('Succeeded in exiting current input type.');
});

[h2]exitCurrentInputType11+

exitCurrentInputType(): Promise<void>

Exits this input type. This API can be called only by the preconfigured default input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800010 not the preconfigured default input method.

Example

import { BusinessError } from '@kit.BasicServicesKit';

keyboardController.exitCurrentInputType().then(() => {
  console.info('Succeeded in exiting current input type.');
}).catch((err: BusinessError) => {
  console.error(`Failed to exit current input type. Code:${err.code}, message:${err.message}`);
});

SecurityMode11+

Describes the security mode.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
BASIC 0 Basic access mode, where network access is restricted.
FULL 1 Full access mode, where network access is not restricted.

ExtendAction10+

Describes the type of the extended edit action on the text box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
SELECT_ALL 0 Select all.
CUT 3 Cut.
COPY 4 Copy.
PASTE 5 Paste.

Direction10+

Enumerates the directions of cursor movement of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
CURSOR_UP 1 Upward.
CURSOR_DOWN 2 Downward.
CURSOR_LEFT 3 Leftward.
CURSOR_RIGHT 4 Rightward.

Range10+

Describes the range of the selected text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
start number No No Index of the first selected character in the text box.
end number No No Index of the last selected character in the text box.

Movement10+

Describes the direction in which the cursor moves when the text is selected.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
direction Direction No No Direction in which the cursor moves when the text is selected.

MessageHandler15+

Represents a custom communication object.

You can register this object to receive custom communication data sent by the edit box application attached to the input method application. When the custom communication data is received, the onMessage callback in this object is triggered.

This object is globally unique. After multiple registrations, only the last registered object is valid and retained, and the onTerminated callback of the penultimate registered object is triggered.

If this object is unregistered, its onTerminated callback will be triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]onMessage15+

onMessage(msgId: string, msgParam?: ArrayBuffer): void

Callback triggered for receiving custom data sent by the edit box application attached to the current input method application.

This callback is triggered when the registered MessageHandler receives custom communication data sent by the edit box application attached to the input method application.

The msgId parameter is mandatory, and the msgParam parameter is optional. If only the custom msgId data is received, confirm it with the data sender.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
msgId string Yes Identifier of the received custom communication data.
msgParam ArrayBuffer No Message body of the received custom communication data.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (keyboardController: inputMethodEngine.KeyboardController, inputClient: inputMethodEngine.InputClient) => {
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info(`recv message, msgId is ${msgId}, msgParam is ${JSON.stringify(msgParam)}`);
        }
      }
      inputClient.recvMessage(messageHandler);
    });

[h2]onTerminated15+

onTerminated(): void

Callback triggered for MessageHandler termination.

When an app registers a new MessageHandler object, the onTerminated callback of the penultimate registered MessageHandler object is triggered.

When an app unregisters a MessageHandler object, the onTerminated callback of the registered MessageHandler object is triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (keyboardController: inputMethodEngine.KeyboardController, inputClient: inputMethodEngine.InputClient) => {
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info(`recv message, msgId is ${msgId}, msgParam is ${JSON.stringify(msgParam)}`);
        }
      }
      inputClient.recvMessage(messageHandler);
    });

InputClient9+

Represents the input method client object for the edit box client attached to the input method app. An InputClient instance is obtained through the on('inputStart') event callback of InputMethodAbility. Each attachment event corresponds to one InputClient instance which the input method app uses to interact with the edit box for text operations.

Core capability overview:

NOTE

You must first use on('inputStart') to obtain an InputClient instance, and then use this instance to call the following APIs.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]sendKeyFunction9+

sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void

Sends the function key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action number Yes

Action of the function key.

- 0: invalid key.

- 1: confirm key (Enter key).
callback AsyncCallback<boolean> Yes Callback used to return the result. If the function key is sent successfully, err is undefined and data is true; if the function key fails to be sent, err is undefined and data is false; otherwise, an error object is returned.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let action: number = 1;

inputClient.sendKeyFunction(action, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
});

[h2]sendKeyFunction9+

sendKeyFunction(action: number): Promise<boolean>

Sends the function key. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action number Yes

Action of the function key.

0: invalid key.

1: confirm key (Enter key).

Return value

Type Description
Promise<boolean> Promise object. If the promise is resolved with true, the function key is sent successfully. If the promise is resolved with false, sending the function key fails. If the promise is rejected, an error object is thrown, indicating an error occurred during execution.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let action: number = 1;
inputClient.sendKeyFunction(action).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
});

[h2]getForward9+

getForward(length:number, callback: AsyncCallback<string>): void

Obtains the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Analyze the entered text to provide intelligent completion suggestions, check the text format, implement text prediction, and perform text semantic analysis, among others.

Use effect: When the operation is successful, the fixed-length text before the cursor is returned, based on which the input method app can update candidate words or input suggestions.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.getForward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting forward, text: ' + text);
});

[h2]getForward9+

getForward(length:number): Promise<string>

Obtains the specific-length text before the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<string> Promise used to return the specific-length text before the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.getForward(length).then((text: string) => {
  console.info('Succeeded in getting forward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
});

[h2]getForwardSync10+

getForwardSync(length:number): string

Obtains the fixed-length text before the cursor.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API getForward.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
string Specific-length text before the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

let length: number = 1;
let text: string = inputClient.getForwardSync(length);
console.info(`Succeeded in getting forward, text: ${text}`);

[h2]getBackward9+

getBackward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.getBackward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting backward, text: ' + text);
});

[h2]getBackward9+

getBackward(length:number): Promise<string>

Obtains the specific-length text after the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<string> Promise used to return the specific-length text after the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.getBackward(length).then((text: string) => {
  console.info('Succeeded in getting backward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
});

[h2]getBackwardSync10+

getBackwardSync(length:number): string

Obtains the fixed-length text after the cursor.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API getBackward.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
string Specific-length text after the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

let length: number = 1;
let text: string = inputClient.getBackwardSync(length);
console.info(`Succeeded in getting backward, text: ${text}`);

[h2]deleteForward9+

deleteForward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Implement the Backspace key function, delete input character by character, delete incorrect input, and implement custom deletion logic, among others.

Use effect: When the operation is successful, the fixed-length text before the cursor in the edit box is deleted.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
callback AsyncCallback<boolean> Yes Callback used to return the result. If the fixed-length text before the cursor is deleted successfully, err is undefined and data is true; if the deletion fails, err is undefined and data is false; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.deleteForward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error(`Failed to deleteForward.`);
  }
});

[h2]deleteForward9+

deleteForward(length:number): Promise<boolean>

Deletes the fixed-length text before the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<boolean> Promise used to return the result. If the promise is resolved with true, the fixed-length text before the cursor is deleted successfully. If the promise is resolved with false, the deletion fails. If the promise is rejected, an error object is thrown, indicating an error occurred during execution.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.deleteForward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to delete Forward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
});

[h2]deleteForwardSync10+

deleteForwardSync(length:number): void

Deletes the fixed-length text before the cursor.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API deleteForward.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let length: number = 1;
inputClient.deleteForwardSync(length);

[h2]deleteBackward9+

deleteBackward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Implement the Delete key function, delete characters after the cursor, quickly correct input, and implement custom deletion logic, among others.

Use effect: When the operation is successful, the fixed-length text after the cursor is deleted.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.deleteBackward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error(`Failed to deleteBackward.`);
  }
});

[h2]deleteBackward9+

deleteBackward(length:number): Promise<boolean>

Deletes the fixed-length text after the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<boolean> Promise used to return the result. If the promise is resolved with true, the fixed-length text after the cursor is deleted successfully. If the promise is resolved with false, the deletion fails. If the promise is rejected, an error object is thrown, indicating an error occurred during execution.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
inputClient.deleteBackward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
});

[h2]deleteBackwardSync10+

deleteBackwardSync(length:number): void

Deletes the fixed-length text after the cursor.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API deleteBackward.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let length: number = 1;
inputClient.deleteBackwardSync(length);

[h2]insertText9+

insertText(text:string, callback: AsyncCallback<boolean>): void

Inserts text. This API uses an asynchronous callback to return the result.

Usage scenarios: Insert candidate words, insert special symbols, implement text auto-completion, and quickly insert common phrases, among others.

Use effect: When the operation is successful, the text is inserted at the cursor position in the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Text to insert.
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.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';


inputClient.insertText('test', (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
});

[h2]insertText9+

insertText(text:string): Promise<boolean>

Inserts text. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Text to insert.

Return value

Type Description
Promise<boolean> Promise used to return the result. If the promise is resolved with true, the text is inserted successfully. If the promise is resolved with false, the insertion fails. If the promise is rejected, an error object is thrown, indicating an error occurred during execution.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.insertText('test').then((result: boolean) => {
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
});

[h2]insertTextSync10+

insertTextSync(text: string): void

Inserts text.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API insertText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Text to insert.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002 input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

inputClient.insertTextSync('test');

[h2]getEditorAttribute9+

getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void

Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result.

Usage scenarios: Adjust the input method UI based on the edit box type, provide different input suggestions based on the edit box configuration, implement specific input logic, and adapt to different types of input boxes, among others.

Use effect: The edit box attribute information (including inputPattern and enterKeyType) is returned, based on which the input method app adjusts the keyboard layout.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<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.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.getEditorAttribute((err: BusinessError, editorAttribute: inputMethodEngine.EditorAttribute) => {
  if (err) {
    console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);
});

[h2]getEditorAttribute9+

getEditorAttribute(): Promise<EditorAttribute>

Obtains the attribute of the edit box. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<EditorAttribute> Promise used to return the attribute of the edit box.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.getEditorAttribute().then((editorAttribute: inputMethodEngine.EditorAttribute) => {
  console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
});

[h2]getEditorAttributeSync10+

getEditorAttributeSync(): EditorAttribute

Obtains edit box attribute information.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API getEditorAttribute instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
EditorAttribute Edit box attribute information.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let editorAttribute: inputMethodEngine.EditorAttribute = inputClient.getEditorAttributeSync();
console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);

[h2]moveCursor9+

moveCursor(direction: number, callback: AsyncCallback<void>): void

Moves the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Move the cursor to a specific position, move the cursor up, down, left, or right, quickly locate the cursor, implement custom cursor control, and more.

Use effect: When the operation is successful, the cursor in the edit box moves one step in the specified direction. For the value of direction, see Constants, where 1 means up, 2 means down, 3 means left, and 4 means right.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
direction number Yes

Direction in which the cursor moves.

- 1: upward.

- 2: downward.

- 3: leftward.

- 4: rightward.

The value cannot be less than 0.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.moveCursor(inputMethodEngine.Direction.CURSOR_UP, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to moveCursor. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in moving cursor.');
});

[h2]moveCursor9+

moveCursor(direction: number): Promise<void>

Moves the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
direction number Yes

Direction in which the cursor moves.

- 1: upward.

- 2: downward.

- 3: leftward.

- 4: rightward.

The value cannot be less than 0.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.moveCursor(inputMethodEngine.Direction.CURSOR_UP).then(() => {
  console.info('Succeeded in moving cursor.');
}).catch((err: BusinessError) => {
  console.error(`Failed to moveCursor. Code is ${err.code}, message is ${err.message}`);
});

[h2]moveCursorSync10+

moveCursorSync(direction: number): void

Moves the cursor.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API moveCursor instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
direction number Yes

Direction in which the cursor moves.

- 1: upward.

- 2: downward.

- 3: leftward.

- 4: rightward.

The value cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

inputClient.moveCursorSync(inputMethodEngine.Direction.CURSOR_UP);

[h2]selectByRange10+

selectByRange(range: Range, callback: AsyncCallback<void>): void

Selects text based on the specified range. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
range Range Yes Range of the selected text.
callback AsyncCallback<void> Yes Callback used to return the result. If the selection event is sent, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the replacement range of the preview text to the first character.
// Set the start and end positions of the selected text.
let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRange(range, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to selectByRange. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in selecting by range.');
});

[h2]selectByRange10+

selectByRange(range: Range): Promise<void>

Selects text based on the specified range. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
range Range Yes Range of the selected text.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the replacement range of the preview text to the first character.
// Set the start and end positions of the selected text.
let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRange(range).then(() => {
  console.info('Succeeded in selecting by range.');
}).catch((err: BusinessError) => {
  console.error(`Failed to selectByRange. Code is ${err.code}, message is ${err.message}`);
});

[h2]selectByRangeSync10+

selectByRangeSync(range: Range): void

Selects text based on the index range.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API selectByRange instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
range Range Yes Range of the selected text.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

// Set the replacement range of the preview text to the first character.
// Set the start and end positions of the selected text.
let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRangeSync(range);

[h2]selectByMovement10+

selectByMovement(movement: Movement, callback: AsyncCallback<void>): void

Selects text based on the cursor movement direction. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
movement Movement Yes Direction in which the cursor moves when the text is selected.
callback AsyncCallback<void> Yes Callback used to return the result. If the selection event is sent, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the cursor to move upward upon text selection.
let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovement(movement, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to selectByMovement. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in selecting by movement.');
});

[h2]selectByMovement10+

selectByMovement(movement: Movement): Promise<void>

Selects text based on the cursor movement direction. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
movement Movement Yes Direction in which the cursor moves when the text is selected.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the cursor to move upward upon text selection.
let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovement(movement).then(() => {
  console.info('Succeeded in selecting by movement.');
}).catch((err: BusinessError) => {
  console.error(`Failed to selectByMovement. Code is ${err.code}, message is ${err.message}`);
});

[h2]selectByMovementSync10+

selectByMovementSync(movement: Movement): void

Selects text based on the cursor movement direction.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API selectByMovement instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
movement Movement Yes Direction in which the cursor moves when the text is selected.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

//  Set the cursor to move upward upon text selection.
let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovementSync(movement);

[h2]getTextIndexAtCursor10+

getTextIndexAtCursor(callback: AsyncCallback<number>): void

Obtains the index of the text where the cursor is located. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<number> Yes Callback used to return the result. If the text index is obtained successfully, err is undefined and index is the text index at the cursor position. Otherwise, err is an error object and index is undefined.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.getTextIndexAtCursor((err: BusinessError, index: number) => {
  if (err) {
    console.error(`Failed to getTextIndexAtCursor. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getTextIndexAtCursor: ' + index);
});

[h2]getTextIndexAtCursor10+

getTextIndexAtCursor(): Promise<number>

Obtains the index of the text where the cursor is located. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<number> Promise used to return the index of the text where the cursor is located.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.getTextIndexAtCursor().then((index: number) => {
  console.info('Succeeded in getTextIndexAtCursor: ' + index);
}).catch((err: BusinessError) => {
  console.error(`Failed to getTextIndexAtCursor. Code is ${err.code}, message is ${err.message}`);
});

[h2]getTextIndexAtCursorSync10+

getTextIndexAtCursorSync(): number

Obtains the text index at the cursor position.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API getTextIndexAtCursor instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
number Index of the text where the cursor is located.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

let index: number = inputClient.getTextIndexAtCursorSync();
console.info(`Succeeded in getTextIndexAtCursorSync, index: ${index}`);

[h2]sendExtendAction10+

sendExtendAction(action: ExtendAction, callback: AsyncCallback<void>): void

Sends an extended edit action. This API uses an asynchronous callback to return the result.

Usage scenarios: An input method app needs to trigger extended editing features of the edit box. Examples include sending the cut action when the user taps the cut button on the keyboard, sending the copy action for the copy button, sending the paste action for the paste button, sending the select‑all action for the select‑all button, and integrating editing shortcuts within a custom toolbar.

The input method applications call this API to send extended edit actions to the edit box. The edit box listens for the corresponding event using on('handleExtendAction') for further processing.

When the edit box responds to the PASTE command of ExtendAction, the edit box application needs to apply for the ohos.permission.READ_PASTEBOARD permission.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action ExtendAction Yes Extended edit action to send.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.sendExtendAction(inputMethodEngine.ExtendAction.COPY, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to sendExtendAction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in sending extend action.');
});

[h2]sendExtendAction10+

sendExtendAction(action: ExtendAction): Promise<void>

Sends an extended edit action. This API uses a promise to return the result.

The input method applications call this API to send extended edit actions to the edit box. The edit box listens for the corresponding event using on('handleExtendAction') for further processing.

When the edit box responds to the PASTE command of ExtendAction, the edit box application needs to apply for the ohos.permission.READ_PASTEBOARD permission.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action ExtendAction Yes Extended edit action to send.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.sendExtendAction(inputMethodEngine.ExtendAction.COPY).then(() => {
  console.info('Succeeded in sending extend action.');
}).catch((err: BusinessError) => {
  console.error(`Failed to sendExtendAction. Code is ${err.code}, message is ${err.message}`);
});

[h2]sendPrivateCommand12+

sendPrivateCommand(commandData: Record<string, CommandDataType>): Promise<void>

Sends private data to the system component that needs to communicate with the input method application. This API uses a promise to return the result.

  • The private data channel allows communication between the system preset input method application and specific system components (such as a text box or a home screen application). Device vendors typically leverage this channel to implement custom input method features for a given device.
  • The total size of the private data is 32 KB, and the maximum number of private data records is 5.
  • Private data is sent to the text box by default. To send it to a home screen application, add a data entry {'sys_cmd':1} to the private data.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
commandData Record<string, CommandDataType> Yes Private data to send.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800010 not the preconfigured default input method.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, textInputClient) => {
  let record: Record<string, inputMethodEngine.CommandDataType> = {
    "valueString1": "abcdefg",
    "valueString2": true,
    "valueString3": 500
  }
textInputClient.sendPrivateCommand(record).then(() => {
  // do something
}).catch((err: BusinessError) => {
    if (err) {
      console.error(`sendPrivateCommand catch error: ${err.code}, message: ${err.message}`);
    }
  });
})

[h2]getCallingWindowInfo12+

getCallingWindowInfo(): Promise<WindowInfo>

Obtains information about the application window, in which the input box that starts an input method is located. This API uses a promise to return the result.

This API applies only to the input method applications that use Panel as the soft keyboard window.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<WindowInfo> Promise used to return the information obtained.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800012 the input method panel does not exist.
12800013 window manager service error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.getCallingWindowInfo().then((windowInfo: inputMethodEngine.WindowInfo) => {
  console.info(`windowInfo.rect: ${windowInfo.rect.left}, ${windowInfo.rect.top}, ${windowInfo.rect.width}, ${windowInfo.rect.height}`);
  console.info(`windowInfo.status: ${windowInfo.status}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getCallingWindowInfo. Code is ${err.code}, message is ${err.message}`);
});

[h2]setPreviewText12+

setPreviewText(text: string, range: Range): Promise<void>

Sets the preview text. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Preview text.
range Range Yes

Range of the text to be replaced.

- When the value is { start: -1, end: -1 }, the input text replaces all content in the current preview region by default.

- When start equals end, the input text is inserted at the cursor position corresponding to start.

- When start does not equal end, the input text replaces text within the specified range.

- For other combinations containing negative start or end values, the API returns a parameter error.

- When the edit box already contains preview text, range must not exceed the bounds of the preview text region; otherwise, a parameter error is returned.

- When the edit box has no preview text, range must not exceed the bounds of text within the edit box; otherwise, a parameter error is returned.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011 text preview not supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Set the replacement range of the preview text to the first character.
// Set the start and end positions of the selected text.
let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.setPreviewText('test', range).then(() => {
  console.info('Succeeded in setting preview text.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setPreviewText. Code is ${err.code}, message is ${err.message}`);
});

[h2]setPreviewTextSync12+

setPreviewTextSync(text: string, range: Range): void

Sets the preview text.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API setPreviewText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Preview text.
range Range Yes

Range of the text to be replaced.

- When the value is { start: -1, end: -1 }, the input text replaces all content in the current preview region by default.

- When start equals end, the input text is inserted at the cursor position corresponding to start.

- When start does not equal end, the input text replaces text within the specified range.

- For other combinations containing negative start or end values, the API returns a parameter error.

- When the edit box already contains preview text, range must not exceed the bounds of the preview text region; otherwise, a parameter error is returned.

- When the edit box has no preview text, range must not exceed the bounds of text within the edit box; otherwise, a parameter error is returned.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011 text preview not supported.

Example

// Set the replacement range of the preview text to the first character.
// Set the start and end positions of the selected text.
let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.setPreviewTextSync('test', range);

[h2]finishTextPreview12+

finishTextPreview(): Promise<void>

Finishes the text preview. This API uses a promise to return the result.

If there is preview text in the current text box, calling this API will display the preview text on the screen.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011 text preview not supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

inputClient.finishTextPreview().then(() => {
  console.info('Succeeded in finishing text preview.');
}).catch((err: BusinessError) => {
  console.error(`Failed to finishTextPreview. Code is ${err.code}, message is ${err.message}`);
});

[h2]finishTextPreviewSync12+

finishTextPreviewSync(): void

Ends the text preview.

This synchronous API may block the main thread and affect UI interaction. Use it with caution. It is recommended that you use the corresponding asynchronous API finishTextPreview instead.

If the current input box already contains preview text, calling this API commits the preview content to the screen.

System capability: SystemCapability.MiscServices.InputMethodFramework

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID Error Message
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011 text preview not supported.

Example

inputClient.finishTextPreviewSync();

[h2]sendMessage15+

sendMessage(msgId: string, msgParam?: ArrayBuffer): Promise<void>

Sends the custom communication to the edit box application attached to the input method application. This API uses a promise to return the result.

This API can be called only when the edit box is attached to the input method and enters the edit mode, and the input method application is in full experience mode.

The maximum length of msgId is 256 B, and the maximum length of msgParam is 128 KB.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
msgId string Yes Identifier of the custom data to be sent to the edit box app attached to the input method app. The maximum length is 256 bytes. If the length exceeds the limit, error code 401 is returned.
msgParam ArrayBuffer No Message body of the custom data to be sent to the edit box app attached to the input method app. The maximum size is 128 KB. If the size exceeds the limit, error code 401 is returned.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Incorrect parameter types. 2. Incorrect parameter length.
12800003 input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800009 input method client detached.
12800014 the input method is in basic mode.
12800015 the other side does not accept the request.
12800016 input method client is not editable.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let msgId: string = "testMsgId";
let msgParam: ArrayBuffer = new ArrayBuffer(128);
inputClient.sendMessage(msgId, msgParam).then(() => {
  console.info('Succeeded send message.');
}).catch((err: BusinessError) => {
  console.error(`Failed to send message. Code is ${err.code}, message is ${err.message}`);
});

[h2]recvMessage15+

recvMessage(msgHandler?: MessageHandler): void;

Registers or unregisters a MessageHandler.

The MessageHandler object is globally unique. After multiple registrations, only the last registered object is valid and retained, and the onTerminated callback of the penultimate registered object is triggered.

If no parameter is set, the globally registered MessageHandler object is unregistered. Its onTerminated callback will be triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
msgHandler MessageHandler No

This object receives custom communication data from the edit box application attached to the input method application through onMessage and receives a message for terminating the subscription to this object through onTerminated.

If no parameter is set, the globally registered MessageHandler object is unregistered. Its onTerminated callback will be triggered.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Incorrect parameter types.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, client: inputMethodEngine.InputClient) => {
      // Create a message handler to receive custom communication data sent by the edit box app.
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info('recv message.');
        }
      }
      // Register the message handler.
      client.recvMessage(messageHandler);
    });

[h2]getAttachOptions19+

getAttachOptions(): AttachOptions

Obtains the additional options for binding an input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
AttachOptions Additional options for binding an input method.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
801

Capability not supported.

Applicable versions: 19-19

Error code 801 Capability not supported. is removed since API version 20.

Example

let attachOptions: inputMethodEngine.AttachOptions = inputClient.getAttachOptions();
console.info(`Succeeded in getting AttachOptions, AttachOptions is ${attachOptions}`);

[h2]on('attachOptionsDidChange')19+

on(type: 'attachOptionsDidChange', callback: Callback<AttachOptions>): void

Subscribes to the event indicating that the additional options for binding an input method are changed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Additional option change event when the input method is bound. The value is fixed to 'attachOptionsDidChange'.
callback Callback<AttachOptions> Yes Callback used to return the additional options for binding an input method.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
801 Capability not supported. Supported versions: 19-19.

Error code 801 Capability not supported. is removed since API version 20.

Example

// Create the callback for additional option changes.
let attachOptionsDidChangeCallback: (attachOptions: inputMethodEngine.AttachOptions) => void =
  (_attachOptions: inputMethodEngine.AttachOptions) => {
    console.info(`AttachOptionsDidChangeCallback1: attachOptionsDidChange event triggered`);
  };

// Subscribe to the additional option change event when the input method is attached.
inputClient.on('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChangeCallback subscribed to attachOptionsDidChange`);
// Unsubscribe from the additional option change event when the input method is attached.
inputClient.off('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChange unsubscribed from attachOptionsDidChange`);

[h2]off('attachOptionsDidChange')19+

off(type: 'attachOptionsDidChange', callback?: Callback<AttachOptions>): void

Unsubscribes from the event indicating that additional options for binding an input method are changed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Additional option change event when the input method is bound. The value is fixed to 'attachOptionsDidChange'.
callback Callback<AttachOptions> No Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type by default.

Example

let attachOptionsDidChangeCallback: (attachOptions: inputMethodEngine.AttachOptions) => void =
  (_attachOptions: inputMethodEngine.AttachOptions) => {
    console.info(`AttachOptionsDidChangeCallback1: attachOptionsDidChange event triggered`);
  };

inputClient.on('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChangeCallback subscribed to attachOptionsDidChange`);
inputClient.off('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChange unsubscribed from attachOptionsDidChange`);

CapitalizeMode20+

Enumerates capitalization modes for the first letter of a text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0 The first letter is not capitalized.
SENTENCES 1 The first letter of each sentence is capitalized.
WORDS 2 The first letter of each word is capitalized.
CHARACTERS 3 All letters are capitalized.

EditorAttribute

Represents the attributes of the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
enterKeyType number Yes No Function attributes of the edit box. For details, see function key definitions in constants.
inputPattern number Yes No Text attributes of the edit box. For details, see edit box definitions in constants.
isTextPreviewSupported12+ boolean No No

Whether text preview is supported.

- true: Supported.

- false: Unsupported.
bundleName14+ string Yes Yes Name of the bundle to which the edit box belongs. The value may be "". Handle this scenario when using the attribute.
immersiveMode15+ ImmersiveMode Yes Yes Immersive mode of the input method.
windowId18+ number Yes Yes ID of the window where the edit box is located.
displayId18+ number Yes Yes Screen ID of the window corresponding to the edit box. If the window ID is not set, the screen ID of the focused window is used.
placeholder20+ string Yes Yes Placeholder information set for the edit box.
abilityName20+ string Yes Yes Ability name set for the edit box.
capitalizeMode20+ CapitalizeMode Yes Yes Capitalization mode for the text in the edit box. If it is not set or is set to an invalid value, the first letter is not capitalized by default.
gradientMode20+ GradientMode Yes Yes Gradient mode. If this attribute is not specified or is set to an invalid value, the gradient mode is not used by default.
extraConfig22+ InputMethodExtraConfig Yes Yes Extra information about the input method.
consumeKeyEvents boolean Yes Yes

Whether the edit box has the full capability to handle keys such as letters, characters, and function keys.

- The value true indicates that it has this capability.

- The value false indicates that it does not have this capability.

Since: 26.0.0

Model restriction: This parameter can be used only in the stage model.

KeyEvent

Represents the attributes of a key.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
keyCode number Yes No Key value. For details, see KeyCode.
keyAction number Yes No

Key event type.

- 2: keydown event.

- 3: keyup event.

PanelFlag10+

Enumerates the state types of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
FLG_FIXED 0 Fixed state type.
FLG_FLOATING 1 Floating state type.
FLAG_CANDIDATE15+ 2 Candidate state type.

PanelType10+

Enumerates the types of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
SOFT_KEYBOARD 0 Soft keyboard type.
STATUS_BAR 1 Status bar type.

PanelInfo10+

Describes the attributes of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
type PanelType No No Type of the panel.
flag PanelFlag No Yes State type of the panel.

PanelRect12+

Represents the size of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
landscapeRect window.Rect No No Size of the input method panel window in landscape mode.
portraitRect window.Rect No No Size of the input method panel window in portrait mode.

EnhancedPanelRect15+

Indicates the position and size of the enhanced input method panel, including the custom avoidance area and hot zone.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
landscapeRect window.Rect No Yes

Size of the input method panel window in landscape mode.

- This attribute is mandatory when fullScreenMode is not set or is set to false.
portraitRect window.Rect No Yes

Size of the input method panel window in portrait mode.

- This attribute is mandatory when fullScreenMode is not set or is set to false.
landscapeAvoidY number No Yes

Distance from the avoidance line in the panel to the top of the panel in landscape mode, in px. The default value is 0.

- Other system components in the app avoid the IME panel area below the avoidance line.

- When the panel is in the fixed state, the height from the avoidance line to the bottom of the screen cannot exceed 70% of the screen height. When the panel height is greater than 70% of the screen height, the default value 0 will fail this check. You need to set it manually so that the height from the avoidance line to the bottom of the screen does not exceed 70% of the screen height.
landscapeInputRegion Array<window.Rect> No Yes

Region where the panel receives input events in landscape mode.

- The array size is limited to [1, 4]. The default value is the panel size in landscape mode.

- The input hot zone is relative to the left vertex of the input method panel window.
portraitAvoidY number No Yes

Distance from the avoidance line in the panel to the top of the panel in portrait mode, in px. The default value is 0.

- Other system components in the app avoid the IME panel area below the avoidance line.

- When the panel is in the fixed state, the height from the avoidance line to the bottom of the screen cannot exceed 70% of the screen height. When the panel height is greater than 70% of the screen height, the default value 0 will fail this check. You need to set it manually so that the height from the avoidance line to the bottom of the screen does not exceed 70% of the screen height.
portraitInputRegion Array<window.Rect> No Yes

Region where the panel receives input events in portrait mode.

- The array size is limited to [1, 4]. The default value is the panel size in portrait mode.

- The input hot zone is relative to the left vertex of the input method panel window.
fullScreenMode boolean No Yes

Whether to enable the full-screen mode. The default value is false.

- If the value is true, landscapeRect and portraitRect are optional.

- If the value is false, landscapeRect and portraitRect are mandatory.

KeyboardArea15+

Represents the keyboard area on the panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
top number No No Distance between the upper boundary of the keyboard area and the upper boundary of the panel area, in pixels. The value is an integer.
bottom number No No Distance between the lower boundary of the keyboard area and the lower boundary of the panel area, in pixels. The value is an integer.
left number No No Distance between the left boundary of the keyboard area and the left boundary of the panel area, in pixels. The value is an integer.
right number No No Distance between the right boundary of the keyboard area and the right border of the panel area, in pixels. The value is an integer.

AttachOptions19+

Defines additional options for binding an input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
requestKeyboardReason RequestKeyboardReason No Yes Reason for requesting the keyboard. This attribute is set by the edit box application. If this attribute is not set or is set to an invalid value, the keyboard is triggered for no reason.
isSimpleKeyboardEnabled20+ boolean No Yes

Whether to enable the simple keyboard. This attribute is set by the edit box application. The value true means that the simple keyboard is enabled, and the value false means the opposite.

If this attribute is not set or is set to an invalid value, the simple keyboard is disabled by default.

WindowInfo12+

Represents window information.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
rect window.Rect No No Rectangular area of the window.
status window.WindowStatusType No No Window status type.

ImmersiveMode15+

Enumerates the immersive modes of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE_IMMERSIVE 0 The immersive mode is not used.
IMMERSIVE 1 The immersive mode is used. Its style is determined by the input method application.
LIGHT_IMMERSIVE 2 Immersive style in light mode.
DARK_IMMERSIVE 3 Immersive style in dark mode.

RequestKeyboardReason19+

Enumerates the reasons for requesting keyboard input.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0 The keyboard request is triggered for no reason.
MOUSE 1 The keyboard request is triggered by a mouse operation.
TOUCH 2 The keyboard request is triggered by a touch operation.
OTHER 20 The keyboard request is triggered by other reasons.

GradientMode20+

Enumerates the gradient modes of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0 The gradient mode is not used.
LINEAR_GRADIENT 1 Linear gradient.

ImmersiveEffect20+

Describes the immersive effect.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
gradientHeight number No No Gradient height, which cannot exceed 15% of the screen height. Unit: px.
gradientMode GradientMode No No Gradient mode.

SystemPanelInsets21+

Defines the offset area between the input method soft keyboard and the system panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-Only Optional Description
bottom number Yes No Distance between the bottom border of the keyboard area and the bottom border of the system panel area, in px. The value is an integer.
left number Yes No Distance between the left border of the keyboard area and the left border of the system panel area, in px. The value is an integer.
right number Yes No Distance between the right border of the keyboard area and the right border of the system panel area, in px. The value is an integer.

TextInputClient(deprecated)

In the following API examples, you must first use on('inputStart') to obtain a TextInputClient instance, and then call the APIs using the obtained instance.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use InputClient instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

[h2]getForward(deprecated)

getForward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Analyze the entered text content to provide intelligent completion suggestions, check text format, implement text prediction, implement text semantic analysis, and more.

Use effect: When the operation is successful, the fixed-length text before the cursor is returned, based on which the input method app can update candidate words or input suggestions.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.getForward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting forward, text: ' + text);
});

[h2]getForward(deprecated)

getForward(length:number): Promise<string>

Obtains the specific-length text before the cursor. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<string> Promise used to return the specific-length text before the cursor.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.getForward(length).then((text: string) => {
  console.info('Succeeded in getting forward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
});

[h2]getBackward(deprecated)

getBackward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.getBackward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting backward, text: ' + text);
});

[h2]getBackward(deprecated)

getBackward(length:number): Promise<string>

Obtains the specific-length text after the cursor. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<string> Promise used to return the specific-length text after the cursor.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.getBackward(length).then((text: string) => {
  console.info(`Succeeded in getting backward: ${text}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
});

[h2]deleteForward(deprecated)

deleteForward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Implement the Backspace key function, delete input character by character, delete incorrect input, and implement custom deletion logic, among others.

Use effect: When the operation is successful, the fixed-length text before the cursor is deleted.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.deleteForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
callback AsyncCallback<boolean> Yes Callback used to return the result. If the fixed-length text before the cursor is deleted successfully, err is undefined and data is true; if the deletion fails, err is undefined and data is false; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.deleteForward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to deleteForward.');
  }
});

[h2]deleteForward(deprecated)

deleteForward(length:number): Promise<boolean>

Deletes the fixed-length text before the cursor. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.deleteForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<boolean> Promise used to return the result. If resolved, the value true indicates that the fixed-length text before the cursor is deleted successfully, and false indicates that the deletion fails. If rejected, an error object is thrown, indicating that an error occurs during execution.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.deleteForward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to delete forward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
});

[h2]deleteBackward(deprecated)

deleteBackward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result.

Usage scenarios: Implement the Backspace key function, delete characters after the cursor, delete incorrect input, and implement custom deletion logic, among others.

Use effect: When the operation is successful, the fixed-length text after the cursor is deleted.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.deleteBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.
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.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.deleteBackward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
});

[h2]deleteBackward(deprecated)

deleteBackward(length:number): Promise<boolean>

Deletes the fixed-length text after the cursor. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.deleteBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
length number Yes Text length, which cannot be less than 0.

Return value

Type Description
Promise<boolean> Promise used to return the result. The value true means that the deletion is successful, and false means the opposite.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let length: number = 1;
textInputClient.deleteBackward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
});

[h2]sendKeyFunction(deprecated)

sendKeyFunction(action: number, callback: AsyncCallback<boolean>): void

Sends the function key. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.sendKeyFunction instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action number Yes

Action of the function key.

- 0: invalid key.

- 1: confirm key (Enter key).
callback AsyncCallback<boolean> Yes Callback used to return the result. If the function key is sent successfully, err is undefined and data is true; if the function key fails to be sent, err is undefined and data is false; otherwise, an error object is returned.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let action: number = 1;
textInputClient.sendKeyFunction(action, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
});

[h2]sendKeyFunction(deprecated)

sendKeyFunction(action: number): Promise<boolean>

Sends the function key. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.sendKeyFunction instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
action number Yes

Action of the function key.

0: invalid key.

1: confirm key (Enter key).

Return value

Type Description
Promise<boolean> Promise used to return the result. The value true means that the setting is successful, and false means the opposite.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let action: number = 1;
textInputClient.sendKeyFunction(action).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to sendKeyFunction:. Code is ${err.code}, message is ${err.message}`);
});

[h2]insertText(deprecated)

insertText(text:string, callback: AsyncCallback<boolean>): void

Inserts text. This API uses an asynchronous callback to return the result.

Usage scenarios: Insert candidate words, insert special symbols, implement text auto-completion, and quickly insert common phrases, among others.

Use effect: When the operation is successful, the text is inserted at the cursor position in the edit box.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.insertText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Text to insert.
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.

Example

import { BusinessError } from '@kit.BasicServicesKit';

textInputClient.insertText('test', (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
});

[h2]insertText(deprecated)

insertText(text:string): Promise<boolean>

Inserts text. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.insertText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Text to insert.

Return value

Type Description
Promise<boolean> Promise used to return the result. The value true means that the insertion is successful, and false means the opposite.

Example

import { BusinessError } from '@kit.BasicServicesKit';

textInputClient.insertText('test').then((result: boolean) => {
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
});

[h2]getEditorAttribute(deprecated)

getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void

Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result.

Usage scenarios: Adjust the input method UI based on the edit box type, provide different input suggestions based on the edit box configuration, implement specific input logic, and adapt to different types of input boxes, among others.

Use effect: The edit box attribute information (including inputPattern and enterKeyType) is returned, based on which the input method app adjusts the keyboard layout.

Supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getEditorAttribute instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<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.

Example

import { BusinessError } from '@kit.BasicServicesKit';


textInputClient.getEditorAttribute((err: BusinessError,
  editorAttribute: inputMethodEngine.EditorAttribute) => {
  if (err) {
    console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`editorAttribute.inputPattern: ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType: ${editorAttribute.enterKeyType}`);
});

[h2]getEditorAttribute(deprecated)

getEditorAttribute(): Promise<EditorAttribute>

Obtains the attribute of the edit box. This API uses a promise to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use inputMethodEngine.InputClient.getEditorAttribute instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<EditorAttribute> Promise used to return the attribute of the edit box.

Example

import { BusinessError } from '@kit.BasicServicesKit';

textInputClient.getEditorAttribute().then((editorAttribute: inputMethodEngine.EditorAttribute) => {
  console.info(`editorAttribute.inputPattern: ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType: ${editorAttribute.enterKeyType}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
});