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
InputContext
MenuItem
方法
setComposition − `chrome.input.ime.setComposition(object parameters, function callback)`
clearComposition − `chrome.input.ime.clearComposition(object parameters, function callback)`
commitText − `chrome.input.ime.commitText(object parameters, function callback)`
sendKeyEvents − `chrome.input.ime.sendKeyEvents(object parameters, function callback)`
hideInputView − `chrome.input.ime.hideInputView()`
setCandidateWindowProperties − `chrome.input.ime.setCandidateWindowProperties(object parameters, function callback)`
setCandidates − `chrome.input.ime.setCandidates(object parameters, function callback)`
setCursorPosition − `chrome.input.ime.setCursorPosition(object parameters, function callback)`
setMenuItems − `chrome.input.ime.setMenuItems(object parameters, function callback)`
updateMenuItems − `chrome.input.ime.updateMenuItems(object parameters, function callback)`
deleteSurroundingText − `chrome.input.ime.deleteSurroundingText(object parameters, function callback)`
keyEventHandled − `chrome.input.ime.keyEventHandled(string requestId, boolean response)`
事件
onActivate
onDeactivated
onFocus
onBlur
onInputContextUpdate
onKeyEvent
onCandidateClicked
onMenuItemActivated
onSurroundingTextChanged
onReset

类型

KeyboardEvent

参见 http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent。

属性
enum of `"keyup"`, or `"keydown"`	type	"keyup"（按键弹起）或 "keydown"（按键按下）。
string	requestId	请求标识符。
string	（可选） extensionId	从 Chrome 34 开始支持。发送键盘事件的扩展程序标识符。
string	key	按下的按键值。
string	code	从 Chrome 26 开始支持。按下的物理按键的值，不受当前键盘布局或组合键状态的影响。
integer	（可选） keyCode	从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容弃用的 HTML5 按键代码，是一种与系统和实现相关的数字代码，表示与按键相关联的未经修改的标识符。
boolean	（可选） altKey	是否按下了 Alt 键。
boolean	（可选） ctrlKey	是否按下了 Ctrl 键。
boolean	（可选） shiftKey	是否按下了 Shift 键。
boolean	（可选） capsLock	从 Chrome 29 开始支持。 Caps Lock 键是否启用。

InputContext

描述输入上下文。

属性
integer	contextID	该属性用来指定文本框操作的目标，一旦接收到 onBlur 事件该标识符就不再有效。
enum of `"text"`, `"search"`, `"tel"`, `"url"`, `"email"`, or `"number"`	type	该文本框编辑的值的类型：文本、数字、URL 等。Type of value this text field edits, (Text, Number, URL, etc)

MenuItem

从 Chrome 30 开始支持。

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

属性
string	id	传递给回调函数的字符串，用来引用这一菜单项。
string	（可选） label	这一菜单项在菜单中显示的文本。
enum of `"check"`, `"radio"`, or `"separator"`	（可选） style	代表这一菜单项是否是："check"（复选）、"radio"（单选）或 "separator"（分隔符）的枚举值。在分隔符之间的单选按钮将认为是同一组的。
boolean	（可选） visible	表示这一菜单项是否可见。
boolean	（可选） checked	表示这一菜单项是否已勾选。
boolean	（可选） enabled	表示这一菜单项是否已启用。

方法

setComposition


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

设置当前的候选内容。如果当前扩展程序没有独占当前输入法，该方法将会失败。

参数

object

parameters

integer

contextID

需要设置候选本文的上下文标识符。

string

text

要设置的文本。

integer

（可选）
selectionStart

选定内容在文本中的起始位置。

integer

（可选）
selectionEnd

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

integer

cursor

光标在文本中的位置。

array of object

（可选）
segments

片段列表以及与它们相关的类型。

每一个对象的属性

integer	start	当前片段开始的字符索引。
integer	end	当前片段结束后的字符索引。
enum of `"underline"`, or `"doubleUnderline"`	style	如何呈现这一片段。

function

（可选）
callback

当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

clearComposition


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

清除当前的候选内容。如果当前扩展程序没有独占当前输入法，该方法将会失败。

参数

object

parameters

integer

contextID

需要清除候选内容的上下文标识符。

function

（可选）
callback

当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

commitText


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

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

参数

object

parameters

integer	contextID	需要提交文本的上下文标识符。
string	text	要提交的文本。

function

（可选）
callback

当操作完成时调用，传递一个布尔值，表示文本是否被接受。如果调用失败，将设置 runtime.lastError。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

sendKeyEvents


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

从 Chrome 33 开始支持。

发送键盘事件，该函数由虚拟键盘使用。用户按下虚拟键盘上的按键时，该函数可以用来将该事件传播给系统。

参数

object

parameters

integer	contextID	发送键盘事件的上下文标识符，如果要向非输入字段发送键盘事件则设为 0。
array of KeyboardEvent	keyData	键盘事件的相关数据。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

hideInputView


              chrome.input.ime.hideInputView()

从 Chrome 34 开始支持。

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

setCandidateWindowProperties


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

