chrome.tabs

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"
    });
  }
});

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);
      }
    }
  }


  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:

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

  • 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

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

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

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