chrome.input.ime

重要事項：這個 API僅適用於 ChromeOS。

說明

使用 chrome.input.ime API 實作 Chrome OS 適用的自訂 IME。如此一來，你的擴充功能就能處理按鍵動作、設定組成及管理候選視窗。

權限

input

您必須在擴充功能資訊清單中宣告「輸入」權限，才能使用 input.ime API。舉例來說：

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

適用國家/地區

僅限 ChromeOS

示例

以下程式碼會建立輸入法編輯器，可將使用者輸入的字母轉換為大寫。

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

  string optional

  ChromeVox 朗讀字串。

• 類型

• 顯示

  boolean

  設為 true 顯示 AssistiveWindow，設為 false 表示隱藏。

AssistiveWindowType

Chrome 85 以上版本

輔助視窗的類型，

價值

AutoCapitalizeType

Chrome 69 以上版本

自動大寫的文字欄位類型。

列舉

"words"

"sentences"

InputContext

說明輸入情境

屬性

• autoCapitalize

  AutoCapitalizeType

  Chrome 69 以上版本

  自動大寫的文字欄位類型。

• autoComplete

  boolean

  指出文字欄位是否希望自動完成。

• autoCorrect

  boolean

  用於指定文字欄位是否需要自動更正。

• contextID

  號碼

  用於指定文字欄位作業的目標。呼叫 onBlur 後，這個 ID 就會失效。

• shouldDoLearning

  boolean

  Chrome 68 以上版本

  是否該使用在文字欄位中輸入的文字，改善使用者的輸入建議。

• spellCheck

  boolean

  文字欄位是否需要拼字檢查。

• 類型

  InputContextType

  這個文字欄位編輯的值類型 (文字、數字、網址等)

InputContextType

Chrome 44 以上版本

這個文字欄位編輯的值類型 (文字、數字、網址等)

列舉

"text"

"url"

"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

  string optional

  這個鍵事件傳送者的擴充功能 ID。

• 金鑰

  字串

  所按下按鍵的值

• keyCode

  編號 選填

  已淘汰的 HTML keyCode，這是系統及實作方面的數字碼，用來代表與按下的按鍵相關聯的未修改 ID。

• requestId

  string optional

  (已淘汰) 要求的 ID。請改用 onKeyEvent 事件中的 requestId 參數。

• shiftKey

  布林值 選填

  是否按下 SHIFT 鍵。

• 類型

  KeyboardEventType

  其中一個按鍵或 keydown。

KeyboardEventType

Chrome 44 以上版本

列舉

"keyup"

"keydown"

MenuItem

輸入法使用的選單項目，可讓使用者透過語言選單與使用者互動。

屬性

• 已勾選

  布林值 選填

  表示此項目應使用檢查繪圖。

• 已啟用

  布林值 選填

  表示這個項目已啟用。

• ID

  字串

  要傳遞至參照這個 MenuItem 回呼的字串。

• 標籤

  string optional

  這個項目的選單中顯示的文字。

• 樣式

  MenuItemStyle 選用

  選單項目的類型。

• 顯示

  布林值 選填

  表示這個項目是可見的。

MenuItemStyle

Chrome 44 以上版本

選單項目的類型。系統會將分隔符之間的圓形按鈕分組。

列舉

MenuParameters

Chrome 88 以上版本

屬性

• engineID

  字串

  要使用的引擎 ID。

• items

  MenuItem[]

  要新增或更新的選單項目。系統會按照陣列中的現有順序新增這些元素。

MouseButton

Chrome 44 以上版本

按下的滑鼠按鈕。

列舉

ScreenType

Chrome 44 以上版本

啟用輸入法編輯器的螢幕類型。

列舉

"normal"

"login"

"secondary-login"

UnderlineStyle

Chrome 44 以上版本

用來修改這個區隔的底線類型。

列舉

"doubleUnderline"

WindowPosition

Chrome 44 以上版本

顯示候選視窗的位置。如果設為「cursor」，視窗會跟隨遊標移動。如果設為「composition」，視窗就會鎖在樂曲開頭處。

列舉

"cursor"

"composition"

方法

clearComposition()

Promise

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

清除目前的樂曲。如果這個擴充功能沒有使用中的輸入法編輯器，就會失敗。

參數

• 參數

  物件

  • contextID

    號碼

    要清除樂曲的背景資訊 ID

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

commitText()

Promise

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

將提供的文字提交到目前的輸入內容。

參數

• 參數

  物件

  • contextID

    號碼

    要修訂文字的背景資訊 ID

  • text

    字串

    要提交的文字

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

deleteSurroundingText()

Promise

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

刪除插入點周圍的文字。

參數

