說明
使用 chrome.input.ime API 為 ChromeOS 實作自訂 IME。這樣一來，擴充功能就能處理按鍵動作、設定組合結構，以及管理候選字視窗。
權限
input您必須在擴充功能資訊清單中宣告「input」權限，才能使用 input.ime API。例如：
{
"name": "My extension",
...
"permissions": [
"input"
],
...
}
可用性
範例
下列程式碼會建立 IME，將輸入的字母轉換為大寫。
var context_id = -1;
browser.input.ime.onFocus.addListener(function(context) {
context_id = context.contextID;
});
browser.input.ime.onKeyEvent.addListener(
function(engineID, keyData) {
if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
browser.input.ime.commitText({"contextID": context_id,
"text": keyData.key.toUpperCase()});
return true;
} else {
return false;
}
}
);
類型
AssistiveWindowButton
輔助視窗中按鈕的 ID。
列舉
"undo"
"addToDictionary"
AssistiveWindowProperties
輔助視窗的屬性。
屬性
-
announceString
字串 選填
ChromeVox 要朗讀的字串。
-
類型
"undo"
-
顯示
布林值
設為 true 即可顯示 AssistiveWindow，設為 false 則會隱藏。
AssistiveWindowType
輔助視窗類型。
值
"undo"
AutoCapitalizeType
文字欄位的自動大寫類型。
列舉
"characters"
"words"
"sentences"
InputContext
說明輸入內容
屬性
-
autoCapitalizeChrome 69 以上版本 Chrome 148 以上版本中的 browser.*
文字欄位的自動大寫類型。
-
autoComplete
布林值
文字欄位是否要自動完成。
-
autoCorrect
布林值
文字欄位是否要自動更正。
-
contextID
數字
這可用來指定文字欄位作業的目標。呼叫 onBlur 後，這個 ID 就會失效。
-
shouldDoLearning
布林值
Chrome 68 以上版本 瀏覽器。*自 Chrome 148 起是否應使用在文字欄位中輸入的文字，改善使用者的輸入建議。
-
spellCheck
布林值
文字欄位是否要拼字檢查。
-
這個文字欄位編輯的值類型 (文字、數字、網址等)
InputContextType
這個文字欄位編輯的值類型 (文字、數字、網址等)
列舉
"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 以上版本 Chrome 148 以上版本中的 browser.*是否按下 ALTGR 鍵。
-
capsLock
布林值 選填
是否啟用 CAPS_LOCK。
-
程式碼
字串
按下的實體按鍵值。這個值不受目前鍵盤配置或輔助鍵狀態影響。
-
ctrlKey
布林值 選填
是否按下 CTRL 鍵。
-
extensionId
字串 選填
這個按鍵事件傳送者的擴充功能 ID。
-
金鑰
字串
按下的按鍵值
-
keyCode
數字 選填
已淘汰的 HTML keyCode，這是與系統和實作相關的數字代碼，代表與按下的按鍵相關聯的未修改 ID。
-
requestId
字串 選填
(已淘汰) 要求 ID。請改用
onKeyEvent事件中的requestId參數。 -
shiftKey
布林值 選填
是否按下 SHIFT 鍵。
-
keyup 或 keydown。
KeyboardEventType
列舉
"keyup"
"keydown"
MenuItem
輸入法用來透過語言選單與使用者互動的選單項目。
屬性
-
已勾選
布林值 選填
表示這個項目應以勾號繪製。
-
已啟用
布林值 選填
表示已啟用這個項目。
-
id
字串
要傳遞給參照這個 MenuItem 的回呼的字串。
-
標籤
字串 選填
選單中顯示的這個項目文字。
-
樣式
選單項目類型。
-
顯示
布林值 選填
表示這個項目可見。
MenuItemStyle
選單項目類型。分隔符之間的圓形按鈕會視為群組。
列舉
「check」
"radio"
"separator"
MenuParameters
屬性
-
engineID
字串
要使用的引擎 ID。
-
項目
MenuItem[]
要新增或更新的 MenuItems。系統會按照陣列中的順序新增。
MouseButton
點按了哪些滑鼠按鈕。
列舉
"left"
"middle"
"right"
ScreenType
啟用 IME 的螢幕類型。
列舉
"normal"
"login"
「鎖定」
"secondary-login"
UnderlineStyle
修改這個區段的底線類型。
列舉
"underline"
"doubleUnderline"
"noUnderline"
WindowPosition
候選字詞視窗的顯示位置。如果設為「cursor」，視窗會跟隨游標移動。如果設為「composition」，視窗會鎖定在組合結構的開頭。
列舉
"cursor"
"composition"
方法
clearComposition()
browser.input.ime.clearComposition(
parameters: object,
): Promise<boolean>
清除目前的組合。如果這個擴充功能不具備有效的 IME，則會失敗。
參數
-
parameters
物件
-
contextID
數字
要清除組合結構的結構定義 ID
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會傳回布林值，指出是否接受文字。如果失敗，系統會拒絕 promise。
commitText()
browser.input.ime.commitText(
parameters: object,
): Promise<boolean>
將提供的文字提交至目前的輸入內容。
參數
-
parameters
物件
-
contextID
數字
要提交文字的內容 ID
-
文字
字串
要提交的文字
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會傳回布林值，指出是否接受文字。如果失敗，系統會拒絕 promise。
deleteSurroundingText()
browser.input.ime.deleteSurroundingText(
parameters: object,
): Promise<void>
刪除插入點周圍的文字。
參數
-
parameters
物件
-
contextID
數字
要刪除周圍文字的情境 ID。
-
engineID
字串
接收事件的引擎 ID。
-
長度
數字
要刪除的字元數
-
碳補償
數字
從插入點位置開始刪除的偏移量。這個值可以為負數。
-
傳回
-
承諾<void>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。
hideInputView()
browser.input.ime.hideInputView(): void
隱藏系統自動彈出的輸入檢視畫面視窗。如果輸入檢視畫面視窗已隱藏，這項函式不會執行任何動作。
keyEventHandled()
browser.input.ime.keyEventHandled(
requestId: string,
response: boolean,
): void
表示已處理 onKeyEvent 接收到的按鍵事件。只有在 onKeyEvent 事件監聽器為非同步時，才應呼叫這個方法。
參數
-
requestId
字串
已處理事件的要求 ID。這應來自 keyEvent.requestId
-
回應
布林值
如果已處理按鍵動作，則傳回 true；否則傳回 false
sendKeyEvents()
browser.input.ime.sendKeyEvents(
parameters: object,
): Promise<void>
傳送按鍵事件。這個函式預期由虛擬鍵盤使用。當使用者按下虛擬鍵盤上的按鍵時，系統會使用這個函式將該事件傳播到系統。
參數
-
parameters
物件
-
contextID
數字
要傳送重要事件的內容 ID，或設為零，將重要事件傳送至非輸入欄位。
-
keyData
重要事件的資料。
-
傳回
-
承諾<void>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。
setAssistiveWindowButtonHighlighted()
browser.input.ime.setAssistiveWindowButtonHighlighted(
parameters: object,
): Promise<void>
醒目顯示/取消醒目顯示輔助視窗中的按鈕。
參數
-
parameters
物件
-
announceString
字串 選填
螢幕閱讀器要朗讀的文字。
-
buttonID
按鈕 ID
-
contextID
數字
擁有輔助視窗的結構定義 ID。
-
重要留言
布林值
是否要醒目顯示按鈕。
-
windowType
"undo"
按鈕所屬的視窗類型。
-
傳回
-
承諾<void>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。如果失敗，系統會拒絕 promise。
setAssistiveWindowProperties()
browser.input.ime.setAssistiveWindowProperties(
parameters: object,
): Promise<boolean>
顯示/隱藏具有指定屬性的輔助視窗。
參數
-
parameters
物件
-
contextID
數字
擁有輔助視窗的結構定義 ID。
-
輔助視窗的屬性。
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。
setCandidates()
browser.input.ime.setCandidates(
parameters: object,
): Promise<boolean>
設定目前的候選字詞清單。如果這個擴充功能並未擁有使用中的 IME，就會失敗
參數
-
parameters
物件
-
待選項目
object[]
候選字詞視窗中顯示的候選字詞清單
-
註解
字串 選填
候選項目的額外說明文字
-
候選
字串
候選人
-
id
數字
候選項目 ID
-
標籤
字串 選填
候選字詞旁顯示的短字串，通常是快速鍵或索引
-
parentId
數字 選填
要新增這些候選項目的 ID
-
用量
物件 選填
字詞的使用方式或詳細說明。
-
body
字串
詳細說明的內文字串。
-
title
字串
詳細資料說明的標題字串。
-
-
-
contextID
數字
擁有候選視窗的內容 ID。
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。
setCandidateWindowProperties()
browser.input.ime.setCandidateWindowProperties(
parameters: object,
): Promise<boolean>
設定候選字詞視窗的屬性。如果擴充功能並非使用中的輸入法，這項操作就會失敗
參數
-
parameters
物件
-
engineID
字串
要設定屬性的引擎 ID。
-
屬性
物件
-
auxiliaryText
字串 選填
顯示在候選字詞視窗底部的文字。
-
auxiliaryTextVisible
布林值 選填
如要顯示輔助文字，請設為 true；如要隱藏，請設為 false。
-
currentCandidateIndex
數字 選填
Chrome 84 以上版本 Chrome 148 以上版本的瀏覽器。*目前選取的候選字詞在所有候選字詞中的索引。
-
cursorVisible
布林值 選填
True 表示顯示游標，False 表示隱藏游標。
-
pageSize
數字 選填
每頁顯示的候選字詞數量。
-
totalCandidates
數字 選填
Chrome 84 以上版本 Chrome 148 以上版本的瀏覽器。*候選視窗的候選項目總數。
-
直向
布林值 選填
如果候選字詞視窗應垂直顯示，則為 True；如果應水平顯示，則為 False。
-
顯示
布林值 選填
如要顯示候選字詞視窗，請設為 true；如要隱藏，請設為 false。
-
windowPosition
候選字詞視窗的顯示位置。
-
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會解析。
setComposition()
browser.input.ime.setComposition(
parameters: object,
): Promise<boolean>
設定目前的組合。如果這個擴充功能不具備有效的 IME，則會失敗。
參數
-
parameters
物件
-
contextID
數字
要設定撰寫文字的內容 ID
-
cursor
數字
游標在文字中的位置。
-
個區隔
object[] 選填
區隔和相關類型的清單。
-
end
數字
這個片段結束後的字元索引。
-
start
數字
這個片段的起始字元索引
-
修改這個區段的底線類型。
-
-
selectionEnd
數字 選填
選取範圍在文字中的結束位置。
-
selectionStart
數字 選填
選取範圍在文字中的起始位置。
-
文字
字串
要設定的文字
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成後，系統會傳回布林值，指出是否接受文字。如果失敗，系統會拒絕 promise。
setCursorPosition()
browser.input.ime.setCursorPosition(
parameters: object,
): Promise<boolean>
設定游標在候選字詞視窗中的位置。如果這個擴充功能並未擁有有效的 IME，則這項操作無效。
參數
-
parameters
物件
-
candidateID
數字
要選取的候選項目 ID。
-
contextID
數字
擁有候選視窗的內容 ID。
-
傳回
-
Promise<boolean>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成時解析
setMenuItems()
browser.input.ime.setMenuItems(
parameters: MenuParameters,
): Promise<void>
這個 IME 啟用時，將提供的選單項目新增至語言選單。
參數
-
parameters
傳回
-
承諾<void>
Chrome 111 以上版本 Chrome 148 起為 browser.*
updateMenuItems()
browser.input.ime.updateMenuItems(
parameters: MenuParameters,
): Promise<void>
更新指定 MenuItems 的狀態
參數
-
parameters
傳回
-
承諾<void>
Chrome 111 以上版本 Chrome 148 起為 browser.*作業完成時解析
事件
onActivate
browser.input.ime.onActivate.addListener(
callback: function,
)
啟用 IME 時，系統會傳送這個事件。這表示 IME 將接收 onKeyPress 事件。
參數
-
callback
函式
callback參數如下：(engineID: string, screen: ScreenType) => void
-
engineID
字串
-
螢幕
-
onAssistiveWindowButtonClicked
browser.input.ime.onAssistiveWindowButtonClicked.addListener(
callback: function,
)
使用者點選輔助視窗中的按鈕時，系統會傳送這個事件。
參數
-
callback
函式
callback參數如下：(details: object) => void
-
詳細資料
物件
-
buttonID
所點擊按鈕的 ID。
-
windowType
輔助視窗的類型。
-
-
onBlur
browser.input.ime.onBlur.addListener(
callback: function,
)
焦點離開文字方塊時，系統會傳送這個事件。系統會將這項事件傳送給所有監聽這項事件，且由使用者啟用的擴充功能。
參數
-
callback
函式
callback參數如下：(contextID: number) => void
-
contextID
數字
-
onCandidateClicked
browser.input.ime.onCandidateClicked.addListener(
callback: function,
)
如果這個擴充功能擁有有效的輸入法，就會傳送這個事件。
參數
-
callback
函式
callback參數如下：(engineID: string, candidateID: number, button: MouseButton) => void
-
engineID
字串
-
candidateID
數字
-
按鈕
-
onDeactivated
browser.input.ime.onDeactivated.addListener(
callback: function,
)
停用 IME 時，系統會傳送這個事件。這表示 IME 不會再收到 onKeyPress 事件。
參數
-
callback
函式
callback參數如下：(engineID: string) => void
-
engineID
字串
-
onFocus
browser.input.ime.onFocus.addListener(
callback: function,
)
焦點進入文字方塊時，系統會傳送這個事件。系統會將這項事件傳送給所有監聽這項事件，且由使用者啟用的擴充功能。
參數
-
callback
函式
callback參數如下：(context: InputContext) => void
-
背景資訊
-
onInputContextUpdate
browser.input.ime.onInputContextUpdate.addListener(
callback: function,
)
當目前 InputContext 的屬性 (例如類型) 變更時，系統會傳送這個事件。系統會將這項事件傳送給所有監聽這項事件，且由使用者啟用的擴充功能。
參數
-
callback
函式
callback參數如下：(context: InputContext) => void
-
背景資訊
-
onKeyEvent
browser.input.ime.onKeyEvent.addListener(
callback: function,
)
作業系統傳送按鍵事件時觸發。如果這個擴充功能擁有有效的 IME，事件就會傳送至該擴充功能。如果事件已處理，事件監聽器函式應傳回 true，否則傳回 false。如果事件會以非同步方式評估，這個函式必須傳回未定義的值，且 IME 之後必須使用結果呼叫 keyEventHandled()。
參數
-
callback
函式
callback參數如下：(engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined
-
engineID
字串
-
keyData
-
requestId
字串
-
returns
boolean | undefined
-
onMenuItemActivated
browser.input.ime.onMenuItemActivated.addListener(
callback: function,
)
使用者選取選單項目時呼叫
參數
-
callback
函式
callback參數如下：(engineID: string, name: string) => void
-
engineID
字串
-
name
字串
-
onReset
browser.input.ime.onReset.addListener(
callback: function,
)
Chrome 終止進行中的文字輸入工作階段時，會傳送這個事件。
參數
-
callback
函式
callback參數如下：(engineID: string) => void
-
engineID
字串
-
onSurroundingTextChanged
browser.input.ime.onSurroundingTextChanged.addListener(
callback: function,
)
當插入點周圍的可編輯字串變更，或插入點位置移動時，系統會呼叫這個方法。每個來回方向的文字長度上限為 100 個字元。
參數
-
callback
函式
callback參數如下：(engineID: string, surroundingInfo: object) => void
-
engineID
字串
-
surroundingInfo
物件
-
anchor
數字
選取範圍的起始位置。如果未選取任何內容，這個值會指出插入點位置。
-
焦點
數字
選取範圍的結束位置。如果未選取任何內容，這個值會指出插入點位置。
-
碳補償
數字
Chrome 46 以上版本 Chrome 148 以上版本為 browser.*text的偏移位置。由於text只包含游標周圍的部分文字，因此偏移量代表text第一個字元的絕對位置。 -
文字
字串
游標周圍的文字。這只是輸入欄位中所有文字的一部分。
-
-