chrome.input.ime

說明

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

權限

input

您必須宣告「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 朗讀字串。

  • 類型

    "復原"

  • 顯示

    布林值

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

AssistiveWindowType

Chrome 85 以上版本

輔助視窗的類型，

值

"復原"

AutoCapitalizeType

Chrome 69 以上版本

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

列舉

"字元"

"words"

"sentences"

InputContext

說明輸入情境

屬性

  • autoCapitalize

    AutoCapitalizeType

    Chrome 69 以上版本

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

  • autoComplete

    布林值

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

  • autoCorrect

    布林值

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

  • contextID

    數字

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

  • shouldDoLearning

    布林值

    Chrome 68 以上版本

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

  • spellCheck

    布林值

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

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

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 鍵。

  • 其中一個按鍵或 keydown。

KeyboardEventType

Chrome 44 以上版本

列舉

"keyup"

"keydown"

MenuItem

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

屬性

  • 已勾選

    布林值 選填

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

  • 已啟用

    布林值 選填

    表示這個項目已啟用。

  • id

    字串

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

  • 標籤

    string optional

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

  • 樣式

    MenuItemStyle 選用

    選單項目的類型。

  • 顯示

    布林值 選填

    表示這個項目是可見的。

MenuItemStyle

Chrome 44 以上版本

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

列舉

「檢查」

"電台"

"分隔符"

MenuParameters

Chrome 88 以上版本

屬性

  • engineID

    字串

    要使用的引擎 ID。

  • 項目

    MenuItem[]

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

MouseButton

Chrome 44 以上版本

按下的滑鼠按鈕。

列舉

"左"

"中間"

"右"

ScreenType

Chrome 44 以上版本

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

列舉

"normal"

"login"

「鎖定」

"secondary-login"

UnderlineStyle

Chrome 44 以上版本

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

列舉

「底線」

"doubleUnderline"

「noUnderline」

WindowPosition

Chrome 44 以上版本

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

列舉

"cursor"

"composition"

方法

clearComposition()

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

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

參數

  • parameters

    物件

    • contextID

      數字

      要清除樂曲的背景資訊 ID

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

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

commitText()

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

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

參數

  • parameters

    物件

    • contextID

      數字

      要修訂文字的背景資訊 ID

    • 文字

      字串

      要提交的文字

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

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

deleteSurroundingText()

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

刪除插入點周圍的文字。

參數

  • parameters

    物件

    • contextID

      數字

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

    • engineID

      字串

      接收事件的引擎 ID。

    • 長度

      數字

      要刪除的字元數

    • 碳補償

      數字

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<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

  • 回應

    布林值

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

sendKeyEvents()

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

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

參數

  • parameters

    物件

    • contextID

      數字

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

    • keyData

      KeyboardEvent[]

      重要事件資料。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 111 以上版本

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

setAssistiveWindowButtonHighlighted()

Promise Chrome 86 以上版本 
chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
  callback?: function,
)

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

參數

  • parameters

    物件

    • announceString

      string optional

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

    • 按鈕的 ID

    • contextID

      數字

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

    • 重要留言

      布林值

      是否應醒目顯示按鈕。

    • windowType

      "復原"

      按鈕所屬的視窗類型。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 111 以上版本

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

setAssistiveWindowProperties()

Promise Chrome 85 以上版本 
chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
  callback?: function,
)

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

參數

  • parameters

    物件

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 111 以上版本

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

setCandidates()

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

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

參數

  • parameters

    物件

    • 待選項目

      object[]

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

      • 註解

        string optional

        描述候選人的額外文字

      • 候選

        字串

        候選人

      • id

        數字

        候選人的 ID

      • 標籤

        string optional

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

      • parentId

        編號 選填

        要新增這些候選項目的 ID

      • 用量

        物件 optional

        字詞的用法或詳細說明。

        • body

          字串

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

        • title

          字串

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

    • contextID

      數字

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 111 以上版本

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

setCandidateWindowProperties()

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

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

參數

  • parameters

    物件

    • 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

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 111 以上版本

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

setComposition()

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

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

參數

  • parameters

    物件

    • contextID

      數字

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

    • cursor

      數字

      遊標文字中的位置。

    • 個區隔

      object[] 選用

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

      • End

        數字

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

      • start

        數字

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

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

    • selectionEnd

      編號 選填

      所選文字結尾的位置。

    • selectionStart

      編號 選填

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

    • 文字

      字串

      要設定的文字

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 111 以上版本

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

setCursorPosition()

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

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

參數

  • parameters

    物件

    • candidateID

      數字

      要選取的候選人 ID。

    • contextID

      數字

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise&lt;boolean&gt;

    Chrome 111 以上版本

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

setMenuItems()

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

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

參數

  • parameters

    MenuParameters

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 111 以上版本

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

updateMenuItems()

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

更新指定的 MenuItems 狀態

參數

  • parameters

    MenuParameters

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 111 以上版本

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

活動

onActivate

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

onAssistiveWindowButtonClicked

Chrome 85 以上版本 
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

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

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

參數

onInputContextUpdate

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

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

參數

onKeyEvent

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • returns

      boolean |未定義

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 第一個字元的絕對位置。

      • 文字

        字串

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