menus.update()

语法

let updating = browser.menus.update(
  id,               // integer or string
  updateProperties // object
)

参数

id

integer 或 string。要更新的项的 ID。

updateProperties

object。要更新的属性。与传递给 menus.create() 的 createProperties 对象相同，但 id 不能设置。此外，icons 只能针对菜单命令进行更改，而不能针对顶级上下文菜单进行更改。顶级图标会匹配扩展在扩展清单文件中声明的主要图标。

checked 可选

boolean。复选框或单选按钮项的初始状态：选中为 true，未选中为 false。在给定的单选按钮组中，一次只能选中一个单选按钮项。

command 可选

string。描述用户单击该项时应执行的操作的字符串。可识别的值有：

• "_execute_browser_action"：模拟单击扩展的浏览器操作，如果它有弹出窗口则打开它（仅限 Manifest V2）
• "_execute_action"：模拟单击扩展的操作，如果它有弹出窗口则打开它（仅限 Manifest V3）
• "_execute_page_action"：模拟单击扩展的页面操作，如果它有弹出窗口则打开它
• "_execute_sidebar_action"：打开扩展的侧边栏

有关详细信息，请参阅清单文件 commands 中特殊快捷方式的文档。

当指定了可识别的值之一时，单击该项不会触发 menus.onClicked 事件；而是触发默认操作，例如打开弹出窗口。否则，单击该项将触发 menus.onClicked，然后可以使用该事件来实现备用行为。

contexts 可选

array of menus.ContextType。此菜单项将显示的上下文数组。如果省略此选项

• 如果项的父项设置了上下文，则此项将继承其父项的上下文
• 否则，该项将获得一个上下文数组 ["page"]。

documentUrlPatterns 可选

array of string。允许您限制该项仅应用于 URL 与给定 匹配模式之一匹配的文档。这也适用于框架。

enabled 可选

boolean。此菜单项是否启用或禁用。默认为 true。

icons 可选

object。一个或多个要显示在该项旁边的自定义图标。自定义图标只能为出现在子菜单中的项设置。此属性是一个对象，其中为每个提供的图标都有一个属性：属性的名称应包含图标的像素大小，而 path 相对于扩展根目录的图标。浏览器会尝试为正常显示选择一个 16x16 像素的图标，或为高密度显示选择一个 32x32 像素的图标。为避免任何缩放，您可以这样指定图标

js

browser.menus.create({
  icons: {
    16: "path/to/geo-16.png",
    32: "path/to/geo-32.png",
  },
});

或者，您可以指定一个单一的 SVG 图标，它将被适当地缩放

js

browser.menus.create({
  icons: {
    16: "path/to/geo.svg",
  },
});

注意： 顶级菜单项使用清单中指定的 图标，而不是此键指定的图标。

id 可选

string。要为此项分配的唯一 ID。对于事件页面是必需的。不能与此扩展的另一个 ID 相同。

onclick 可选

function。单击菜单项时调用的函数。事件页面不能使用此函数：它们应该注册一个 menus.onClicked 的监听器。

parentId 可选

integer 或 string。父菜单项的 ID；这使得该项成为先前添加项的子项。注意：如果您创建了多个菜单项，这些项将放置在子菜单中。子菜单的父项将以扩展的名称标记。

targetUrlPatterns 可选

array of string。与 documentUrlPatterns 类似，但允许您基于 anchor 标签的 href 以及 img/audio/video 标签的 src 属性进行过滤。此参数支持任何 URL 方案，即使是通常不允许在匹配模式中使用的方案。

title 可选

string。要在该项中显示的文本。除非 type 是 "separator"，否则是必需的。

您可以在字符串中使用 %s。如果您在菜单项中使用此功能，并且当菜单显示时页面上选择了一些文本，那么选中的文本将被插入到标题中。例如，如果 title 是 "Translate '%s' to Pig Latin"，用户选择了单词 "cool" 然后激活了菜单，那么菜单项的标题将是："Translate 'cool' to Pig Latin"。

如果标题包含一个 ampersand "&"，则下一个字符将用作该项的访问键，ampersand 不会显示。例外情况是

• 如果下一个字符也是一个 ampersand：则会显示一个 ampersand，并且不会设置访问键。实际上，"&&" 用于显示一个 ampersand。
• 如果下一个字符是插值指令 "%s"：则 ampersand 不会显示，也不会设置访问键。
• 如果 ampersand 是标题中的最后一个字符：则 ampersand 不会显示，也不会设置访问键。

只有第一个 ampersand 将用于设置访问键：后续的 ampersands 不会显示，但也不会设置键。因此 "&A and &B" 将显示为 "A and B" 并将 "A" 设置为访问键。

type 可选

menus.ItemType。菜单项的类型："normal"（普通）、"checkbox"（复选框）、"radio"（单选按钮）、"separator"（分隔符）。默认为 "normal"。

viewTypes 可选

extension.ViewType。菜单项将显示在该视图类型列表。默认为任何视图，包括没有 viewType 的视图。

visible 可选

boolean。该项是否显示在菜单中。默认为 true。

返回值

一个 Promise，如果更新成功，它将以无参数的形式 fulfilled；如果更新失败，它将以错误消息的形式 rejected。

示例

此示例创建了一个菜单项，然后在用户单击它时更新其标题

function onUpdated() {
  console.log("item updated successfully");
}

function onError() {
  console.log("error updating item:", browser.runtime.lastError);
}

browser.menus.create({
  id: "do-not-click-me",
  title: "Do not click this button",
  contexts: ["all"],
});

browser.menus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "do-not-click-me") {
    let updating = browser.menus.update(info.menuItemId, {
      title: "Do not click this button again",
    });
    updating.then(onUpdated, onError);
  }
});

扩展程序示例

• menu-accesskey-visible
• menu-demo
• menu-labelled-open

浏览器兼容性