@ohos.inputMethod (Input Method Framework)

The inputMethod module is oriented to common foreground applications (third-party applications and system applications such as Notes, Messaging, and Settings). It provides input method control and management capabilities, including displaying or hiding the soft keyboard, switching between input methods, and obtaining the list of all input methods.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

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

Constant

Provides the constants.

System capability: SystemCapability.MiscServices.InputMethodFramework

InputMethodProperty⁸⁺

Describes the input method application attributes.

System capability: SystemCapability.MiscServices.InputMethodFramework

inputMethod.getController⁹⁺

getController(): InputMethodController

Obtains an InputMethodController instance.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

let inputMethodController = inputMethod.getController();

inputMethod.getDefaultInputMethod¹¹⁺

getDefaultInputMethod(): InputMethodProperty

Obtains the default input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

try {
  let defaultIme = inputMethod.getDefaultInputMethod();
} catch(err) {
  console.error(`Failed to getDefaultInputMethod: ${JSON.stringify(err)}`);
}

inputMethod.getSystemInputMethodConfigAbility¹¹⁺

getSystemInputMethodConfigAbility(): ElementName

Obtains the information about the input method configuration page ability.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

try {
  let inputMethodConfig = inputMethod.getSystemInputMethodConfigAbility();
} catch(err) {
  console.error(`Failed to get getSystemInputMethodConfigAbility: ${JSON.stringify(err)}`);
}

inputMethod.getSetting⁹⁺

getSetting(): InputMethodSetting

Obtains an InputMethodSetting instance.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

let inputMethodSetting = inputMethod.getSetting();

inputMethod.switchInputMethod⁹⁺

switchInputMethod(target: InputMethodProperty, callback: AsyncCallback<boolean>): void

Switches to another input method. This API uses an asynchronous callback to return the result.

NOTE

• In API versions 9 and 10, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

