chrome.tabs

Observação:a API Tabs pode ser usada pelo service worker e pelas páginas de extensão, mas não por scripts de conteúdo.

Descrição

Use a API chrome.tabs para interagir com o sistema de guias do navegador. É possível usar essa API para criar, modificar e reorganizar guias no navegador.

A API Tabs não oferece apenas recursos para manipular e gerenciar guias, mas também pode detectar o idioma da guia, fazer uma captura de tela e se comunicar com os scripts de conteúdo de uma guia.

Permissões

A maioria dos recursos não exige permissões para uso. Por exemplo: criar uma nova guia, recarregar uma guia, navegar para outro URL etc.

Os desenvolvedores precisam conhecer três permissões ao trabalhar com a API Tabs.

A permissão "tabs"

Essa permissão não dá acesso ao namespace chrome.tabs. Em vez disso, concede a uma extensão a capacidade de chamar tabs.query() em quatro propriedades sensíveis em instâncias tabs.Tab: url, pendingUrl, title e favIconUrl.

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}

Permissões do host

As permissões de host permitem que uma extensão leia e consulte as quatro propriedades tabs.Tab sensíveis de uma guia correspondente. Eles também podem interagir diretamente com as guias correspondentes usando métodos como tabs.captureVisibleTab(), tabs.executeScript(), tabs.insertCSS() e tabs.removeCSS().

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}

A permissão "activeTab"

activeTab concede uma permissão de host temporária de extensão para a guia atual em resposta a uma invocação do usuário. Ao contrário das permissões do host, activeTab não aciona nenhum alerta.

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

Casos de uso

As seções a seguir demonstram alguns casos de uso comuns.

Abrir uma página de extensão em uma nova guia

Um padrão comum para extensões é abrir uma página de integração em uma nova guia quando a extensão é instalada. O exemplo a seguir mostra como fazer isso.

background.js:

chrome.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    chrome.tabs.create({
      url: "onboarding.html"
    });
  }
});

Observação:este exemplo não exige permissões.

Receber a guia atual

Este exemplo demonstra como o service worker de uma extensão pode recuperar a guia ativa da janela atualmente em foco (ou da janela em foco mais recente, se nenhuma janela do Chrome estiver em foco). Isso pode ser considerado a guia atual do usuário.

  async function getCurrentTab() {
    let queryOptions = { active: true, lastFocusedWindow: true };
    // `tab` will either be a `tabs.Tab` instance or `undefined`.
    let [tab] = await chrome.tabs.query(queryOptions);
    return tab;
  }

  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    chrome.tabs.query(queryOptions, ([tab]) => {
      if (chrome.runtime.lastError)
      console.error(chrome.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

Desativar o som da guia especificada

Este exemplo mostra como uma extensão pode alternar o estado de silenciamento de uma determinada guia.

  async function toggleMuteState(tabId) {
    const tab = await chrome.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await chrome.tabs.update(tabId, {muted});
    console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
  }

  function toggleMuteState(tabId) {
    chrome.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await chrome.tabs.update(tabId, { muted });
      console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
    });
  }

Mover a guia atual para a primeira posição quando clicada

Este exemplo mostra como mover uma guia enquanto uma ação de arrastar pode ou não estar em andamento. Embora este exemplo use chrome.tabs.move, você pode usar o mesmo padrão de espera para outras chamadas que modificam guias enquanto uma arrastada está em andamento.

  chrome.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await chrome.tabs.move(activeInfo.tabId, {index: 0});
      console.log("Success.");
    } catch (error) {
      if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
        setTimeout(() => moveToFirstPosition(activeInfo), 50);
      } else {
        console.error(error);
      }
    }
  }

Importante:usar catch(error) em uma promessa é uma maneira de garantir que um erro que, de outra forma, preenche "chrome.runtime.lastError" não seja desmarcado.

  chrome.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    chrome.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (chrome.runtime.lastError) {
        const error = chrome.runtime.lastError;
        if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
          setTimeout(() => moveToFirstPositionMV2(activeInfo), 50);
        } else {
          console.error(error);
        }
      } else {
        console.log("Success.");
      }
    });
  }

Transmitir uma mensagem para o script de conteúdo de uma guia selecionada

Este exemplo demonstra como o service worker de uma extensão pode se comunicar com scripts de conteúdo em guias de navegador específicas usando tabs.sendMessage().

function sendMessageToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await chrome.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

Exemplos de extensões

Para mais demonstrações de extensões da API Tabs, confira:

• Manifest V2: extensões da API Tabs.
• Manifest V3: gerenciador de guias.

Tipos

MutedInfo

Chrome 46 ou mais recente

O estado de silenciamento da guia e o motivo da última mudança de estado.

Propriedades

• extensionId

  string opcional

  O ID da extensão que mudou o estado de silenciamento. Não é definido se uma extensão não foi o motivo da última mudança no estado de silenciamento.

• silenciado

  booleano

  Indica se a guia está silenciada (não pode reproduzir som). A guia pode estar silenciada mesmo que não tenha tocado ou esteja tocando som no momento. Indica se o indicador de áudio "Sem som" está aparecendo.

• reason

  MutedInfoReason opcional

  O motivo da ativação ou desativação do som da guia. Não é definido se o estado de desativação do som da guia nunca foi alterado.

MutedInfoReason

Chrome 46 ou mais recente

Um evento que causou uma mudança no estado de silenciamento.

Enumeração

"user"
Uma ação de entrada do usuário define o estado de silêncio.

"capture"
A captura de guias foi iniciada, forçando uma mudança no estado de silenciamento.

"extension"
Uma extensão, identificada pelo campo extensionId, definiu o estado de silenciamento.

Tab

Propriedades

• ativo

  booleano

  Indica se a guia está ativa na janela. Não significa necessariamente que a janela está em foco.

• Audible

  booleano opcional

  Chrome 45 e versões mais recentes

  Se a guia produziu som nos últimos segundos (mas pode não ser ouvido se estiver desativado). Equivalente a se o indicador de "áudio do alto-falante" está aparecendo.

• autoDiscardable

  booleano

  Chrome 54 ou mais recente

  Indica se a guia pode ser descartada automaticamente pelo navegador quando os recursos estão baixos.

• descartou

  booleano

  Chrome 54 ou mais recente

  Se a guia é descartada. Uma guia descartada é aquela cujo conteúdo foi removido da memória, mas ainda está visível na faixa de guias. O conteúdo é recarregado na próxima vez que é ativado.

• favIconUrl

  string opcional

  O URL do favicon da guia. Essa propriedade só estará presente se o manifesto da extensão incluir a permissão "tabs". Também pode ser uma string vazia se a guia estiver carregando.

• congelado

  booleano

  Pendente

  Se a guia está congelada. Uma guia congelada não pode executar tarefas, incluindo manipuladores de eventos ou timers. Ele fica visível na faixa de guias, e o conteúdo é carregado na memória. Ele é descongelado na ativação.

• groupId

  number

  Chrome 88 e versões mais recentes

  O ID do grupo ao qual a guia pertence.

• altura

  número opcional

  A altura da guia em pixels.

• em destaque

  booleano

  Indica se a guia está destacada.

• id

  número opcional

  O ID da guia. Os IDs de guias são exclusivos em uma sessão do navegador. Em algumas circunstâncias, uma guia pode não receber um ID. Por exemplo, ao consultar guias externas usando a API sessions, um ID de sessão pode estar presente. O ID da guia também pode ser definido como chrome.tabs.TAB_ID_NONE para apps e janelas do DevTools.

• navegação anônima

  booleano

  Indica se a guia está em uma janela anônima.

• index

  number

  O índice baseado em zero da guia na janela.

• lastAccessed

  number

  Chrome 121 e versões mais recentes

  A última vez que a guia foi acessada como o número de milissegundos desde a época.

• mutedInfo

  MutedInfo opcional

  Chrome 46 ou mais recente

  O estado de silenciamento da guia e o motivo da última mudança de estado.

• openerTabId

  número opcional

  O ID da guia que abriu essa guia, se houver. Essa propriedade só estará presente se a guia de abertura ainda existir.

• pendingUrl

  string opcional

  Chrome 79 e versões mais recentes

  O URL para o qual a guia está navegando, antes de ser confirmada. Essa propriedade só está presente se o manifesto da extensão incluir a permissão "tabs" e houver uma navegação pendente.

