chrome.commands

说明

您可以使用 Command API 添加可在扩展程序中触发操作的键盘快捷键,例如,用于打开浏览器操作或向扩展程序发送命令的操作。

清单

必须在清单中声明以下键才能使用此 API。

"commands"

用法

Commands API 允许扩展程序开发者定义特定命令,并将它们绑定到默认命令 组合键。扩展程序接受的每个命令都必须声明为 "commands" 对象。

属性键用作命令的名称。命令对象可以采用两个属性。

suggested_key

可选属性,用于声明命令的默认键盘快捷键。如果省略, 命令就会解除绑定此属性可以采用字符串或对象值。

  • 字符串值用于指定所有应该使用的默认键盘快捷键 平台。

  • 借助对象值,扩展程序开发者可为每个对象值自定义键盘快捷键 平台。提供特定于平台的快捷方式时,有效的对象属性为 defaultchromeoslinuxmacwindows

如需了解更多详情,请参阅组合键要求

description

用于向用户提供命令用途简短说明的字符串。此字符串 显示在扩展程序键盘快捷键管理界面中。必须为标准广告添加说明 命令,但对于操作命令会被忽略。

一个扩展程序可以包含多个命令,但最多可以指定四个建议的键盘快捷键。通过 用户可以通过 chrome://extensions/shortcuts 对话框手动添加更多快捷方式。

支持的键

以下为可用的命令快捷键。关键定义区分大小写。正在尝试 使用大小写不正确的键加载扩展程序时,将导致清单解析错误,位于 安装时间。

Alpha 键
AZ
数字键
09
标准键字符串

常规 - CommaPeriodHomeEndPageUpPageDownSpaceInsertDelete

箭头键 - UpDownLeftRight

媒体键 - MediaNextTrackMediaPlayPauseMediaPrevTrackMediaStop

辅助键字符串

CtrlAlt(macOS 上为 Option)、ShiftMacCtrl(仅限 macOS)、Command(仅限 macOS)、Search(仅限 ChromeOS)

键组合要求

  • 扩展程序命令快捷方式必须包含 CtrlAlt

    • 修饰符不能与媒体键结合使用。
  • 在 macOS 上,Ctrl 会自动转换为 Command

    • 如需在 macOS 上使用 Ctrl 键,请在定义 "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

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((reason) => {
  if (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

属性

  • 说明

    字符串(可选)

    扩展程序命令说明

  • name

    字符串(可选)

    扩展程序命令的名称

  • 快捷指令

    字符串(可选)

    用于此命令的快捷键,如果未激活,则为空。

方法

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.commands.getAll(
  callback?: function,
)

返回此扩展程序及其快捷方式(如果处于活动状态)的所有已注册扩展程序命令。在 Chrome 110 之前,此命令不返回 _execute_action

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    (commands: Command[]) => void

返回

  • Promise<命令[]>

    Chrome 96 及更高版本

    只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

事件

onCommand

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

在使用键盘快捷键激活注册的命令时触发。

参数

  • callback

    函数

    callback 参数如下所示:

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

    • 命令

      字符串

    • Tab

      tabs.Tab(可选)