Descrição
Use a API chrome.pageAction
para colocar ícones da barra de ferramentas principal do Google Chrome, à direita da barra de endereço. As ações da página representam ações que podem ser realizadas na página atual, mas que não são aplicáveis a todas as páginas. As ações da página aparecem esmaecidas quando estão inativas.
Disponibilidade
Alguns exemplos:
- Inscrever-se no feed RSS desta página
- Fazer uma apresentação de slides com as fotos desta página
O ícone RSS na captura de tela a seguir representa uma ação da página que permite que você se inscreva no feed RSS da página atual.
As ações da página oculta aparecem esmaecidas. Por exemplo, o feed RSS abaixo está esmaecido, porque não é possível se inscrever no feed da página atual:
Em vez disso, use uma ação do navegador para que os usuários possam sempre interagir com sua extensão.
Manifesto
Registre a ação da página no manifesto de extensões da seguinte forma:
{
"name": "My extension",
...
"page_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional; shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Como dispositivos com fatores de escala menos comuns, como 1,5x ou 1,2x, estão se tornando mais comuns, recomendamos fornecer vários tamanhos para os ícones. O Chrome selecionará o mais próximo e o dimensionará para preencher o espaço de 16 dip. Isso também garante que, se o tamanho de exibição do ícone for mudado, você não vai precisar fazer mais nada para fornecer ícones diferentes. No entanto, se a diferença de tamanho for muito extrema, esse dimensionamento poderá fazer com que o ícone perca detalhes ou pareça distorcido.
A sintaxe antiga para registrar o ícone padrão ainda é compatível:
{
"name": "My extension",
...
"page_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
Partes da interface
Assim como as ações do navegador, as ações da página podem ter um ícone, uma dica e um pop-up. No entanto, elas não podem ter selos. Além disso, as ações da página podem ficar esmaecidas. Para encontrar informações sobre ícones, dicas e pop-ups, leia sobre a interface de ação do navegador.
Para fazer com que uma ação de página apareça e fique esmaecida, use os métodos pageAction.show
e
pageAction.hide
, respectivamente. Por padrão, uma ação da página aparece esmaecida. Ao
mostrar, você especifica a guia em que o ícone deve aparecer. O ícone permanece visível até que a guia
seja fechada ou comece a exibir um URL diferente, porque o usuário clica em um link, por exemplo.
Dicas
Para ter o melhor impacto visual, siga estas diretrizes:
- Use as ações da página nos recursos que fazem sentido para apenas algumas páginas.
- Não use ações de página para recursos que fazem sentido para a maioria das páginas. Use as ações do navegador.
- Não anime seu ícone constantemente. Isso é chato.
Tipos
ImageDataType
Dados de pixel de uma imagem. Precisa ser um objeto ImageData (por exemplo, de um elemento canvas
).
Tipo
ImageData
TabDetails
Propriedades
-
tabId
número opcional
O ID da guia para consultar o estado. Se nenhuma guia for especificada, o estado não específico de tabulação será retornado.
Métodos
getPopup()
chrome.pageAction.getPopup(
details: TabDetails,
callback?: function,
)
Extrai o documento html definido como o pop-up para esta ação de página.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
Recebe o título da ação da página.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
hide()
chrome.pageAction.hide(
tabId: number,
callback?: function,
)
Oculta a ação da página. As ações de páginas ocultas ainda aparecem na barra de ferramentas do Chrome, mas estão esmaecidas.
Parâmetros
-
tabId
number
O ID da guia em que você quer modificar a ação da página.
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setIcon()
chrome.pageAction.setIcon(
details: object,
callback?: function,
)
Define o ícone da ação da página. O ícone pode ser especificado como o caminho para um arquivo de imagem ou como os dados de pixel de um elemento de tela ou como um dicionário de qualquer um desses itens. É preciso especificar a propriedade path ou imageData.
Parâmetros
-
detalhes
objeto
-
iconIndex
número opcional
Obsoleto. Esse argumento é ignorado.
-
imageData
ImageData | objeto opcional
Um objeto ImageData ou um dicionário {size -> ImageData} que representa o ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem real a ser usada será escolhida de acordo com a densidade de pixels da tela. Se o número de pixels de imagem que cabem em uma unidade de espaço de tela for igual a
scale
, a imagem com tamanhoscale
* n será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe que "details.imageData = foo" é equivalente a "details.imageData = {'16': foo}" -
caminho
string | objeto opcional
Um caminho de imagem relativo ou um dicionário {size -> relative image path} que aponta para o ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem real a ser usada será escolhida de acordo com a densidade de pixels da tela. Se o número de pixels de imagem que cabem em uma unidade de espaço de tela for igual a
scale
, a imagem com tamanhoscale
* n será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe que "details.path = foo" é equivalente a "details.path = {'16': foo}" -
tabId
number
O ID da guia em que você quer modificar a ação da página.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setPopup()
chrome.pageAction.setPopup(
details: object,
callback?: function,
)
Define o documento HTML para ser aberto como um pop-up quando o usuário clicar no ícone de ação da página.
Parâmetros
-
detalhes
objeto
-
pop-up
string
O caminho relativo para o arquivo HTML a ser exibido em um pop-up. Se definido como a string vazia (
''
), nenhum pop-up será mostrado. -
tabId
number
O ID da guia em que você quer modificar a ação da página.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setTitle()
chrome.pageAction.setTitle(
details: object,
callback?: function,
)
Define o título da ação da página. Isso é exibido em uma dica sobre a ação da página.
Parâmetros
-
detalhes
objeto
-
tabId
number
O ID da guia em que você quer modificar a ação da página.
-
title
string
A string da dica.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
show()
chrome.pageAction.show(
tabId: number,
callback?: function,
)
Mostra a ação da página. A ação da página é mostrada sempre que a guia é selecionada.
Parâmetros
-
tabId
number
O ID da guia em que você quer modificar a ação da página.
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 101 e mais recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.