• pixado

  booleano

  Indica se a guia está fixada.

• selecionado

  booleano

  Descontinuado

  Use tabs.Tab.highlighted.

  Indica se a guia está selecionada.

• sessionId

  string opcional

  O ID da sessão usado para identificar de forma exclusiva uma guia obtida da API sessions.

• status

  TabStatus opcional

  O status de carregamento da guia.

• título

  string opcional

  O título da guia. Essa propriedade só estará presente se o manifesto da extensão incluir a permissão "tabs".

• url

  string opcional

  O último URL confirmado do frame principal da guia. Essa propriedade só está presente se o manifesto da extensão incluir a permissão "tabs" e pode ser uma string vazia se a guia ainda não tiver sido confirmada. Consulte também Tab.pendingUrl.

• largura

  número opcional

  A largura da guia em pixels.

• windowId

  number

  O ID da janela que contém a guia.

TabStatus

Chrome 44 e versões mais recentes

O status de carregamento da guia.

Enumeração

"unloaded"

"loading"

"complete"

WindowType

Chrome 44 e versões mais recentes

O tipo de janela.

Enumeração

"normal"

"popup"

"panel"

"app"

"devtools"

ZoomSettings

Define como as mudanças de zoom em uma guia são tratadas e em qual escopo.

Propriedades

• defaultZoomFactor

  número opcional

  Chrome 43 e versões mais recentes

  Usado para retornar o nível de zoom padrão da guia atual em chamadas para tabs.getZoomSettings.

• modo

  ZoomSettingsMode opcional

  Define como as mudanças de zoom são processadas, ou seja, qual entidade é responsável pela escala real da página. O padrão é automatic.

• escopo

  ZoomSettingsScope opcional

  Define se as mudanças de zoom persistem para a origem da página ou se têm efeito apenas nessa guia. O padrão é per-origin no modo automatic e per-tab em outros casos.

ZoomSettingsMode

Chrome 44 e versões mais recentes

Define como as mudanças de zoom são processadas, ou seja, qual entidade é responsável pela escala real da página. O padrão é automatic.

Enumeração

"automático"
As mudanças de zoom são processadas automaticamente pelo navegador.

"manual"
Substitui o processamento automático de mudanças de zoom. O evento onZoomChange ainda será enviado, e é responsabilidade da extensão detectar esse evento e dimensionar a página manualmente. Esse modo não oferece suporte ao zoom per-origin e, portanto, ignora a configuração de zoom scope e assume per-tab.

"desativado"
Desativa o zoom na guia. A guia volta ao nível de zoom padrão, e todas as tentativas de mudança de zoom são ignoradas.

ZoomSettingsScope

Chrome 44 e versões mais recentes

Define se as mudanças de zoom persistem para a origem da página ou se têm efeito apenas nessa guia. O padrão é per-origin no modo automatic e per-tab em outros casos.

Enumeração

"Por origem"
As mudanças de zoom persistem na origem da página ampliada, ou seja, todas as outras guias navegadas para essa mesma origem também são ampliadas. Além disso, as mudanças de zoom do per-origin são salvas com a origem, o que significa que, ao navegar para outras páginas na mesma origem, todas elas são ampliadas para o mesmo fator de zoom. O escopo per-origin só está disponível no modo automatic.

"Por guia"
As mudanças de zoom só têm efeito nessa guia, e as mudanças de zoom em outras guias não afetam o zoom dessa guia. Além disso, as mudanças de zoom do per-tab são redefinidas na navegação. A navegação em uma guia sempre carrega páginas com os fatores de zoom per-origin.

Propriedades

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome 92 e versões mais recentes

O número máximo de vezes que captureVisibleTab pode ser chamado por segundo. captureVisibleTab é caro e não deve ser chamado com muita frequência.

Valor

2

TAB_ID_NONE

Chrome 46 ou mais recente

Um ID que representa a ausência de uma guia do navegador.

Valor

-1

TAB_INDEX_NONE

Chrome 123+

Um índice que representa a ausência de um índice de guias em uma tab_strip.

Valor

-1

Métodos

captureVisibleTab()

Promessa

chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
  callback?: function,
)

