chrome.input.ime

說明

使用 chrome.input.ime API 為 ChromeOS 實作自訂 IME。這樣擴充功能就能處理按鍵輸入、設定組合，以及管理候選字視窗。

權限

input

如要使用 input.ime API，必須在擴充功能資訊清單中宣告「input」權限。例如：

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

可用性

僅適用於 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。

列舉

「undo」

「addToDictionary」

AssistiveWindowProperties

Chrome 85 以上版本

輔助視窗的屬性。

屬性

  • announceString

    字串 選填

    ChromeVox 要朗讀的字串。

  • 類型

    「undo」

  • 顯示

    布林值

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

AssistiveWindowType

Chrome 85 以上版本

輔助視窗類型。

值

「undo」

AutoCapitalizeType

Chrome 69 以上版本

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

列舉

「characters」

「words」

「sentences」

InputContext

說明輸入情境

屬性

  • autoCapitalize

    AutoCapitalizeType

    Chrome 69 以上版本

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

  • autoComplete

    布林值

    文字欄位是否要自動完成。

  • autoCorrect

    布林值

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

  • contextID

    數字

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

  • shouldDoLearning

    布林值

    Chrome 68 以上版本

    是否應使用在文字欄位中輸入的文字，為使用者提供更準確的輸入建議。

  • spellCheck

    布林值

    文字欄位是否要進行拼字檢查。

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

InputContextType

Chrome 44 以上版本

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

列舉

「text」

「search」

「tel」

「url」

「email」

「number」

「password」

「null」

KeyboardEvent

請參閱 http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

屬性

  • altKey

    布林值 選填

    ALT 鍵是否已按下。

  • altgrKey

    布林值 選填

    Chrome 79 以上版本

    是否按下 ALTGR 鍵。

  • capsLock

    布林值 選填

    大寫鎖定鍵是否已啟用。

  • 程式碼

    字串

    按下實體按鍵的值。這個值不受目前鍵盤配置或修飾鍵狀態影響。

  • ctrlKey

    布林值 選填

    是否按下 Ctrl 鍵。

  • extensionId

    字串 選填

    這個 keyevent 傳送者的擴充功能 ID。

  • 金鑰

    字串

    按下按鍵的值

  • keyCode

    號碼 選填

    已淘汰的 HTML keyCode，這是與所按按鍵相關聯的未修改 ID，以數字代碼表示，且取決於系統和實作方式。

  • requestId

    字串 選填

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

  • shiftKey

    布林值 選填

    SHIFT 鍵是否已按下。

  • keyup 或 keydown 其中之一。

KeyboardEventType

Chrome 44 以上版本

列舉

"keyup"

「keydown」

MenuItem

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

屬性

  • 已勾選

    布林值 選填

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

  • 已啟用

    布林值 選填

    表示這個項目已啟用。

  • id

    字串

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

  • 標籤

    字串 選填

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

  • 樣式

    MenuItemStyle 選用

    選單項目的類型。

  • 顯示

    布林值 選填

    表示這個項目設為顯示狀態。

MenuItemStyle

Chrome 44 以上版本

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

列舉

「check」

「radio」

「separator」

MenuParameters

Chrome 88 以上版本

屬性

  • engineID

    字串

    要使用的引擎 ID。

  • 項目

    MenuItem[]

    要新增或更新的 MenuItems。系統會按照陣列中的順序新增這些項目。

MouseButton

Chrome 44 以上版本

按下的滑鼠按鈕。

列舉

「left」

「middle」

「right」

ScreenType

Chrome 44 以上版本

啟動輸入法編輯器的畫面類型。

列舉

「normal」

「login」

「lock」

「secondary-login」

UnderlineStyle

Chrome 44 以上版本

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

列舉

「underline」

"doubleUnderline"

「noUnderline」

WindowPosition

Chrome 44 以上版本

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

列舉

「cursor」

「composition」

方法

clearComposition()

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

清除目前的構圖。如果這個擴充功能不擁有有效的 IME，就會失敗。

參數

  • parameters

    物件

    • contextID

      數字

      要清除組合的環境 ID

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

commitText()

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

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

參數

  • parameters

    物件

    • contextID

      數字

      要提交文字的內容 ID

    • 文字

      字串

      要提交的文字

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

deleteSurroundingText()

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

刪除插入號周圍的文字。

參數

  • parameters

    物件

    • contextID

      數字

      要刪除周圍文字的內容 ID。

    • engineID

      字串

      接收事件的引擎 ID。

    • 長度

      數字

      要刪除的字元數

    • 碳補償

      數字

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

hideInputView()

