chrome.input.ime
| 描述： |
使用 chrome.input.ime API 为 Chrome OS 实现自定义的输入法，它允许您的扩展程序处理键盘输入、设置候选内容及管理候选窗口。
|
| 可用版本： |
从 Chrome 21 开始稳定支持。
|
| 权限： |
"input"
|
清单文件
您必须在扩展程序的清单文件中声明
"input" 权限才能使用输入法 API。例如：
{
"name": "我的扩展程序",
...
"permissions": [
"input"
],
...
}
例子
如下代码创建一个将输入字母转换为大写的输入法：
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;
}
});
有关使用该API的一个例子，请参见基本的 input.ime 示例。有关其他例子以及查看源代码的帮助，请参见示例。
类型
KeyboardEvent
参见 http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent。
-
type
(
enum of "keyup", or "keydown"
)
-
"keyup"（按键弹起）或 "keydown"（按键按下）。
-
requestId
(
string
)
-
请求标识符。
-
code
(
string
)
-
按下的物理按键的值，不受当前键盘布局或组合键状态的影响。
-
altKey
(
optional
boolean
)
-
是否按下了 Alt 键。
-
ctrlKey
(
optional
boolean
)
-
是否按下了 Ctrl 键。
-
shiftKey
(
optional
boolean
)
-
是否按下了 Shift 键。
-
capsLock
(
optional
boolean
)
-
Caps Lock 键是否启用。
InputContext
描述输入上下文。
-
contextID
(
integer
)
-
该属性用来指定文本框操作的目标，一旦接收到 onBlur 事件该标识符就不再有效。
-
type
(
enum of "text", "search", "tel", "url", "email", or "number"
)
-
该文本框编辑的值的类型：文本、数字、URL 等。Type of value this text field edits, (Text, Number, URL, etc)
在语言菜单中，输入法用来与用户交互的菜单项。
-
-
代表这一菜单项是否是："check"（复选）、"radio"（单选）或 "separator"（分隔符）的枚举值。在分隔符之间的单选按钮将认为是同一组的。
方法
setComposition
chrome.input.ime.setComposition(object parameters, function callback)
设置当前的候选内容。如果当前扩展程序没有独占当前输入法，该方法将会失败。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
需要设置候选本文的上下文标识符。
-
selectionStart
(
optional
integer
)
-
选定内容在文本中的起始位置。
-
selectionEnd
(
optional
integer
)
-
选定内容在文本中的结束位置。
-
cursor
(
integer
)
-
光标在文本中的位置。
-
segments
(
optional
array of object
)
-
片段列表以及与它们相关的类型。
每一个对象的属性
-
-
start
(
integer
)
-
当前片段开始的字符索引。
-
end
(
integer
)
-
当前片段结束后的字符索引。
-
style
(
enum of "underline", or "doubleUnderline"
)
-
如何呈现这一片段。
-
callback
(
optional
function
)
-
当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
clearComposition
chrome.input.ime.clearComposition(object parameters, function callback)
清除当前的候选内容。如果当前扩展程序没有独占当前输入法，该方法将会失败。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
需要清除候选内容的上下文标识符。
-
callback
(
optional
function
)
-
当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
commitText
chrome.input.ime.commitText(object parameters, function callback)
将提供的文本提交至当前输入。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
需要提交文本的上下文标识符。
-
callback
(
optional
function
)
-
当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
sendKeyEvents
chrome.input.ime.sendKeyEvents(object parameters, function callback)
发送键盘事件，该函数由虚拟键盘使用。用户按下虚拟键盘上的按键时，该函数可以用来将该事件传播给系统。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
发送键盘事件的上下文标识符。
-
callback
(
optional
function
)
-
操作完成时调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
chrome.input.ime.hideInputView()
隐藏系统自动弹出的输入视图窗口。如果输入视图窗口已经隐藏，该函数不进行任何操作。
setCandidateWindowProperties
chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)
设置候选窗口的属性。如果当前扩展程序没有独占当前输入法，该方法将会失败。
参数
-
parameters
(
object
)
-
-
属性
-
engineID
(
string
)
-
要设置属性的引擎标识符。
-
properties
(
object
)
-
-
属性
-
visible
(
optional
boolean
)
-
要显示候选窗口则为 true，隐藏则为 false。
-
cursorVisible
(
optional
boolean
)
-
要显示光标则为 true，隐藏则为 false。
-
vertical
(
optional
boolean
)
-
如果候选窗口竖排则为 true，横排则为 false。
-
pageSize
(
optional
integer
)
-
每一页显示的候选项数目。
-
auxiliaryText
(
optional
string
)
-
候选窗口底部显示的文字。
-
auxiliaryTextVisible
(
optional
boolean
)
-
要显示辅助文字则为 true，隐藏则为 false。
-
windowPosition
(
optional
enum of "cursor", or "composition"
)
-
显示候选窗口的位置。如果设置为 'cursor'，窗口会跟随光标；如果设置为 'composition'，窗口会固定在候选内容的开头。
-
callback
(
optional
function
)
-
操作完成时调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
setCandidates
chrome.input.ime.setCandidates(object parameters, function callback)
设置当前的候选列表。如果当前扩展程序没有独占当前输入法，该方法将会失败。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
拥有候选窗口的上下文标识符。
-
candidates
(
array of object
)
-
在候选窗口中显示的候选项列表。
每一个对象的属性
-
-
candidate
(
string
)
-
候选项。
-
parentId
(
optional
integer
)
-
将这些候选项添加至其下的标识符。
-
label
(
optional
string
)
-
显示在候选项旁边的短字符串，通常为快捷键或索引。
-
annotation
(
optional
string
)
-
描述候选项的附加文字。
-
usage
(
optional
object
)
-
词语的用法或详细描述。
-
属性
-
title
(
string
)
-
详细描述的标题字符串。
-
body
(
string
)
-
详细描述的正文字符串。
-
callback
(
optional
function
)
-
操作完成时调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
setCursorPosition
chrome.input.ime.setCursorPosition(object parameters, function callback)
设置候选窗口中的光标位置。如果当前扩展程序没有独占当前输入法，则不进行任何操作。
参数
-
parameters
(
object
)
-
-
属性
-
contextID
(
integer
)
-
拥有候选窗口的上下文标识符。
-
candidateID
(
integer
)
-
选定的候选项标识符。
-
callback
(
optional
function
)
-
操作完成时调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(boolean success) {...};
chrome.input.ime.setMenuItems(object parameters, function callback)
当前输入法处于活动状态时，向语言菜单添加提供的菜单项。
参数
-
-
-
属性
-
engineID
(
string
)
-
要使用的引擎标识符。
-
items
(
array of MenuItem
)
-
要添加的菜单项，将按照数组中出现的顺序添加。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
chrome.input.ime.updateMenuItems(object parameters, function callback)
更新指定菜单项的状态。
参数
-
-
-
属性
-
engineID
(
string
)
-
要使用的引擎标识符。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
deleteSurroundingText
chrome.input.ime.deleteSurroundingText(object parameters, function callback)
删除光标周围的文本。
参数
-
parameters
(
object
)
-
-
属性
-
engineID
(
string
)
-
接收该事件的引擎标识符。
-
contextID
(
integer
)
-
要删除周围文本的上下文标识符。
-
offset
(
integer
)
-
删除开始的位置，表示为从光标位置开始的偏移，可以为负值。
-
length
(
integer
)
-
要删除的字符数目。
-
callback
(
optional
function
)
-
操作完成时调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
keyEventHandled
chrome.input.ime.keyEventHandled(string requestId, boolean response)
表示 onKeyEvent 接收到的键盘事件已处理，只有当 onKeyEvent 监听器为异步时才应该调用该方法。
参数
-
requestId
(
string
)
-
处理的事件的请求标识符，应该从 keyEvent.requestId 获得。
-
response
(
boolean
)
-
如果按键已处理则为 true，否则为 false。
事件
onActivate
输入法激活时发送这一事件，这意味着当前输入法将会接收 onKeyEvent 事件。
addListener
chrome.input.ime.onActivate.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID) {...};
-
engineID
(
string
)
-
接收这一事件的引擎标识符。
onDeactivated
当输入法处于不活动状态时产生，这意味着当前输入法不会继续接收 onKeyEvent 事件。
addListener
chrome.input.ime.onDeactivated.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID) {...};
-
engineID
(
string
)
-
接收这一事件的引擎标识符。
onFocus
当焦点进入文本框时发送该事件，它将发送至用户启用并且监听该事件的所有扩展程序。
addListener
chrome.input.ime.onFocus.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(InputContext context) {...};
onBlur
当焦点离开文本框时发送这一事件，它将发送至用户启用并且监听该事件的所有扩展程序。
addListener
chrome.input.ime.onBlur.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(integer contextID) {...};
-
contextID
(
integer
)
-
失去焦点的文本框标识符，在这一调用后该标识符不再有效。
onInputContextUpdate
当前的 InputContext（输入上下文）属性（例如类型）更改时发送这一事件，它将发送至用户启用并且监听该事件的所有扩展程序。
addListener
chrome.input.ime.onInputContextUpdate.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(InputContext context) {...};
-
-
描述已更改文本框的 InputContext 对象。
onKeyEvent
如果当前扩展程序独占当前输入法，则会发送这一事件。
addListener
chrome.input.ime.onKeyEvent.addListener(function callback, array of enum of "async" extraInfoSpec)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID, KeyboardEvent keyData) {...};
-
engineID
(
string
)
-
接收此事件的引擎标识符。
监听器返回值
-
( boolean )
-
如果处理了这一次按键操作则返回 true，否则返回 false。如果没有指定 "async" 的话该函数必须返回一个值。
onCandidateClicked
如果当前扩展程序独占当前输入法，则会发送这一事件。
addListener
chrome.input.ime.onCandidateClicked.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID, integer candidateID, enum of "left", "middle", or "right" button) {...};
-
engineID
(
string
)
-
接收这一事件的引擎标识符。
-
candidateID
(
integer
)
-
单击的候选项标识符。
当用户选择菜单项时调用。
addListener
chrome.input.ime.onMenuItemActivated.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID, string name) {...};
onSurroundingTextChanged
当光标周围可编辑的字符串更改或光标位置移动时调用，前进和后退方向的文本长度限制都是 100 个字符。
addListener
chrome.input.ime.onSurroundingTextChanged.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID, object surroundingInfo) {...};
-
engineID
(
string
)
-
接收该事件的引擎标识符。
-
surroundingInfo
(
object
)
-
周围文本的信息。
-
属性
-
focus
(
integer
)
-
选定内容的结束位置，如果没有选择内容则表示光标位置。
-
anchor
(
integer
)
-
选定内容的起始位置，如果没有选择内容则表示光标位置。
onReset
当 Chrome 浏览器终止正在进行的文字输入会话时发送该事件。
addListener
chrome.input.ime.onReset.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string engineID) {...};
-
engineID
(
string
)
-
接收该事件的引擎标识符。
chrome