Captura a área visível da guia ativa na janela especificada. Para chamar esse método, a extensão precisa ter a permissão <all_urls> ou activeTab. Além dos sites que as extensões podem acessar normalmente, esse método permite que elas capturem sites sensíveis que seriam restritos, incluindo páginas chrome:-scheme, outras páginas de extensões e URLs data:. Esses sites sensíveis só podem ser capturados com a permissão activeTab. Os URLs de arquivos só podem ser capturados se a extensão tiver acesso a eles.

Parâmetros

• windowId

  número opcional

  A janela de destino. O padrão é a janela atual.

• opções

  ImageDetails opcional

• callback

  função opcional

  O parâmetro callback tem este formato:

  (dataUrl: string) => void

  • dataUrl

    string

    Um URL de dados que codifica uma imagem da área visível da guia capturada. Pode ser atribuído à propriedade "src" de um elemento img HTML para exibição.

Retorna

• Promise<string>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
)

Conecta-se aos scripts de conteúdo na guia especificada. O evento runtime.onConnect é acionado em cada script de conteúdo executado na guia especificada para a extensão atual. Para mais detalhes, consulte Mensagens de script de conteúdo.

Parâmetros

• tabId

  number

• connectInfo

  objeto opcional

  • documentId

    string opcional

    Chrome 106 e versões mais recentes

    Abrir uma porta para um documento específico identificado por documentId em vez de todos os frames na guia.

  • frameId

    número opcional

    Abra uma porta para um frame específico identificado por frameId em vez de todos os frames na guia.

  • nome

    string opcional

    É transmitido para onConnect em scripts de conteúdo que estão detectando o evento de conexão.

Retorna

• runtime.Port

  Uma porta que pode ser usada para se comunicar com os scripts de conteúdo em execução na guia especificada. O evento runtime.Port da porta é acionado se a guia for fechada ou não existir.

create()

Promessa

chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

Cria uma nova guia.

Parâmetros

• createProperties

  objeto

  • ativo

    booleano opcional

    Indica se a guia precisa se tornar a guia ativa na janela. Não afeta se a janela está com o foco (consulte windows.update). O padrão é true.

  • index

    número opcional

    A posição que a guia precisa ocupar na janela. O valor fornecido é limitado entre zero e o número de guias na janela.

  • openerTabId

    número opcional

    O ID da guia que abriu essa guia. Se especificado, a guia de abertura precisa estar na mesma janela que a guia recém-criada.

  • pixado

    booleano opcional

    Se a guia precisa ser fixada. O valor padrão é false.

  • selecionado

    booleano opcional

    Descontinuado

    Use ativo.

    Define se a guia vai se tornar a guia selecionada na janela. O valor padrão é true.

  • url

    string opcional

    O URL para navegar inicialmente na guia. Os URLs totalmente qualificados precisam incluir um esquema (por exemplo, "http://www.google.com", não "www.google.com"). Os URLs relativos são relativos à página atual na extensão. O padrão é a página "Nova guia".

  • windowId

    número opcional

    Janela em que a nova guia será criada. O padrão é a janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab: Tab) => void

  • tab

    Tab

    A guia criada.

Retorna

• Promessa<Tab>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

detectLanguage()

Promessa

chrome.tabs.detectLanguage(
  tabId?: number,
  callback?: function,
)

Detecta o idioma principal do conteúdo em uma guia.

Parâmetros

• tabId

  número opcional

  A que vem configurada é a guia ativa da janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (language: string) => void

  • language

    string

    Um código de idioma ISO, como en ou fr. Para conferir uma lista completa de idiomas aceitos por esse método, consulte kLanguageInfoTable. A segunda a quarta colunas são verificadas, e o primeiro valor não nulo é retornado, exceto para o chinês simplificado, para o qual zh-CN é retornado. Para um idioma desconhecido/não definido, und é retornado.

Retorna

• Promise<string>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

discard()

Promise Chrome 54+

chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

Descarta uma guia da memória. As guias descartadas ainda aparecem na barra de guias e são recarregadas quando ativadas.

Parâmetros

• tabId

  número opcional

  O ID da guia a ser descartada. Se especificado, a guia será descartada, a menos que esteja ativa ou já descartada. Se omitido, o navegador descarta a guia menos importante. Isso pode falhar se não houver guias descartáveis.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab?: Tab) => void

  • tab

    Guia opcional

    A guia descartada, se ela foi descartada; indefinido, caso contrário.

