chrome.input.ime

说明

使用 chrome.input.ime API 为 ChromeOS 实现自定义 IME。这样一来,您的扩展程序就可以处理按键、设置构图和管理候选窗口。

权限

input

您必须声明“input”权限,以使用 input.ime API。例如:

{
  "name": "My extension",
  ...
  "permissions": [
    "input"
  ],
  ...
}

可用性

<ph type="x-smartling-placeholder"></ph> 仅限 ChromeOS

示例

以下代码会创建一个 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 朗读的字符串。

  • 类型

    "撤消"

  • 可见

    布尔值

    设为 true 以显示 AssistiveWindow,设为 false 以显示 AssistiveWindow。

AssistiveWindowType

Chrome 85 及更高版本

辅助窗口的类型。

"撤消"

AutoCapitalizeType

Chrome 69 及更高版本

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

枚举

"字符"

"字词"

"sentences"

InputContext

描述输入上下文

属性

  • autoCapitalize
    Chrome 69 及更高版本

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

  • autoComplete

    布尔值

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

  • autoCorrect

    布尔值

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

  • contextID

    number

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

  • shouldDoLearning

    布尔值

    Chrome 68 及更高版本

    是否应使用在文本字段输入的文本来改进用户的输入建议。

  • spellCheck

    布尔值

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

  • 此文本字段所修改的值的类型(文本、数字、网址等)

InputContextType

Chrome 44 及更高版本

此文本字段所修改的值的类型(文本、数字、网址等)

枚举

"文本"

"搜索"

"tel"

“url”

“电子邮件”

“number”

“密码”

"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

    编号(选填

    已废弃的 HTML keyCode,它是依赖于系统和实现的数字代码,表示与按下的键相关联的未经修改的标识符。

  • requestId

    字符串(可选)

    (已弃用)请求的 ID。请改用 onKeyEvent 事件中的 requestId 参数。

  • shiftKey

    布尔值(可选)

    是否按下了 SHIFT 键。

  • keyup 或 keydown 之一。

KeyboardEventType

Chrome 44 及更高版本

枚举

"keyup"

“keydown”

MenuItem

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

属性

  • 已勾选

    布尔值(可选)

    表示此项应在绘制时用勾选标记。

  • 已启用

    布尔值(可选)

    表示此项已启用。

  • id

    字符串

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

  • 标签

    字符串(可选)

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

  • 样式

    菜单项的类型。

  • 可见

    布尔值(可选)

    表示此内容可见。

MenuItemStyle

Chrome 44 及更高版本

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

枚举

"check"

"radio"

“separator”

MenuParameters

Chrome 88 及更高版本

属性

  • engineID

    字符串

    要使用的引擎的 ID。

  • 项目

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

MouseButton

Chrome 44 及更高版本

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

枚举

“左”

"mid"

"right"

ScreenType

Chrome 44 及更高版本

激活 IME 的屏幕类型。

枚举

“normal”

“登录”

“锁定”

“secondary-login”

UnderlineStyle

Chrome 44 及更高版本

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

枚举

"下划线"

"doubleUnderline"

“noUnderline”

WindowPosition

Chrome 44 及更高版本

候选字词窗口的显示位置。如果设置为“cursor”,窗口会跟随光标。如果设置为“composition”,则该窗口会锁定在合成内容的开头。

枚举

"cursor"

“组合”

方法

clearComposition()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.clearComposition(
  parameters: object,
  callback?: function,
)

清除当前的乐曲。如果此扩展程序不拥有有效 IME,则测试将失败。

参数

  • 参数

    对象

    • contextID

      number

      将清除组合的上下文的 ID

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

commitText()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.commitText(
  parameters: object,
  callback?: function,
)

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

参数

  • 参数

    对象

    • contextID

      number

      将提交文本的上下文的 ID

    • text

      字符串

      要提交的文本

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

deleteSurroundingText()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.deleteSurroundingText(
  parameters: object,
  callback?: function,
)

删除插入符号周围的文本。

参数

  • 参数

    对象

    • contextID

      number

      将在其中删除周围文本的上下文的 ID。

    • engineID

      字符串

      接收事件的引擎的 ID。

    • 长度

      number

      要删除的字符数

    • offset

      number

      与开始删除的插入符号位置的偏移量。此值可以为负数。

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 111 及更高版本

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

hideInputView()

chrome.input.ime.hideInputView()

隐藏输入视图窗口,该窗口由系统自动弹出。如果输入视图窗口已隐藏,此函数将不执行任何操作。

keyEventHandled()

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

表示处理 onKeyEvent 接收的按键事件。只有在 onKeyEvent 监听器为异步时,才应调用此方法。

参数

  • requestId

    字符串

    已处理事件的请求 ID。应来自 keyEvent.requestId

  • Response

    布尔值

    如果处理了按键操作,则为 true,否则为 false

sendKeyEvents()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.sendKeyEvents(
  parameters: object,
  callback?: function,
)

发送按键事件。预计虚拟键盘会使用此函数。当用户按下虚拟键盘上的按键时,此函数用于向系统传播该事件。

参数

  • 参数

    对象

    • contextID

      number

      将关键事件发送到的上下文的 ID,如果使用零,则将关键事件发送到非输入字段。

    • keyData

      关键事件的相关数据。

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 111 及更高版本

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

setAssistiveWindowButtonHighlighted()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 86 及更高版本
chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
  callback?: function,
)

