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"
    }
  }
}

浏览器兼容性