Retorna

• Promise<Tab | undefined>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

duplicate()

Promessa

chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

Duplica uma guia.

Parâmetros

• tabId

  number

  O ID da guia a ser duplicada.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab?: Tab) => void

  • tab

    Guia opcional

    Detalhes sobre a guia duplicada. O objeto tabs.Tab não contém url, pendingUrl, title e favIconUrl se a permissão "tabs" não foi solicitada.

Retorna

• Promise<Tab | undefined>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

get()

Promessa

chrome.tabs.get(
  tabId: number,
  callback?: function,
)

Recupera detalhes sobre a guia especificada.

Parâmetros

• tabId

  number

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab: Tab) => void

  • tab

    Tab

Retorna

• Promessa<Tab>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getCurrent()

Promessa

chrome.tabs.getCurrent(
  callback?: function,
)

Recebe a guia em que a chamada de script está sendo feita. Retorna undefined se for chamado de um contexto que não seja de guia, como uma página em segundo plano ou uma visualização pop-up.

Parâmetros

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab?: Tab) => void

  • tab

    Guia opcional

Retorna

• Promise<Tab | undefined>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getZoom()

Promessa

chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

Recebe o fator de zoom atual de uma guia especificada.

Parâmetros

• tabId

  número opcional

  O ID da guia de onde o fator de zoom atual será extraído. O padrão é a guia ativa da janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (zoomFactor: number) => void

  • zoomFactor

    number

    O fator de zoom atual da guia.

Retorna

• Promise<number>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getZoomSettings()

Promessa

chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

Recebe as configurações de zoom atuais de uma guia especificada.

Parâmetros

• tabId

  número opcional

  O ID da guia de onde as configurações atuais do Zoom são extraídas. O padrão é a guia ativa da janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (zoomSettings: ZoomSettings) => void

  • zoomSettings

    ZoomSettings

    As configurações de zoom atuais da guia.

Retorna

• Promise<ZoomSettings>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

goBack()

Promessa Chrome 72+

chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

Volte para a página anterior, se houver uma disponível.

Parâmetros

• tabId

  número opcional

  O ID da guia para voltar. O padrão é a guia selecionada da janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

goForward()

Promessa Chrome 72+

chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

Acesse a próxima página, se disponível.

Parâmetros

• tabId

  número opcional

  O ID da guia para navegar para frente. O padrão é a guia selecionada da janela atual.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

group()

Promessa Chrome 88+

chrome.tabs.group(
  options: object,
  callback?: function,
)

Adiciona uma ou mais guias a um grupo especificado ou, se nenhum grupo for especificado, adiciona as guias a um grupo recém-criado.

Parâmetros

• opções

  objeto

  • createProperties

    objeto opcional

    Configurações para criar um grupo. Não pode ser usado se groupId já estiver especificado.

    • windowId

      número opcional

      A janela do novo grupo. O padrão é a janela atual.

  • groupId

    número opcional

    O ID do grupo em que as guias serão adicionadas. Se não for especificado, um novo grupo será criado.

  • tabIds

    número | [número, ...número[]]

    O ID ou a lista de IDs de guias a serem adicionados ao grupo especificado.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (groupId: number) => void

  • groupId

    number

    O ID do grupo em que as guias foram adicionadas.

Retorna

• Promise<number>

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

highlight()

Promessa

chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

Destaca as guias especificadas e foca na primeira do grupo. Não vai fazer nada se a guia especificada estiver ativa.

Parâmetros

• highlightInfo

  objeto

  • guias

    number | number[]

    Um ou mais índices de guias para destacar.

  • windowId

    número opcional

    A janela que contém as guias.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (window: Window) => void

  • janela

    Janela

    Contém detalhes sobre a janela com as guias destacadas.

Retorna

• Promessa<windows.Window>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

move()

Promessa

chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
  callback?: function,
)

Move uma ou mais guias para uma nova posição na janela ou para uma nova janela. As guias só podem ser movidas para e de janelas normais (window.type === "normal").

Parâmetros

