menus.update()

更新先前创建的菜单项。

为了与其他浏览器兼容,Firefox 将此方法同时通过 contextMenusmenus 命名空间提供。

这是一个异步函数,返回一个 Promise

语法

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

参数

id

integerstring。要更新的项的 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 可选

integerstring。父菜单项的 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。

示例

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

js
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);
  }
});

扩展程序示例

浏览器兼容性

注意: 此 API 基于 Chromium 的 chrome.contextMenus API。本文档摘自 Chromium 代码中的 context_menus.json