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. Você pode usar essa API para criar, modificar e reorganizar guias no navegador.

A API Tabs não apenas oferece recursos para manipular e gerenciar guias, mas também pode detectar o idioma da guia, fazer uma captura de tela e comunicar com 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.

Há três permissões que os desenvolvedores precisam conhecer ao trabalhar com a API Tabs.

A permissão "tabs"

Essa permissão não dá acesso ao namespace chrome.tabs. Em vez disso, ela 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 sensíveis de tabs.Tab de uma guia correspondente. Eles também podem interagir diretamente com as guias correspondentes usando métodos como tabs.captureVisibleTab(), scripting.executeScript(), scripting.insertCSS() e scripting.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 de host, activeTab não aciona nenhum aviso.

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

Casos de uso

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

Abrir a página de uma 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 focada no momento (ou da janela focada mais recentemente, se nenhuma janela do Chrome estiver focada). Isso geralmente pode ser considerado como 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 mudo 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 ação de arrastar 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 ao script de conteúdo de uma guia selecionada

Este exemplo demonstra como um service worker de extensão pode se comunicar com scripts de conteúdo em guias específicas do navegador 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 uma das seguintes opções:

Tipos

MutedInfo

Chrome 46 ou mais recente

O estado de mudo 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 mudo. Não definido se uma extensão não foi o motivo da última mudança no estado silenciado.
silenciado

booleano

Indica se a guia está silenciada (impedida de reproduzir som). A guia pode estar silenciada mesmo que não tenha reproduzido ou não esteja reproduzindo som no momento. Equivalente a se o indicador de áudio "silenciado" está sendo mostrado.
reason

MutedInfoReason opcional

O motivo de a guia ter sido silenciada ou não. Não definido se o estado de mudo da guia nunca foi alterado.

MutedInfoReason

Chrome 46 ou mais recente

Um evento que causou uma mudança de estado silenciosa.

Enumeração

"user"
Uma ação de entrada do usuário definiu o estado silenciado.

"capture"
A captura de guia foi iniciada, forçando uma mudança de estado silenciado.

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

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

Se a guia emitiu som nos últimos segundos (mas talvez não seja possível ouvir se ela também estiver silenciada). Equivalente a se o indicador "áudio do alto-falante" está sendo mostrado.
autoDiscardable

booleano

Chrome 54 ou mais recente

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 foi descartada. Uma guia descartada é aquela cujo conteúdo foi descarregado da memória, mas ainda está visível na barra de guias. O conteúdo é recarregado na próxima vez que ele é ativado.
favIconUrl

string opcional

O URL do favicon da guia. Essa propriedade só está presente se a extensão tiver a permissão "tabs" ou permissões de host para a página. Também pode ser uma string vazia se a guia estiver carregando.
congelado

booleano

Chrome 132 ou mais recente

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

número

Chrome 88 ou mais recente

O ID do grupo a que a guia pertence.
altura

número optional

A altura da guia em pixels.
em destaque

booleano

Indica se a guia está destacada.
ID

número optional

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 de ferramentas de desenvolvimento.
navegação anônima

booleano

Se a guia está em uma janela anônima.
index

número

O índice baseado em zero da guia na janela.
lastAccessed

número

Chrome 121+

A última vez que a guia ficou ativa na janela como o número de milissegundos desde a época.
mutedInfo

MutedInfo opcional

Chrome 46 ou mais recente

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

número optional

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

string opcional

Chrome 79 ou mais recente

O URL para que a guia está navegando antes de ser confirmada. Essa propriedade só está presente se a extensão tiver a permissão "tabs" ou permissões de host para a página e houver uma navegação pendente.
pixado

booleano

Se a guia está fixada.
selecionado

booleano

Descontinuado

Use tabs.Tab.highlighted.
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ó está presente se a extensão tiver a permissão "tabs" ou permissões de host para a página.
url

string opcional

O último URL confirmado do frame principal da guia. Essa propriedade só está presente se a extensão tiver a permissão "tabs" ou permissões de host para a página. Pode ser uma string vazia se a guia ainda não tiver sido confirmada. Consulte também Tab.pendingUrl.
largura

número optional

A largura da guia em pixels.
windowId

número

O ID da janela que contém a guia.

TabStatus

Chrome 44 ou mais recente

O status de carregamento da guia.

