目录

@ohos.InputMethodSubtype (Input Method Subtype)

The @ohos.InputMethodSubtype module provides data definitions for input method subtype properties. It supports describing subtype information of an input method for different languages or modes.

This module is the subtype data module of the input method framework. It defines the InputMethodSubtype interface, which is used to describe a specific input mode or language of an input method, such as Chinese keyboard, an English keyboard, or uppercase-mode keyboard. Each subtype represents the form of the input method in a specific language or mode.

This module provides capabilities for describing input method subtype properties. You can use InputMethodSubtype to obtain subtype identifiers (id, name), locale and language information (locale, language), display label (label), mode (mode: uppercase/lowercase), icon, and other properties. These are used for identification, display, and switching of input‑method subtypes.

Use this module when you need to query, display, or switch between different language‑ or mode‑based subtypes of an input method. Typical scenarios include: the system settings app displays a list of input method subtypes for user selection; an input‑method app switches languages or modes according to subtype information; an app obtains information about the current input method subtype.

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

InputMethodSubtype is a pure data definition module. Its objects are created and returned by the system framework, and cannot be constructed by you. Typical cross‑module usage process:

  1. Edit box app side (@ohos.inputMethod module): Queries the list of input method subtypes via InputMethodSetting.listInputMethodSubtype(), and switches to the specified subtype via inputMethod.switchCurrentInputMethodSubtype().

  2. Input method app side (@ohos.inputMethodEngine module): Listens for subtype switch events through InputMethodAbility.on('setSubtype'). The callback parameter is an InputMethodSubtype object, based on which the keyboard layout and language can be adjusted.

Core open capabilities of this module are provided by the key interface below:

Interface Description
InputMethodSubtype

Interface for input method subtype properties, which describes a specific language or mode form of an input method.

Mandatory properties: name (app bundle name), id (subtype ID), locale (locale), language (language).

Optional properties: label (label), labelId (label resource ID), mode (uppercase/lowercase mode), icon (icon), iconId (icon ID), and extra (extra information).

This module is a pure data definition module. As subtype description data, InputMethodSubtype must be used together with APIs from other modules. Typical usage combinations: query and switch subtypes via @ohos.inputMethod module using InputMethodSetting; listen for subtype switch events via InputMethodAbility in the @ohos.inputMethodEngine module.

// The following is pseudocode for illustrating the calling logic.

// 1. Query the input method subtype list (combined with the @ohos.inputMethod module).
let setting = inputMethod.getSetting();
let subtypes = setting.listInputMethodSubtype(inputMethodProperty);

// 2. Switch to the specified subtype.
inputMethod.switchCurrentInputMethodSubtype(targetSubtype);

InputMethodSubtype objects are created and returned by the system framework. You obtain these objects through query APIs of other modules and cannot construct them directly.

Modules to Import

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

InputMethodSubtype

Input method subtype attribute. Used to describe a specific language or mode form of an input method. Each subtype represents the form of an input method under a specific language or mode (for example, Chinese keyboard, English keyboard, uppercase‑mode keyboard). InputMethodSubtype objects are created and returned by the system framework and cannot be constructed by you.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read Only Optional Description
label string Yes Yes Label of the input method subtype. Used to display the subtype name in the UI, for example, "English".
labelId10+ number Yes Yes Label resource ID of the input method subtype. Used to load the label text through the resource ID, supporting internationalized label display in multi-language scenarios.
name string Yes No Bundle name of the app to which the input method subtype belongs. It must stay consistent with the bundleName configured in module.json5 of the input method app, and is used to identify which input method app the subtype belongs to.
id string Yes No ID of the input method subtype. It must stay consistent with the subtype id configured in module.json5 of the input method app, and is used to uniquely identify a subtype within the same input method app.
mode 'upper' | 'lower' Yes Yes Mode of the input method subtype, including upper (uppercase) and lower (lowercase). Used to describe the case state mode of the keyboard.
locale string Yes No Locale of the input method subtype. It follows the ICU locale format (separated by underscores, for example, 'zh_CN'), and is also compatible with the POSIX style (separated by hyphens, for example, 'zh-CN'). Used to identify the language and locale of the subtype.
language string Yes No Language of the input method subtype, for example, 'zh' (Chinese) and 'en' (English). Used to identify the language of the subtype, and is a subset of locale.
icon string Yes Yes Icon of the input method subtype, which can be obtained with iconId queried.
iconId number Yes Yes Icon ID of the input method subtype. Used to load the subtype icon through the resource ID.
extra object No Yes

Other information about the input method subtype.

NOTE

- Since API version 10, this is an optional parameter.

[h2]Parameter Usage Suggestions

name parameter:

id parameter:

locale parameter:

language parameter:

mode parameter:

label parameter:

labelId parameter:

icon and iconId parameters:

extra parameter: