chrome.input.ime

說明

使用 chrome.input.ime API 為 Chrome 作業系統實作自訂輸入法編輯器。如此一來，您的擴充功能就能處理按鍵動作、設定組合及管理候選視窗。

權限

input

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

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

示例

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

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 要朗讀的字串。

• 類型

• 顯示

  boolean

  設為 true 以顯示 AssistiveWindow，設定 false 則可隱藏。

AssistiveWindowType

Chrome 85 以上版本

輔助視窗類型。

值

AutoCapitalizeType

Chrome 69 以上版本

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

列舉

"words"

"sentences"

InputContext

說明輸入情境

屬性

• autoCapitalize

  AutoCapitalizeType

  Chrome 69 以上版本

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

• autoComplete

  boolean

  文字欄位是否要使用自動完成功能。

• autoCorrect

  boolean

  文字欄位是否要自動更正。

• contextID

  號碼

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

• shouldDoLearning

  boolean

  Chrome 68 以上版本

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

• spellCheck

  boolean

  文字欄位是否要使用拼字檢查功能。

• 類型

  InputContextType

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

InputContextType

Chrome 44 以上版本

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

列舉

"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

  字串 選用

  此 keyevent 傳送者的擴充功能 ID。

• 金鑰

  字串

  所按下金鑰的值

• keyCode

  數字 選填

  已淘汰的 HTML keyCode。這是系統和實作相依的數字代碼，用來表示與已按下按鍵相關聯的未修改識別碼。

• requestId

  字串 選用

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

• shiftKey

  布林值 (選用)

  是否按下 SHIFT 鍵。

• 類型

  KeyboardEventType

  Keyup 或 Keydown 其中之一。

KeyboardEventType

Chrome 44 以上版本

列舉

"keyup"

MenuItem

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

屬性

• 已勾選

  布林值 (選用)

  表示這個項目應使用勾號繪製。

• 已啟用

  布林值 (選用)

  表示這個項目已啟用。

• id

  字串

  系統會將字串傳遞到參照此 MenuItem 的回呼。

• 標籤

  字串 選用

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

• 樣式

  MenuItemStyle 選用

  選單項目的類型。

• 顯示

  布林值 (選用)

  表示該項目會顯示。

MenuItemStyle

Chrome 44 以上版本

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

列舉

MenuParameters

Chrome 88 以上版本

屬性

• engineID

  字串

  要使用的引擎 ID。

• items

  MenuItem[]

  要新增或更新的 MenuItem。系統會依照陣列在陣列中的順序加入。

MouseButton

Chrome 44 以上版本

使用者點選了哪些滑鼠按鈕。

列舉

"left"

ScreenType

Chrome 44 以上版本

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

列舉

UnderlineStyle

Chrome 44 以上版本

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

列舉

"doubleUnderline"

WindowPosition

Chrome 44 以上版本

候選視窗顯示位置。如果設為「cursor」，視窗會跟著遊標移動。如果設為「composition」，視窗會鎖定為組合的開頭。

列舉

方法

clearComposition()

Promise

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

清除目前的組合。如果這項擴充功能不是使用中的輸入法編輯器，就會失敗。

參數

• 參數

  物件

  • contextID

    號碼

    要清除組合的背景資訊 ID

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

commitText()

Promise

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

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

參數

• 參數

  物件

  • contextID

    號碼

    即將修訂文字的背景資訊 ID

  • text

    字串

    要修訂的文字

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

deleteSurroundingText()

Promise

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

刪除插入點周圍的文字。

參數

• 參數

  物件

  • contextID

    號碼

    刪除周圍文字的背景資訊 ID。

  • engineID

    字串

    接收事件的引擎 ID。

  • length

    號碼

    要刪除的字元數

  • 碳補償

    號碼

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

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 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setAssistiveWindowButtonHighlighted()

Promise Chrome 86 以上版本

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

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

參數