Enumeração

"unloaded"

"loading"

"concluído"

WindowType

Chrome 44 ou mais recente

O tipo de janela.

Enumeração

"normal"

"popup"

"panel"

"app"

"devtools"

ZoomSettings

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

Propriedades

defaultZoomFactor

número optional

Chrome 43 ou mais recente

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 pelo dimensionamento 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 só têm efeito nesta guia. O padrão é per-origin no modo automatic e per-tab em outros casos.

ZoomSettingsMode

Chrome 44 ou mais recente

Define como as mudanças de zoom são processadas, ou seja, qual entidade é responsável pelo dimensionamento 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 é compatível com o zoom per-origin e, portanto, ignora a configuração de zoom scope e assume per-tab.

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

ZoomSettingsScope

Chrome 44 ou mais recente

Define se as mudanças de zoom persistem para a origem da página ou só têm efeito nesta 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 que navegam até essa mesma origem também são ampliadas. Além disso, as mudanças de zoom per-origin são salvas com a origem. Isso significa que, ao navegar para outras páginas na mesma origem, todas elas são ampliadas com o mesmo fator de zoom. O escopo per-origin só está disponível no modo automatic.

"por guia"
As mudanças de zoom só entram em vigor nesta guia, e as mudanças de zoom em outras guias não afetam o zoom desta guia. Além disso, as per-tab mudanças de zoom são redefinidas na navegação. Navegar em uma guia sempre carrega páginas com os fatores de zoom per-origin.

Propriedades

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome 92 ou mais recente

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 guia em uma tab_strip.

Valor

-1

Métodos

captureVisibleTab()

chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
): Promise<string>

Captura a área visível da guia ativa no momento 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, de outra forma, seriam restritos, incluindo páginas do esquema chrome:, páginas de outras 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 recebido acesso a eles.

Parâmetros

windowId

número optional

A janela de destino. O padrão é a janela atual.
opções

ImageDetails opcional

Retorna

Promise<string>

Chrome 88 ou mais recente

connect()

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

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

Parâmetros

tabId

número
connectInfo

objeto opcional
- documentId
  
  string opcional
  
  Chrome 106 ou mais recente
  
  Abra uma porta para um documento específico identificado por documentId em vez de todos os frames na guia.
- frameId
  
  número optional
  
  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()

chrome.tabs.create(
  createProperties: object,
): Promise<Tab>

Cria uma nova guia.

Parâmetros

createProperties

objeto
- ativo
  
  booleano opcional
  
  Se a guia deve se tornar a guia ativa na janela. Não afeta se a janela está em foco (consulte windows.update). O padrão é true.
- index
  
  número optional
  
  A posição que a guia deve ocupar na janela. O valor fornecido é fixado entre zero e o número de guias na janela.
- openerTabId
  
  número optional
  
  O ID da guia que abriu esta guia. Se especificada, a guia de abertura precisa estar na mesma janela que a guia recém-criada.
- pixado
  
  booleano opcional
  
  Se a guia deve ser fixada. O valor padrão é false.
- selecionado
  
  booleano opcional
  
  Descontinuado
  
  Use active.
  Se a guia deve se tornar a guia selecionada na janela. O valor padrão é true.
