O Chrome agora oferece suporte ao namespace browser.* padronizado (disponível no Chrome 148). Estamos atualizando a documentação gradualmente. Leia mais no nosso guia de transição.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

browser.contextMenus

Descrição

Use a API chrome.contextMenus para adicionar itens ao menu de contexto do Google Chrome. Você pode escolher a quais tipos de objetos as adições do menu de contexto se aplicam, como imagens, hiperlinks e páginas.

Permissões

contextMenus

É necessário declarar a permissão "contextMenus" no manifesto da extensão para usar a API. Além disso, especifique um ícone de 16 x 16 pixels para ser exibido ao lado do item de menu. Exemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Conceitos e uso

Os itens do menu de contexto podem aparecer em qualquer documento (ou frame em um documento), mesmo aqueles com URLs file:// ou chrome://. Para controlar em quais documentos os itens podem aparecer, especifique o campo documentUrlPatterns ao chamar os métodos create() ou update().

É possível criar quantos itens de menu de contexto forem necessários, mas se mais de um da sua extensão estiver visível ao mesmo tempo, o Google Chrome os recolherá automaticamente em um único menu pai.

A maior parte desta página contém informações de referência para os membros dessa API. Para instruções sobre como usar a API, consulte Criar um menu de contexto.

Exemplos

Para testar essa API, instale o exemplo da API contextMenus do repositório chrome-extension-samples.

Tipos

ContextType

Chrome 44+ browser.* desde o Chrome 148

Os diferentes contextos em que um menu pode aparecer. Especificar "all" equivale à combinação de todos os outros contextos, exceto "launcher" e "tab". O contexto "launcher" só é compatível com apps e é usado para adicionar itens ao menu de contexto que aparece ao clicar no ícone do app no acesso rápido, na barra de tarefas, no dock etc. Plataformas diferentes podem limitar o que é realmente compatível em um menu de contexto de acesso rápido.

Enumeração

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
Aplica-se ao menu de contexto da ação da extensão (o ícone da barra de ferramentas).

"tab"
Aplica-se ao menu de contexto de uma guia na barra de guias.

CreateProperties

Chrome 123+ browser.* desde o Chrome 148

Propriedades do novo item do menu de contexto.

Propriedades

checked

booleano opcional

O estado inicial de uma caixa de seleção ou botão de opção: true para selecionado, false para não selecionado. Só é possível selecionar um botão de opção por vez em um determinado grupo.
contexts

[ContextType, ...ContextType[]] opcional

Lista de contextos em que esse item de menu vai aparecer. O valor padrão é ['page'].
documentUrlPatterns

string[] opcional

Restringe o item para que ele seja aplicado apenas a documentos ou frames com um URL que corresponda a um dos padrões fornecidos. Para detalhes sobre os formatos de padrão, consulte Padrões de correspondência.
enabled

booleano opcional

Indica se este item do menu de contexto está ativado ou desativado. O valor padrão é true.
id

string opcional

O ID exclusivo a ser atribuído a este item. Obrigatório para páginas de eventos. Não pode ser igual a outro ID desta extensão.
parentId

string | número opcional

O ID de um item de menu pai, o que torna o item um filho de um item adicionado anteriormente.
targetUrlPatterns

string[] opcional

Semelhante a documentUrlPatterns, filtra com base no atributo src das tags img, audio e video e no atributo href das tags a.
title

string opcional

O texto a ser exibido no item. É obrigatório, a menos que type seja separator. Quando o contexto for selection, use %s na string para mostrar o texto selecionado. Por exemplo, se o valor desse parâmetro for "Traduzir '%s' para Pig Latin" e o usuário selecionar a palavra "legal", o item do menu de contexto para a seleção será "Traduzir 'legal' para Pig Latin".
type

ItemType opcional

O tipo de item de menu. O valor padrão é normal.
visible

booleano opcional

Indica se o item está visível no menu.
onclick

void optional

Uma função que é chamada de volta quando o item de menu é clicado. Isso não está disponível em um service worker. Em vez disso, registre um listener para contextMenus.onClicked.

A função onclick é semelhante a:
```
(info: OnClickData, tab: Tab) => {...}
```
- info
  
  OnClickData
  
  Informações sobre o item clicado e o contexto em que o clique ocorreu.
- tab
  
  Tab
  
  Os detalhes da guia em que o clique ocorreu. Esse parâmetro não está presente em apps de plataforma.

ItemType

Chrome 44+ browser.* desde o Chrome 148

O tipo de item de menu.

Enumeração

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informações enviadas quando um item do menu de contexto é clicado.

Propriedades

checked

booleano opcional

Uma flag que indica o estado de uma caixa de seleção ou de um item de rádio depois de ser clicado.
editable

booleano

