說明
使用 Commands API 新增鍵盤快速鍵，在擴充功能中觸發動作，例如開啟瀏覽器動作或傳送指令至擴充功能。
資訊清單
概念和用途
Commands API 可讓擴充功能開發人員定義特定指令，並繫結至預設按鍵組合。擴充功能接受的每個指令，都必須在擴充功能的資訊清單中，宣告為 "commands" 物件的屬性。
屬性鍵會做為指令名稱。指令物件可採用兩個屬性。
suggested_key選用屬性，用於宣告指令的預設鍵盤快速鍵。如果省略，指令將不會繫結。這個屬性可採用字串或物件值。
字串值會指定應在所有平台上使用的預設鍵盤快速鍵。
- 物件值可讓擴充功能開發人員自訂各平台的鍵盤快速鍵。提供平台專屬快速鍵時，有效的物件屬性為
default、chromeos、linux、mac和windows。
詳情請參閱按鍵組合規定。
- 物件值可讓擴充功能開發人員自訂各平台的鍵盤快速鍵。提供平台專屬快速鍵時，有效的物件屬性為
description- 這個字串用於向使用者簡短說明指令用途。這個字串會顯示在擴充功能鍵盤快速鍵管理 UI 中。標準指令必須提供說明，但動作指令會忽略說明。
擴充功能可以有多個指令，但最多只能指定四個建議的鍵盤快速鍵。使用者可以透過 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、Shift、MacCtrl(僅限 macOS)、Option(僅限 macOS)、Command(僅限 macOS)、Search(僅限 ChromeOS)
按鍵組合規定
擴充功能指令快速鍵必須包含
Ctrl或Alt。修飾鍵無法與媒體鍵搭配使用。
在許多 macOS 鍵盤上，
Alt是指 Option 鍵。在 macOS 上，
Command或MacCtrl也可以用來取代Ctrl，而Option鍵可以用來取代Alt(請參閱下一個項目符號)。
在 macOS 上，
Ctrl會自動轉換為Command。Command也可以在"mac"快速鍵中，明確指稱 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：
browser.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：
browser.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：
browser.action.onClicked.addListener((tab) => {
browser.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"
browser.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" called`);
});
驗證已註冊的指令
如果擴充功能嘗試註冊其他擴充功能已使用的快速鍵，第二個擴充功能的快速鍵將無法正常註冊。您可以預測這種可能性，並在安裝時檢查是否有衝突，為使用者提供更穩定的體驗。
service-worker.js：
browser.runtime.onInstalled.addListener((details) => {
if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
checkCommandShortcuts();
}
});
// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
browser.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.
}
});
}