- url
  
  string opcional
  
  O URL para navegar inicialmente até a guia. Os URLs totalmente qualificados precisam incluir um esquema (ou seja, "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 optional
  
  A janela em que a nova guia será criada. O padrão é a janela atual.

Retorna

Promise<Tab>

Chrome 88 ou mais recente

detectLanguage()

chrome.tabs.detectLanguage(
  tabId?: number,
): Promise<string>

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

Parâmetros

tabId

número optional

O padrão é a guia ativa da janela atual.

Retorna

Promise<string>

Chrome 88 ou mais recente

discard()

Chrome 54 ou mais recente

chrome.tabs.discard(
  tabId?: number,
): Promise<Tab | undefined>

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

Parâmetros

tabId

número optional

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

Retorna

Promise<Tab | undefined>

Chrome 88 ou mais recente

duplicate()

chrome.tabs.duplicate(
  tabId: number,
): Promise<Tab | undefined>

Duplica uma guia.

Parâmetros

tabId

número

O ID da guia a ser duplicada.

Retorna

Promise<Tab | undefined>

Chrome 88 ou mais recente

get()

chrome.tabs.get(
  tabId: number,
): Promise<Tab>

Recupera detalhes sobre a guia especificada.

Parâmetros

tabId

número

Retorna

Promise<Tab>

Chrome 88 ou mais recente

getCurrent()

chrome.tabs.getCurrent(): Promise<Tab | undefined>

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

Retorna

Promise<Tab | undefined>

Chrome 88 ou mais recente

getZoom()

chrome.tabs.getZoom(
  tabId?: number,
): Promise<number>

Recebe o fator de zoom atual de uma guia especificada.

Parâmetros

tabId

número optional

O ID da guia para receber o fator de zoom atual. O padrão é a guia ativa da janela atual.

Retorna

Promise<number>

Chrome 88 ou mais recente

getZoomSettings()

chrome.tabs.getZoomSettings(
  tabId?: number,
): Promise<ZoomSettings>

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

Parâmetros

tabId

número optional

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

Retorna

Promise<ZoomSettings>

Chrome 88 ou mais recente

goBack()

Chrome 72 ou mais recente

chrome.tabs.goBack(
  tabId?: number,
): Promise<void>

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

Parâmetros

tabId

número optional

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

Retorna

Promessa<void>

Chrome 88 ou mais recente

goForward()

Chrome 72 ou mais recente

chrome.tabs.goForward(
  tabId?: number,
): Promise<void>

Avançar para a próxima página, se houver uma.

Parâmetros

tabId

número optional

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

Retorna

Promessa<void>

Chrome 88 ou mais recente

group()

Chrome 88 ou mais recente

chrome.tabs.group(
  options: object,
): Promise<number>

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 optional
    
    A janela do novo grupo. O padrão é a janela atual.
- groupId
  
  número optional
  
  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 da guia ou a lista de IDs de guias a serem adicionadas ao grupo especificado.

Retorna

Promise<number>

highlight()

chrome.tabs.highlight(
  highlightInfo: object,
): Promise<windows.Window>

Destaca as guias fornecidas e se concentra 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 optional
  
  A janela que contém as guias.

Retorna

Promise<windows.Window>

Chrome 88 ou mais recente

move()

chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
): Promise<Tab | Tab[]>

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 da guia ou a lista de IDs das guias a serem movidas.
moveProperties

objeto
- index
  
  número
  
  A posição para onde a janela será movida. Use -1 para colocar a guia no final da janela.
- windowId
  
  número optional
  
  O padrão é a janela em que a guia está aberta.

Retorna

Promise<Tab | Tab[]>

Chrome 88 ou mais recente

query()

chrome.tabs.query(
  queryInfo: object,
): Promise<Tab[]>

Recebe todas as guias com as propriedades especificadas ou todas as guias se nenhuma propriedade for especificada.

Parâmetros

queryInfo

objeto
- ativo
  
  booleano opcional
  
  Se as guias estão ativas nas janelas.
- Audible
  
  booleano opcional
  
  Chrome 45 ou mais recente
  
  Se as guias estã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 descarregado da memória, mas ainda está visível na barra de guias. O conteúdo é recarregado na próxima vez que ele é ativado.
- congelado
  
  booleano opcional
  
  Chrome 132 ou mais recente
  
  Se as guias estão congeladas. Uma guia congelada não pode executar tarefas, incluindo manipuladores de eventos ou timers. Ela fica visível na barra de guias, e o conteúdo dela é carregado na memória. Ele é descongelado na ativação.
- groupId
  
  número optional
  
  Chrome 88 ou mais recente
  
  O ID do grupo em que as guias estão ou tabGroups.TAB_GROUP_ID_NONE para guias desagrupadas.
- em destaque
  
  booleano opcional
  
  Indica se as guias estão destacadas.
- index
  
  número optional
  
  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 ou mais recente
  
  Se as guias estão silenciadas.
- pixado
  
  booleano opcional
  
  Se as guias estão fixadas.
- splitViewId
  
  número optional
  
  Chrome 140 ou mais recente
  
  O ID da visualização dividida em que as guias estão ou tabs.SPLIT_VIEW_ID_NONE para guias que não estão em uma visualização dividida.
- status
  
  TabStatus opcional
  
  O status de carregamento da guia.
