commands

語法

commands 鍵是一個物件，每個快捷鍵是它的一個屬性。屬性的名稱就是快捷鍵的名稱。

每個快捷鍵的值是一個最多包含 2 個屬性的物件

1. suggested_key 可選：啟用快捷鍵的按鍵組合。
2. description 可選：一個描述快捷鍵的字串，即它的功能。

suggested_key 屬性是一個物件，包含以下任意或全部屬性（均為字串）：

• "default"
• "mac"
• "linux"
• "windows"
• "chromeos"
• "android"
• "ios"

每個屬性的值是該平臺命令的鍵盤快捷鍵，以 + 分隔的按鍵組成的字串。"default" 的值用於所有未明確列出的平臺。如果未包含 "default"，則該命令在未包含的任何平臺上都沒有鍵盤快捷鍵，除非使用者配置了快捷鍵或透過 commands.update API 配置。

例如

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event to the extension"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  },
  "do-something-else": {
    "suggested_key": {
      "linux": "Ctrl+Shift+P"
    }
  },
  "do-nothing-yet": {}
}

此 JSON 定義了以下快捷鍵：

1. "toggle-feature"，在 Linux 上透過 Ctrl + Shift + U 訪問，在所有其他平臺上透過 Alt + Shift + U 訪問。
2. "do-another-thing"，在所有平臺上透過 Ctrl + Shift + Y 訪問。
3. "do-something-else"，僅在 Linux 上透過 Ctrl + Shift + P 訪問，在其他平臺上沒有預設快捷鍵。
4. "do-nothing-yet"，不設定鍵盤快捷鍵，但允許使用者透過 commands.update API 設定快捷鍵。

您可以使用如下程式碼監聽命令，這裡以 "toggle-feature" 命令為例：

browser.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("Toggling the feature!");
  }
});

特殊快捷鍵

有 4 個具有預設操作的特殊快捷鍵，對於這些快捷鍵，commands.onCommand 事件不會觸發。

• _execute_browser_action：作用類似於點選透過 browserAction 建立或在 manifest.json 的 browser_action 鍵中指定的工具欄按鈕。
• _execute_action：作用類似於點選透過 action 建立或在 manifest.json 的 action 鍵中指定的工具欄按鈕。
• _execute_page_action：作用類似於點選透過 pageAction 建立或在 manifest.json 的 page_action 鍵中指定的位址列按鈕。
• _execute_sidebar_action：開啟擴充套件程式在 manifest.json 的 sidebar_action 鍵中指定的側邊欄。

這些特殊快捷鍵的可用性因 manifest 版本和瀏覽器而異，如下所示：

例如，此 JSON 定義了一個點選擴充套件程式瀏覽器操作的按鍵組合：

"commands": {
  "_execute_browser_action": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}

快捷鍵值

快捷鍵有兩種有效格式：按鍵組合或媒體鍵。

按鍵組合

按鍵組合必須包含 2 或 3 個按鍵：

1. 修飾鍵（必需，功能鍵除外）。可以是以下任何一個："Ctrl"、"Alt"、"Command" 或 "MacCtrl"。
2. 次要修飾鍵（可選）。如果提供，必須是 "Shift" 或（對於 Firefox ≥ 63）"Ctrl"、"Alt"、"Command" 或 "MacCtrl" 中的任意一個。不能是已用作主修飾鍵的修飾鍵。
3. 鍵（必需）。可以是以下任何一個：
   • 字母 A – Z
   • 數字 0 – 9
   • 功能鍵 F1 – F12

     注意：從 Firefox 135 開始，使用者可以使用管理擴充套件快捷鍵將 F13 到 F19 鍵分配給擴充套件。您的擴充套件程式無法從 manifest 檔案中分配這些鍵。但是，您可以使用 commands.update 進行分配。

   • Comma、Period、Home、End、PageUp、PageDown、Space、Insert、Delete、Up、Down、Left、Right

按鍵組合以字串形式給出，其中包含上述順序的按鍵值，並用 + 分隔。例如，"Ctrl+Shift+Z"。

如果按鍵組合已被瀏覽器（如 "Ctrl+P"）或現有附加元件使用，則您無法覆蓋它。您可以定義它，但當用戶按下該按鍵組合時，您的事件處理程式將不會被呼叫。

媒體鍵

或者，快捷鍵可以指定為以下媒體鍵之一：

• "MediaNextTrack"
• "MediaPlayPause"
• "MediaPrevTrack"
• "MediaStop"

更新快捷鍵

在 Firefox 中，您的擴充套件程式可以使用 commands.update() 更新快捷鍵設定。使用者可以使用 about:addons 中的管理擴充套件快捷鍵選項更新快捷鍵，如此影片所示。您的擴充套件程式可以使用 commands.openShortcutSettings() 開啟此選項。

在 Chrome 中，擴充套件程式無法以程式設計方式更新快捷鍵。使用者可以在 chrome://extensions/shortcuts 中更改快捷鍵，該頁面可以使用 tabs.create() 開啟。

Safari 不支援對擴充套件快捷鍵進行程式設計或使用者修改。

示例

僅使用預設按鍵組合定義鍵盤快捷鍵

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

定義兩個鍵盤快捷鍵，其中一個具有平臺特定的按鍵組合

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}

瀏覽器相容性