chrome.input.ime

说明

使用 chrome.input.ime API 为 Chrome 操作系统实现自定义 IME。这样一来，您的扩展程序就可以处理按键、设置组合以及管理候选窗口。

权限

input

您必须在扩展程序清单中声明“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

Chrome 85 及更高版本

辅助窗口中按钮的 ID。

枚举

"addToDictionary"

AssistiveWindowProperties

Chrome 85 及更高版本

辅助窗口的属性。

属性

  • announceString

    字符串（可选）

    供 ChromeVox 读出的字符串。

  • 类型

  • visible

    boolean

    设置为 true 以显示 AssistiveWindow，设置为 false 以隐藏。

AssistiveWindowType

Chrome 85 及更高版本

辅助窗口的类型。

值

AutoCapitalizeType

Chrome 69 及更高版本

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

枚举

"characters"

"words"

"sentences"

InputContext

描述输入上下文

属性

  • autoCapitalize

    AutoCapitalizeType

    Chrome 69 及更高版本

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

  • autoComplete

    boolean

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

  • autoCorrect

    boolean

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

  • contextID

    number

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

  • shouldDoLearning

    boolean

    Chrome 68 及更高版本

    是否应将在文本字段中输入的文本用于改进为用户提供的输入建议。

  • spellCheck

    boolean

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

  • 此文本字段编辑的值的类型（文本、数字、网址等）

InputContextType

Chrome 44 及更高版本

此文本字段编辑的值的类型（文本、数字、网址等）

枚举

"tel"

"url"

"number"

"password"

"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 键。

  • 可以是 keyup 或 keydown。

KeyboardEventType

Chrome 44 及更高版本

枚举

"keyup"

"keydown"

MenuItem

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

属性

  • 已选中

    布尔值 选填

    表示此项应使用勾号绘制。

  • 已启用

    布尔值 选填

    表示此项已启用。

  • id

    string

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

  • 标签

    字符串（可选）

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

  • 样式

    MenuItemStyle 可选

    菜单项的类型。

  • visible

    布尔值 选填

    表示此内容可见。

MenuItemStyle

Chrome 44 及更高版本

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

枚举

"radio"

MenuParameters

Chrome 88 及更高版本

属性

  • engineID

    string

    要使用的引擎的 ID。

  • items

    MenuItem[]

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

MouseButton

Chrome 44 及更高版本

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

枚举

ScreenType

Chrome 44 及更高版本

启用 IME 的屏幕类型。

枚举

"normal"

"secondary-login"

UnderlineStyle

Chrome 44 及更高版本

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

枚举

"doubleUnderline"

"noUnderline"

WindowPosition

Chrome 44 及更高版本

候选窗口的显示位置。如果设置为“cursor”，窗口会跟随光标移动。如果设为“composition”，窗口将锁定在组合的开头。

枚举

"cursor"

"composition"

方法

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，若为 0，则将按键事件发送到非输入字段。

    • 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

      字符串（可选）

      屏幕阅读器读出的文本。

    • 按钮的 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,
)

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

参数

  • 形参

    对象

  • 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

      光标文本中的位置。

    • 细分受众群

      对象 [] 可选

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

      • end

        number

        此段结束的字符索引。

      • start

        number

        此段开始的字符索引

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

    • 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 处于活动状态时，将提供的菜单项添加到语言菜单。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 111 及更高版本

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

updateMenuItems()

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

更新指定的 MenuItem 的状态

参数

  • 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

onAssistiveWindowButtonClicked

Chrome 85 及更高版本 
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

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

参数

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,
)

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

参数

onInputContextUpdate

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

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

参数

onKeyEvent

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

在操作系统发送按键事件时触发。如果此扩展程序拥有有效的 IME，系统就会将事件发送到该扩展程序。如果事件未处理，则监听器函数应返回 true。如果对事件进行异步求值，则此函数必须返回“undefined”，IME 稍后必须通过结果调用 keyEventHandled()。

参数

  • callback

    功能

    callback 参数如下所示：

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

    • 返回

      boolean|undefined

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 仅包含光标周围的文本子集，因此 offset 表示 text 第一个字符的绝对位置。

      • text

        string

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