- título
  
  string opcional
  
  Corresponder títulos de página a um padrão. Essa propriedade é ignorada se a extensão não tiver a permissão "tabs" ou permissões de host para a página.
- url
  
  string | string[] opcional
  
  Corresponda 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" ou permissões de host para a página.
- windowId
  
  número optional
  
  O ID da janela principal ou windows.WINDOW_ID_CURRENT para a janela atual.
- windowType
  
  WindowType opcional
  
  O tipo de janela em que as guias estão.

Retorna

Promise<Tab[]>

Chrome 88 ou mais recente

reload()

chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
): Promise<void>

Atualize uma guia.

Parâmetros

tabId

número optional

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

objeto opcional
- bypassCache
  
  booleano opcional
  
  Se o cache local deve ser ignorado. O valor padrão é false.

Retorna

Promessa<void>

Chrome 88 ou mais recente

remove()

chrome.tabs.remove(
  tabIds: number | number[],
): Promise<void>

Fecha uma ou mais guias.

Parâmetros

tabIds

number | number[]

O ID da guia ou a lista de IDs de guias a serem fechadas.

Retorna

Promessa<void>

Chrome 88 ou mais recente

sendMessage()

chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
): Promise<any>

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

Parâmetros

tabId

número
mensagem

qualquer

A mensagem a ser enviada. Essa mensagem precisa ser um objeto JSON.
opções

objeto opcional
- documentId
  
  string opcional
  
  Chrome 106 ou mais recente
  
  Enviar uma mensagem para um documento específico identificado por documentId em vez de todos os frames na guia.
- frameId
  
  número optional
  
  Envie uma mensagem para um frame específico identificado por frameId em vez de todos os frames na guia.

Retorna

Promise<any>

Chrome 99+

setZoom()

chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
): Promise<void>

Aplica zoom em uma guia especificada.

Parâmetros

tabId

número optional

O ID da guia a ser ampliada. O padrão é a guia ativa da janela atual.
zoomFactor

número

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

Retorna

Promessa<void>

Chrome 88 ou mais recente

setZoomSettings()

chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
): Promise<void>

Define as configurações de zoom para 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 na guia.

Parâmetros

tabId

número optional

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.

Retorna

Promessa<void>

Chrome 88 ou mais recente

ungroup()

Chrome 88 ou mais recente

chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
): Promise<void>

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 da guia ou a lista de IDs de guias a serem removidas dos respectivos grupos.

Retorna

Promessa<void>

update()

chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
): Promise<Tab | undefined>

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

Parâmetros

tabId

número optional

O padrão é a guia selecionada da janela atual.
updateProperties

objeto
- ativo
  
  booleano opcional
  
  Se a guia deve 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 deve 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 ou mais recente
  
  Se a guia deve ser silenciada.
- openerTabId
  
  número optional
  
  O ID da guia que abriu esta guia. Se especificado, a guia de abertura precisa estar na mesma janela que esta guia.
- pixado
  
  booleano opcional
  
  Se a guia deve ser fixada.
- selecionado
  
  booleano opcional
  
  Descontinuado
  
  Use destacado.
  Se a guia deve ser selecionada.
- url
  
  string opcional
  
  Um URL para navegar até a guia. URLs JavaScript não são aceitos. Use scripting.executeScript.

Retorna

Promise<Tab | undefined>

Chrome 88 ou mais recente

Eventos

onActivated

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

Disparado quando a guia ativa em uma janela muda. O URL da guia pode não estar definido quando esse evento é acionado, mas você pode ouvir eventos "onUpdated" para receber uma notificação quando um URL for definido.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(activeInfo: object) => void
```
- activeInfo
  
  objeto
  - tabId
    
    número
    
    O ID da guia que foi ativada.
  - windowId
    
    número
    
    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 esta aparência:
```
(tabId: number, attachInfo: object) => void
```
- tabId
  
  número
- attachInfo
  
  objeto
  - newPosition
    
    número
  - newWindowId
    
    número

onCreated

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

Disparado quando uma guia é criada. O URL da guia e a associação ao grupo de guias podem não estar definidos quando esse evento é acionado, mas você pode ouvir eventos "onUpdated" para receber uma notificação quando um URL é definido ou a guia é adicionada a um grupo de guias.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(tab: Tab) => void
```
- tab
  
  Tab

