chrome.pageAction

Descrição

Use a API chrome.pageAction para colocar ícones na barra de ferramentas principal do Google Chrome, à direita da barra de endereço. As ações na página representam ações que podem ser realizadas na página atual, mas que não são aplicáveis a todas elas. As ações da página aparecem esmaecidas quando 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 do RSS na captura de tela a seguir representa uma ação da página que permite assinar o RSS feed 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 inscrever-se no feed da página atual:

Considere usar uma ação do navegador para que os usuários sempre possam interagir com seus .

Manifesto

Registre a ação de página no manifesto da extensão desta 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, você está são incentivados a fornecer vários tamanhos para os ícones. O Chrome vai selecionar e escalonar a imagem mais próxima para preencher o espaço de 16 mergulhos. Isso também garante que, se o tamanho de exibição do ícone for alterado, você não precisamos fazer mais um trabalho para fornecer ícones diferentes! No entanto, se a diferença de tamanho for muito extrema, esse dimensionamento pode fazer com que o ícone perca detalhes ou pareça confuso.

A sintaxe antiga para registro do í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. não podem ter selos, No entanto. Além disso, as ações da página podem estar esmaecidas. Encontre informações sobre ícones, dicas de ferramentas e pop-ups lendo sobre a interface de ação do navegador.

Você faz uma ação de página aparecer e ficar esmaecida usando pageAction.show e pageAction.hide, respectivamente. Por padrão, uma ação de página aparece esmaecida. Quando você para mostrá-lo, especifique a guia em que o ícone deve aparecer. O ícone permanece visível até que a guia estiver fechado ou começar a exibir um URL diferente (porque o usuário clica em um link, por exemplo).

Dicas

Para obter o melhor impacto visual, siga estas diretrizes:

  • Use as ações para recursos que fazem sentido apenas para algumas páginas.
  • Não use ações para recursos que fazem sentido para a maioria das páginas. Usar ações do navegador como alternativa.
  • Não anime o ícone constantemente. Isso é apenas irritante.

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 superior

Propriedades

  • tabId

    número opcional

    O ID da guia em que o estado da consulta será consultado. Se nenhuma guia for especificada, o estado não específico da guia 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 da página.

Parâmetros

  • detalhes

    TabDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: string) => void

    • resultado

      string

Retorna

  • Promessa<string>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getTitle()

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

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

Parâmetros

  • detalhes

    TabDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: string) => void

    • resultado

      string

Retorna

  • Promessa<string>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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 ficam esmaecidas.

Parâmetros

  • tabId

    number

    O ID da guia em que você quer modificar a ação da página.

  • callback

    função opcional

    Chrome 67 ou superior

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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, como os dados de pixel de um elemento de tela ou como um dicionário de qualquer um deles. É 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 dependendo da densidade de pixels da tela. Se o número de pixels da imagem que cabem em uma unidade de espaço na 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 -> caminho da imagem relativa} apontando para o ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem real a ser usada será escolhida dependendo da densidade de pixels da tela. Se o número de pixels da imagem que cabem em uma unidade de espaço na 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 opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setPopup()

Promessa 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
)

Define o documento HTML que 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 que será mostrado em um pop-up. Se definida como a string vazia (''), nenhum pop-up será exibido.

    • tabId

      number

      O ID da guia em que você quer modificar a ação da página.

  • callback

    função opcional

    Chrome 67 ou superior

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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.

    • título

      string

      A string da dica.

  • callback

    função opcional

    Chrome 67 ou superior

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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 de página aparece 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 opcional

    Chrome 67 ou superior

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto 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