說明
你可以使用 Command API 新增鍵盤快速鍵,在擴充功能中觸發動作,例如開啟瀏覽器動作或傳送指令給擴充功能。
資訊清單
概念和用法
Commands API 可讓擴充功能開發人員定義特定指令,並將這些指令繫結至預設的按鍵組合。擴充功能接受的每個指令都必須在擴充功能的資訊清單中宣告為 "commands"
物件的屬性。
屬性索引鍵會做為指令的名稱。指令物件可以採用兩種屬性。
suggested_key
為指令宣告預設鍵盤快速鍵的選用屬性。如果省略,指令將取消繫結。這個屬性可接受字串或物件值。
「字串值」指定應用於所有平台的預設鍵盤快速鍵。
物件值可讓擴充功能開發人員自訂每個平台的鍵盤快速鍵。提供平台專屬捷徑時,有效的物件屬性為
default
、chromeos
、linux
、mac
和windows
。
詳情請參閱「按鍵組合相關規定」。
description
這個字串是用來為使用者提供指令用途的簡短說明。這個字串會顯示在擴充功能鍵盤快速鍵管理 UI 中。標準指令必須提供說明,但 Action 指令將忽略說明。
擴充功能可以有許多指令,但最多只能指定四個建議的鍵盤快速鍵。使用者可以透過 chrome://extensions/shortcuts
對話方塊手動新增更多捷徑。
支援的金鑰
以下按鍵可以使用指令��速鍵。主要定義須區分大小寫。如果嘗試載入擴充功能時使用了錯誤的大小寫金鑰,就會在安裝時產生資訊清單剖析錯誤。
- Alpha 金鑰
A
...Z
- 數字鍵
0
...9
- 標準索引鍵字串
一般:
Comma
、Period
、Home
、End
、PageUp
、PageDown
、Space
、Insert
、Delete
方向鍵:
Up
、Down
、Left
、Right
媒體鍵:
MediaNextTrack
、MediaPlayPause
、MediaPrevTrack
、MediaStop
- 輔助鍵字串
Ctrl
、Alt
(在 macOS 上為Option
)、Shift
、MacCtrl
(僅限 macOS)、Command
(僅限 ChromeOS)、Search
(僅限 ChromeOS)
按鍵組合規定
擴充功能指令快速鍵必須包含
Ctrl
或Alt
。- 修飾符無法與媒體鍵合併使用。
在 macOS 上,
Ctrl
會自動轉換為Command
。如要在 macOS 上使用 Control 鍵,請在定義
"mac"
快速鍵時將Ctrl
替換為MacCtrl
。將
MacCtrl
用於其他平台時會產生驗證錯誤,並導致無法安裝擴充功能。
Shift
是所有平台上的選用修飾符。Search
是 ChromeOS 專用的選用輔助鍵。特定作業系統和 Chrome 捷徑 (例如視窗管理) 一律優先於擴充功能指令���徑,且無法覆寫。
處理指令事件
manifest.json:
{
"name": "My extension",
...
"commands": {
"run-foo": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y"
},
"description": "Run \"foo\" on the current page."
},
"_execute_action": {
"suggested_key": {
"windows": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y",
"chromeos": "Ctrl+Shift+U",
"linux": "Ctrl+Shift+J"
}
}
},
...
}
在 Service Worker 中,您可以使用 onCommand.addListener
將處理常式繫結至資訊清單所定義的每個指令。例如:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
動作指令
_execute_action
(Manifest V3)、_execute_browser_action
(Manifest V2) 和 _execute_page_action
(Manifest V2) 指令會分別保留給觸發動作、瀏覽器動作或網頁動作的動作。這些指令不會分派 command.onCommand 事件,例如標準指令。
如果您需要根據彈出式視窗開啟內容執行動作,請考慮在彈出式視窗的 JavaScript 中監聽 DOMContentLoaded 事件。
內容範圍
根據預設,指令的範圍僅限於 Chrome 瀏覽器。這表示當瀏覽器沒有焦點時,指令快速鍵就會停用。從 Chrome 35 版開始,擴充功能開發人員可選擇將指令標示為「全域」。全域指令在 Chrome 沒有焦點時也能正常運作。
系統針對全域指令提供的鍵盤快速鍵建議只能用於 Ctrl+Shift+[0..9]
。這項保護措施可以降低其他應用程式中覆寫捷徑的風險,因為舉例來說,如果系統允許使用 Alt+P
做為全域語法,用來開啟列印對話方塊的鍵盤快速鍵可能不適用於其他應用程式。
使用者可以自由使用在 chrome://extensions/shortcuts
公開的 UI,將全域指令重新對應至偏好的按鍵組合。
範例:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
示例
下列範例可展現 Commands API 的核心功能。
基本指令
指令可讓擴充功能將邏輯對應至使用者可叫用的鍵盤快速鍵。基本上,指令只需要擴充功能資訊清單的指令宣告和註冊事件監聽器,如以下範例所示。
manifest.json:
{
"name": "Command demo - basic",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"commands": {
"inject-script": {
"suggested_key": "Ctrl+Shift+Y",
"description": "Inject a script on the page"
}
}
}
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" triggered`);
});
動作指令
如「使用」一節所述,您也可以將指令對應至擴充功能的動作。以下範例插入的內容指令碼,當使用者點選擴充功能的動作或觸發鍵盤快速鍵時,在目前頁面顯示快訊。
manifest.json:
{
"name": "Commands demo - action invocation",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"permissions": ["activeTab", "scripting"],
"action": {},
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+U",
"mac": "Command+U"
}
}
}
}
service-worker.js:
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
func: contentScriptFunc,
args: ['action'],
});
});
function contentScriptFunc(name) {
alert(`"${name}" executed`);
}
// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" called`);
});
確認指令已註冊
如果擴充功能嘗試註冊已有其他擴充功能的捷徑,則第二個擴充功能的快速指令將不會正常登錄。建議您預期這種可能性,並在安裝時檢查是否有衝突,藉此提供更可靠的使用者體驗。
service-worker.js:
chrome.runtime.onInstalled.addListener((details) => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
checkCommandShortcuts();
}
});
// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
chrome.commands.getAll((commands) => {
let missingShortcuts = [];
for (let {name, shortcut} of commands) {
if (shortcut === '') {
missingShortcuts.push(name);
}
}
if (missingShortcuts.length > 0) {
// Update the extension UI to inform the user that one or more
// commands are currently unassigned.
}
});
}
類型
Command
屬性
-
description
string optional
擴充功能指令說明
-
名稱
string optional
Extension 指令的名稱
-
捷徑
string optional
這個指令的快速鍵已啟用,如未使用,則為空白。
方法
getAll()
chrome.commands.getAll(
callback?: function,
)
傳回這個擴充功能及其捷徑的所有已註冊擴充功能指令 (如果已啟用)。在 Chrome 110 以下版本中,這個指令沒有傳回 _execute_action
。
傳回
-
Promise<Command[]>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但為了回溯相容性,提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。