chrome.input.ime

重要提示：此 API 仅适用于 ChromeOS。

说明

使用 chrome.input.ime API 为 ChromeOS 实现自定义 IME。这样一来，您的扩展程序就可以处理按键、设置构图和管理候选窗口。

权限

input

您必须在扩展程序清单中声明“input”权限，才能使用 input.ime API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "input"
  ],
  ...
}

可用性

仅限 ChromeOS

示例

以下代码会创建一个 IME，用于将输入的字母转换为大写。

var context_id = -1;

chrome.input.ime.onFocus.addListener(function(context) {
  context_id = context.contextID;
});

chrome.input.ime.onKeyEvent.addListener(
  function(engineID, keyData) {
    if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
      chrome.input.ime.commitText({"contextID": context_id,
                                    "text": keyData.key.toUpperCase()});
      return true;
    } else {
      return false;
    }
  }
);

类型

AssistiveWindowButton

Chrome 85 及更高版本

辅助窗口中按钮的 ID。

枚举

"addToDictionary"

AssistiveWindowProperties

Chrome 85 及更高版本

辅助窗口的属性。

属性

• announceString

  字符串（可选）

  ChromeVox 朗读的字符串。

• 类型

• visible

  boolean

  设为 true 以显示 AssistiveWindow，设为 false 以显示 AssistiveWindow。

AssistiveWindowType

Chrome 85 及更高版本

辅助窗口的类型。

价值

AutoCapitalizeType

Chrome 69 及更高版本

文本字段的自动大写类型。

枚举

"sentences"

InputContext

描述输入上下文

属性

• autoCapitalize

  AutoCapitalizeType

  Chrome 69 及更高版本

  文本字段的自动大写类型。

• autoComplete

  boolean

  文本字段是否需要自动填充。

• autoCorrect

  boolean

  文本字段是否需要自动更正。

• contextID

  number

  用于指定文本字段操作的目标。调用 onBlur 后，此 ID 会立即失效。

• shouldDoLearning

  boolean

  Chrome 68 及更高版本

  是否应使用在文本字段输入的文本来改进用户的输入建议。

• spellCheck

  boolean

  文本字段是否需要拼写检查。

• 类型

  InputContextType

  此文本字段所修改的值的类型（文本、数字、网址等）

InputContextType

Chrome 44 及更高版本

此文本字段所修改的值的类型（文本、数字、网址等）

枚举

"tel"

"null"

KeyboardEvent

请参阅 http://www.w3.org/TR/DOM-Level-3-Events/#events-keyboardEvent

属性

• altKey

  布尔值（可选）

  是否按下 ALT 键。

• altgrKey

  布尔值（可选）

  Chrome 79 及更高版本

  是否按下了 ALTGR 键。

• capsLock

  布尔值（可选）

  是否启用 CAPS_LOCK。

• 验证码

  string

  被按下的实体按键的值。该值不受当前键盘布局或辅助键状态的影响。

• ctrlKey

  布尔值（可选）

  是否按下了 CTRL 键。

• extensionId

  字符串（可选）

  此关键事件的发送者的扩展程序 ID。

• key

  string

  所按的键的值

• keyCode

  编号（选填）

  已废弃的 HTML keyCode，它是依赖于系统和实现的数字代码，表示与按下的键相关联的未经修改的标识符。

• requestId

  字符串（可选）

  （已弃用）请求的 ID。请改用 onKeyEvent 事件中的 requestId 参数。

• shiftKey

  布尔值（可选）

  是否按下了 SHIFT 键。

• 类型

  KeyboardEventType

  keyup 或 keydown 之一。

KeyboardEventType

Chrome 44 及更高版本

枚举

"keyup"

MenuItem

输入法用来与语言菜单中的用户互动的菜单项。

属性

• 已勾选

  布尔值（可选）

  表示此项应在绘制时用勾选标记。

• 已启用

  布尔值（可选）

  表示此项已启用。

• id

  string

  将传递给引用此 MenuItem 的回调的字符串。

• 标签

  字符串（可选）

  菜单中针对此项显示的文字。

• 样式

  MenuItemStyle 可选

  菜单项的类型。

• visible

  布尔值（可选）

  表示此内容可见。