• 參數

  物件

  • contextID

    號碼

    要刪除前後文字的背景資訊 ID。

  • engineID

    字串

    接收事件的引擎 ID。

  • length

    號碼

    要刪除的字元數

  • 碳補償

    號碼

    刪除開始的插入點位置偏移值。這個值可以是負數。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

hideInputView()

chrome.input.ime.hideInputView()

隱藏系統自動彈出的輸入檢視視窗。如果輸入檢視視窗已隱藏，此函式不會有任何作用。

keyEventHandled()

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

表示已處理 onKeyEvent 收到的重要事件。只有在 onKeyEvent 事件監聽器為非同步時，才能呼叫此方法。

參數

• requestId

  字串

  處理事件的要求 ID。這項資訊應來自 keyEvent.requestId

• 則回應

  boolean

  如果按鍵動作已處理，則為「true」，否則傳回「false」

sendKeyEvents()

Promise

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

傳送重要事件。虛擬鍵盤應使用此函式。當使用者按下虛擬鍵盤上的按鍵時，系統會使用這個函式將事件傳播到系統。

參數

• 參數

  物件

  • contextID

    號碼

    傳送重要事件的背景資訊 ID，或是設為 0 將重要事件傳送至非輸入欄位。

  • keyData

    KeyboardEvent[]

    重要事件資料。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setAssistiveWindowButtonHighlighted()

Promise Chrome 86 以上版本

chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
  callback?: function,
)

醒目顯示/取消醒目顯示輔助視窗中的按鈕。

參數

• 參數

  物件

  • announceString

    string optional

    供螢幕閱讀器朗讀的文字。

  • buttonID

    AssistiveWindowButton

    按鈕的 ID

  • contextID

    號碼

    擁有輔助視窗的背景資訊 ID。

  • 重要留言

    boolean

    是否應醒目顯示按鈕。

  • windowType

    按鈕所屬的視窗類型。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setAssistiveWindowProperties()

Promise Chrome 85 以上版本

chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
  callback?: function,
)

顯示/隱藏含指定屬性的輔助視窗。

參數

• 參數

  物件

  • contextID

    號碼

    擁有輔助視窗的背景資訊 ID。

  • 資源

    AssistiveWindowProperties

    輔助視窗的屬性。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setCandidates()

Promise

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

設定目前的候選人清單。如果這個擴充功能沒有使用中的輸入法編輯器，這個擴充功能就會失敗

參數

• 參數

  物件

  • 待選項目

    物體 []

    要在候選人視窗中顯示的候選名單清單

    • 註解

      string optional

      描述候選人的額外文字

    • 候選

      字串

      候選人

    • ID

      號碼

      候選人的 ID

    • 標籤

      string optional

      候選項目旁邊的短字串，通常是快速鍵或索引

    • parentId

      編號 選填

      要新增這些候選項目的 ID

    • 用量

      物件 optional

      字詞的用法或詳細說明。

      • body

        字串

        詳細資料說明的主體字串。

      • title

        字串

        詳細資料說明的標題字串。

  • contextID

    號碼

    擁有候選視窗的背景資訊 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setCandidateWindowProperties()

Promise

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

設定候選視窗的屬性。如果擴充功能沒有使用中的輸入法編輯器，將失敗

參數

• 參數

  物件

  • engineID

    字串

    要設定屬性的引擎 ID。

  • 資源

    物件

    • auxiliaryText

      string optional

      顯示在候選視窗底部的文字。

    • auxiliaryTextVisible

      布林值 選填

      設為 True 會顯示輔助文字，false 則會隱藏。

    • currentCandidateIndex

      編號 選填

      Chrome 84 以上版本

      目前所選候選人的索引，在候選項目總數中。

    • cursorVisible

      布林值 選填

      設為 True 會顯示遊標，設為 false 則會隱藏遊標。

    • pageSize

      編號 選填

      每頁顯示的候選字數量。

    • totalCandidates

      編號 選填

      Chrome 84 以上版本

      候選人期間的候選人總數。

    • 直向

      布林值 選填

      如果候選視窗應直向顯示，則為 True，false 則表示可以水平。

    • 顯示

      布林值 選填

      設為 True 會顯示「候選」視窗，設為 false 則會隱藏該視窗。

    • windowPosition

      WindowPosition 選用

      顯示候選視窗的位置。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setComposition()

Promise

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

設定目前的組成。如果這個擴充功能沒有使用中的輸入法編輯器，就會失敗。

參數