onDetached

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

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

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(tabId: number, detachInfo: object) => void
```
- tabId
  
  número
- detachInfo
  
  objeto
  - oldPosition
    
    número
  - oldWindowId
    
    número

onHighlighted

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

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

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(highlightInfo: object) => void
```
- highlightInfo
  
  objeto
  - tabIds
    
    number[]
    
    Todas as guias destacadas na janela.
  - windowId
    
    número
    
    A janela com as guias alteradas.

onMoved

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

Disparado quando uma guia é movida em uma janela. Apenas um evento de movimentação é disparado, representando a guia que o usuário moveu diretamente. Os eventos de movimento não são disparados para as outras guias que precisam se mover em resposta à guia movida manualmente. Esse evento não é disparado quando uma guia é movida entre janelas. Para mais detalhes, consulte tabs.onDetached.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(tabId: number, moveInfo: object) => void
```
- tabId
  
  número
- moveInfo
  
  objeto
  - fromIndex
    
    número
  - toIndex
    
    número
  - windowId
    
    número

onRemoved

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

Disparado quando uma guia é fechada.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(tabId: number, removeInfo: object) => void
```
- tabId
  
  número
- removeInfo
  
  objeto
  - isWindowClosing
    
    booleano
    
    Verdadeiro quando a guia foi fechada porque a janela principal foi fechada.
  - windowId
    
    número
    
    A janela cuja guia foi fechada.

onReplaced

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

Disparado quando uma guia é substituída por outra devido à pré-renderização ou instantânea.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(addedTabId: number, removedTabId: number) => void
```
- addedTabId
  
  número
- removedTabId
  
  número

onUpdated

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

Disparado quando uma guia é atualizada.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(tabId: number, changeInfo: object, tab: Tab) => void
```
- tabId
  
  número
- changeInfo
  
  objeto
  - Audible
    
    booleano opcional
    
    Chrome 45 ou mais recente
    
    O novo estado audível 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 descartado da guia.
  - favIconUrl
    
    string opcional
    
    O novo URL do favicon da guia.
  - congelado
    
    booleano opcional
    
    Chrome 132 ou mais recente
    
    O novo estado congelado da guia.
  - groupId
    
    número optional
    
    Chrome 88 ou mais recente
    
    O novo grupo da guia.
  - mutedInfo
    
    MutedInfo opcional
    
    Chrome 46 ou mais recente
    
    O novo estado de mudo da guia e o motivo da mudança.
  - pixado
    
    booleano opcional
    
    O novo estado fixado da guia.
  - splitViewId
    
    número optional
    
    Chrome 140 ou mais recente
    
    A nova visualização dividida da guia.
  - status
    
    TabStatus opcional
    
    O status de carregamento da guia.
  - título
    
    string opcional
    
    Chrome 48 ou mais recente
    
    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 recebe zoom.

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(ZoomChangeInfo: object) => void
```
- ZoomChangeInfo
  
  objeto
  - newZoomFactor
    
    número
  - oldZoomFactor
    
    número
  - tabId
    
    número
  - zoomSettings
    
    ZoomSettings

chrome.tabs Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Permissões

Casos de uso

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

Receber a guia atual

Desativar o som da guia especificada

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

Transmitir uma mensagem ao script de conteúdo de uma guia selecionada

Exemplos de extensões

Tipos

MutedInfo

Propriedades

MutedInfoReason

Enumeração

Tab

Propriedades

TabStatus

Enumeração

WindowType

Enumeração

ZoomSettings

Propriedades

ZoomSettingsMode

Enumeração

ZoomSettingsScope

Enumeração

Propriedades

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Valor

TAB_ID_NONE

Valor

TAB_INDEX_NONE

Valor

Métodos

captureVisibleTab()

Parâmetros

Retorna

connect()

Parâmetros

Retorna

create()

Parâmetros

Retorna

detectLanguage()

Parâmetros

Retorna

discard()

Parâmetros

Retorna

duplicate()

Parâmetros

Retorna

get()

Parâmetros

Retorna

getCurrent()

Retorna

getZoom()

Parâmetros

Retorna

getZoomSettings()

Parâmetros

Retorna

goBack()

Parâmetros

Retorna

goForward()

Parâmetros

Retorna

group()

Parâmetros

Retorna

highlight()

Parâmetros

Retorna

move()

Parâmetros

Retorna

query()

chrome.tabs