设置候选窗口的属性。如果当前扩展程序没有独占当前输入法，该方法将会失败。

参数

object

parameters

string

engineID

要设置属性的引擎标识符。

object

properties

boolean	（可选） visible	要显示候选窗口则为 true，隐藏则为 false。
boolean	（可选） cursorVisible	要显示光标则为 true，隐藏则为 false。
boolean	（可选） vertical	如果候选窗口竖排则为 true，横排则为 false。
integer	（可选） pageSize	每一页显示的候选项数目。
string	（可选） auxiliaryText	候选窗口底部显示的文字。
boolean	（可选） auxiliaryTextVisible	要显示辅助文字则为 true，隐藏则为 false。
enum of `"cursor"`, or `"composition"`	（可选） windowPosition	从 Chrome 28 开始支持。显示候选窗口的位置。如果设置为 'cursor'，窗口会跟随光标；如果设置为 'composition'，窗口会固定在候选内容的开头。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

setCandidates


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

设置当前的候选列表。如果当前扩展程序没有独占当前输入法，该方法将会失败。

参数

object

parameters

integer

contextID

拥有候选窗口的上下文标识符。

array of object

candidates

在候选窗口中显示的候选项列表。

每一个对象的属性

string

candidate

候选项。

integer

候选项标识符。

integer

（可选）
parentId

将这些候选项添加至其下的标识符。

string

（可选）
label

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

string

（可选）
annotation

描述候选项的附加文字。

object

（可选）
usage

词语的用法或详细描述。

string	title	详细描述的标题字符串。
string	body	详细描述的正文字符串。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

setCursorPosition


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

设置候选窗口中的光标位置。如果当前扩展程序没有独占当前输入法，则不进行任何操作。

参数

object

parameters

integer	contextID	拥有候选窗口的上下文标识符。
integer	candidateID	选定的候选项标识符。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(boolean success) {...};

boolean

success

setMenuItems


              chrome.input.ime.setMenuItems(object parameters, function callback)

当前输入法处于活动状态时，向语言菜单添加提供的菜单项。

参数

object

parameters

string	engineID	要使用的引擎标识符。
array of MenuItem	items	要添加的菜单项，将按照数组中出现的顺序添加。

function

（可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

updateMenuItems


              chrome.input.ime.updateMenuItems(object parameters, function callback)

更新指定菜单项的状态。

参数

object

parameters

string	engineID	要使用的引擎标识符。
array of MenuItem	items	要更新的菜单项数组。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

deleteSurroundingText


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

从 Chrome 27 开始支持。

删除光标周围的文本。

参数

object

parameters

string	engineID	接收该事件的引擎标识符。
integer	contextID	要删除周围文本的上下文标识符。
integer	offset	删除开始的位置，表示为从光标位置开始的偏移，可以为负值。
integer	length	要删除的字符数目。

function

（可选）
callback

操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

keyEventHandled


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

从 Chrome 25 开始支持。

表示 onKeyEvent 接收到的键盘事件已处理，只有当 onKeyEvent 监听器为异步时才应该调用该方法。

参数
string	requestId	处理的事件的请求标识符，应该从 keyEvent.requestId 获得。
boolean	response	如果按键已处理则为 true，否则为 false。

事件

onActivate

输入法激活时发送这一事件，这意味着当前输入法将会接收 onKeyEvent 事件。

addListener


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

参数

function

callback


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

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string engineID, KeyboardEvent keyData) {...};

string	engineID	接收此事件的引擎标识符。
KeyboardEvent	keyData	键盘事件的数据。

监听器返回值

( boolean ): 如果处理了这一次按键操作则返回 true，否则返回 false。如果没有指定 "async" 的话该函数必须返回一个值。

onCandidateClicked

如果当前扩展程序独占当前输入法，则会发送这一事件。

addListener


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

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string engineID, integer candidateID, enum of "left", "middle", or "right" button) {...};

string	engineID	接收这一事件的引擎标识符。
integer	candidateID	单击的候选项标识符。
enum of `"left"`, `"middle"`, or `"right"`	button	单击了哪个鼠标按钮。

onMenuItemActivated

当用户选择菜单项时调用。

addListener


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

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string engineID, string name) {...};

string	engineID	接收此事件的引擎标识符。
string	name	激活的菜单项名称。

onSurroundingTextChanged

从 Chrome 27 开始支持。

当光标周围可编辑的字符串更改或光标位置移动时调用，前进和后退方向的文本长度限制都是 100 个字符。

addListener


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

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string engineID, object surroundingInfo) {...};

string

engineID

接收该事件的引擎标识符。

object

surroundingInfo

周围文本的信息。

string	text	光标周围的文本。
integer	focus	选定内容的结束位置，如果没有选择内容则表示光标位置。
integer	anchor	选定内容的起始位置，如果没有选择内容则表示光标位置。

onReset

从 Chrome 29 开始支持。

当 Chrome 浏览器终止正在进行的文字输入会话时发送该事件。

addListener


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

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string engineID) {...};

string

engineID

接收该事件的引擎标识符。

示例扩展程序

Test IME – A simple IME that converts all keystrokes to upper case.