chrome.contextMenus

Descrição

Use a API chrome.contextMenus para adicionar itens ao menu de contexto do Google Chrome. Escolha a que 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 por 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 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 os métodos create() ou update().

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

Exemplos

Para testar essa API, instale o exemplo da API contextoMenus no 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 por "launcher". O contexto da tela de início 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 com o menu de contexto da tela de início.

Tipo enumerado

"frame"

"link"

"browser_action"

"page_action"

CreateProperties

Chrome 123 ou mais recente

Propriedades do novo item de menu de contexto.

Propriedades

  • marcado

    booleano opcional

    O estado inicial de uma caixa de seleção ou um botão de opção: true para o selecionado, false para o não selecionado. 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 será exibido. O valor padrão é ['page'].

  • documentUrlPatterns

    string[] opcional

    Restringe o item para ser aplicado somente a documentos ou frames cujo URL corresponda a um dos padrões fornecidos. Para detalhes sobre formatos de padrões, consulte Corresponder padrões.

  • ativado

    booleano opcional

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

  • id

    string opcional

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

  • parentId

    string|number opcional

    O ID de um item de menu pai; o item o torna 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.

  • título

    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 o Pig Latin" e o usuário selecionar a palavra "frio", o item do menu de contexto da seleção será "Traduzir 'legal' para o latino do Pig".

  • 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 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

      Informações sobre o item clicado e o contexto em que o clique aconteceu.

    • .

      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.

Tipo enumerado

"normal"

OnClickData

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

Propriedades

  • marcado

    booleano opcional

    Sinalizador que indica o estado de uma caixa de seleção ou de um item de opção depois de ser clicado.

  • editável

    boolean

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

  • frameId

    número opcional

    Chrome 51 ou mais recente

    É o ID do frame do elemento em que o menu de contexto foi clicado, se ele estivesse em um frame.

  • frameUrl

    string opcional

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

  • linkUrl

    string opcional

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

  • mediaType

    string opcional

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

  • menuItemId

    string|number

    O ID do item de menu que foi clicado.

  • pageUrl

    string opcional

    O URL da página em que o item do menu foi clicado. Esta propriedade não é definida quando o clique ocorre em um contexto em que não há uma página atual, como um menu de contexto da tela de início.

  • parentMenuItemId

    string|number opcional

    O ID pai, se houver, do item clicado.

  • selectionText

    string opcional

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

  • srcUrl

    string opcional

    Estará presente para elementos com um URL "src".

  • wasChecked

    booleano opcional

    Sinalizador que indica o estado de uma caixa de seleção ou de um item de opção antes do clique.

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 ocorrer um erro durante a criação, ele poderá não ser detectado até que o callback de criação seja disparado. Os detalhes estarão em runtime.lastError.

Parâmetros

  • createProperties

    CreateProperties

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • number|string

    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|number

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

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 123 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

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 optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 123 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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|number

    ID do item a ser atualizado.

  • updateProperties

    objeto

    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|number opcional

      ID do item que será definido como pai deste item. Observação: não é possível definir um item para se tornar filho de seu 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 tem esta aparência: 

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

      • informações

        OnClickData

        Chrome 44 ou mais recente
      • .

        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 optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 123 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

Eventos

onClicked

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

Disparado quando um item de menu de contexto é clicado.

Parâmetros