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

Você precisa 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 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 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 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.

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

  • marcado

    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.

  • ativado

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

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

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

  • 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

    number 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

    Um de "image", "video" ou "audio" se o menu de contexto foi 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 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 | number opcional

    O ID do item pai, se houver, do 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

  • number | string

    O ID do item recém-criado.

remove()

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

Remove um item do menu de contexto.

Parâmetros

  • menuItemId

    string | number

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

Retorna

  • Promise<void>

    Chrome 123+

removeAll()

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

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

Retorna

  • Promise<void>

    Chrome 123+

update()

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

Atualiza um item de menu de contexto criado anteriormente.

Parâmetros

  • ID

    string | number

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

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

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

      • informações

        OnClickData

        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.

Retorna

  • Promise<void>

    Chrome 123+

Eventos

onClicked

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

Disparado quando um item do menu de contexto é clicado.

Parâmetros