突出显示/取消突出显示辅助窗口中的按钮。

参数

  • 参数

    对象

    • announceString

      字符串(可选)

      屏幕阅读器要读出的文本。

    • 按钮的 ID

    • contextID

      number

      拥有辅助窗口的上下文的 ID。

    • 突出显示

      布尔值

      是否应突出显示按钮。

    • windowType

      "撤消"

      按钮所属的窗口类型。

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 111 及更高版本

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

setAssistiveWindowProperties()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 85 及更高版本
chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
  callback?: function,
)

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

参数

  • 参数

    对象

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

setCandidates()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.setCandidates(
  parameters: object,
  callback?: function,
)

设置当前候选字词列表。如果此扩展程序不拥有有效的 IME,则会失败

参数

  • 参数

    对象

    • 候选

      object[]

      要在候选人窗口中显示的候选人列表

      • annotation

        字符串(可选)

        用于描述候选人的其他文字

      • 候选定位设置

        字符串

        候选人

      • id

        number

        候选人 ID

      • 标签

        字符串(可选)

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

      • parentId

        编号(选填

        要添加这些候选人的 ID

      • 使用量

        对象(可选

        字词的用途或详细说明。

        • body

          字符串

          详细描述的正文字符串。

        • 标题

          字符串

          详情说明的标题字符串。

    • contextID

      number

      拥有候选窗口的上下文的 ID。

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

setCandidateWindowProperties()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.setCandidateWindowProperties(
  parameters: object,
  callback?: function,
)

设置候选窗口的属性。如果扩展程序不拥有有效 IME,则会失败

参数

  • 参数

    对象

    • engineID

      字符串

      要为其设置属性的引擎的 ID。

    • 媒体资源

      对象

      • auxiliaryText

        字符串(可选)

        候选字词窗口底部显示的文本。

      • auxiliaryTextVisible

        布尔值(可选)

        True 表示显示辅助文本,false 表示隐藏辅助文本。

      • currentCandidateIndex

        编号(选填

        Chrome 84 及更高版本

        当前所选候选者在总候选者中的索引。

      • cursorVisible

        布尔值(可选)

        True 表示显示光标,False 表示隐藏光标。

      • pageSize

        编号(选填

        每页显示的候选字词数量。

      • totalCandidates

        编号(选填

        Chrome 84 及更高版本

        候选人时段的候选人总数。

      • 类别

        布尔值(可选)

        如果应垂直渲染候选窗口,则为 true;如果要将其设为水平渲染,则为 false。

      • 可见

        布尔值(可选)

        如果为 true,则显示“候选字词”窗口;值为 false 时,则隐藏该窗口。

      • windowPosition

        WindowPosition(可选)

        候选字词窗口的显示位置。

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

setComposition()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.setComposition(
  parameters: object,
  callback?: function,
)

设置当前乐曲。如果此扩展程序不拥有有效 IME,则测试将失败。

参数

  • 参数

    对象

    • contextID

      number

      将设置撰写文本的上下文 ID

    • cursor

      number

      光标文本中的位置。

    • 细分

      object[] 可选

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

      • end

        number

        要在其后结束此句段的字符的索引。

      • start

        number

        此句段起始字符的索引

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

    • selectionEnd

      编号(选填

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

    • selectionStart

      编号(选填

      文本中从选择内容开始的位置。

    • text

      字符串

      要设置的文本

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

setCursorPosition()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.setCursorPosition(
  parameters: object,
  callback?: function,
)

设置候选窗口中的光标位置。如果此扩展程序不拥有有效 IME,则此项为空操作。

参数

  • 参数

    对象

    • candidateID

      number

      要选择的候选人的 ID。

    • contextID

      number

      拥有候选窗口的上下文的 ID。

  • callback

    函数(可选)

    callback 参数如下所示:

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    Chrome 111 及更高版本

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

setMenuItems()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.setMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

当此 IME 处于活动状态时,将提供的菜单项添加到语言菜单。

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 111 及更高版本

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

updateMenuItems()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.input.ime.updateMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

更新指定的 MenuItem 的状态

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<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,
)

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

参数

  • callback

    函数

    callback 参数如下所示:

    (details: object) => void

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

      字符串

    • candidateID

      number

    • 按钮

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

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

参数

onInputContextUpdate

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

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

参数

onKeyEvent

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

在操作系统发送关键事件时触发。如果该扩展程序拥有有效 IME,则会将该事件发送给该扩展程序。如果事件处理后为 false,则监听器函数应返回 true。如果将异步评估事件,则此函数必须返回未定义的值,且 IME 稍后必须调用 keyEventHandled() 并返回结果。

参数

  • callback

    函数

    callback 参数如下所示:

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

    • 返回

      boolean |未定义

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

        number

        所选内容的开始位置。如果未做任何选择,此值表示插入符号的位置。

      • 焦点

        number

        所选内容的结束位置。如果未做任何选择,此值表示插入符号的位置。

      • offset

        number

        Chrome 46 及更高版本

        text 的偏移位置。由于 text 仅包含光标周围的文本子集,因此偏移量表示 text 第一个字符的绝对位置。

      • text

        字符串

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