• 參數

  物件

  • announceString

    字串 選用

    螢幕閱讀器朗讀的文字。

  • buttonID

    AssistiveWindowButton

    按鈕的 ID

  • contextID

    號碼

    擁有輔助視窗的結構定義 ID。

  • 重要留言

    boolean

    是否要讓按鈕醒目顯示。

  • windowType

    按鈕所屬的視窗類型。

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setAssistiveWindowProperties()

Promise Chrome 85 以上版本

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

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

參數

• 參數

  物件

  • contextID

    號碼

    擁有輔助視窗的結構定義 ID。

  • 資源

    AssistiveWindowProperties

    輔助視窗的屬性。

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setCandidates()

Promise

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

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

參數

• 參數

  物件

  • 待選項目

    物件 []

    要在候選視窗中顯示的候選文字清單

    • 註解

      字串 選用

      描述候選人的其他文字

    • 候選

      字串

      候選人

    • id

      號碼

      候選人 ID

    • 標籤

      字串 選用

      顯示在候選文字旁邊的簡短字串，通常為快速鍵或索引

    • parentId

      數字 選填

      要新增這些候選文字的 ID

    • 用量

      物件選用

      字詞的使用方式或詳細說明。

      • body

        字串

        詳細資料說明的內文字串。

      • title

        字串

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

  • contextID

    號碼

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

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setCandidateWindowProperties()

Promise

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

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

參數

• 參數

  物件

  • engineID

    字串

    要設定屬性的引擎 ID。

  • 資源

    物件

    • auxiliaryText

      字串 選用

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

    • auxiliaryTextVisible

      布林值 (選用)

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

    • currentCandidateIndex

      數字 選填

      Chrome 84 以上版本

      目前所選候選項目的索引 (佔所有候選人總數)。

    • cursorVisible

      布林值 (選用)

      True 可顯示遊標，設為 false 即可隱藏遊標。

    • pageSize

      數字 選填

      每頁顯示的候選字數目。

    • totalCandidates

      數字 選填

      Chrome 84 以上版本

      候選項目期間的候選總數。

    • 直向

      布林值 (選用)

      如果候選視窗應以垂直方向顯示，則為 True，設為 false 表示橫向。

    • 顯示

      布林值 (選用)

      True 顯示「Candidate」視窗，輕觸「false」即可隱藏。

    • windowPosition

      WindowPosition 選用

      候選視窗顯示位置。

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setComposition()

Promise

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

設定目前的組合。如果這項擴充功能不是使用中的輸入法編輯器，就會失敗。

參數

• 參數

  物件

  • contextID

    號碼

    要設定樂曲文字的情境 ID

  • 游標

    號碼

    遊標在遊標文字中的位置。

  • 區隔」

    object[] optional

    區隔及相關類型的清單。

    • end

      號碼

      此片段後結束的字元索引。

    • start

      號碼

      此片段開始的字元索引

    • 樣式

      UnderlineStyle

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

  • selectionEnd

    數字 選填

    選取項目在文字中的結尾位置。

  • selectionStart

    數字 選填

    選取範圍文字中的起始位置。

  • text

    字串

    要設定的文字

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setCursorPosition()

Promise

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

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

參數

• 參數

  物件

  • candidateID

    號碼

    要選取的候選項目 ID。

  • contextID

    號碼

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

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setMenuItems()

Promise

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

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

參數

• 參數

  MenuParameters

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

updateMenuItems()

Promise

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

更新指定的 MenuItems 狀態

參數

• 參數

  MenuParameters

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 111 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onActivate

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

系統會在輸入法編輯器啟用時傳送這個事件。它可通知 IME 將接收 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,
)

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

參數

• 回呼

  功能

  callback 參數如下所示：

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

  • engineID

    字串

  • keyData

    KeyboardEvent

  • requestId

    字串

  • returns

    boolean|undefined

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

      字串

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