• 參數

  物件

  • contextID

    號碼

    要設定樂曲文字的背景資訊 ID

  • 游標

    號碼

    遊標文字中的位置。

  • 區隔」

    object[] 選用

    區隔清單及相關類型清單。

    • end

      號碼

      這個區隔之後要結束的字元索引。

    • start

      號碼

      這個片段開始位置的字元索引

    • 樣式

      UnderlineStyle

      用來修改這個區隔的底線類型。

  • selectionEnd

    編號 選填

    所選文字結尾的位置。

  • selectionStart

    編號 選填

    文字在所選起始位置的起始位置。

  • text

    字串

    要設定的文字

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setCursorPosition()

Promise

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

在候選視窗中設定遊標位置。如果這個擴充功能沒有使用中的輸入法編輯器，此為免人工管理。

參數

• 參數

  物件

  • candidateID

    號碼

    要選取的候選人 ID。

  • contextID

    號碼

    擁有候選視窗的背景資訊 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setMenuItems()

Promise

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

這個輸入法編輯器啟用時，將提供的選單項目加入語言選單。

參數

• 參數

  MenuParameters

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

updateMenuItems()

Promise

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

更新指定的 MenuItems 狀態

參數

• 參數

  MenuParameters

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 111 以上版本

  Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

活動

onActivate

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

如果啟用輸入法編輯器，系統就會傳送這個事件。指出輸入法編輯器會收到 onKeyPress 事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string, screen: ScreenType) => void

  • engineID

    字串

  • 螢幕

    ScreenType

onAssistiveWindowButtonClicked

Chrome 85 以上版本

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

按一下輔助視窗中的按鈕時，就會傳送這個事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object) => void

  • 詳細資料

    物件

    • buttonID

      AssistiveWindowButton

      所點選按鈕的 ID。

    • windowType

      AssistiveWindowType

      輔助視窗的類型，

onBlur

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

當焦點離開文字方塊時，系統就會傳送這個事件。系統會向監聽這個事件的所有擴充功能傳送這則訊息，且由使用者啟用。

參數

• 回呼

  功能

  callback 參數如下所示：

  (contextID: number) => void

  • contextID

    號碼

onCandidateClicked

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

如果這個擴充功能擁有有效的輸入法編輯器，系統就會傳送這個事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string, candidateID: number, button: MouseButton) => void

  • engineID

    字串

  • candidateID

    號碼

  • 按鈕

    MouseButton

onDeactivated

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

如果停用輸入法編輯器，系統就會傳送這個事件。表示輸入法編輯器不會再收到 onKeyPress 事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string) => void

  • engineID

    字串

onFocus

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

當焦點移到文字方塊時，系統就會傳送這個事件。系統會向監聽這個事件的所有擴充功能傳送這則訊息，且由使用者啟用。

參數

• 回呼

  功能

  callback 參數如下所示：

  (context: InputContext) => void

  • context

    InputContext

onInputContextUpdate

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

當目前 InputContext 的屬性變更 (例如類型) 變更時，會傳送這個事件。系統會向監聽這個事件的所有擴充功能傳送這則訊息，且由使用者啟用。

參數

• 回呼

  功能

  callback 參數如下所示：

  (context: InputContext) => void

  • context

    InputContext

onKeyEvent

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

作業系統傳送重要事件時觸發。如果這個擴充功能擁有有效的輸入法編輯器，系統會將事件傳送至擴充功能。如果沒有處理事件，則事件監聽器函式應傳回 true。如果是非同步評估事件，這個函式必須傳回未定義，且輸入法編輯器稍後必須呼叫含有結果的 keyEventHandled()。

參數

• 回呼

  功能

  callback 參數如下所示：

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

  • engineID

    字串

  • keyData

    KeyboardEvent

  • requestId

    字串

  • returns

    布林值 | 未定義

onMenuItemActivated

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

在使用者選取選單項目時呼叫

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string, name: string) => void

  • engineID

    字串

  • 名稱

    字串

onReset

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

當 Chrome 終止進行中的文字輸入工作階段時，就會傳送這個事件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string) => void

  • engineID

    字串

onSurroundingTextChanged

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

在插入點前後的可編輯字串變更或插入點位置移動時呼叫。每個往返方向的文字長度上限為 100 個字元。

參數

• 回呼

  功能

  callback 參數如下所示：

  (engineID: string, surroundingInfo: object) => void

  • engineID

    字串

  • surroundingInfo

    物件

    • anchor

      號碼

      選取範圍的起始位置。這個值表示如果沒有選項，代表插入點位置。

    • 主軸

      號碼

      選取項目的結束位置。這個值表示如果沒有選項，代表插入點位置。

    • 碳補償

      號碼

      Chrome 46 以上版本

      text 的偏移位置。由於 text 只包含遊標周圍的部分文字，因此偏移值表示 text 第一個字元的絕對位置。

    • text

      字串

      遊標周圍的文字。這只是輸入欄位中所有文字的子集。