MenuItemStyle

Chrome 44 及更高版本

菜单项的类型。分隔符之间的单选按钮会被视为已分组。

枚举

"check"

"radio"

MenuParameters

Chrome 88 及更高版本

属性

• engineID

  string

  要使用的引擎的 ID。

• items

  MenuItem[]

  要添加或更新的 MenuItem。将按照它们在数组中存在的顺序添加。

MouseButton

Chrome 44 及更高版本

用户点击了哪些鼠标按钮。

枚举

"right"

ScreenType

Chrome 44 及更高版本

激活 IME 的屏幕类型。

枚举

UnderlineStyle

Chrome 44 及更高版本

用于修改此细分的下划线类型。

枚举

"doubleUnderline"

WindowPosition

Chrome 44 及更高版本

候选字词窗口的显示位置。如果设置为“cursor”，则窗口会跟随光标。如果设置为“composition”，则该窗口会锁定在合成内容的开头。

枚举

"cursor"

方法

clearComposition()

Promise

chrome.input.ime.clearComposition(
  parameters: object,
  callback?: function,
)

清除当前的乐曲。如果此扩展程序不拥有有效 IME，则测试将失败。

参数

• 形参

  对象

  • contextID

    number

    将清除组合的上下文的 ID

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

commitText()

Promise

chrome.input.ime.commitText(
  parameters: object,
  callback?: function,
)

将提供的文本提交到当前输入。

参数

• 形参

  对象

  • contextID

    number

    将提交文本的上下文的 ID

  • text

    string

    要提交的文本

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

deleteSurroundingText()

Promise

chrome.input.ime.deleteSurroundingText(
  parameters: object,
  callback?: function,
)

删除插入符号周围的文本。

参数

• 形参

  对象

  • contextID

    number

    将在其中删除周围文本的上下文的 ID。

  • engineID

    string

    接收事件的引擎的 ID。

  • length

    number

    要删除的字符数

  • offset

    number

    与开始删除的插入符号位置的偏移量。此值可以为负数。

• callback

  函数（可选）

  callback 参数的格式为：

  () => void

返回

• Promise<void>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

hideInputView()

chrome.input.ime.hideInputView()

隐藏输入视图窗口，该窗口由系统自动弹出。如果输入视图窗口已隐藏，此函数将不执行任何操作。

keyEventHandled()

chrome.input.ime.keyEventHandled(
  requestId: string,
  response: boolean,
)

表示处理 onKeyEvent 接收的按键事件。只有在 onKeyEvent 监听器为异步时，才应调用此方法。

参数

• requestId

  string

  已处理事件的请求 ID。应来自 keyEvent.requestId

• 条回复

  boolean

  如果处理了按键操作，则为 true，否则为 false

sendKeyEvents()

Promise

chrome.input.ime.sendKeyEvents(
  parameters: object,
  callback?: function,
)

发送按键事件。预计虚拟键盘会使用此函数。当用户按下虚拟键盘上的按键时，此函数用于向系统传播该事件。

参数

• 形参

  对象

  • contextID

    number

    将关键事件发送到的上下文的 ID；如果将关键事件发送到非输入字段，则为零。

  • keyData

    KeyboardEvent[]

    关键事件的相关数据。

• callback

  函数（可选）

  callback 参数的格式为：

  () => void

返回

• Promise<void>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setAssistiveWindowButtonHighlighted()

Promise Chrome 86 及更高版本

chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
  callback?: function,
)

突出显示/取消突出显示辅助窗口中的按钮。

参数

• 形参

  对象

  • announceString

    字符串（可选）

    屏幕阅读器要读出的文本。

  • buttonID

    AssistiveWindowButton

    按钮的 ID

  • contextID

    number

    拥有辅助窗口的上下文的 ID。

  • 突出显示

    boolean

    是否应突出显示按钮。

  • windowType

    按钮所属的窗口类型。

• callback

  函数（可选）

  callback 参数的格式为：

  () => void

返回

• Promise<void>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setAssistiveWindowProperties()

Promise Chrome 85 及更高版本

chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
  callback?: function,
)

显示/隐藏具有给定属性的辅助窗口。

参数