let currentIme = inputMethod.getCurrentInputMethod();
try{
  inputMethod.switchInputMethod(currentIme, (err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
      return;
    }
    if (result) {
      console.info('Succeeded in switching inputmethod.');
    } else {
      console.error('Failed to switchInputMethod.');
    }
  });
} catch(err) {
  console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.switchInputMethod⁹⁺

switchInputMethod(target: InputMethodProperty): Promise<boolean>

Switches to another input method. This API uses a promise to return the result.

NOTE

• In API versions 9 and 10, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

let currentIme = inputMethod.getCurrentInputMethod();
try {
  inputMethod.switchInputMethod(currentIme).then((result: boolean) => {
    if (result) {
      console.info('Succeeded in switching inputmethod.');
    } else {
      console.error('Failed to switchInputMethod.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
  })
} catch (err) {
  console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.getCurrentInputMethod⁹⁺

getCurrentInputMethod(): InputMethodProperty

Obtains the current input method. This API returns the result synchronously.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Example

let currentIme = inputMethod.getCurrentInputMethod();

inputMethod.switchCurrentInputMethodSubtype⁹⁺

switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback<boolean>): void

Switches to another subtype of this input method. This API uses an asynchronous callback to return the result.

NOTE

• In API version 9, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• In API version 10, this API can only be called by system applications and the current input method application, and the ohos.permission.CONNECT_IME_ABILITY permission is required.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  let extra: Record<string, string> = {}
  inputMethod.switchCurrentInputMethodSubtype({
    id: "ServiceExtAbility",
    label: "",
    name: "com.example.kikakeyboard",
    mode: "upper",
    locale: "",
    language: "",
    icon: "",
    iconId: 0,
    extra: extra
  }, (err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
      return;
    }
    if (result) {
      console.info('Succeeded in switching currentInputMethodSubtype.');
    } else {
      console.error('Failed to switchCurrentInputMethodSubtype');
    }
  });
} catch(err) {
  console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.switchCurrentInputMethodSubtype⁹⁺

switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise<boolean>

Switches to another subtype of this input method. This API uses a promise to return the result.

NOTE

• In API version 9, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• In API version 10, this API can only be called by system applications and the current input method application, and the ohos.permission.CONNECT_IME_ABILITY permission is required.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let extra: Record<string, string> = {}
  inputMethod.switchCurrentInputMethodSubtype({
    id: "ServiceExtAbility",
    label: "",
    name: "com.example.kikakeyboard",
    mode: "upper",
    locale: "",
    language: "",
    icon: "",
    iconId: 0,
    extra: extra
  }).then((result: boolean) => {
    if (result) {
      console.info('Succeeded in switching currentInputMethodSubtype.');
    } else {
      console.error('Failed to switchCurrentInputMethodSubtype.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.getCurrentInputMethodSubtype⁹⁺

getCurrentInputMethodSubtype(): InputMethodSubtype

Obtains the current input method subtype.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Example

let currentImeSubType = inputMethod.getCurrentInputMethodSubtype();

inputMethod.switchCurrentInputMethodAndSubtype⁹⁺

switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback<boolean>): void

Switches to a specified subtype of a specified input method. This API uses an asynchronous callback to return the result.

NOTE

• In API versions 9 and 10, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

let currentIme = inputMethod.getCurrentInputMethod();
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
  inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType, (err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
      return;
    }
    if (result) {
      console.info('Succeeded in switching currentInputMethodAndSubtype.');
    } else {
      console.error('Failed to switchCurrentInputMethodAndSubtype.');
    }
  });
} catch (err) {
  console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.switchCurrentInputMethodAndSubtype⁹⁺

switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean>

Switches to a specified subtype of a specified input method. This API uses a promise to return the result.

NOTE

• In API versions 9 and 10, this API can only be called by system applications granted the ohos.permission.CONNECT_IME_ABILITY permission.
• Since API version 11, this API can only be called by the current input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

let currentIme = inputMethod.getCurrentInputMethod();
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
  inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType).then((result: boolean) => {
    if (result) {
      console.info('Succeeded in switching currentInputMethodAndSubtype.');
    } else {
      console.error('Failed to switchCurrentInputMethodAndSubtype.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
}

NOTE

Since API version 11, the error code 201 permissions check fails is removed.

inputMethod.getInputMethodController^(deprecated)

getInputMethodController(): InputMethodController

Obtains an InputMethodController instance.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use getController() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Example

let inputMethodController = inputMethod.getInputMethodController();

inputMethod.getInputMethodSetting^(deprecated)

getInputMethodSetting(): InputMethodSetting

Obtains an InputMethodSetting instance.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use getSetting() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Example

let inputMethodSetting = inputMethod.getInputMethodSetting();

TextInputType¹⁰⁺

Enumerates the text input types.

System capability: SystemCapability.MiscServices.InputMethodFramework

EnterKeyType¹⁰⁺

Enumerates the function types represented by the Enter key of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

KeyboardStatus¹⁰⁺

Enumerates the soft keyboard states of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Direction¹⁰⁺

Enumerates the directions of cursor movement of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

ExtendAction¹⁰⁺

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

System capability: SystemCapability.MiscServices.InputMethodFramework

FunctionKey¹⁰⁺

Describes the type of the input method function key.

System capability: SystemCapability.MiscServices.InputMethodFramework

InputAttribute¹⁰⁺

Describes the attributes of the edit box, including the text input type and Enter key function type.

System capability: SystemCapability.MiscServices.InputMethodFramework

TextConfig¹⁰⁺

Describes the configuration of the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

CursorInfo¹⁰⁺

Represents the cursor information.

System capability: SystemCapability.MiscServices.InputMethodFramework

Range¹⁰⁺

Describes the range of the selected text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Movement¹⁰⁺

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

System capability: SystemCapability.MiscServices.InputMethodFramework

InputWindowInfo¹⁰⁺

Describes the window information of the input method keyboard.

System capability: SystemCapability.MiscServices.InputMethodFramework

EnabledState¹⁵⁺

Indicates whether the input method is enabled.

System capability: SystemCapability.MiscServices.InputMethodFramework

RequestKeyboardReason¹⁵⁺

Describes the reason for keyboard request.

System capability: SystemCapability.MiscServices.InputMethodFramework

MessageHandler¹⁵⁺

Represents a custom communication object.

NOTE

You can register this object to receive custom communication data sent by 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.

onMessage¹⁵⁺

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

Receives custom data sent by the input method application.

NOTE

This callback is triggered when the registered MeesageHandler receives custom communication data sent by 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

Example

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

let inputMethodController = inputMethod.getController();
try {
    let messageHandler: inputMethod.MessageHandler = {
        onTerminated(): void {
            console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?:ArrayBuffer): void {
            console.info('recv message.');
        }
    }
    inputMethodController.recvMessage(messageHandler);
} catch(err) {
  console.error(`Failed to recvMessage: ${JSON.stringify(err)}`);
}

onTerminated¹⁵⁺

onTerminated(): void

Listens for MessageHandler termination.

NOTE

When an application registers a new MessageHandler object, the OnTerminated callback of the previous registered MessageHandler object is triggered.

When an application unregisters a MessageHandler object, the OnTerminated callback of the current registered MessageHandler object is triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Example

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

let inputMethodController = inputMethod.getController();
try {
    let messageHandler: inputMethod.MessageHandler = {
        onTerminated(): void {
            console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?:ArrayBuffer): void {
            console.info('recv message.');
        }
    }
    inputMethodController.recvMessage(messageHandler);
} catch(err) {
  console.error(`Failed to recvMessage: ${JSON.stringify(err)}`);
}

SetPreviewTextCallback¹⁷⁺

type SetPreviewTextCallback = (text: string, range: Range) => void

Callback triggered when the input method framework needs to display the text preview.

System capability: SystemCapability.MiscServices.InputMethodFramework

InputMethodController

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

attach¹⁰⁺

attach(showKeyboard: boolean, textConfig: TextConfig, callback: AsyncCallback<void>): void

Attaches a self-drawing component to the input method. This API uses an asynchronous callback to return the result.

NOTE

An input method can use the following features only when it has a self-drawing component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  let textConfig: inputMethod.TextConfig = {
    inputAttribute: {
      textInputType: 0,
      enterKeyType: 1
    }
  };
  inputMethodController.attach(true, textConfig, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to attach: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in attaching the inputMethod.');
  });
} catch(err) {
  console.error(`Failed to attach: ${JSON.stringify(err)}`);
}

attach¹⁰⁺

attach(showKeyboard: boolean, textConfig: TextConfig): Promise<void>

Attaches a self-drawing component to the input method. This API uses a promise to return the result.

NOTE

An input method can use the following features only when it has a self-drawing component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let textConfig: inputMethod.TextConfig = {
    inputAttribute: {
      textInputType: 0,
      enterKeyType: 1
    }
  };
  inputMethodController.attach(true, textConfig).then(() => {
    console.info('Succeeded in attaching inputMethod.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to attach: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to attach: ${JSON.stringify(err)}`);
}

attach¹⁵⁺

attach(showKeyboard: boolean, textConfig: TextConfig, requestKeyboardReason: RequestKeyboardReason): Promise<void>

Attaches a self-drawing component to the input method. This API uses a promise to return the result.

NOTE

An input method can use the following features only when it has a self-drawing component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let textConfig: inputMethod.TextConfig = {
    inputAttribute: {
      textInputType: 0,
      enterKeyType: 1
    }
  };

  let requestKeyboardReason: inputMethod.RequestKeyboardReason = inputMethod.RequestKeyboardReason.MOUSE;

  inputMethodController.attach(true, textConfig, requestKeyboardReason).then(() => {
    console.info('Succeeded in attaching inputMethod.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to attach: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to attach: ${JSON.stringify(err)}`);
}

showTextInput¹⁰⁺

showTextInput(callback: AsyncCallback<void>): void

Enters the text editing mode. This API uses an asynchronous callback to return the result.

NOTE

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

inputMethodController.showTextInput((err: BusinessError) => {
  if (err) {
    console.error(`Failed to showTextInput: ${JSON.stringify(err)}`);
    return;
  }
  console.info('Succeeded in showing the inputMethod.');
});

showTextInput¹⁰⁺

showTextInput(): Promise<void>

Enters the text editing mode. This API uses a promise to return the result.

NOTE

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

inputMethodController.showTextInput().then(() => {
  console.info('Succeeded in showing text input.');
}).catch((err: BusinessError) => {
  console.error(`Failed to showTextInput: ${JSON.stringify(err)}`);
});

showTextInput¹⁵⁺

showTextInput(requestKeyboardReason: RequestKeyboardReason): Promise<void>

Enters the text editing mode. This API uses a promise to return the result.

NOTE

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

let requestKeyboardReason = inputMethod.RequestKeyboardReason.MOUSE;

inputMethodController.showTextInput(requestKeyboardReason).then(() => {
  console.info('Succeeded in showing text input.');
}).catch((err: BusinessError) => {
  console.error(`Failed to showTextInput: ${JSON.stringify(err)}`);
});

hideTextInput¹⁰⁺

hideTextInput(callback: AsyncCallback<void>): void

Exits the text editing mode. This API uses an asynchronous callback to return the result.

NOTE

If the soft keyboard is displayed when this API is called, it will be hidden.

Calling this API does not detach the edit box from the input method. The edit box can call showTextInput again to reenter the text editing mode.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

inputMethodController.hideTextInput((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hideTextInput: ${JSON.stringify(err)}`);
    return;
  }
  console.info('Succeeded in hiding text input.');
});

hideTextInput¹⁰⁺

hideTextInput(): Promise<void>

Exits the text editing mode. This API uses a promise to return the result.

NOTE

If the soft keyboard is displayed when this API is called, it will be hidden.

Calling this API does not detach the edit box from the input method. The edit box can call showTextInput again to reenter the text editing mode.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

inputMethodController.hideTextInput().then(() => {
  console.info('Succeeded in hiding inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hideTextInput: ${JSON.stringify(err)}`);
})

detach¹⁰⁺

detach(callback: AsyncCallback<void>): void

Detaches the self-drawing component from the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

inputMethodController.detach((err: BusinessError) => {
  if (err) {
    console.error(`Failed to detach: ${JSON.stringify(err)}`);
    return;
  }
  console.info('Succeeded in detaching inputMethod.');
});

detach¹⁰⁺

detach(): Promise<void>

Detaches the self-drawing component from the input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

inputMethodController.detach().then(() => {
  console.info('Succeeded in detaching inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to detach: ${JSON.stringify(err)}`);
});

setCallingWindow¹⁰⁺

setCallingWindow(windowId: number, callback: AsyncCallback<void>): void

Sets the window to be avoided by the input method. This API uses an asynchronous callback to return the result.

NOTE

After the window ID of the application bound to the input method is passed in the API, the input method window will not cover the window holding the application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  let windowId: number = 2000;
  inputMethodController.setCallingWindow(windowId, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in setting callingWindow.');
  });
} catch(err) {
  console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
}

setCallingWindow¹⁰⁺

setCallingWindow(windowId: number): Promise<void>

Sets the window to be avoided by the input method. This API uses a promise to return the result.

NOTE

After the window ID of the application bound to the input method is passed in the API, the input method window will not cover the window holding the application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let windowId: number = 2000;
  inputMethodController.setCallingWindow(windowId).then(() => {
    console.info('Succeeded in setting callingWindow.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
}

updateCursor¹⁰⁺

updateCursor(cursorInfo: CursorInfo, callback: AsyncCallback<void>): void

Updates the cursor information in this edit box. This API can be called to notify the input method of the cursor changes. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  let cursorInfo: inputMethod.CursorInfo = { left: 0, top: 0, width: 600, height: 800 };
  inputMethodController.updateCursor(cursorInfo, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in updating cursorInfo.');
  });
} catch(err) {
  console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
}

updateCursor¹⁰⁺

updateCursor(cursorInfo: CursorInfo): Promise<void>

Updates the cursor information in this edit box. This API can be called to notify the input method of the cursor changes. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let cursorInfo: inputMethod.CursorInfo = { left: 0, top: 0, width: 600, height: 800 };
  inputMethodController.updateCursor(cursorInfo).then(() => {
    console.info('Succeeded in updating cursorInfo.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
}

changeSelection¹⁰⁺

changeSelection(text: string, start: number, end: number, callback: AsyncCallback<void>): void

Updates the information about the selected text in this edit box, to notify the input method when the selected text content or text range changes. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  inputMethodController.changeSelection('text', 0, 5, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in changing selection.');
  });
} catch(err) {
  console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
}

changeSelection¹⁰⁺

changeSelection(text: string, start: number, end: number): Promise<void>

Updates the information about the selected text in this edit box, to notify the input method when the selected text content or text range changes. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  inputMethodController.changeSelection('test', 0, 5).then(() => {
    console.info('Succeeded in changing selection.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
}

updateAttribute¹⁰⁺

updateAttribute(attribute: InputAttribute, callback: AsyncCallback<void>): void

Updates the attribute information of this edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
  inputMethodController.updateAttribute(inputAttribute, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in updating attribute.');
  });
} catch(err) {
  console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
}

updateAttribute¹⁰⁺

updateAttribute(attribute: InputAttribute): Promise<void>

Updates the attribute information of this edit box. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
  let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
  inputMethodController.updateAttribute(inputAttribute).then(() => {
    console.info('Succeeded in updating attribute.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
}

stopInputSession⁹⁺

stopInputSession(callback: AsyncCallback<boolean>): void

Ends this input session. This API uses an asynchronous callback to return the result.

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

try {
  inputMethodController.stopInputSession((err: BusinessError, result: boolean) => {
    if (err) {
      console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
      return;
    }
    if (result) {
      console.info('Succeeded in stopping inputSession.');
    } else {
      console.error('Failed to stopInputSession.');
    }
  });
} catch(err) {
  console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
}

stopInputSession⁹⁺

stopInputSession(): Promise<boolean>

Ends this input session. This API uses a promise to return the result.

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

try {
  inputMethodController.stopInputSession().then((result: boolean) => {
    if (result) {
      console.info('Succeeded in stopping inputSession.');
    } else {
      console.error('Failed to stopInputSession.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
}

showSoftKeyboard⁹⁺

showSoftKeyboard(callback: AsyncCallback<void>): void

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

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to show the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

inputMethodController.showSoftKeyboard((err: BusinessError) => {
  if (!err) {
    console.info('Succeeded in showing softKeyboard.');
  } else {
    console.error(`Failed to show softKeyboard: ${JSON.stringify(err)}`);
  }
})

showSoftKeyboard⁹⁺

showSoftKeyboard(): Promise<void>

Shows the soft keyboard. This API uses a promise to return the result.

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to show the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

inputMethodController.showSoftKeyboard().then(() => {
  console.info('Succeeded in showing softKeyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show softKeyboard: ${JSON.stringify(err)}`);
});

hideSoftKeyboard⁹⁺

hideSoftKeyboard(callback: AsyncCallback<void>): void

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

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to hide the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

inputMethodController.hideSoftKeyboard((err: BusinessError) => {
  if (!err) {
    console.info('Succeeded in hiding softKeyboard.');
  } else {
    console.error(`Failed to hide softKeyboard: ${JSON.stringify(err)}`);
  }
})

hideSoftKeyboard⁹⁺

hideSoftKeyboard(): Promise<void>

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

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to hide the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Error codes

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

Example

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

inputMethodController.hideSoftKeyboard().then(() => {
  console.info('Succeeded in hiding softKeyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide softKeyboard: ${JSON.stringify(err)}`);
});

sendMessage¹⁵⁺

sendMessage(msgId: string, msgParam?: ArrayBuffer): Promise<void>

Sends the custom communication to the input method application. This API uses a promise to return the result.

NOTE

This API can be called only when the edit box is attached to the input method and enter 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

Return value

Error codes

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

Example

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

let msgId: string = "testMsgId";
let msgParam: ArrayBuffer = new ArrayBuffer(128);
inputMethodController.sendMessage(msgId, msgParam).then(() => {
  console.info('Succeeded send message.');
}).catch((err: BusinessError) => {
  console.error(`Failed to send message: ${JSON.stringify(err)}`);
});

recvMessage¹⁵⁺

recvMessage(msgHandler?: MessageHandler): void

Registers or unregisters MessageHandler.

NOTE

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, unregister MessageHandler. Its onTerminated callback will be triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

try {
    let messageHandler: inputMethod.MessageHandler = {
        onTerminated(): void {
            console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?:ArrayBuffer): void {
            console.info('recv message.');
        }
    }
inputMethodController.recvMessage(messageHandler);
inputMethodController.recvMessage();
} catch(err) {
  console.error(`Failed to recvMessage: ${JSON.stringify(err)}`);
}

stopInput^(deprecated)

stopInput(callback: AsyncCallback<boolean>): void

Ends this input session. This API uses an asynchronous callback to return the result.

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

This API is supported since API version 6 and deprecated since API version 9. You are advised to use stopInputSession() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

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

inputMethodController.stopInput((err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to stopInput: ${JSON.stringify(err)}`);
    return;
  }
  if (result) {
    console.info('Succeeded in stopping input.');
  } else {
    console.error('Failed to stopInput.');
  }
});

stopInput^(deprecated)

stopInput(): Promise<boolean>

Ends this input session. This API uses a promise to return the result.

NOTE

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

This API is supported since API version 6 and deprecated since API version 9. You are advised to use stopInputSession() instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Example

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

inputMethodController.stopInput().then((result: boolean) => {
  if (result) {
    console.info('Succeeded in stopping input.');
  } else {
    console.error('Failed to stopInput.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to stopInput: ${JSON.stringify(err)}`);
})

on('insertText')¹⁰⁺

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

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

function callback1(text: string) {
  console.info('Succeeded in getting callback1 data: ' + JSON.stringify(text));
}

function callback2(text: string) {
  console.info('Succeeded in getting callback2 data: ' + JSON.stringify(text));
}

try {
  inputMethodController.on('insertText', callback1);
  inputMethodController.on('insertText', callback2);
  // Cancel only callback1 of insertText.
  inputMethodController.off('insertText', callback1);
  // Cancel all callbacks of insertText.
  inputMethodController.off('insertText');
} catch(err) {
  console.error(`Failed to subscribe insertText: ${JSON.stringify(err)}`);
}

off('insertText')¹⁰⁺

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

Disables listening for the text insertion event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onInsertTextCallback = (text: string) => {
    console.info(`Succeeded in subscribing insertText: ${text}`);
};
inputMethodController.off('insertText', onInsertTextCallback);
inputMethodController.off('insertText');

on('deleteLeft')¹⁰⁺

on(type: 'deleteLeft', callback: (length: number) => void): void

Enables listening for the leftward delete event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('deleteLeft', (length: number) => {
    console.info(`Succeeded in subscribing deleteLeft, length: ${length}`);
  });
} catch(err) {
  console.error(`Failed to subscribe deleteLeft: ${JSON.stringify(err)}`);
}

off('deleteLeft')¹⁰⁺

off(type: 'deleteLeft', callback?: (length: number) => void): void

Disables listening for the leftward delete event.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onDeleteLeftCallback = (length: number) => {
    console.info(`Succeeded in subscribing deleteLeft, length: ${length}`);
};
inputMethodController.off('deleteLeft', onDeleteLeftCallback);
inputMethodController.off('deleteLeft');

on('deleteRight')¹⁰⁺

on(type: 'deleteRight', callback: (length: number) => void): void

Enables listening for the rightward delete event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('deleteRight', (length: number) => {
    console.info(`Succeeded in subscribing deleteRight, length: ${length}`);
  });
} catch(err) {
  console.error(`Failed to subscribe deleteRight: ${JSON.stringify(err)}`);
}

off('deleteRight')¹⁰⁺

off(type: 'deleteRight', callback?: (length: number) => void): void

Disables listening for the rightward delete event.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onDeleteRightCallback = (length: number) => {
    console.info(`Succeeded in subscribing deleteRight, length: ${length}`);
};
inputMethodController.off('deleteRight', onDeleteRightCallback);
inputMethodController.off('deleteRight');

on('sendKeyboardStatus')¹⁰⁺

on(type: 'sendKeyboardStatus', callback: (keyboardStatus: KeyboardStatus) => void): void

Enables listening for the soft keyboard status event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('sendKeyboardStatus', (keyboardStatus: inputMethod.KeyboardStatus) => {
    console.info(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
  });
} catch(err) {
  console.error(`Failed to subscribe sendKeyboardStatus: ${JSON.stringify(err)}`);
}

off('sendKeyboardStatus')¹⁰⁺

off(type: 'sendKeyboardStatus', callback?: (keyboardStatus: KeyboardStatus) => void): void

Disables listening for the soft keyboard status event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onSendKeyboardStatus = (keyboardStatus: inputMethod.KeyboardStatus) => {
    console.info(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
};
inputMethodController.off('sendKeyboardStatus', onSendKeyboardStatus);
inputMethodController.off('sendKeyboardStatus');

on('sendFunctionKey')¹⁰⁺

on(type: 'sendFunctionKey', callback: (functionKey: FunctionKey) => void): void

Enables listening for the function key sending event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('sendFunctionKey', (functionKey: inputMethod.FunctionKey) => {
    console.info(`Succeeded in subscribing sendFunctionKey, functionKey.enterKeyType: ${functionKey.enterKeyType}`);
  });
} catch(err) {
  console.error(`Failed to subscribe sendFunctionKey: ${JSON.stringify(err)}`);
}

off('sendFunctionKey')¹⁰⁺

off(type: 'sendFunctionKey', callback?: (functionKey: FunctionKey) => void): void

Disables listening for the function key sending event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onSendFunctionKey = (functionKey: inputMethod.FunctionKey) => {
    console.info(`Succeeded in subscribing sendFunctionKey, functionKey: ${functionKey.enterKeyType}`);
};
inputMethodController.off('sendFunctionKey', onSendFunctionKey);
inputMethodController.off('sendFunctionKey');

on('moveCursor')¹⁰⁺

on(type: 'moveCursor', callback: (direction: Direction) => void): void

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('moveCursor', (direction: inputMethod.Direction) => {
    console.info(`Succeeded in subscribing moveCursor, direction: ${direction}`);
  });
} catch(err) {
  console.error(`Failed to subscribe moveCursor: ${JSON.stringify(err)}`);
}

off('moveCursor')¹⁰⁺

off(type: 'moveCursor', callback?: (direction: Direction) => void): void

Disables listening for the cursor movement event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let onMoveCursorCallback = (direction: inputMethod.Direction) => {
    console.info(`Succeeded in subscribing moveCursor, direction: ${direction}`);
};
inputMethodController.off('moveCursor', onMoveCursorCallback);
inputMethodController.off('moveCursor');

on('handleExtendAction')¹⁰⁺

on(type: 'handleExtendAction', callback: (action: ExtendAction) => void): void

Enables listening for the extended action handling event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('handleExtendAction', (action: inputMethod.ExtendAction) => {
    console.info(`Succeeded in subscribing handleExtendAction, action: ${action}`);
  });
} catch(err) {
  console.error(`Failed to subscribe handleExtendAction: ${JSON.stringify(err)}`);
}

off('handleExtendAction')¹⁰⁺

off(type: 'handleExtendAction', callback?: (action: ExtendAction) => void): void

Disables listening for the extended action handling event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let onHandleExtendActionCallback = (action: inputMethod.ExtendAction) => {
    console.info(`Succeeded in subscribing handleExtendAction, action: ${action}`);
  };
  inputMethodController.off('handleExtendAction', onHandleExtendActionCallback);
  inputMethodController.off('handleExtendAction');
} catch(err) {
  console.error(`Failed to subscribe handleExtendAction: ${JSON.stringify(err)}`);
}

on('selectByRange')¹⁰⁺

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

Enables listening for the select-by-range event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('selectByRange', (range: inputMethod.Range) => {
    console.info(`Succeeded in subscribing selectByRange: start: ${range.start} , end: ${range.end}`);
  });
} catch(err) {
  console.error(`Failed to subscribe selectByRange: ${JSON.stringify(err)}`);
}

off('selectByRange')¹⁰⁺

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

Disables listening for the select-by-range event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let onSelectByRangeCallback = (range: inputMethod.Range) => {
    console.info(`Succeeded in subscribing selectByRange, start: ${range.start} , end: ${range.end}`);
  };
  inputMethodController.off('selectByRange', onSelectByRangeCallback);
  inputMethodController.off('selectByRange');
} catch(err) {
  console.error(`Failed to subscribe selectByRange: ${JSON.stringify(err)}`);
}

on('selectByMovement')¹⁰⁺

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

Enables listening for the select-by-cursor-movement event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('selectByMovement', (movement: inputMethod.Movement) => {
    console.info('Succeeded in subscribing selectByMovement: direction: ' + movement.direction);
  });
} catch(err) {
  console.error(`Failed to subscribe selectByMovement: ${JSON.stringify(err)}`);
}

off('selectByMovement')¹⁰⁺

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

Disables listening for the select-by-cursor-movement event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let onSelectByMovementCallback = (movement: inputMethod.Movement) => {
    console.info(`Succeeded in subscribing selectByMovement, movement.direction: ${movement.direction}`);
  };
  inputMethodController.off('selectByMovement', onSelectByMovementCallback);
  inputMethodController.off('selectByMovement');
} catch(err) {
  console.error(`Failed to unsubscribing selectByMovement: ${JSON.stringify(err)}`);
}

on('getLeftTextOfCursor')¹⁰⁺

on(type: 'getLeftTextOfCursor', callback: (length: number) => string): void

Enables listening for the event of obtaining the length of text deleted leftward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('getLeftTextOfCursor', (length: number) => {
    console.info(`Succeeded in subscribing getLeftTextOfCursor, length: ${length}`);
    let text:string = "";
    return text;
  });
} catch(err) {
  console.error(`Failed to unsubscribing getLeftTextOfCursor. err: ${JSON.stringify(err)}`);
}

off('getLeftTextOfCursor')¹⁰⁺

off(type: 'getLeftTextOfCursor', callback?: (length: number) => string): void

Disables listening for the event of obtaining the length of text deleted leftward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let getLeftTextOfCursorCallback = (length: number) => {
    console.info(`Succeeded in unsubscribing getLeftTextOfCursor, length: ${length}`);
    let text:string = "";
    return text;
  };
  inputMethodController.off('getLeftTextOfCursor', getLeftTextOfCursorCallback);
  inputMethodController.off('getLeftTextOfCursor');
} catch(err) {
  console.error(`Failed to unsubscribing getLeftTextOfCursor. err: ${JSON.stringify(err)}`);
}

on('getRightTextOfCursor')¹⁰⁺

on(type: 'getRightTextOfCursor', callback: (length: number) => string): void

Enables listening for the event of obtaining the length of text deleted rightward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('getRightTextOfCursor', (length: number) => {
    console.info(`Succeeded in subscribing getRightTextOfCursor, length: ${length}`);
    let text:string = "";
    return text;
  });
} catch(err) {
  console.error(`Failed to subscribe getRightTextOfCursor. err: ${JSON.stringify(err)}`);
}

