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
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
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 atributosrc
das tagsimg
,audio
evideo
e no atributohref
das tagsa
. -
title
string opcional
O texto a ser exibido no item. Obrigatório, a menos que
type
sejaseparator
. Quando o contexto forselection
, 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
Informações sobre o item clicado e o contexto em que o clique aconteceu.
-
.
Os detalhes da guia em que o clique ocorreu. Esse parâmetro não está presente em apps de plataforma.
-
ItemType
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.
-
string | número
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
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
número | string
ID do item recém-criado.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Remove um item de menu de contexto.
Parâmetros
-
string | número
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 recentePromessas 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()
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 recentePromessas 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()
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
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
-
title
string opcional
-
Tipo
ItemType opcional
-
visível
booleano opcional
Chrome 62 ou mais recenteIndica se o item está visível no menu.
-
onclick
void optional
A função
onclick
tem esta aparência:(info: OnClickData, tab: Tab) => {...}
-
informaçõesChrome 44 ou mais recente
-
.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 recentePromessas 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
-
callback
função
O parâmetro
callback
tem esta aparência:(info: OnClickData, tab?: tabs.Tab) => void
-
informações
-
.
tabs.Tab opcional
-