path: root/files/zh-cn/mozilla/add-ons/webextensions/api/menus/index.html

---
title: contextMenus
slug: Mozilla/Add-ons/WebExtensions/API/menus
tags:
  - API
  - WebExtensions
  - contextMenus
translation_of: Mozilla/Add-ons/WebExtensions/API/menus
original_slug: Mozilla/Add-ons/WebExtensions/API/contextMenus
---
<div>{{AddonSidebar}}</div>

<div>在浏览器菜单中添加条目。</div>

<div></div>

<div>此API基于Chrome的“contextMenus”API构建，该API可让Chrome扩展程序将项目添加到浏览器的上下文菜单中。 <code>browser.menus</code> API为Chrome的API添加了一些功能，特别是可以将项目添加到浏览器的“工具”菜单以及上下文菜单中。</div>

<div></div>

<div>在Firefox 55之前，这个API最初也被命名为<code>contextMenus</code>，并且这个名字被保留为别名，所以你可以使用<code>contextMenus</code>编写在Firefox和其他浏览器中工作的代码。</div>

<div></div>

<div>你需要拥有“menus”（或别名" contextMenus "）权限来使用此API。</div>

<h2 id="创建菜单项">创建菜单项</h2>

<p>使用 {{WebExtAPIRef("menus.create()")}}方法创建一个菜单项。你需要传递一个包含条目选项的对象，它包括条目的id，类型，和需要显示出来的文本值。</p>

<p>绑定一个监听器到{{WebExtAPIRef("contextMenus.onClicked")}}事件来监听你菜单项目的点击事件。此监听器会传递一个{{WebExtAPIRef("contextMenus.OnClickData")}}，它包含该事件的详细信息。</p>

<p>你可以根据在调用<code>create()</code>时所传递的参数中使用不同的<code>type</code>值来创建四种不同类型的菜单：</p>

<ul>
 <li>"normal"：只显示为一个标签的菜单项</li>
 <li>"checkbox"：一个表示二进制状态的菜单项。 它在菜单项旁边显示一个复选标记。 点击该菜单项切换复选标记。监听器会被传递两个额外的属性：“checked”，指示当前是否被选中，以及“wasChecked”，指示在此点击事件发生前是否被选中。</li>
 <li>"radio"：表示一组选项之一的上下文菜单项。 类似于复选框，它也在菜单项旁边显示一个复选标记，监听它的监听器也会被传递“checked”和“wasChecked”。 但是，如果您创建多个单选项，则这些项目将作为一组单选：组内只能选择一项，点击菜单项来选中它。</li>
 <li>"separator"：用于分割菜单的分割线。</li>
</ul>

<p>如果您创建了多个上下文菜单项目或多个工具菜单项目，则这些项目将被放置在子菜单中。 子菜单的父项将标有扩展名。 例如，下面是一个名为“Menu Demo”的扩展，添加了两个上下文菜单项：</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/15431/menus-1.png" style="display: block; height: 501px; margin-left: auto; margin-right: auto; width: 700px;"></p>

<h2 id="图标">图标</h2>

<p>如果你使用 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/icons">"icons" manifest key</a> 为你的扩展指定一个图标，你的菜单项的旁边就会显示一个指定的图标。浏览器会尝试在普通分辨率下使用16 x 16像素的图标，在高分辨率下使用32 x 32像素的图标：</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/15433/menus-2.png" style="display: block; height: 409px; margin-left: auto; margin-right: auto; width: 500px;"> 你可以通过调用 {{WebExtAPIRef("menus.create()")}} 时指定icons选项来给子菜单项设置图标。</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/15435/menus-3.png" style="display: block; height: 396px; margin-left: auto; margin-right: auto; width: 500px;"></p>

<h2 id="例子">例子</h2>

<p>下面是一个包含四个项目的菜单，他们分别是：一个普通选项，两个周围有分割线的单选，和一个复选框。单选框使用了自定义图标。</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/15437/menus-4.png" style="display: block; height: 790px; margin-left: auto; margin-right: auto; width: 500px;"></p>

<p>你可以使用以下代码创建一个这样的子菜单：</p>

<pre class="brush: js line-numbers  language-js"><code class="language-js">browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"remove-me"</span><span class="punctuation token">,</span>
  title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemRemoveMe"</span><span class="punctuation token">)</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span>

browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"separator-1"</span><span class="punctuation token">,</span>
  type<span class="punctuation token">:</span> <span class="string token">"separator"</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span>

browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"greenify"</span><span class="punctuation token">,</span>
  type<span class="punctuation token">:</span> <span class="string token">"radio"</span><span class="punctuation token">,</span>
  title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemGreenify"</span><span class="punctuation token">)</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span>
  checked<span class="punctuation token">:</span> <span class="keyword token">true</span><span class="punctuation token">,</span>
  icons<span class="punctuation token">:</span> <span class="punctuation token">{</span>
    <span class="string token">"16"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-green-16.png"</span><span class="punctuation token">,</span>
    <span class="string token">"32"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-green-32.png"</span>
  <span class="punctuation token">}</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span>

browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"bluify"</span><span class="punctuation token">,</span>
  type<span class="punctuation token">:</span> <span class="string token">"radio"</span><span class="punctuation token">,</span>
  title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemBluify"</span><span class="punctuation token">)</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span>
  checked<span class="punctuation token">:</span> <span class="keyword token">false</span><span class="punctuation token">,</span>
  icons<span class="punctuation token">:</span> <span class="punctuation token">{</span>
    <span class="string token">"16"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-blue-16.png"</span><span class="punctuation token">,</span>
    <span class="string token">"32"</span><span class="punctuation token">:</span> <span class="string token">"icons/paint-blue-32.png"</span>
  <span class="punctuation token">}</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span>

browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"separator-2"</span><span class="punctuation token">,</span>
  type<span class="punctuation token">:</span> <span class="string token">"separator"</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span>

<span class="keyword token">var</span> checkedState <span class="operator token">=</span> <span class="keyword token">true</span><span class="punctuation token">;</span>

browser<span class="punctuation token">.</span>menus<span class="punctuation token">.</span><span class="function token">create</span><span class="punctuation token">(</span><span class="punctuation token">{</span>
  id<span class="punctuation token">:</span> <span class="string token">"check-uncheck"</span><span class="punctuation token">,</span>
  type<span class="punctuation token">:</span> <span class="string token">"checkbox"</span><span class="punctuation token">,</span>
  title<span class="punctuation token">:</span> browser<span class="punctuation token">.</span>i18n<span class="punctuation token">.</span><span class="function token">getMessage</span><span class="punctuation token">(</span><span class="string token">"menuItemUncheckMe"</span><span class="punctuation token">)</span><span class="punctuation token">,</span>
  contexts<span class="punctuation token">:</span> <span class="punctuation token">[</span><span class="string token">"all"</span><span class="punctuation token">]</span><span class="punctuation token">,</span>
  checked<span class="punctuation token">:</span> checkedState
<span class="punctuation token">}</span><span class="punctuation token">,</span> onCreated<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>

<h2 id="类型">类型</h2>

<dl>
 <dt>{{WebExtAPIRef("contextMenus.ContextType")}}</dt>
 <dd>菜单里可以出现的不同内容。可能的值有："all", "audio", "browser_action", "editable", "frame", "image", "link", "page", "page_action", "password", "selection", "tab", "video".</dd>
 <dt>{{WebExtAPIRef("contextMenus.ItemType")}}</dt>
 <dd>菜单项的类别有: "normal", "checkbox", "radio", "separator".</dd>
 <dt>{{WebExtAPIRef("contextMenus.OnClickData")}}</dt>
 <dd>当菜单项被点击时发送的信息。</dd>
</dl>

<h2 id="属性">属性</h2>

<dl>
 <dt>{{WebExtAPIRef("contextMenus.ACTION_MENU_TOP_LEVEL_LIMIT")}}</dt>
 <dd>可以被添加进上下文菜单项的顶级扩展项的最大值，其ContextType可以是"browser_action" 或者 "page_action".</dd>
</dl>

<h2 id="函数">函数</h2>

<dl>
 <dt>{{WebExtAPIRef("contextMenus.create()")}}</dt>
 <dd>创建一个新的上下文菜单项目。</dd>
 <dt>{{WebExtAPIRef("contextMenus.update()")}}</dt>
 <dd>更新一个已经创建了的上下文菜单项目。</dd>
 <dt>{{WebExtAPIRef("contextMenus.remove()")}}</dt>
 <dd>删除一个上下文菜单项目。</dd>
 <dt>{{WebExtAPIRef("contextMenus.removeAll()")}}</dt>
 <dd>移除该插件创建的所有上下文菜单项目。</dd>
</dl>

<h2 id="事件">事件</h2>

<dl>
 <dt>{{WebExtAPIRef("contextMenus.onClicked")}}</dt>
 <dd>当一个上下文菜单项被点击时触发。</dd>
</dl>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{ Compat("webextensions.api.menus", 1, "true") }}</p>

<p>{{WebExtExamples("h2")}}</p>

<div class="note"><strong>致谢</strong>

<p>此API基于Chromium的 <a href="https://developer.chrome.com/extensions/contextMenus"><code>chrome.contextMenus</code></a> API. 此文档来自于Chromium代码中的<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/context_menus.json"><code>context_menus.json</code></a>。</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>