menus.update()
更新先前创建的菜单项。
为了与其他浏览器兼容,Firefox 将此方法同时通过 contextMenus
和 menus
命名空间提供。
这是一个异步函数,返回一个 Promise
。
语法
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
ofmenus.ContextType
。此菜单项将显示的上下文数组。如果省略此选项- 如果项的父项设置了上下文,则此项将继承其父项的上下文
- 否则,该项将获得一个上下文数组 ["page"]。
documentUrlPatterns
可选-
array
ofstring
。允许您限制该项仅应用于 URL 与给定 匹配模式之一匹配的文档。这也适用于框架。 enabled
可选-
boolean
。此菜单项是否启用或禁用。默认为true
。 icons
可选-
object
。一个或多个要显示在该项旁边的自定义图标。自定义图标只能为出现在子菜单中的项设置。此属性是一个对象,其中为每个提供的图标都有一个属性:属性的名称应包含图标的像素大小,而 path 相对于扩展根目录的图标。浏览器会尝试为正常显示选择一个 16x16 像素的图标,或为高密度显示选择一个 32x32 像素的图标。为避免任何缩放,您可以这样指定图标jsbrowser.menus.create({ icons: { 16: "path/to/geo-16.png", 32: "path/to/geo-32.png", }, });
或者,您可以指定一个单一的 SVG 图标,它将被适当地缩放
jsbrowser.menus.create({ icons: { 16: "path/to/geo.svg", }, });
注意: 顶级菜单项使用清单中指定的 图标,而不是此键指定的图标。
id
可选-
string
。要为此项分配的唯一 ID。对于事件页面是必需的。不能与此扩展的另一个 ID 相同。 onclick
可选-
function
。单击菜单项时调用的函数。事件页面不能使用此函数:它们应该注册一个menus.onClicked
的监听器。 parentId
可选-
integer
或string
。父菜单项的 ID;这使得该项成为先前添加项的子项。注意:如果您创建了多个菜单项,这些项将放置在子菜单中。子菜单的父项将以扩展的名称标记。 targetUrlPatterns
可选-
array
ofstring
。与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);
}
});
扩展程序示例
浏览器兼容性
加载中…
注意: 此 API 基于 Chromium 的 chrome.contextMenus
API。本文档摘自 Chromium 代码中的 context_menus.json
。