说明
使用 chrome.input.ime API 为 Chrome OS 实现自定义 IME。这样，扩展程序就可以处理按键、设置组合并管理候选字窗口。
权限
input必须在扩展程序清单中声明“输入”权限，才能使用 input.ime API。例如：
{
"name": "My extension",
...
"permissions": [
"input"
],
...
}
可用性
示例
以下代码创建了一个将输入的字母转换为大写的 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
辅助窗口中按钮的 ID。
枚举
“撤消”
"addToDictionary"
AssistiveWindowProperties
辅助窗口的属性。
属性
-
announceString
字符串 可选
供 ChromeVox 朗读的字符串。
-
类型
“撤消”
-
可见
布尔值
设置为 true 可显示 AssistiveWindow，设置为 false 可隐藏。
AssistiveWindowType
辅助窗口的类型。
值
“撤消”
AutoCapitalizeType
文本字段的自动首字母大写类型。
枚举
"characters"
"words"
"sentences"
InputContext
描述输入上下文
属性
-
autoCapitalizeChrome 69 及更高版本
文本字段的自动首字母大写类型。
-
autoComplete
布尔值
文本字段是否需要自动补全。
-
autoCorrect
布尔值
文本字段是否需要自动更正。
-
contextID
数值
用于指定文本字段操作的目标。一旦调用 onBlur，此 ID 就会失效。
-
shouldDoLearning
布尔值
Chrome 68 及更高版本是否应使用在文本字段中输入的文本来改进用户的输入建议。
-
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 及更高版本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()
chrome.input.ime.clearComposition(
parameters: object,
): Promise<boolean>
清除当前乐曲。如果此扩展服务不拥有有效的 IME，则会失败。
参数
-
参数
对象
-
contextID
数值
将清除乐曲的上下文的 ID
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析，并提供一个布尔值来指明文本是否被接受。如果失败，promise 将被拒绝。
commitText()
chrome.input.ime.commitText(
parameters: object,
): Promise<boolean>
将提供的文本提交到当前输入。
参数
-
参数
对象
-
contextID
数值
将提交文本的上下文的 ID
-
text
字符串
要提交的文本
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析，并提供一个布尔值来指明文本是否被接受。如果失败，promise 将被拒绝。
deleteSurroundingText()
chrome.input.ime.deleteSurroundingText(
parameters: object,
): Promise<void>
删除插入符号周围的文字。
参数
-
参数
对象
-
contextID
数值
要删除周围文本的上下文的 ID。
-
engineID
字符串
接收事件的引擎的 ID。
-
长度
数值
要删除的字符数
-
offset
数值
从光标位置开始删除的偏移量。此值可以为负数。
-
返回
-
Promise<void>
Chrome 111 及更高版本在操作完成时解析。
hideInputView()
chrome.input.ime.hideInputView(): void
隐藏由系统自动弹出的输入视图窗口。如果输入视图窗口已隐藏，此函数将不执行任何操作。
keyEventHandled()
chrome.input.ime.keyEventHandled(
requestId: string,
response: boolean,
): void
表示 onKeyEvent 收到的关键事件已得到处理。仅当 onKeyEvent 监听器为异步时才应调用此方法。
参数
-
requestId
字符串
已处理的事件的请求 ID。此值应来自 keyEvent.requestId
-
Response
布尔值
如果按键操作已处理，则为 true；否则为 false
sendKeyEvents()
chrome.input.ime.sendKeyEvents(
parameters: object,
): Promise<void>
发送按键事件。此函数应由虚拟键盘使用。当用户按下虚拟键盘上的某个键时，此函数用于将该事件传播到系统。
参数
-
参数
对象
-
contextID
数值
将发送按键事件的上下文的 ID，如果为零，则将按键事件发送到非输入字段。
-
keyData
有关关键事件的数据。
-
返回
-
Promise<void>
Chrome 111 及更高版本在操作完成时解析。
setAssistiveWindowButtonHighlighted()
chrome.input.ime.setAssistiveWindowButtonHighlighted(
parameters: object,
): Promise<void>
突出显示/取消突出显示辅助窗口中的按钮。
参数
-
参数
对象
-
announceString
字符串 可选
供屏幕阅读器朗读的文字。
-
buttonID
按钮的 ID
-
contextID
数值
拥有辅助窗口的上下文的 ID。
-
突出显示
布尔值
按钮是否应突出显示。
-
windowType
“撤消”
按钮所属的窗口类型。
-
返回
-
Promise<void>
Chrome 111 及更高版本在操作完成时解析。如果失败，promise 将被拒绝。
setAssistiveWindowProperties()
chrome.input.ime.setAssistiveWindowProperties(
parameters: object,
): Promise<boolean>
显示/隐藏具有指定属性的辅助窗口。
参数
-
参数
对象
-
contextID
数值
拥有辅助窗口的上下文的 ID。
-
辅助窗口的属性。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析。
setCandidates()
chrome.input.ime.setCandidates(
parameters: object,
): Promise<boolean>
设置当前候选字词列表。如果相应扩展程序不拥有有效的 IME，则此方法会失败
参数
-
参数
对象
-
候选
object[]
要在候选字词窗口中显示的候选字词列表
-
annotation
字符串 可选
描述候选人的其他文本
-
候选定位设置
字符串
候选人
-
id
数值
候选人的 ID
-
标签
字符串 可选
显示在候选对象旁边的短字符串，通常是快捷键或索引
-
parentId
number 可选
要将这些候选人添加到哪个 ID 下
-
使用量
对象（可选）
相应字词的用法或详细说明。
-
body
字符串
详细说明的正文字符串。
-
title
字符串
详细说明的标题字符串。
-
-
-
contextID
数值
拥有候选窗口的上下文的 ID。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析。
setCandidateWindowProperties()
chrome.input.ime.setCandidateWindowProperties(
parameters: object,
): Promise<boolean>
设置候选窗口的属性。如果扩展程序不拥有活跃的 IME，则此方法会失败
参数
-
参数
对象
-
engineID
字符串
要设置属性的引擎的 ID。
-
属性
对象
-
auxiliaryText
字符串 可选
显示在候选窗口底部的文字。
-
auxiliaryTextVisible
布尔值 （可选）
如果为 true，则显示辅助文本；如果为 false，则隐藏辅助文本。
-
currentCandidateIndex
number 可选
Chrome 84 及更高版本当前所选候选人在所有候选人中的索引。
-
cursorVisible
布尔值 （可选）
设置为 true 可显示光标，设置为 false 可隐藏光标。
-
pageSize
number 可选
每页显示的候选字词数。
-
totalCandidates
number 可选
Chrome 84 及更高版本候选字词窗口中的候选字词总数。
-
类别
布尔值 （可选）
如果候选窗口应垂直呈现，则为 true；如果应水平呈现，则为 false。
-
可见
布尔值 （可选）
如果为 true，则显示候选字窗口；如果为 false，则隐藏候选字窗口。
-
windowPosition
候选字词窗口的显示位置。
-
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析。
setComposition()
chrome.input.ime.setComposition(
parameters: object,
): Promise<boolean>
设置当前合成。如果此扩展服务不拥有有效的 IME，则会失败。
参数
-
参数
对象
-
contextID
数值
将设置撰写文本的上下文的 ID
-
cursor
数值
光标在文本中的位置。
-
细分
object[] 可选
细分及其关联类型的列表。
-
end
数值
相应字符的索引，用于指定此片段的结束位置。
-
start
数值
相应分段的起始字符的索引
-
要修改相应细分的下划线类型。
-
-
selectionEnd
number 可选
选择内容在文本中的结束位置。
-
selectionStart
number 可选
选中内容在文本中的起始位置。
-
text
字符串
要设置的文本
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析，并提供一个布尔值来指明文本是否被接受。如果失败，promise 将被拒绝。
setCursorPosition()
chrome.input.ime.setCursorPosition(
parameters: object,
): Promise<boolean>
设置候选字窗口中光标的位置。如果此扩展程序不拥有有效的 IME，则此方法不执行任何操作。
参数
-
参数
对象
-
candidateID
数值
要选择的候选对象的 ID。
-
contextID
数值
拥有候选窗口的上下文的 ID。
-
返回
-
Promise<boolean>
Chrome 111 及更高版本在操作完成时解析
setMenuItems()
chrome.input.ime.setMenuItems(
parameters: MenuParameters,
): Promise<void>
当此 IME 处于活动状态时，将提供的菜单项添加到语言菜单。
参数
返回
-
Promise<void>
Chrome 111 及更高版本
updateMenuItems()
chrome.input.ime.updateMenuItems(
parameters: MenuParameters,
): Promise<void>
更新指定 MenuItem 的状态
参数
返回
-
Promise<void>
Chrome 111 及更高版本在操作完成时解析
事件
onActivate
chrome.input.ime.onActivate.addListener(
callback: function,
)
此事件在 IME 处于活动状态时发送。它表示 IME 将接收 onKeyPress 事件。
参数
-
callback
函数
callback参数的格式如下：(engineID: string, screen: ScreenType) => void
-
engineID
字符串
-
屏幕
-
onAssistiveWindowButtonClicked
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
callback: function,
)
当辅助窗口中的按钮被点击时，系统会发送此事件。
参数
-
callback
函数
callback参数的格式如下：(details: object) => void
-
详细信息
对象
-
buttonID
所点击按钮的 ID。
-
windowType
辅助窗口的类型。
-
-
onBlur
chrome.input.ime.onBlur.addListener(
callback: function,
)
此事件在焦点离开文本框时发送。它会发送给所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数的格式如下：(contextID: number) => void
-
contextID
数值
-
onCandidateClicked
chrome.input.ime.onCandidateClicked.addListener(
callback: function,
)
如果此扩展程序拥有有效的 IME，则会发送此事件。
参数
-
callback
函数
callback参数的格式如下：(engineID: string, candidateID: number, button: MouseButton) => void
-
engineID
字符串
-
candidateID
数值
-
按钮
-
onDeactivated
chrome.input.ime.onDeactivated.addListener(
callback: function,
)
此事件在 IME 被停用时发送。表示 IME 将不再接收 onKeyPress 事件。
参数
-
callback
函数
callback参数的格式如下：(engineID: string) => void
-
engineID
字符串
-
onFocus
chrome.input.ime.onFocus.addListener(
callback: function,
)
当焦点进入文本框时，系统会发送此事件。它会发送给所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数的格式如下：(context: InputContext) => void
-
context
-
onInputContextUpdate
chrome.input.ime.onInputContextUpdate.addListener(
callback: function,
)
当当前 InputContext 的属性（例如类型）发生更改时，系统会发送此事件。它会发送给所有正在监听此事件且已由用户启用的扩展程序。
参数
-
callback
函数
callback参数的格式如下：(context: InputContext) => void
-
context
-
onKeyEvent
chrome.input.ime.onKeyEvent.addListener(
callback: function,
)
当操作系统发送按键事件时触发。如果扩展程序拥有有效的 IME，则系统会将事件发送给该扩展程序。如果事件已处理，监听器函数应返回 true；如果未处理，则应返回 false。如果事件将异步评估，则此函数必须返回未定义，并且 IME 必须稍后使用结果调用 keyEventHandled()。
参数
-
callback
函数
callback参数的格式如下：(engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined
-
engineID
字符串
-
keyData
-
requestId
字符串
-
返回
布尔值 | 未定义
-
onMenuItemActivated
chrome.input.ime.onMenuItemActivated.addListener(
callback: function,
)
当用户选择菜单项时调用
参数
-
callback
函数
callback参数的格式如下：(engineID: string, name: string) => void
-
engineID
字符串
-
name
字符串
-
onReset
chrome.input.ime.onReset.addListener(
callback: function,
)
当 Chrome 终止正在进行的文本输入会话时，系统会发送此事件。
参数
-
callback
函数
callback参数的格式如下：(engineID: string) => void
-
engineID
字符串
-
onSurroundingTextChanged
chrome.input.ime.onSurroundingTextChanged.addListener(
callback: function,
)
当插入符号周围的可编辑字符串发生更改或插入符号位置发生移动时调用。每个来回方向的文本长度上限为 100 个字符。
参数
-
callback
函数
callback参数的格式如下：(engineID: string, surroundingInfo: object) => void
-
engineID
字符串
-
surroundingInfo
对象
-
anchor
数值
所选内容的起始位置。如果没有选择内容，此值表示光标位置。
-
焦点
数值
所选内容的结束位置。如果没有选择内容，此值表示光标位置。
-
offset
数值
Chrome 46 及更高版本text的偏移位置。由于text仅包含光标周围的部分文本，因此 offset 表示text的第一个字符的绝对位置。 -
text
字符串
光标周围的文本。这只是输入字段中所有文本的一部分。
-
-