chrome.input.ime.hideInputView(): void

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

keyEventHandled()

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

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

參數

  • requestId

    字串

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

  • 回應

    布林值

    如果系統處理了按鍵，則傳回 true，否則傳回 false

sendKeyEvents()

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

傳送按鍵事件。這項函式預計會由虛擬鍵盤使用。當使用者按下虛擬鍵盤上的按鍵時，系統會使用這個函式將該事件傳播至系統。

參數

  • parameters

    物件

    • contextID

      數字

      重要事件將傳送至的內容 ID，或將重要事件傳送至非輸入欄位的零。

    • keyData

      KeyboardEvent[]

      重要事件的資料。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

setAssistiveWindowButtonHighlighted()

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

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

參數

  • parameters

    物件

    • announceString

      字串 選填

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

    • 按鈕的 ID

    • contextID

      數字

      擁有輔助視窗的內容 ID。

    • 重要留言

      布林值

      是否要醒目顯示按鈕。

    • windowType

      「undo」

      按鈕所屬的視窗類型。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

setAssistiveWindowProperties()

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

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

參數

  • parameters

    物件

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

setCandidates()

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

設定目前的候選字清單。如果擴充功能不擁有有效的 IME，這項作業就會失敗

參數

  • parameters

    物件

    • 待選項目

      object[]

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

      • 註解

        字串 選填

        描述候選人的其他文字

      • 候選

        字串

        候選人

      • id

        數字

        候選人 ID

      • 標籤

        字串 選填

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

      • parentId

        號碼 選填

        要將這些候選人新增至哪個 ID 底下

      • 用量

        object 選填

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

        • body

          字串

          詳細說明的主體字串。

        • title

          字串

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

    • contextID

      數字

      擁有候選視窗的內容 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

setCandidateWindowProperties()

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

設定候選視窗的屬性。如果擴充功能不擁有使用中的 IME，這項操作就會失敗

參數

  • parameters

    物件

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

setComposition()

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

設定目前的合成。如果這個擴充功能不擁有有效的 IME，就會失敗。

參數

  • parameters

    物件

    • contextID

      數字

      要設定樂曲文字的環境 ID

    • cursor

      數字

      游標在文字中的位置。

    • 個區隔

      object[] optional

      區隔及其相關聯類型的清單。

      • End

        數字

        這個片段結尾的字元索引。

      • start

        數字

        這個區段的起始字元索引

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

    • selectionEnd

      號碼 選填

      選取範圍在文字中的結束位置。

    • selectionStart

      號碼 選填

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

    • 文字

      字串

      要設定的文字

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

setCursorPosition()

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

在候選字視窗中設定游標位置。如果這個擴充功能不擁有使用中的 IME，這項操作就不會執行任何動作。

參數

  • parameters

    物件

    • candidateID

      數字

      要選取的候選人 ID。

    • contextID

      數字

      擁有候選視窗的內容 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 111 以上版本

setMenuItems()

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

當這個 IME 處於啟用狀態時，將提供的選單項目新增至語言選單。

參數

  • parameters

    MenuParameters

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

updateMenuItems()

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

更新指定 MenuItem 的狀態

參數

  • parameters

    MenuParameters

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 111 以上版本

事件

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

      數字

onCandidateClicked

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

如果擴充功能擁有有效的 IME，就會傳送這個事件。

參數

  • callback

    函式

    callback 參數如下： 

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

    • engineID

      字串

    • candidateID

      數字

    • 按鈕

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

當焦點進入文字方塊時，系統會傳送這個事件。系統會將這項事件傳送給所有監聽這項事件且由使用者啟用的擴充功能。

參數

onInputContextUpdate

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

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

參數

onKeyEvent

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

作業系統傳送按鍵事件時觸發。如果擴充功能擁有有效的 IME，系統就會將事件傳送給該擴充功能。如果事件已處理，監聽器函式應傳回 true，否則傳回 false。如果系統會非同步評估事件，這個函式必須傳回未定義的值，且 IME 稍後必須使用結果呼叫 keyEventHandled()。

參數

  • callback

    函式

    callback 參數如下： 

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

    • returns

      boolean | undefined

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

        數字

        選取範圍的起始位置。如果沒有選取項目，這個值會指出插入號位置。

      • 焦點

        數字

        選取範圍的結束位置。如果沒有選取項目，這個值會指出插入號位置。

      • 碳補償

        數字

        Chrome 46 以上版本

        text 的偏移位置。由於 text 只包含游標附近的文字子集，因此位移值會指出 text 第一個字元的絕對位置。

      • 文字

        字串

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