off('getRightTextOfCursor')¹⁰⁺

off(type: 'getRightTextOfCursor', callback?: (length: number) => string): void

Disables listening for the event of obtaining the length of text deleted rightward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let getRightTextOfCursorCallback = (length: number) => {
    console.info(`Succeeded in unsubscribing getRightTextOfCursor, length: ${length}`);
    let text:string = "";
    return text;
  };
  inputMethodController.off('getRightTextOfCursor', getRightTextOfCursorCallback);
  inputMethodController.off('getRightTextOfCursor');
} catch(err) {
  console.error(`Failed to unsubscribing getRightTextOfCursor. err: ${JSON.stringify(err)}`);
}

on('getTextIndexAtCursor')¹⁰⁺

on(type: 'getTextIndexAtCursor', callback: () => number): void

Enables listening for the event of obtaining the index of text at the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

try {
  inputMethodController.on('getTextIndexAtCursor', () => {
    console.info(`Succeeded in subscribing getTextIndexAtCursor.`);
    let index:number = 0;
    return index;
  });
} catch(err) {
  console.error(`Failed to subscribe getTextIndexAtCursor. err: ${JSON.stringify(err)}`);
}

off('getTextIndexAtCursor')¹⁰⁺

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

Disables listening for the event of obtaining the index of text at the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