• tabIds

  number | number[]

  O ID ou a lista de IDs das guias a serem movidas.

• moveProperties

  objeto

  • index

    number

    A posição para mover a janela. Use -1 para colocar a guia no final da janela.

  • windowId

    número opcional

    O padrão é a janela em que a guia está no momento.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tabs: Tab | Tab[]) => void

  • guias

    Guia | Guia[]

    Detalhes sobre as guias movidas.

Retorna

• Promise<Tab | Tab[]>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

query()

Promessa

chrome.tabs.query(
  queryInfo: object,
  callback?: function,
)

Recebe todas as guias que têm as propriedades especificadas ou todas as guias se nenhuma propriedade for especificada.

Parâmetros

• queryInfo

  objeto

  • ativo

    booleano opcional

    Indica se as guias estão ativas nas janelas.

  • Audible

    booleano opcional

    Chrome 45 e versões mais recentes

    Se as guias são audíveis.

  • autoDiscardable

    booleano opcional

    Chrome 54 ou mais recente

    Se as guias podem ser descartadas automaticamente pelo navegador quando os recursos estão baixos.

  • currentWindow

    booleano opcional

    Se as guias estão na janela atual.

  • descartou

    booleano opcional

    Chrome 54 ou mais recente

    Se as guias são descartadas. Uma guia descartada é aquela cujo conteúdo foi removido da memória, mas ainda está visível na faixa de guias. O conteúdo é recarregado na próxima vez que é ativado.

  • congelado

    booleano opcional

    Pendente

    Se as guias estão congeladas. Uma guia congelada não pode executar tarefas, incluindo manipuladores de eventos ou timers. Ele fica visível na faixa de guias, e o conteúdo é carregado na memória. Ele é descongelado na ativação.

  • groupId

    número opcional

    Chrome 88 e versões mais recentes

    O ID do grupo em que as guias estão ou tabGroups.TAB_GROUP_ID_NONE para guias não agrupadas.

  • em destaque

    booleano opcional

    Se as guias estão destacadas.

  • index

    número opcional

    A posição das guias nas janelas.

  • lastFocusedWindow

    booleano opcional

    Se as guias estão na última janela em foco.

  • silenciado

    booleano opcional

    Chrome 45 e versões mais recentes

    Se as guias estão silenciadas.

  • pixado

    booleano opcional

    Se as guias estão fixadas.

  • status

    TabStatus opcional

    O status de carregamento da guia.

  • título

    string opcional

    Correlacionar títulos de páginas a um padrão. Essa propriedade é ignorada se a extensão não tiver a permissão "tabs".

  • url

    string | string[] opcional

    Associe as guias a um ou mais padrões de URL. Os identificadores de fragmento não são correspondentes. Essa propriedade é ignorada se a extensão não tiver a permissão "tabs".

  • windowId

    número opcional

    O ID da janela pai ou windows.WINDOW_ID_CURRENT para a janela atual.

  • windowType

    WindowType opcional

    O tipo de janela em que as guias estão.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (result: Tab[]) => void

  • resultado

    Guia[]

Retorna

• Promise<Tab[]>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

reload()

Promessa

chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

Atualize uma guia.

Parâmetros

• tabId

  número opcional

  O ID da guia a ser recarregada. O padrão é a guia selecionada da janela atual.

• reloadProperties

  objeto opcional

  • bypassCache

    booleano opcional

    Se o armazenamento em cache local será ignorado. O valor padrão é false.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

remove()

Promessa

chrome.tabs.remove(
  tabIds: number | number[],
  callback?: function,
)

Fecha uma ou mais guias.

Parâmetros

• tabIds

  number | number[]

  O ID ou a lista de IDs das guias a serem fechadas.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

sendMessage()

Promessa

chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
  callback?: function,
)

Envia uma única mensagem para os scripts de conteúdo na guia especificada, com um callback opcional para ser executado quando uma resposta for enviada de volta. O evento runtime.onMessage é acionado em cada script de conteúdo executado na guia especificada para a extensão atual.

Parâmetros

• tabId

  number

• mensagem

  qualquer um

  A mensagem a ser enviada. Essa mensagem precisa ser um objeto JSON.

