chrome.contextMenus

Descrição

Use a API chrome.contextMenus para adicionar itens ao menu de contexto do Google Chrome. Você pode escolher os tipos de objetos aos quais 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 exibição ao lado do item do 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 seus itens podem aparecer, especifique o campo documentUrlPatterns ao chamar os métodos create() ou update().

Você pode 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 vai automaticamente fechá-los em um único menu pai.

Exemplos

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

Tipos

ContextType

Chrome 44 e versões mais recentes

Os diferentes contextos em que um menu pode aparecer. Especificar "all" é equivalente à combinação de todos os outros contextos, exceto "launcher". O contexto "launcher" tem suporte apenas para apps e é usado para adicionar itens ao menu de contexto que aparece ao clicar no ícone do app na tela de início/barra de tarefas/dock/etc. Diferentes plataformas podem limitar o que é realmente compatível com um menu de contexto de acesso rápido.

Enumeração

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123+

Propriedades do novo item do menu de contexto.

Propriedades

  • marcado

    booleano opcional

    O estado inicial de uma caixa de seleção ou botão de opção: true para selecionado, false para desmarcado. 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 o item de menu vai aparecer. O valor padrão é ['page'].

  • documentUrlPatterns

    string[] opcional

    Restringe o item para aplicar apenas a documentos ou frames cujo URL corresponde a um dos padrões fornecidos. Para mais detalhes sobre os formatos de padrão, consulte Padrões de correspondência.

  • ativado

    booleano opcional

    Indica se o 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 para essa extensão.

  • parentId

    string | número opcional

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

  • targetUrlPatterns

    string[] opcional

    Assim como documentUrlPatterns, os filtros são baseados no atributo src das tags img, audio e video e no atributo href das tags a.

  • título

    string opcional

    O texto a ser exibido no item. Isso é 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".

  • tipo

    ItemType opcional

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

  • visível

    booleano opcional

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

  • onclick

    void optional

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

    A função onclick é semelhante a esta: 

    (info: OnClickData, tab: Tab) => {...}

    • informações

      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 e versões mais recentes

O tipo de item de menu.

Enumeração

"normal"

"Caixa de seleção"

"radio"

"separator"

OnClickData

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

Propriedades

  • marcado

    booleano opcional

    Uma flag que indica o estado de uma caixa de seleção ou um item de opção depois que ele é clicado.

  • editável

    booleano

    Uma flag que indica se o elemento é editável (entrada de texto, textarea etc.).

  • frameId

    número opcional

    Chrome 51 e versões mais recentes

    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 ele estava em um frame.

  • linkUrl

    string opcional

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

  • mediaType

    string opcional

    "imagem", "vídeo" ou "áudio", se o menu de contexto foi ativado em um desses tipos de elementos.

  • menuItemId

    string | número

    O ID do item de menu clicado.

  • pageUrl

    string opcional

    O URL da página em que o item de menu foi clicado. Essa propriedade não é definida se o clique ocorreu em um contexto em que não há uma página atual, como em um menu de contexto do iniciador.

  • parentMenuItemId

    string | número opcional

    O ID pai, se houver, do item clicado.

  • selectionText

    string opcional

    O texto da seleção de contexto, se houver.

  • srcUrl

    string opcional

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

  • wasChecked

    booleano opcional

    Uma flag que indica o estado de uma caixa de seleção ou um item de opção antes de clicar nele.

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. Itens além desse limite serão ignorados.

Valor

6

Métodos

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

Cria um novo item de menu de contexto. Se um erro ocorrer durante a criação, ele poderá 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 opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • number | string

    O ID do item recém-criado.

remove()

Promessa 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

Remove um item do menu de contexto.

Parâmetros

  • menuItemId

    string | número

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 123+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

removeAll()

Promessa 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 123+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

update()

Promessa 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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 da função contextMenus.create.

    • marcado

      booleano opcional

    • contexts

      [ContextType, ...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • ativado

      booleano opcional

    • parentId

      string | número opcional

      O ID do item que será definido como principal. Observação: não é possível definir um item para se tornar filho do próprio descendente.

    • targetUrlPatterns

      string[] opcional

    • título

      string opcional

    • tipo

      ItemType opcional

    • visível

      booleano opcional

      Chrome 62 ou mais recente

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

    • onclick

      void optional

      A função onclick é semelhante a esta: 

      (info: OnClickData, tab: Tab) => {...}

      • informações

        OnClickData

        Chrome 44 e versões mais recentes
      • tab

        Tab

        Chrome 44 e versões mais recentes

        Os detalhes da guia em que o clique ocorreu. Esse parâmetro não está presente em apps de plataforma.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 123+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

Eventos

onClicked

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

É acionado quando um item do menu de contexto é clicado.

Parâmetros