• 形参

  对象

  • contextID

    number

    拥有辅助窗口的上下文的 ID。

  • 媒体资源

    AssistiveWindowProperties

    辅助窗口的属性。

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setCandidates()

Promise

chrome.input.ime.setCandidates(
  parameters: object,
  callback?: function,
)

设置当前候选字词列表。如果此扩展程序不拥有有效的 IME，则会失败

参数

• 形参

  对象

  • 候选

    对象 []

    要在候选人窗口中显示的候选人列表

    • 注解

      字符串（可选）

      用于描述候选人的其他文字

    • 候选定位设置

      string

      候选人

    • id

      number

      候选人 ID

    • 标签

      字符串（可选）

      在候选字词旁边显示的短字符串，通常为快捷键或索引

    • parentId

      编号（选填）

      要添加这些候选人的 ID

    • 使用量

      对象（可选）

      字词的用途或详细说明。

      • body

        string

        详细描述的正文字符串。

      • title

        string

        详情说明的标题字符串。

  • contextID

    number

    拥有候选窗口的上下文的 ID。

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setCandidateWindowProperties()

Promise

chrome.input.ime.setCandidateWindowProperties(
  parameters: object,
  callback?: function,
)

设置候选窗口的属性。如果扩展程序不拥有有效 IME，则会失败

参数

• 形参

  对象

  • engineID

    string

    要为其设置属性的引擎的 ID。

  • 媒体资源

    对象

    • auxiliaryText

      字符串（可选）

      候选字词窗口底部显示的文本。

    • auxiliaryTextVisible

      布尔值（可选）

      True 表示显示辅助文本，false 表示隐藏辅助文本。

    • currentCandidateIndex

      编号（选填）

      Chrome 84 及更高版本

      当前所选候选者在总候选者中的索引。

    • cursorVisible

      布尔值（可选）

      True 表示显示光标，False 表示隐藏光标。

    • pageSize

      编号（选填）

      每页显示的候选字词数量。

    • totalCandidates

      编号（选填）

      Chrome 84 及更高版本

      候选人时段的候选人总数。

    • 类别

      布尔值（可选）

      如果应垂直渲染候选窗口，则为 true；如果应垂直渲染，则为 false。

    • visible

      布尔值（可选）

      值为 true 可显示“候选字词”窗口，值为 false 则隐藏该窗口。

    • windowPosition

      WindowPosition（可选）

      候选字词窗口的显示位置。

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setComposition()

Promise

chrome.input.ime.setComposition(
  parameters: object,
  callback?: function,
)

设置当前乐曲。如果此扩展程序不拥有有效 IME，则测试将失败。

参数

• 形参

  对象

  • contextID

    number

    将设置撰写文本的上下文 ID

  • cursor

    number

    光标文本中的位置。

  • 细分受众群

    object[] 可选

    细分及其相关类型的列表。

    • end

      number

      要在其后结束此句段的字符的索引。

    • start

      number

      此句段起始字符的索引

    • 样式

      UnderlineStyle

      用于修改此细分的下划线类型。

  • selectionEnd

    编号（选填）

    文本中选定内容结束的位置。

  • selectionStart

    编号（选填）

    文本中从选择内容开始的位置。

  • text

    string

    要设置的文本

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setCursorPosition()

Promise

chrome.input.ime.setCursorPosition(
  parameters: object,
  callback?: function,
)

设置候选窗口中的光标位置。如果此扩展程序不拥有有效 IME，则此项为空操作。

参数

• 形参

  对象

  • candidateID

    number

    要选择的候选人的 ID。

  • contextID

    number

    拥有候选窗口的上下文的 ID。

• callback

  函数（可选）

  callback 参数的格式为：

  (success: boolean) => void

  • 成功

    boolean

返回

• Promise<boolean>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

setMenuItems()

Promise

chrome.input.ime.setMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

当此 IME 处于活动状态时，将提供的菜单项添加到语言菜单。

参数

• 形参

  MenuParameters

• callback

  函数（可选）

  callback 参数的格式为：

  () => void

返回

• Promise<void>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

updateMenuItems()

Promise

chrome.input.ime.updateMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

更新指定的 MenuItem 的状态

参数

• 形参

  MenuParameters

• callback

  函数（可选）

  callback 参数的格式为：

  () => void