try {
  let getTextIndexAtCursorCallback = () => {
    console.info(`Succeeded in unsubscribing getTextIndexAtCursor.`);
    let index:number = 0;
    return index;
  };
  inputMethodController.off('getTextIndexAtCursor', getTextIndexAtCursorCallback);
  inputMethodController.off('getTextIndexAtCursor');
} catch(err) {
  console.error(`Failed to unsubscribing getTextIndexAtCursor. err: ${JSON.stringify(err)}`);
}

on('setPreviewText')¹⁷⁺

on(type: 'setPreviewText', callback: SetPreviewTextCallback): void

Subscribes to the event for text preview operations in an input method application. This API uses an asynchronous callback to return the result.

NOTE

To use the text preview function, you need to subscribe to this event before calling attach and subscribe to this event together with on('finishTextPreview').

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

let setPreviewTextCallback1: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range) => {
  console.info(`SetPreviewTextCallback1: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let setPreviewTextCallback2: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range) => {
  console.info(`setPreviewTextCallback2: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

try {
  inputMethodController.on('setPreviewText', setPreviewTextCallback1);
  console.info(`SetPreviewTextCallback1 subscribed to setPreviewText`);
  inputMethodController.on('setPreviewText', setPreviewTextCallback2);
  console.info(`SetPreviewTextCallback2 subscribed to setPreviewText`);
  // Cancel only the callback1 of setPreviewText.
  inputMethodController.off('setPreviewText', setPreviewTextCallback1);
  console.info(`SetPreviewTextCallback1 unsubscribed from setPreviewText`);
  // Cancel all callbacks of setPreviewText.
  inputMethodController.off('setPreviewText');
  console.info(`All callbacks unsubscribed from setPreviewText`);
} catch(err) {
  console.error(`Failed to operate on setPreviewText: ${JSON.stringify(err)}`);
}

off('setPreviewText')¹⁷⁺

off(type: 'setPreviewText', callback?: SetPreviewTextCallback): void

Unsubscribes from the event for text preview operations in an input method application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let setPreviewTextCallback1: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range) => {
  console.info(`SetPreviewTextCallback1: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let setPreviewTextCallback2: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range) => {
  console.info(`setPreviewTextCallback2: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

try {
  inputMethodController.on('setPreviewText', setPreviewTextCallback1);
  console.info(`SetPreviewTextCallback1 subscribed to setPreviewText`);
  inputMethodController.on('setPreviewText', setPreviewTextCallback2);
  console.info(`SetPreviewTextCallback2 subscribed to setPreviewText`);
  // Cancel only the callback1 of setPreviewText.
  inputMethodController.off('setPreviewText', setPreviewTextCallback1);
  console.info(`SetPreviewTextCallback1 unsubscribed from setPreviewText`);
  // Cancel all callbacks of setPreviewText.
  inputMethodController.off('setPreviewText');
  console.info(`All callbacks unsubscribed from setPreviewText`);
} catch(err) {
  console.error(`Failed to operate on setPreviewText: ${JSON.stringify(err)}`);
}

on('finishTextPreview')¹⁷⁺

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

Subscribes to the event of finishing text preview. This API uses an asynchronous callback to return the result.

NOTE

To use the text preview function, you need to subscribe to this event before calling attach and subscribe to this event together with on('setPreviewText').

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

let finishTextPreviewCallback1 = () => {
  console.info(`FinishTextPreviewCallback1: finishTextPreview event triggered`);
};
let finishTextPreviewCallback2 = () => {
  console.info(`FinishTextPreviewCallback2: finishTextPreview event triggered`);
};

try {
  inputMethodController.on('finishTextPreview', finishTextPreviewCallback1);
  console.info(`FinishTextPreviewCallback1 subscribed to finishTextPreview`);
  inputMethodController.on('finishTextPreview', finishTextPreviewCallback2);
  console.info(`FinishTextPreviewCallback2 subscribed to finishTextPreview`);
  // Cancel only the callback1 of finishTextPreview.
  inputMethodController.off('finishTextPreview', finishTextPreviewCallback1);
  console.info(`FinishTextPreviewCallback1 unsubscribed from finishTextPreview`);
  // Cancel all callbacks of finishTextPreview.
  inputMethodController.off('finishTextPreview');
  console.info(`All callbacks unsubscribed from finishTextPreview`);
} catch(err) {
  console.error(`Failed to operate on finishTextPreview (subscribe/off): ${JSON.stringify(err)}`);
}

off('finishTextPreview')¹⁷⁺

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

Unsubscribes from the event of finishing text preview. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

let finishTextPreviewCallback1 = () => {
  console.info(`FinishTextPreviewCallback1: finishTextPreview event triggered`);
};
let finishTextPreviewCallback2 = () => {
  console.info(`FinishTextPreviewCallback2: finishTextPreview event triggered`);
};

try {
  inputMethodController.on('finishTextPreview', finishTextPreviewCallback1);
  console.info(`FinishTextPreviewCallback1 subscribed to finishTextPreview`);
  inputMethodController.on('finishTextPreview', finishTextPreviewCallback2);
  console.info(`FinishTextPreviewCallback2 subscribed to finishTextPreview`);
  // Cancel only the callback1 of finishTextPreview.
  inputMethodController.off('finishTextPreview', finishTextPreviewCallback1);
  console.info(`FinishTextPreviewCallback1 unsubscribed from finishTextPreview`);
  // Cancel all callbacks of finishTextPreview.
  inputMethodController.off('finishTextPreview');
  console.info(`All callbacks unsubscribed from finishTextPreview`);
} catch(err) {
  console.error(`Failed to operate on finishTextPreview (subscribe/off): ${JSON.stringify(err)}`);
}

InputMethodSetting⁸⁺

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

on('imeChange')⁹⁺

on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

import { InputMethodSubtype } from '@kit.IMEKit';
try {
  inputMethodSetting.on('imeChange', (inputMethodProperty: inputMethod.InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => {
    console.info('Succeeded in subscribing imeChange: inputMethodProperty: ' + JSON.stringify(inputMethodProperty) + " , inputMethodSubtype: " + JSON.stringify(inputMethodSubtype));
  });
} catch(err) {
  console.error(`Failed to unsubscribing inputMethodProperty. err: ${JSON.stringify(err)}`);
}

off('imeChange')⁹⁺

off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Example

inputMethodSetting.off('imeChange');

listInputMethodSubtype⁹⁺

listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void

Obtains all subtypes of a specified input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

let inputMethodProperty: inputMethod.InputMethodProperty = {
  name: 'com.example.kikakeyboard',
  id: 'propertyId',
  packageName: 'com.example.kikakeyboard',
  methodId: 'propertyId',
}
let inputMethodSetting = inputMethod.getSetting();
try {
  inputMethodSetting.listInputMethodSubtype(inputMethodProperty, (err: BusinessError, data: Array<InputMethodSubtype>) => {
    if (err) {
      console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in listing inputMethodSubtype.');
  });
} catch (err) {
  console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
}

listInputMethodSubtype⁹⁺

listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>>

Obtains all subtypes of a specified input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Return value

Error codes

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

Example

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

let inputMethodProperty: inputMethod.InputMethodProperty = {
  name: 'com.example.kikakeyboard',
  id: 'propertyId',
  packageName: 'com.example.kikakeyboard',
  methodId: 'propertyId',
}
let inputMethodSetting = inputMethod.getSetting();
try {
  inputMethodSetting.listInputMethodSubtype(inputMethodProperty).then((data: Array<InputMethodSubtype>) => {
    console.info('Succeeded in listing inputMethodSubtype.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
  })
} catch(err) {
  console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
}

listCurrentInputMethodSubtype⁹⁺

listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void

Obtains all subtypes of this input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Error codes

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

Example

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

let inputMethodSetting = inputMethod.getSetting();
try {
  inputMethodSetting.listCurrentInputMethodSubtype((err: BusinessError, data: Array<InputMethodSubtype>) => {
    if (err) {
      console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
      return;
    }
    console.info('Succeeded in listing currentInputMethodSubtype.');
  });
} catch(err) {
  console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}

listCurrentInputMethodSubtype⁹⁺

listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>>

Obtains all subtypes of this input method. This API uses a promise to return the result.