chrome.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 suas adições ao menu de contexto se aplicam, como imagens, hiperlinks e páginas.

Permissões

contextMenus

Uso

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

Você pode criar quantos itens de menu de contexto precisar, mas se mais de um da sua extensão estiver visível ao mesmo tempo, o Google Chrome vai recolher automaticamente todos em um único menu principal.

Manifesto

Você precisa 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 de menu. Exemplo:

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

Exemplos

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

Tipos

ContextType

Chrome 44 ou mais recente

Os diferentes contextos em que um menu pode aparecer. Especificar "all" é equivalente à combinação de todos os outros contextos, exceto "launcher". O contexto "launcher" só é compatível com apps e é usado para adicionar itens de menu 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 em um menu de contexto da tela de início.

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

  • checked

    booleano opcional

    O estado inicial de uma caixa de seleção ou um botão de opção: true para selecionado e 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 este 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 cujo URL corresponda a um dos padrões fornecidos. Para mais detalhes sobre formatos de padrões, consulte Padrões de correspondência.

  • enabled

    booleano opcional

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

  • parentId

    string | número opcional

    O ID de um item de menu principal. Isso faz com que o item seja filho de um item adicionado anteriormente.

  • targetUrlPatterns

    string[] opcional

    Semelhante a documentUrlPatterns, filtros baseados 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. 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".

  • 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 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 é assim: 

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

    • 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 ou mais recente

O tipo de item de menu.

Enumeração

"normal"

"checkbox"

"rádio"

"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 um item de opção depois que ele é clicado.

  • editable

    booleano

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

  • frameId

    número optional

    Chrome 51 ou mais recente

    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 onde 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 é definida se o clique ocorreu em um contexto sem uma página atual, como um menu de contexto do iniciador.

  • parentMenuItemId

    string | número opcional

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

  • selectionText

    string opcional

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

  • srcUrl

    string opcional

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

Valor

6

Métodos

create()

chrome.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 só será detectado quando o callback de criação for acionado. Os detalhes estarão em runtime.lastError.

Parâmetros

  • createProperties

    CreateProperties

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • número | string

    O ID do item recém-criado.

remove()

Promessa 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
): 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.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 123+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

removeAll()

Promessa 
chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 123+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

update()

Promessa 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
): 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 da 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 principal. 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 ou mais recente

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

    • onclick

      void optional

      A função onclick é assim: 

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

      • Chrome 44 ou mais recente
      • tab

        Tab

        Chrome 44 ou mais recente

        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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 123+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onClicked

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

Disparado quando um item do menu de contexto é clicado.

Parâmetros