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

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 o método 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.

Manifesto

É necessário declarar a permissão "contextMenus" no manifesto da extensão para usar a API. Além disso, você deve especificar 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 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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas 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,
)

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 apenas 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 de menu de contexto é clicado.

Parâmetros