Esta página foi traduzida pela API Cloud Translation.

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.

Visão geral

A API Tabs não oferece apenas recursos para manipular e gerenciar guias, mas também pode detectar a língua 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.
Permissões do host: permissões do 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().
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 alertas.

Manifesto

Confira a seguir exemplos de como declarar cada permissão no manifest:

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

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

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

Casos de uso

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

Como 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 não 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 silenciamento.

"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 guia 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

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 de 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

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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
  
  Abra 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 deve 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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

Assume 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 com suporte a 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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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. Caso contrário, será indefinido.

Retorna

Promise<Tab | undefined>

Chrome 88 e versões mais recentes

As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

executeScript()

Promessa &leq; MV2 Suspensa desde o Chrome 91

chrome.tabs.executeScript(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

Substituído por scripting.executeScript no Manifest V3.

Injeta código JavaScript em uma página. Para mais detalhes, consulte a seção Injeção programática do documento de scripts de conteúdo.

Parâmetros

tabId

número opcional

O ID da guia em que o script será executado. O padrão é a guia ativa da janela atual.
detalhes

InjectDetails

Detalhes do script a ser executado. O código ou a propriedade do arquivo precisam ser definidos, mas não ao mesmo tempo.
callback

função opcional

O parâmetro callback tem este formato:
```
(result?: any[]) => void
```
- resultado
  
  any[] opcional
  
  O resultado do script em cada frame injetado.

Retorna

Promise<any[] | undefined>

Chrome 88 e versões mais recentes

As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAllInWindow()

Promessa &leq; MV2 Descontinuado

chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
)

Use tabs.query {windowId: windowId}.

Consegue detalhes sobre todas as guias na janela especificada.

Parâmetros

windowId

número opcional

O padrão é a janela atual.
callback

função opcional

O parâmetro callback tem este formato:
```
(tabs: Tab[]) => void
```
- guias
  
  Tab[]

Retorna

Promise<Tab[]>

Chrome 88 e versões mais recentes

As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getSelected()

Promessa &leq; MV2 Descontinuado

chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

Use tabs.query {active: true}.

Recebe a guia selecionada na janela especificada.

Parâmetros

windowId

número opcional

O padrão é a janela atual.
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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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
  
  number | [number, ...number[]]
  
  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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

insertCSS()

Promessa &leq; MV2 Suspensa desde o Chrome 91

chrome.tabs.insertCSS(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

Substituído por scripting.insertCSS no Manifest V3.

Injeta CSS em uma página. Os estilos inseridos com esse método podem ser removidos com scripting.removeCSS. Para mais detalhes, consulte a seção Injeção programática do documento de scripts de conteúdo.

Parâmetros

tabId

número opcional

O ID da guia em que o CSS será inserido. O padrão é a guia ativa da janela atual.
detalhes

InjectDetails

Detalhes do texto CSS a ser inserido. O código ou a propriedade do arquivo precisam ser definidos, mas não ao mesmo tempo.
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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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
  
  Tab[]

Retorna

Promise<Tab[]>

Chrome 88 e versões mais recentes

As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

removeCSS()

Promessa Chrome 87+ &leq; MV2 Suspensa desde o Chrome 91

chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

Substituído por scripting.removeCSS no Manifest V3.

Remove do CSS de uma página que foi injetado anteriormente por uma chamada para scripting.insertCSS.

Parâmetros

tabId

número opcional

O ID da guia de onde o CSS será removido. O padrão é a guia ativa da janela atual.
detalhes

DeleteInjectionDetails

Detalhes do texto CSS a ser removido. O código ou a propriedade do arquivo precisam ser definidos, mas não ao mesmo tempo.
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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

sendRequest()

Promessa &leq; MV2 Descontinuado

chrome.tabs.sendRequest(
  tabId: number,
  request: any,
  callback?: function,
)

Use runtime.sendMessage.

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

Parâmetros

tabId

number
solicitação

qualquer um
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 solicitação. 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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

number | [number, ...number[]]

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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 ou mais recente
  
  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
  
  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 de 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 apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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.

onActiveChanged

&leq; MV2 Descontinuado

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

Use tabs.onActivated.

É acionado quando a guia selecionada 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 tabs.onUpdated para receber uma notificação quando um URL for definido.

Parâmetros

callback

função

O parâmetro callback tem este formato:
```
(tabId: number, selectInfo: object) => void
```
- tabId
  
  number
- selectInfo
  
  objeto
  - windowId
    
    number
    
    O ID da janela em que a guia selecionada mudou.

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

onHighlightChanged

&leq; MV2 Descontinuado

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

Use tabs.onHighlighted.

Acionada quando as guias destacadas ou selecionadas em uma janela mudam.

Parâmetros

callback

função

O parâmetro callback tem este formato:
```
(selectInfo: object) => void
```
- selectInfo
  
  objeto
  - tabIds
    
    number[]
    
    Todas as guias destacadas na janela.
  - windowId
    
    number
    
    A janela com as guias alteradas.

onHighlighted

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

Acionada 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 que tem 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

onSelectionChanged

&leq; MV2 Descontinuado

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

Use tabs.onActivated.

É acionado quando a guia selecionada em uma janela muda.

Parâmetros

callback

função

O parâmetro callback tem este formato:
```
(tabId: number, selectInfo: object) => void
```
- tabId
  
  number
- selectInfo
  
  objeto
  - windowId
    
    number
    
    O ID da janela em que a guia selecionada mudou.

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 ou mais recente
    
    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