本頁面由 Cloud Translation API 翻譯而成。

chrome.commands

說明

你可以使用 Command API 新增鍵盤快速鍵，在擴充功能中觸發動作，例如開啟瀏覽器動作或傳送指令給擴充功能。

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"commands"

概念和用法

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 (在 macOS 上為 Option)、Shift、MacCtrl (僅限 macOS)、Command (僅限 ChromeOS)、Search (僅限 ChromeOS)

注意： Tab 基於無障礙功能考量，已從 Chrome 33 的支援金鑰清單中移除。

按鍵組合規定

擴充功能指令快速鍵必須包含 Ctrl 或 Alt。
- 修飾符無法與媒體鍵合併使用。
在 macOS 上，Ctrl 會自動轉換為 Command。
- 如要在 macOS 上使用 Control 鍵，請在定義 "mac" 時將 Ctrl 替換為 MacCtrl 快速鍵。
- 將 MacCtrl 用於其他平台時會產生驗證錯誤，並導致無法安裝擴充功能。
Shift 是所有平台上的選用修飾符。
Search 是 ChromeOS 專用的選用輔助鍵。
系統一律會優先採用特定作業系統和 Chrome 捷徑 (例如視窗管理) 擴充功能指令快捷鍵，無法覆寫。

，瞭解如何調查及移除這項存取權。

注意：不可使用涉及 Ctrl+Alt 的按鍵組合，以免與 AltGr 金鑰。

處理指令事件

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 事件。

如果您需要根據彈出式視窗開啟內容執行動作，建議您監聽 DOMContentLoaded 事件。

範圍

根據預設，指令的範圍僅限於 Chrome 瀏覽器。這表示瀏覽器無法有焦點，指令快速鍵已停用。從 Chrome 35 版開始，擴充功能開發人員可以可選擇將指令標示為「global」全域指令在 Chrome 沒有焦點時也能正常運作。

系統針對全域指令提供的鍵盤快速鍵建議只能用於 Ctrl+Shift+[0..9]。這是，盡可能降低覆寫其他應用程式捷徑的風險舉例來說，系統允許使用 Alt+P 做為全域指令，使用鍵盤快速鍵開啟列印對話方塊可能無法在其他應用程式中運作

使用者可以藉由公開的使用者介面，將全域指令重新對應至偏好的按鍵組合通知時間：chrome://extensions/shortcuts。

範例：

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

屬性

說明

string optional

擴充功能指令說明
名稱

string optional

Extension 指令的名稱
捷徑

string optional

這個指令的快速鍵已啟用，如未使用，則為空白。

方法

getAll()

Promise

chrome.commands.getAll(
  callback?: function,
)

傳回這個擴充功能及其捷徑的所有已註冊擴充功能指令 (如果已啟用)。在 Chrome 110 以下版本中，這個指令沒有傳回 _execute_action。

參數

回呼

函式選用

callback 參數如下所示：
```
(commands: Command[]) => void
```
- commands
  
  Command[] 鍵

傳回

Promise<Command[]>

Chrome 96 以上版本

Promise 適用於 Manifest V3 及以上版本，但系統會為回溯相容性您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的相同類型來解析。

活動

onCommand

chrome.commands.onCommand.addListener(
  callback: function,
)

使用鍵盤快速鍵啟用已註冊的指令時觸發。

參數

回呼

函式

callback 參數如下所示：
```
(command: string, tab?: tabs.Tab) => void
```
- Command 鍵
  
  字串
- 分頁
  
  tabs.Tab 選用