返回

• Promise<void>

  Chrome 111 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调的类型进行解析。

活动

onActivate

chrome.input.ime.onActivate.addListener(
  callback: function,
)

此事件在 IME 启用时发送。它表示 IME 将接收 onKeyPress 事件。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string, screen: ScreenType) => void

  • engineID

    string

  • 屏幕

    ScreenType

onAssistiveWindowButtonClicked

Chrome 85 及更高版本

chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

当用户点击辅助窗口中的按钮时，系统会发送此事件。

参数

• callback

  功能

  callback 参数的格式为：

  (details: object) => void

  • 详细信息

    对象

    • buttonID

      AssistiveWindowButton

      所点击按钮的 ID。

    • windowType

      AssistiveWindowType

      辅助窗口的类型。

onBlur

chrome.input.ime.onBlur.addListener(
  callback: function,
)

当焦点离开文本框时，系统会发送此事件。系统会将该事件发送到监听此事件并由用户启用的所有扩展程序。

参数

• callback

  功能

  callback 参数的格式为：

  (contextID: number) => void

  • contextID

    number

onCandidateClicked

chrome.input.ime.onCandidateClicked.addListener(
  callback: function,
)

如果此扩展程序拥有有效 IME，系统会发送此事件。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string, candidateID: number, button: MouseButton) => void

  • engineID

    string

  • candidateID

    number

  • 按钮

    MouseButton

onDeactivated

chrome.input.ime.onDeactivated.addListener(
  callback: function,
)

停用 IME 时发送此事件。它表示 IME 不再接收 onKeyPress 事件。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string) => void

  • engineID

    string

onFocus

chrome.input.ime.onFocus.addListener(
  callback: function,
)

当焦点进入文本框时发送此事件。系统会将该事件发送到监听此事件并由用户启用的所有扩展程序。

参数

• callback

  功能

  callback 参数的格式为：

  (context: InputContext) => void

  • context

    InputContext

onInputContextUpdate

chrome.input.ime.onInputContextUpdate.addListener(
  callback: function,
)

此事件在当前 InputContext 的属性（例如类型）发生更改时发送。系统会将该事件发送到监听此事件并由用户启用的所有扩展程序。

参数

• callback

  功能

  callback 参数的格式为：

  (context: InputContext) => void

  • context

    InputContext

onKeyEvent

chrome.input.ime.onKeyEvent.addListener(
  callback: function,
)

在操作系统发送关键事件时触发。如果该扩展程序拥有有效 IME，则会将该事件发送给该扩展程序。如果事件处理后为 false，则监听器函数应返回 true。如果将异步评估事件，则此函数必须返回未定义的值，且 IME 稍后必须调用 keyEventHandled() 并返回结果。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined

  • engineID

    string

  • keyData

    KeyboardEvent

  • requestId

    string

  • 返回

    布尔值 | 未定义

onMenuItemActivated

chrome.input.ime.onMenuItemActivated.addListener(
  callback: function,
)

在用户选择菜单项时调用

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string, name: string) => void

  • engineID

    string

  • name

    string

onReset

chrome.input.ime.onReset.addListener(
  callback: function,
)

当 Chrome 终止正在进行的文本输入会话时，系统会发送此事件。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string) => void

  • engineID

    string

onSurroundingTextChanged

chrome.input.ime.onSurroundingTextChanged.addListener(
  callback: function,
)

在插入符号周围的可编辑字符串发生变化或移动光标位置时调用。文本长度限制在两个方向上分别不超过 100 个字符。

参数

• callback

  功能

  callback 参数的格式为：

  (engineID: string, surroundingInfo: object) => void

  • engineID

    string

  • surroundingInfo

    对象

    • 锚标记

      number

      所选内容的开始位置。如果未做任何选择，此值表示插入符号的位置。

    • 焦点

      number

      所选内容的结束位置。如果未做任何选择，此值表示插入符号的位置。

    • offset

      number

      Chrome 46 及更高版本

      text 的偏移位置。由于 text 仅包含光标周围的文本子集，因此偏移量表示 text 第一个字符的绝对位置。

    • text

      string

      光标周围的文本。这只是输入字段中所有文本的子集。