Uma sinalização que indica se o elemento é editável (entrada de texto, área de texto etc.).
frameId

número optional

Chrome 51+ browser.* desde o Chrome 148

O ID do frame do elemento em que o menu de contexto foi clicado, se ele estava em um frame.
frameUrl

string opcional

O URL do frame do elemento em que o menu de contexto foi clicado, se estiver em um frame.
linkUrl

string opcional

Se o elemento for um link, o URL para o qual ele aponta.
mediaType

string opcional

Pode ser "image", "video" ou "audio" se o menu de contexto foi ativado em um desses tipos de elementos.
menuItemId

string | número

O ID do item de menu que foi clicado.
pageUrl

string opcional

O URL da página em que o item de menu foi clicado. Essa propriedade não será definida se o clique ocorrer em um contexto em que não há uma página atual, como em um menu de contexto do acesso rápido.
parentMenuItemId

string | número opcional

O ID do item pai, se houver, para o item clicado.
selectionText

string opcional

O texto para a seleção de contexto, se houver.
srcUrl

string opcional

Vai estar presente para elementos com um URL "src".
wasChecked

booleano opcional

Uma sinalização que indica o estado de uma caixa de seleção ou de um item de rádio antes de ser clicado.

Propriedades

ACTION_MENU_TOP_LEVEL_LIMIT

O número máximo de itens de extensão de nível superior que podem ser adicionados a um menu de contexto de ação de extensão. Os itens acima desse limite serão ignorados.

Valor

Métodos

create()

browser.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

Cria um novo item de menu de contexto. Se ocorrer um erro durante a criação, ele pode não ser detectado até que o callback de criação seja acionado. Os detalhes estarão em runtime.lastError.

Parâmetros

createProperties

CreateProperties
callback

função optional

O parâmetro callback é semelhante a:
```
() => void
```

Retorna

número | string

O ID do item recém-criado.

remove()

browser.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

Remove um item do menu de contexto.

Parâmetros

menuItemId

string | número

O ID do item do menu de contexto a ser removido.

Retorna

Promessa<void>

Chrome 123+ browser.* desde o Chrome 148

É resolvido quando o menu de contexto é removido.

removeAll()

browser.contextMenus.removeAll(): Promise<void>

Remove todos os itens do menu de contexto adicionados por esta extensão.

Retorna

Promessa<void>

Chrome 123+ browser.* desde o Chrome 148

É resolvida quando a remoção é concluída.

update()

browser.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

Atualiza um item de menu de contexto criado anteriormente.

Parâmetros

id

string | número

O ID do item a ser atualizado.
updateProperties

objeto

As propriedades a serem atualizadas. Aceita os mesmos valores que a função contextMenus.create.
- checked
  
  booleano opcional
- contexts
  
  [ContextType, ...ContextType[]] opcional
- documentUrlPatterns
  
  string[] opcional
- enabled
  
  booleano opcional
- parentId
  
  string | número opcional
  
  O ID do item que será o pai deste item. Observação: não é possível definir um item como filho do próprio descendente.
- targetUrlPatterns
  
  string[] opcional
- title
  
  string opcional
- type
  
  ItemType opcional
- visible
  
  booleano opcional
  
  Chrome 62+ browser.* desde o Chrome 148
  
  Indica se o item está visível no menu.
- onclick
  
  void optional
  
  A função onclick é semelhante a:
```
(info: OnClickData, tab: Tab) => {...}
```
  - info
    
    OnClickData
    
    Chrome 44+ browser.* desde o Chrome 148
  - tab
    
    Tab
    
    Chrome 44+ browser.* desde o Chrome 148
    
    Os detalhes da guia em que o clique ocorreu. Esse parâmetro não está presente em apps de plataforma.

Retorna

Promessa<void>

Chrome 123+ browser.* desde o Chrome 148

É resolvido quando o menu de contexto é atualizado.

Eventos

onClicked

browser.contextMenus.onClicked.addListener(
  callback: function,
)

Disparado quando um item do menu de contexto é clicado.

Parâmetros

callback

função

O parâmetro callback é semelhante a:
```
(info: OnClickData, tab?: tabs.Tab) => void
```
- info
  
  OnClickData
- tab
  
  tabs.Tab opcional

browser.contextMenus Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Permissões

Conceitos e uso

Exemplos

Tipos

ContextType

Enumeração

CreateProperties

Propriedades

ItemType

Enumeração

OnClickData

Propriedades

Propriedades

ACTION_MENU_TOP_LEVEL_LIMIT

Valor

Métodos

create()

Parâmetros

Retorna

remove()

Parâmetros

Retorna

removeAll()

Retorna

update()

Parâmetros

Retorna

Eventos

onClicked

Parâmetros

browser.contextMenus