menus

Adicione itens ao sistema de menu do navegador.

Esta API √© modelada sobre a API "contextMenus" do Chrome, que permite que extens√Ķes do Chrome adicione itens para o contexto de menu do navegador. A API browser.menus adiciona alguns recursos √† API do Chrome.

Antes do Firefox 55, esta API foi também nomeada, originalmente, de contextMenus, e esse nome era mantido como um alias; portanto, você pode usar o contextMenus para escrever um código que funcione no Firefox e também em outros navegadores.

Para usar essa API, você precisa da permissão de menus. Você também pode usar o alias contextMenus em vez de menus, mas se usar, a API deve ser acessada como browser.contextMenus.

Exceto para menus.getTargetElement(), essa API n√£o pode ser usada de scripts de conte√ļdo (content scripts).

Criando itens de menu

Para criar um item de menu, chamme o m√©todo menus.create() (en-US). Voc√™ passa esse m√©todo como um objeto contendo op√ß√Ķes para o item, incluindo o ID do item, o tipo do item, e os contextos no qual ele deve ser mostrado.

Escute os cliques no seu item de menu adicionando um ouvinte para o evento menus.onClicked (en-US). Este ouvinte ser√° passado

Listen for clicks on your menu item by adding a listener to the menus.onClicked (en-US) event. Este ouvinte receberá um objeto menus.OnClickData (en-US) que contém os detalhes do evento.

Voc√™ pode criar quatro tipos diferentes de itens de menu, com base no valor da propriedade type que voc√™ fornece nas op√ß√Ķes para create():

  • "normal": um item de menu que apenas mostra um r√≥tulo.
  • "checkbox": um item de menu que representa um estado bin√°rio. Ele mostra uma marca de verifica√ß√£o pr√≥xima ao r√≥tulo. Clicar no item ativa esta marca. O ouvinte de clique receber√° duas propriedades extras: "checked", indicando que o item foi marcado agora, e "wasChecked", indicando que o item foi marcado antes do evento do clique.
  • "radio": um item de menu que representa um de um grupo de escolhas. Como uma marca de verifica√ß√£o, isso tamb√©m mostra uma marca de verifica√ß√£o pr√≥xima ao r√≥tulo, e seu ouvinte de clique receber√° "checked" e "wasChecked". No entanto, se voc√™ criar mais de um item de r√°dio, os itens funcionar√£o como um grupo de itens de r√°dio: apenas um item no grupo poder√° ser verificado e clicar em um item o tornar√° o item marcado.
  • "separator": uma linha separando um grupo de itens.

Se você criou mais de um item de menu de contexto ou mais de um item de menu de ferramentas, os itens serão colocados em um submenu. O pai do submenu será identificado com o nome da extensão. Por exemplo, aqui está uma extensão chamada "Demonstração de menu" ("Menu demo"), que adicionou dois itens de menu de contexto:

√ćcones

Se você especificou ícones para sua extensão usando a chave "icons" do manifest, o item de menu exibirá o ícone especificado ao lado do rótulo. O navegador tentará escolher um ícone de 16x16 pixels para uma exibição normal ou um ícone de 32x32 pixels para uma exibição de alta densidade:

Apenas para itens dentro de um submenu, você pode especificar ícones customizados passando a opção icons para o menus.create() (en-US):

Exemplo

Aqui está um menu de contexto contendo quatro itens: um item normal, dois itens de rádio com separadores em cada lado, e uma marca de seleção. Os itens de rádio receberam ícones customizados.

Você pode criar um submenu como este usando o código abaixo:

browser.menus.create({
  id: "remove-me",
  title: browser.i18n.getMessage("menuItemRemoveMe"),
  contexts: ["all"]
}, onCreated);

browser.menus.create({
  id: "separator-1",
  type: "separator",
  contexts: ["all"]
}, onCreated);

browser.menus.create({
  id: "greenify",
  type: "radio",
  title: browser.i18n.getMessage("menuItemGreenify"),
  contexts: ["all"],
  checked: true,
  icons: {
    "16": "icons/paint-green-16.png",
    "32": "icons/paint-green-32.png"
  }
}, onCreated);

browser.menus.create({
  id: "bluify",
  type: "radio",
  title: browser.i18n.getMessage("menuItemBluify"),
  contexts: ["all"],
  checked: false,
  icons: {
    "16": "icons/paint-blue-16.png",
    "32": "icons/paint-blue-32.png"
  }
}, onCreated);

browser.menus.create({
  id: "separator-2",
  type: "separator",
  contexts: ["all"]
}, onCreated);

var checkedState = true;

browser.menus.create({
  id: "check-uncheck",
  type: "checkbox",
  title: browser.i18n.getMessage("menuItemUncheckMe"),
  contexts: ["all"],
  checked: checkedState
}, onCreated);

Tipos

menus.ContextType (en-US)
Os diferentes contextos em que um menu pode aparecer.
menus.ItemType (en-US)
O tipo de item de menu: "normal", "checkbox", "radio", "separator".
menus.OnClickData (en-US)
Informação enviada quando um item do menu é clicado.

Propriedades

menus.ACTION_MENU_TOP_LEVEL_LIMIT (en-US)
O n√ļmero m√°ximo de itens de extens√£o de n√≠vel superior que podem ser adicionados a um item de menu cujo ContextType seja "browser_action" ou "page_action".

Fun√ß√Ķes

menus.create() (en-US)
Cria um novo item de menu.
menus.getTargetElement() (en-US)
Retorna o elemento para um info.targetElementId determinado.
menus.overrideContext() (en-US)
Oculta todos os itens de menu padr√£o do Firefox para fornecer uma interface de usu√°rio personalizada do menu de contexto.
menus.refresh() (en-US)
Atualiza um menu que est√° sendo exibido no momento.
menus.remove() (en-US)
Remove um item do menu.
menus.removeAll() (en-US)
Remove todos os itens do menu adicionados por esta extens√£o.
menus.update() (en-US)
Atualiza um item do menu criado anteriormente.

Eventos

menus.onClicked (en-US)
Ativado quando um item de menu é clicado.
menus.onHidden (en-US)
Ativado quando o navegador esconde um menu.
menus.onShown (en-US)
Ativado quando o navegador mostra um menu.

Compatibilidade com navegadores

BCD tables only load in the browser

Example extensions

Reconhecimentos

Esta API é baseada na API chrome.contextMenus do Chromium. Esta documentação é derivada do context_menus.json do código do Chromium .