此页面由 Cloud Translation API 翻译。

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

AutoCapitalizeType

Chrome 69 及更高版本

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

布尔值

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

布尔值

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

number

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

布尔值

Chrome 68 及更高版本

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

布尔值

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

InputContextType

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

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 键。
类型

KeyboardEventType

keyup 或 keydown 之一。

KeyboardEventType

Chrome 44 及更高版本

枚举

"keyup"

“keydown”

MenuItem

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

属性

已勾选

布尔值（可选）

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

布尔值（可选）

表示此项已启用。
id

字符串

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

字符串（可选）

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

MenuItemStyle 可选

菜单项的类型。
可见

布尔值（可选）

表示此内容可见。

MenuItemStyle

Chrome 44 及更高版本

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

枚举

"check"

"radio"

“separator”

MenuParameters

Chrome 88 及更高版本

属性

engineID

字符串

要使用的引擎的 ID。
项目

MenuItem[]

要添加或更新的 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<boolean>

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<boolean>

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
  
  KeyboardEvent[]
  
  关键事件的相关数据。
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
  
  字符串（可选）
  
  屏幕阅读器要读出的文本。
- buttonID
  
  AssistiveWindowButton
  
  按钮的 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,
)

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

参数

参数

对象
- contextID
  
  number
  
  拥有辅助窗口的上下文的 ID。
- 媒体资源
  
  AssistiveWindowProperties
  
  辅助窗口的属性。
callback

函数（可选）

callback 参数如下所示：
```
(success: boolean) => void
```
- 成功
  
  布尔值

Promise<boolean>

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<boolean>

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<boolean>

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
    
    此句段起始字符的索引
  - 样式
    
    UnderlineStyle
    
    用于修改此细分的下划线类型。
- selectionEnd
  
  编号（选填）
  
  文本中选定内容结束的位置。
- selectionStart
  
  编号（选填）
  
  文本中从选择内容开始的位置。
- text
  
  字符串
  
  要设置的文本
callback

函数（可选）

callback 参数如下所示：
```
(success: boolean) => void
```
- 成功
  
  布尔值

Promise<boolean>

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<boolean>

Chrome 111 及更高版本

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

setMenuItems()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

参数

MenuParameters
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 的状态

参数

参数

MenuParameters
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
```
- engineID
  
  字符串
- 屏幕
  
  ScreenType

onAssistiveWindowButtonClicked

Chrome 85 及更高版本

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

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

参数

callback

函数

callback 参数如下所示：
```
(details: object) => void
```
- 详细信息
  
  对象
  - buttonID
    
    AssistiveWindowButton
    
    所点击按钮的 ID。
  - windowType
    
    AssistiveWindowType
    
    辅助窗口的类型。

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
- 按钮
  
  MouseButton

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
  
  InputContext

onInputContextUpdate

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

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

参数

callback

函数

callback 参数如下所示：
```
(context: InputContext) => void
```
- context
  
  InputContext

onKeyEvent

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

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

参数

callback

函数

callback 参数如下所示：
```
(engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined
```
- engineID
  
  字符串
- keyData
  
  KeyboardEvent
- requestId
  
  字符串
- 返回
  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
    
    字符串
    
    光标周围的文本。这只是输入字段中所有文本的子集。