chrome.contextMenus

Descrição

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

Permissões

contextMenus

Declare a permissão "contextMenus" no manifesto da sua extensão para usar a API. Além disso, você deve especificar um ícone de 16 por 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"
  },
  ...
}

Conceitos e uso

Os itens do menu de contexto podem aparecer em qualquer documento (ou frame dentro de um documento), mesmo aqueles com file:// ou chrome://. Para controlar em quais documentos seus itens podem aparecer, especifique o documentUrlPatterns quando você chama os métodos create() ou update().

Você pode criar quantos itens de menu de contexto precisar, mas se mais de um da sua extensão for visíveis de uma só vez, o Google Chrome as recolhe automaticamente em um único menu principal.

Exemplos

Para testar essa API, instale o exemplo de API contextoMenus da página chrome-extension-samples repositório de dados.

Tipos

ContextType

Chrome 44 ou superior

Os diferentes contextos em que um menu pode aparecer. Especificar "todos" é equivalente à combinação de todos os outros contextos, exceto "launcher". A "tela de início" contexto 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/taskbar/dock/etc. Diferentes plataformas podem limitar o que é realmente suportado no menu de contexto da tela de início.

Enumeração

"todos"

"página"

"frame"

"seleção"

"link"

"editável"

"imagem"

"vídeo"

"áudio"

"tela de início"

"browser_action"

"page_action"

"ação"

CreateProperties

Chrome 123 ou versões mais recentes

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 selecionados, false para não selecionados. Somente um botão de opção pode ser selecionado 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 a ser aplicado apenas a documentos ou frames cujo URL corresponda a um dos padrões fornecidos. Para detalhes sobre formatos de padrão, consulte Padrões de correspondência.

  • ativado

    booleano opcional

    Indica se esse 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. isso torna o item um item 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.

  • 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 "Translate '%s' ao Pig Latin" e o usuário selecionar a palavra "cool" (legal), o item do menu de contexto para seleção será "traduzir 'legal'". ao Pig Latin".

  • tipo

    ItemType opcional

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

  • visível

    booleano opcional

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

  • clique

    void opcional

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

    A função onclick tem esta aparência: 

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

    • informações

      OnClickData

      As informações sobre o item clicado e o contexto em que ele ocorreu.

    • tab

      Tab

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

ItemType

Chrome 44 ou superior

Tipo de item de menu.

Enumeração

"normal"

"caixa de seleção"

"rádio"

"separador"

OnClickData

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

Propriedades

  • marcado

    booleano opcional

    Uma sinalização que indica o estado de uma caixa de seleção ou de um item de opção após ser clicado.

  • editável

    booleano

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

  • frameId

    número opcional

    Chrome 51 ou superior

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

  • frameUrl

    string opcional

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

  • linkUrl

    string opcional

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

  • mediaType

    string opcional

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

  • menuItemId

    string | número

    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 tiver ocorrido em um contexto em que não houver uma página atual, como em um menu de contexto da tela de início.

  • parentMenuItemId

    string | número opcional

    O ID pai, se houver, do item clicado.

  • selectionText

    string opcional

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

  • srcUrl

    string opcional

    Estará presente para elementos com "src" URL.

  • wasChecked

    booleano opcional

    Uma sinalização que indica o estado de uma caixa de seleção ou de 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. Todos os 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 ocorrer um erro durante a criação, talvez ele não seja 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 esta aparência: 

    () => void

Retorna

  • número | corda

    ID do item recém-criado.

remove()

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

Remove um item de 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 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

removeAll()

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

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

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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

    ID do item a ser atualizado.

  • updateProperties

    objeto

    As propriedades a serem atualizadas. Aceita os mesmos valores que a função contextMenus.create.

    • marcado

      booleano opcional

    • contexts

      [ContextType, ...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • ativado

      booleano opcional

    • parentId

      string | número opcional

      ID do item que será o pai dele. Observação: não é possível configurar 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 superior

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

    • clique

      void opcional

      A função onclick tem esta aparência: 

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

      • informações

        OnClickData

        Chrome 44 ou superior
      • tab

        Tab

        Chrome 44 ou superior

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 123 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onClicked

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

Disparado quando um item de menu de contexto é clicado.

Parâmetros