chrome.commands

說明

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

資訊清單

如要使用這個 API，您必須在資訊清單中宣告下列鍵。

"commands"

概念和用法

Commands API 可讓擴充功能開發人員定義特定指令，並將指令繫結至預設的按鍵組合。擴充功能接受的每個指令，都必須在擴充功能資訊清單中宣告為 "commands" 物件的屬性。

屬性鍵會用做指令名稱。指令物件可採用兩種屬性。

suggested_key

這是個選屬性，用於宣告指令的預設鍵盤快速鍵。如果省略，則指令將不會綁定。這個屬性可接受字串或物件值。

  • 字串值：指定應在所有平台上使用的預設鍵盤快速鍵。

  • 物件值可讓擴充功能開發人員為每個平台自訂鍵盤快速鍵。提供平台專屬捷徑時，有效的物件屬性為 default、chromeos、linux、mac 和 windows。

詳情請參閱按鍵組合規定。

description

用來向使用者提供指令用途的簡短說明。這個字串會顯示在擴充功能鍵盤快速鍵管理 UI 中。標準指令需要說明，但動作指令會忽略說明。

擴充功能可以包含多個指令，但最多只能指定四個建議的鍵盤快速鍵。使用者可以透過 chrome://extensions/shortcuts 對話方塊手動新增更多捷徑。

支援的鍵

以下是可用的指令快捷鍵。鍵定義區分大小寫。如果嘗試以錯誤大小寫的鍵載入擴充功能，會在安裝時導致資訊清單剖析錯誤。

英文字母鍵
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)、Command (僅限 macOS)、Search (僅限 ChromeOS)

按鍵組合規定

  • 擴充功能指令快捷鍵必須包含 Ctrl 或 Alt。

    • 輔助鍵不能與媒體鍵搭配使用。

    • 在許多 macOS 鍵盤上，Alt 是指 Option 鍵。

    • 在 macOS 上，Command 或 MacCtrl 也可以用來取代 Ctrl 或 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"
      }
    }
  },
  ...
}

在服務工作站中，您可以使用 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

屬性

  • 說明

    string 選填

    擴充功能指令說明

  • 名稱

    string 選填

    擴充功能指令的名稱

  • 捷徑

    string 選填

    這個指令的有效快速鍵，如果未啟用，則為空白。

方法

getAll()

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

傳回此擴充功能的所有已註冊擴充功能指令，以及其快速鍵 (如果已啟用)。在 Chrome 110 之前，這個指令不會傳回 _execute_action。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (commands: Command[]) => void

傳回

  • Promise<Command[]>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onCommand

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (command: string, tab?: tabs.Tab) => void