• opções

  objeto opcional

  • documentId

    string opcional

    Chrome 106 e versões mais recentes

    Enviar uma mensagem para um documento específico identificado por documentId em vez de todos os frames na guia.

  • frameId

    número opcional

    Enviar uma mensagem para um frame específico identificado por frameId em vez de todos os frames na guia.

• callback

  função opcional

  Chrome 99 e versões mais recentes

  O parâmetro callback tem este formato:

  (response: any) => void

  • resposta

    qualquer um

    O objeto de resposta JSON enviado pelo gerenciador da mensagem. Se ocorrer um erro ao se conectar à guia especificada, o callback será chamado sem argumentos e runtime.lastError será definido como a mensagem de erro.

Retorna

• Promise<any>

  Chrome 99 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

setZoom()

Promessa

chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
  callback?: function,
)

Aplica zoom em uma guia especificada.

Parâmetros

• tabId

  número opcional

  O ID da guia para aplicar zoom. O padrão é a guia ativa da janela atual.

• zoomFactor

  number

  O novo fator de zoom. Um valor de 0 define a guia como o fator de zoom padrão atual. Valores maiores que 0 especificam um fator de zoom (talvez não padrão) para a guia.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

setZoomSettings()

Promessa

chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

Define as configurações de zoom de uma guia especificada, que definem como as mudanças de zoom são processadas. Essas configurações são redefinidas para os padrões ao navegar pela guia.

Parâmetros

• tabId

  número opcional

  O ID da guia para mudar as configurações de zoom. O padrão é a guia ativa da janela atual.

• zoomSettings

  ZoomSettings

  Define como as mudanças de zoom são processadas e em qual escopo.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

ungroup()

Promessa Chrome 88+

chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
  callback?: function,
)

Remove uma ou mais guias dos respectivos grupos. Se algum grupo ficar vazio, ele será excluído.

Parâmetros

• tabIds

  número | [número, ...número[]]

  O ID ou a lista de IDs das guias a serem removidas dos respectivos grupos.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

update()

Promessa

chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

Modifica as propriedades de uma guia. As propriedades que não são especificadas em updateProperties não são modificadas.

Parâmetros

• tabId

  número opcional

  Assume a guia selecionada da janela atual.

• updateProperties

  objeto

  • ativo

    booleano opcional

    Indica se a guia precisa estar ativa. Não afeta se a janela está em foco (consulte windows.update).

  • autoDiscardable

    booleano opcional

    Chrome 54 e versões mais recentes

    Se a guia precisa ser descartada automaticamente pelo navegador quando os recursos estão baixos.

  • em destaque

    booleano opcional

    Adiciona ou remove a guia da seleção atual.

  • silenciado

    booleano opcional

    Chrome 45 e versões mais recentes

    Indica se a guia precisa ser silenciada.

  • openerTabId

    número opcional

    O ID da guia que abriu essa guia. Se especificado, a guia de abertura precisa estar na mesma janela que esta.

  • pixado

    booleano opcional

    Se a guia precisa ser fixada.

  • selecionado

    booleano opcional

    Descontinuado

    Use destacado.

    Se a guia precisa ser selecionada.

  • url

    string opcional

    Um URL para navegar até a guia. Os URLs JavaScript não são compatíveis. Use scripting.executeScript.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (tab?: Tab) => void

  • tab

    Guia opcional

    Detalhes sobre a guia atualizada. O objeto tabs.Tab não contém url, pendingUrl, title e favIconUrl se a permissão "tabs" não foi solicitada.

Retorna

• Promise<Tab | undefined>

  Chrome 88 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

Eventos

onActivated

chrome.tabs.onActivated.addListener(
  callback: function,
)

É acionado quando a guia ativa em uma janela muda. O URL da guia pode não estar definido no momento em que o evento é acionado, mas você pode detectar eventos onUpdated para receber uma notificação quando um URL for definido.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (activeInfo: object) => void

  • activeInfo

    objeto

    • tabId

      number

      O ID da guia que se tornou ativa.

    • windowId

      number

      O ID da janela em que a guia ativa foi alterada.

onAttached

chrome.tabs.onAttached.addListener(
  callback: function,
)

