说明
使用 chrome.input.ime API 为 ChromeOS 实现自定义 IME。这样，您的扩展程序就可以处理按键、设置组合和管理候选窗口。
权限
input必须在扩展程序清单中声明“input”权限，才能使用 input.ime API。例如：
{
"name": "My extension",
...
"permissions": [
"input"
],
...
}
可用性
示例
以下代码会创建一个 IME，用于将输入的字母转换为大写。
var context_id = -1;
browser.input.ime.onFocus.addListener(function(context) {
context_id = context.contextID;
});
browser.input.ime.onKeyEvent.addListener(
function(engineID, keyData) {
if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
browser.input.ime.commitText({"contextID": context_id,
"text": keyData.key.toUpperCase()});
return true;
} else {
return false;
}
}
);
类型
AssistiveWindowButton
辅助窗口中按钮的 ID。
枚举
"undo"
"addToDictionary"
AssistiveWindowProperties
辅助窗口的属性。
属性
-
announceString
字符串 可选
ChromeVox 要朗读的字符串。
-
类型
"undo"
-
可见
布尔值
设置为 true 可显示 AssistiveWindow，设置为 false 可隐藏。
AssistiveWindowType
辅助窗口的类型。
值
"undo"
AutoCapitalizeType
文本字段的自动大写类型。
枚举
"characters"
"words"
"sentences"
InputContext
描述输入上下文
属性
-
autoCapitalizeChrome 69 及更高版本 browser.*（自 Chrome 148 起）
文本字段的自动大写类型。
-
autoComplete
布尔值
文本字段是否需要自动补全。
-
autoCorrect
布尔值
文本字段是否需要自动更正。
-
contextID
数值
此参数用于指定文本字段操作的目标。调用 onBlur 后，此 ID 就会失效。
-
shouldDoLearning
布尔值
Chrome 68 及更高版本 browser.*（自 Chrome 148 起）是否应使用在文本字段中输入的文本来改进为用户提供的输入建议。
-
spellCheck
布尔值
文本字段是否需要拼写检查。
-
此文本字段编辑的值类型（文本、数字、网址等）
InputContextType
此文本字段编辑的值类型（文本、数字、网址等）
枚举
"text"
"search"
"tel"
"url"
"email"
"number"
"password"
"null"
KeyboardEvent
请参阅 http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
属性
-
altKey
布尔值 （可选）
是否按下了 ALT 键。
-
altgrKey
布尔值 （可选）
Chrome 79 及更高版本 browser.*（自 Chrome 148 起）是否按下了 ALTGR 键。
-
capsLock
布尔值 （可选）
是否已启用 CAPS_LOCK。
-
代码
字符串
所按实体键的值。该值不受当前键盘布局或修饰键状态的影响。
-
ctrlKey
布尔值 （可选）
是否按下了 Ctrl 键。
-
extensionId
字符串 可选
此按键事件的发送者的扩展程序 ID。
-
键
字符串
所按键的值
-
keyCode
number 可选
已弃用的 HTML keyCode，它是取决于系统和实现的数字代码，表示与所按键关联的未修改标识符。
-
requestId
字符串 可选
（已弃用）请求的 ID。请改用
onKeyEvent事件中的requestId参数。 -
shiftKey
布尔值 （可选）
是否按下了 SHIFT 键。
-
keyup 或 keydown。
KeyboardEventType
枚举
"keyup"
"keydown"
MenuItem
输入法用于通过语言菜单与用户互动的菜单项。
属性
-
已勾选
布尔值 （可选）
表示此项应绘制为勾选状态。
-
已启用
布尔值 （可选）
表示此项已启用。
-
id
字符串
将传递给引用此 MenuItem 的回调的字符串。
-
标签
字符串 可选
此条目在菜单中显示的文本。
-
样式
菜单项的类型。
-
可见
布尔值 （可选）
表示此内容可见。
MenuItemStyle
菜单项的类型。分隔符之间的单选按钮会被视为一组。
枚举
"check"
"radio"
"separator"
MenuParameters
属性
-
engineID
字符串
要使用的引擎的 ID。
-
项目
MenuItem[]
要添加或更新的 MenuItem。这些工具将按照其在数组中的顺序进行添加。
MouseButton
点击了哪些鼠标按钮。
枚举
"left"
"middle"
"right"
ScreenType
激活 IME 的屏幕类型。
枚举
"normal"
"login"
"lock"
"secondary-login"
UnderlineStyle
用于修改此片段的下划线类型。
枚举
"underline"
"doubleUnderline"
"noUnderline"
WindowPosition
候选字词窗口的显示位置。如果设置为“cursor”，窗口会跟随光标。如果设置为“composition”，则窗口会锁定到乐曲的开头。
枚举
"cursor"
"composition"
方法
clearComposition()
browser.input.ime.clearComposition(
parameters: object,
): Promise<boolean>
清除当前创作内容。如果此扩展程序不拥有活跃的 IME，则此操作会失败。
参数
-
参数
对象
-
contextID
数值
要清除组合的上下文的 ID
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析，并返回一个布尔值，指示文本是否被接受。如果失败，promise 将被拒绝。
commitText()
browser.input.ime.commitText(
parameters: object,
): Promise<boolean>
将提供的文本提交到当前输入。
参数
-
参数
对象
-
contextID
数值
要提交文本的上下文的 ID
-
text
字符串
要提交的文本
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析，并返回一个布尔值，指示文本是否被接受。如果失败，promise 将被拒绝。
deleteSurroundingText()
browser.input.ime.deleteSurroundingText(
parameters: object,
): Promise<void>
删除光标周围的文本。
参数
-
参数
对象
-
contextID
数值
要删除周围文本的上下文的 ID。
-
engineID
字符串
接收事件的引擎的 ID。
-
长度
数值
要删除的字符数
-
offset
数值
从光标位置开始删除的偏移量。此值可以为负数。
-
返回
-
承诺<void>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。
hideInputView()
browser.input.ime.hideInputView(): void
隐藏由系统自动弹出的输入视图窗口。如果输入视图窗口已隐藏，此函数将不执行任何操作。
keyEventHandled()
browser.input.ime.keyEventHandled(
requestId: string,
response: boolean,
): void
表示已处理 onKeyEvent 接收到的按键事件。只有在 onKeyEvent 监听器是异步的情况下，才应调用此方法。
参数
-
requestId
字符串
已处理事件的请求 ID。此值应来自 keyEvent.requestId
-
Response
布尔值
如果按键操作已处理，则为 true；否则为 false
sendKeyEvents()
browser.input.ime.sendKeyEvents(
parameters: object,
): Promise<void>
发送按键事件。此函数应由虚拟键盘使用。当用户按下虚拟键盘上的按键时，此函数用于将该事件传播到系统。
参数
-
参数
对象
-
contextID
数值
要将按键事件发送到的上下文的 ID，或设为 0 以将按键事件发送到非输入字段。
-
keyData
关键事件的相关数据。
-
返回
-
承诺<void>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。
setAssistiveWindowButtonHighlighted()
browser.input.ime.setAssistiveWindowButtonHighlighted(
parameters: object,
): Promise<void>
突出显示/取消突出显示辅助窗口中的按钮。
参数
-
参数
对象
-
announceString
字符串 可选
屏幕阅读器要朗读的文本。
-
buttonID
按钮的 ID
-
contextID
数值
拥有辅助窗口的上下文的 ID。
-
突出显示
布尔值
是否应突出显示按钮。
-
windowType
"undo"
按钮所属的窗口类型。
-
返回
-
承诺<void>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。如果失败，promise 将被拒绝。
setAssistiveWindowProperties()
browser.input.ime.setAssistiveWindowProperties(
parameters: object,
): Promise<boolean>
显示/隐藏具有给定属性的辅助窗口。
参数
-
参数
对象
-
contextID
数值
拥有辅助窗口的上下文的 ID。
-
辅助窗口的属性。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。
setCandidates()
browser.input.ime.setCandidates(
parameters: object,
): Promise<boolean>
设置当前候选字词列表。如果此扩展程序不拥有活跃的 IME，则此操作会失败
参数
-
参数
对象
-
候选
object[]
要在候选字词窗口中显示的候选字词列表
-
annotation
字符串 可选
描述候选对象的其他文本
-
候选定位设置
字符串
候选人
-
id
数值
候选对象的 ID
-
标签
字符串 可选
候选字词旁边显示的短字符串，通常是快捷键或索引
-
parentId
number 可选
要将这些候选人添加到的 ID
-
使用量
对象（可选）
字词的用法或详细说明。
-
正文
字符串
详细说明的正文字符串。
-
title
字符串
详细说明的标题字符串。
-
-
-
contextID
数值
拥有候选窗口的上下文的 ID。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。
setCandidateWindowProperties()
browser.input.ime.setCandidateWindowProperties(
parameters: object,
): Promise<boolean>
设置候选窗口的属性。如果扩展程序不拥有活跃的 IME，则此操作会失败
参数
-
参数
对象
-
engineID
字符串
要设置属性的引擎的 ID。
-
属性
对象
-
auxiliaryText
字符串 可选
候选字词窗口底部显示的文本。
-
auxiliaryTextVisible
布尔值 （可选）
如果为 true，则显示辅助文本；如果为 false，则隐藏辅助文本。
-
currentCandidateIndex
number 可选
Chrome 84 及更高版本 browser.*（自 Chrome 148 起）当前所选候选词在所有候选词中的索引。
-
cursorVisible
布尔值 （可选）
如果为 true，则显示光标；如果为 false，则隐藏光标。
-
pageSize
number 可选
每页显示的候选人数量。
-
totalCandidates
number 可选
Chrome 84 及更高版本 browser.*（自 Chrome 148 起）候选窗口中的候选集总数。
-
类别
布尔值 （可选）
如果候选字词窗口应垂直呈现，则为 true；如果应水平呈现，则为 false。
-
可见
布尔值 （可选）
如果为 true，则显示候选字词窗口；如果为 false，则隐藏该窗口。
-
windowPosition
候选字词窗口的显示位置。
-
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析。
setComposition()
browser.input.ime.setComposition(
parameters: object,
): Promise<boolean>
设置当前组合。如果此扩展程序不拥有活跃的 IME，则此操作会失败。
参数
-
参数
对象
-
contextID
数值
要设置组合文本的上下文的 ID
-
cursor
数值
光标在文本中的位置。
-
细分
object[] 可选
细分受众群及其关联类型的列表。
-
end
数值
此片段结束位置之后的字符索引。
-
start
数值
此片段的起始字符索引
-
用于修改此片段的下划线类型。
-
-
selectionEnd
number 可选
所选内容在文本中的结束位置。
-
selectionStart
number 可选
所选内容在文本中的起始位置。
-
text
字符串
要设置的文本
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析，并返回一个布尔值，指示文本是否被接受。如果失败，promise 将被拒绝。
setCursorPosition()
browser.input.ime.setCursorPosition(
parameters: object,
): Promise<boolean>
设置光标在候选字词窗口中的位置。如果此扩展程序不拥有活跃的 IME，则此操作无效。
参数
-
参数
对象
-
candidateID
数值
要选择的候选推介对象的 ID。
-
contextID
数值
拥有候选窗口的上下文的 ID。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析
setMenuItems()
browser.input.ime.setMenuItems(
parameters: MenuParameters,
): Promise<void>
当此 IME 处于活动状态时，将提供的菜单项添加到语言菜单中。
参数
返回
-
承诺<void>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）
updateMenuItems()
browser.input.ime.updateMenuItems(
parameters: MenuParameters,
): Promise<void>
更新指定 MenuItems 的状态
参数
返回
-
承诺<void>
Chrome 111 及更高版本 browser.*（自 Chrome 148 起）在操作完成时解析
事件
onActivate
browser.input.ime.onActivate.addListener(
callback: function,
)
此事件会在 IME 激活时发送。它表示 IME 将接收 onKeyPress 事件。
参数
-
callback
函数
callback参数如下所示：(engineID: string, screen: ScreenType) => void
-
engineID
字符串
-
屏幕
-
onAssistiveWindowButtonClicked
browser.input.ime.onAssistiveWindowButtonClicked.addListener(
callback: function,
)
当用户点击辅助窗口中的按钮时，系统会发送此事件。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
buttonID
所点击按钮的 ID。
-
windowType
辅助窗口的类型。
-
-
onBlur
browser.input.ime.onBlur.addListener(
callback: function,
)
当焦点离开文本框时，系统会发送此事件。此事件会发送到所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数如下所示：(contextID: number) => void
-
contextID
数值
-
onCandidateClicked
browser.input.ime.onCandidateClicked.addListener(
callback: function,
)
如果此扩展程序拥有活跃的 IME，则会发送此事件。
参数
-
callback
函数
callback参数如下所示：(engineID: string, candidateID: number, button: MouseButton) => void
-
engineID
字符串
-
candidateID
数值
-
按钮
-
onDeactivated
browser.input.ime.onDeactivated.addListener(
callback: function,
)
当 IME 停用时，系统会发送此事件。这表示 IME 将不再接收 onKeyPress 事件。
参数
-
callback
函数
callback参数如下所示：(engineID: string) => void
-
engineID
字符串
-
onFocus
browser.input.ime.onFocus.addListener(
callback: function,
)
当焦点进入文本框时，系统会发送此事件。此事件会发送到所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数如下所示：(context: InputContext) => void
-
context
-
onInputContextUpdate
browser.input.ime.onInputContextUpdate.addListener(
callback: function,
)
当当前 InputContext 的属性（例如类型）发生变化时，系统会发送此事件。此事件会发送到所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数如下所示：(context: InputContext) => void
-
context
-
onKeyEvent
browser.input.ime.onKeyEvent.addListener(
callback: function,
)
在操作系统发送按键事件时触发。如果此扩展程序拥有活跃的 IME，则事件将发送到该扩展程序。如果事件已处理，监听器函数应返回 true，否则返回 false。如果事件将异步评估，则此函数必须返回 undefined，并且 IME 稍后必须使用结果调用 keyEventHandled()。
参数
-
callback
函数
callback参数如下所示：(engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined
-
engineID
字符串
-
keyData
-
requestId
字符串
-
返回
boolean | undefined
-
onMenuItemActivated
browser.input.ime.onMenuItemActivated.addListener(
callback: function,
)
在用户选择菜单项时调用
参数
-
callback
函数
callback参数如下所示：(engineID: string, name: string) => void
-
engineID
字符串
-
name
字符串
-
onReset
browser.input.ime.onReset.addListener(
callback: function,
)
当 Chrome 终止正在进行的文本输入会话时，系统会发送此事件。
参数
-
callback
函数
callback参数如下所示：(engineID: string) => void
-
engineID
字符串
-
onSurroundingTextChanged
browser.input.ime.onSurroundingTextChanged.addListener(
callback: function,
)
当光标周围的可修改字符串发生更改或光标位置发生移动时调用。每个来回方向的文本长度上限为 100 个字符。
参数
-
callback
函数
callback参数如下所示：(engineID: string, surroundingInfo: object) => void
-
engineID
字符串
-
surroundingInfo
对象
-
anchor
数值
所选内容的起始位置。如果未选择任何内容，此值表示光标位置。
-
焦点
数值
所选内容的结束位置。如果未选择任何内容，此值表示光标位置。
-
offset
数值
Chrome 46 及更高版本 browser.*（自 Chrome 148 起）text的偏移位置。由于text仅包含光标周围的部分文本，因此偏移量表示text第一个字符的绝对位置。 -
text
字符串
光标周围的文本。这只是输入字段中所有文本的一部分。
-
-