chrome.pageAction

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

≤ MV2

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

Chrome 88 ou mais recente

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

Promessa 
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

    TabDetails

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (result: string)=>void

    • resultado

      string

Retorna

  • Promessa<string>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getTitle()

Promessa 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Recebe o título da ação da página.

Parâmetros

  • detalhes

    TabDetails

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (result: string)=>void

    • resultado

      string

Retorna

  • Promessa<string>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

hide()

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

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setIcon()

Promessa 
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|object 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 tamanho scale * 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 tamanho scale * 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 recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setPopup()

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

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setTitle()

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

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

show()

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

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 101 e mais recentes

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onClicked

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

Disparado quando um ícone de ação da página é clicado. Este evento não será disparado se a ação da página tiver um pop-up.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (tab: tabs.Tab)=>void