É disparado quando uma guia é anexada a uma janela, por exemplo, porque foi movida entre janelas.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tabId: number, attachInfo: object) => void

  • tabId

    number

  • attachInfo

    objeto

    • newPosition

      number

    • newWindowId

      number

onCreated

chrome.tabs.onCreated.addListener(
  callback: function,
)

É acionado quando uma guia é criada. O URL da guia e a associação ao grupo de guias podem não estar definidos no momento em que o evento é acionado, mas você pode detectar eventos onUpdated para receber uma notificação quando um URL for definido ou a guia for adicionada a um grupo.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tab: Tab) => void

  • tab

    Tab

onDetached

chrome.tabs.onDetached.addListener(
  callback: function,
)

É acionado quando uma guia é separada de uma janela, por exemplo, porque foi movida entre janelas.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tabId: number, detachInfo: object) => void

  • tabId

    number

  • detachInfo

    objeto

    • oldPosition

      number

    • oldWindowId

      number

onHighlighted

chrome.tabs.onHighlighted.addListener(
  callback: function,
)

É acionado quando as guias destacadas ou selecionadas em uma janela mudam.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (highlightInfo: object) => void

  • highlightInfo

    objeto

    • tabIds

      number[]

      Todas as guias destacadas na janela.

    • windowId

      number

      A janela com as guias alteradas.

onMoved

chrome.tabs.onMoved.addListener(
  callback: function,
)

Acionada quando uma guia é movida em uma janela. Apenas um evento de movimento é acionado, representando a guia que o usuário moveu diretamente. Os eventos de movimentação não são acionados para as outras guias que precisam ser movidas em resposta à guia movida manualmente. Esse evento não é acionado quando uma guia é movida entre janelas. Para saber mais, consulte tabs.onDetached.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tabId: number, moveInfo: object) => void

  • tabId

    number

  • moveInfo

    objeto

    • fromIndex

      number

    • toIndex

      number

    • windowId

      number

onRemoved

chrome.tabs.onRemoved.addListener(
  callback: function,
)

Disparado quando uma guia é fechada.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tabId: number, removeInfo: object) => void

  • tabId

    number

  • removeInfo

    objeto

    • isWindowClosing

      booleano

      Verdadeiro quando a guia foi fechada porque a janela mãe foi fechada.

    • windowId

      number

      A janela com a guia fechada.

onReplaced

chrome.tabs.onReplaced.addListener(
  callback: function,
)

É acionado quando uma guia é substituída por outra devido à pré-renderização ou ao modo instantâneo.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (addedTabId: number, removedTabId: number) => void

  • addedTabId

    number

  • removedTabId

    number

onUpdated

chrome.tabs.onUpdated.addListener(
  callback: function,
)

Acionada quando uma guia é atualizada.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (tabId: number, changeInfo: object, tab: Tab) => void

  • tabId

    number

  • changeInfo

    objeto

    • Audible

      booleano opcional

      Chrome 45 e versões mais recentes

      O novo estado sonoro da guia.

    • autoDiscardable

      booleano opcional

      Chrome 54 e versões mais recentes

      O novo estado de descarte automático da guia.

    • descartou

      booleano opcional

      Chrome 54 ou mais recente

      O novo estado de descarte da guia.

    • favIconUrl

      string opcional

      O novo URL do ícone da guia.

    • congelado

      booleano opcional

      Pendente

      O novo estado congelado da guia.

    • groupId

      número opcional

      Chrome 88 e versões mais recentes

      O novo grupo da guia.

    • mutedInfo

      MutedInfo opcional

      Chrome 46 ou mais recente

      O novo estado de silenciamento da guia e o motivo da mudança.

    • pixado

      booleano opcional

      O novo estado fixado da guia.

    • status

      TabStatus opcional

      O status de carregamento da guia.

    • título

      string opcional

      Chrome 48 e versões mais recentes

      O novo título da guia.

    • url

      string opcional

      O URL da guia, se ele tiver mudado.

  • tab

    Tab

onZoomChange

chrome.tabs.onZoomChange.addListener(
  callback: function,
)

Disparado quando uma guia é ampliada.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (ZoomChangeInfo: object) => void

  • ZoomChangeInfo

    objeto

    • newZoomFactor

      number

    • oldZoomFactor

      number

    • tabId

      number

    • zoomSettings

      ZoomSettings