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.
Visão geral
A API Tabs não só oferece 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 requer 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 concede acesso ao namespace
chrome.tabs
. Em vez disso, concedeu a uma extensão a capacidade de chamartabs.query()
em quatro propriedades confidenciais em instâncias detabs.Tab
:url
,pendingUrl
,title
efavIconUrl
. - Permissões do host
- As permissões de host permitem que uma extensão leia e consulte as quatro propriedades
tabs.Tab
confidenciais de uma guia correspondente. Eles também podem interagir diretamente com as guias correspondentes usando métodos comotabs.captureVisibleTab()
,tabs.executeScript()
,tabs.insertCSS()
etabs.removeCSS()
. - A permissão "activeTab"
activeTab
concede a uma extensão permissão de host temporária 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 aviso.
Manifesto
Confira abaixo exemplos de como declarar cada permissão no manifesto:
{
"name": "My extension",
...
"permissions": [
"tabs"
],
...
}
{
"name": "My extension",
...
"host_permissions": [
"http://*/*",
"https://*/*"
],
...
}
{
"name": "My extension",
...
"permissions": [
"activeTab"
],
...
}
Casos de uso
As seções abaixo demonstram alguns casos de uso comuns.
Como abrir uma página de extensão em uma nova guia
Um padrão comum para as extensões é abrir uma página de integração em uma nova guia quando a extensão estiver instalada. O exemplo abaixo mostra como fazer isso.
background.js:
chrome.runtime.onInstalled.addListener(({reason}) => {
if (reason === 'install') {
chrome.tabs.create({
url: "onboarding.html"
});
}
});
Acessar a guia atual
Este exemplo demonstra como o service worker de uma extensão pode recuperar a guia ativa da janela em foco no momento (ou da janela mais recente, se nenhuma janela do Chrome estiver em foco). Ela geralmente pode ser considerada 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 silenciado 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 esse 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 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 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ão
Para acessar mais demonstrações de extensões da API Tabs, confira uma das opções abaixo:
Tipos
MutedInfo
O estado silenciado da guia e o motivo da última alteração de estado.
Propriedades
-
extensionId
string opcional
O ID da extensão que alterou o estado silenciado. Não definido se uma extensão não foi a razão pela qual o estado silenciado pela última vez foi alterado.
-
silenciado
boolean
Indica se o som da guia está desativado (impedido que o som seja reproduzido). O som da guia pode ser desativado mesmo que não tenha sido reproduzido ou esteja sem nenhum som. Equivalente à exibição do indicador de áudio "silenciado".
-
reason
MutedInfoReason opcional
O motivo da ativação ou desativação do som da guia. Não definido se o estado de silenciamento da guia nunca tiver sido alterado.
MutedInfoReason
Um evento que causou uma alteração de estado silenciado.
Tipo enumerado
"user"
Uma ação de entrada do usuário definiu o estado silenciado.
"captura"
A captura da guia foi iniciada, forçando uma mudança de estado silenciada.
"extensão"
Uma extensão, identificada pelo campo extensionId, define o estado silenciado.
Tab
Propriedades
-
ativo
boolean
Se a guia está ativa na janela dela. Isso não significa necessariamente que a janela está em foco.
-
Audible
booleano opcional
Chrome 45 ou mais recenteIndica se a guia produziu som nos últimos segundos, mas talvez ele não seja ouvido se o som também estiver desativado. Equivalente à exibição do indicador de "áudio do alto-falante".
-
autoDiscardable
boolean
Chrome 54 ou mais recenteDefine se a guia pode ser descartada automaticamente pelo navegador quando os recursos estiverem baixos.
-
descartou
boolean
Chrome 54 ou mais recenteIndica se a guia é descartada. Uma guia descartada é aquela que tem o conteúdo descarregado da memória, mas ainda está visível na barra de guias. O conteúdo será recarregado na próxima vez em que for ativado.
-
favIconUrl
string opcional
É o URL do favicon da guia. Esta propriedade só estará presente se o manifesto da extensão incluir a permissão
"tabs"
. Ela também pode ser uma string vazia se a guia estiver sendo carregada. -
groupId
number
Chrome 88 ou mais recenteO ID do grupo a que a guia pertence.
-
height
número opcional
A altura da guia em pixels.
-
em destaque
boolean
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 estrangeiras usando a API
sessions
. Nesse caso, um ID de sessão pode estar presente. O ID da guia também pode ser definido comochrome.tabs.TAB_ID_NONE
para apps e janelas do DevTools. -
navegação anônima
boolean
Se a guia está em uma janela anônima.
-
índice
number
O índice baseado em zero da guia dentro da janela.
-
lastAccessed
número opcional
Chrome 121 ou mais recenteA última vez que a guia foi acessada como o número de milissegundos desde o período.
-
mutedInfo
MutedInfo opcional
Chrome 46 ou mais recenteO estado silenciado da guia e o motivo da última alteração de estado.
-
openerTabId
número opcional
O ID da guia que abriu a guia, se houver. Essa propriedade só estará presente se a guia que o abrir ainda existir.
-
pendingUrl
string opcional
Chrome 79 ou mais recenteO URL para o qual a guia está navegando antes da confirmação. Esta propriedade só estará presente se o manifesto da extensão incluir a permissão
"tabs"
e houver uma navegação pendente. -
fixado
boolean
Indica se a guia está fixada.
-
selecionado
boolean
DescontinuadoUse
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 recebida da API
sessions
. -
status
TabStatus opcional
Status de carregamento da guia.
-
title
string opcional
O título da guia. Esta 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. Esta propriedade só estará presente se o manifesto da extensão incluir a permissão
"tabs"
e poderá ser uma string vazia se a guia ainda não tiver sido confirmada. Consulte tambémTab.pendingUrl
. -
width
número opcional
A largura da guia em pixels.
-
windowId
number
O ID da janela que contém a guia.
TabStatus
Status de carregamento da guia.
Tipo enumerado
WindowType
O tipo de janela.
Tipo enumerado
"normal"
"app"
ZoomSettings
Define como as alterações de zoom em uma guia são manipuladas e em qual escopo.
Propriedades
-
defaultZoomFactor
número opcional
Chrome 43 ou mais recenteUsado 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 na origem da página ou só entram em vigor nesta guia. O padrão é
per-origin
no modoautomatic
. Caso contrário, éper-tab
.
ZoomSettingsMode
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
.
Tipo enumerado
"automático"
As mudanças de zoom são controladas automaticamente pelo navegador.
"manual"
Modifica o gerenciamento automático de mudanças de zoom. O evento onZoomChange
ainda será despachado, e é responsabilidade da extensão detectar esse evento e dimensionar a página manualmente. Esse modo não oferece suporte ao zoom com per-origin
. Portanto, ele ignora a configuração de zoom do scope
e pressupõe o uso de per-tab
.
"desativado"
Desativa todo o zoom na guia. A guia é revertida para o nível de zoom padrão, e todas as tentativas de mudança de zoom são ignoradas.
ZoomSettingsScope
Define se as mudanças de zoom persistem na origem da página ou só entram em vigor nesta guia. O padrão é per-origin
no modo automatic
. Caso contrário, é per-tab
.
Tipo enumerado
"per-origin"
As mudanças de zoom persistem na origem da página com zoom, ou seja, todas as outras guias navegadas para a 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 vão ter o mesmo zoom. O escopo per-origin
está disponível apenas no modo automatic
.
"por guia"
As mudanças de zoom só têm efeito nesta guia, e as mudanças em outras guias não afetam o zoom dela. Além disso, as mudanças de zoom de per-tab
são redefinidas na navegação. A navegação em uma guia sempre carrega páginas com os fatores de zoom de per-origin
.
Propriedades
MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND
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
Um ID que representa a ausência de uma guia do navegador.
Valor
1
TAB_INDEX_NONE
Um índice que representa a ausência de um índice de guias em um tab_strip.
Valor
1
Métodos
captureVisibleTab()
chrome.tabs.captureVisibleTab(
windowId?: number,
options?: ImageDetails,
callback?: function,
)
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 as extensões capturem sites confidenciais que são restritos, incluindo páginas chrome:-scheme, páginas de outras extensões e URLs de dados: dados. Esses sites confidenciais só podem ser capturados com a permissão activeTab. Os URLs de arquivos só poderão ser capturados se a extensão tiver recebido acesso ao arquivo.
Parâmetros
-
windowId
número opcional
A janela de segmentação. O padrão é a janela atual.
-
do modelo.
ImageDetails opcional
-
callback
função optional
O parâmetro
callback
tem esta aparência:(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 HTML
img
para exibição.
-
Retorna
-
Promessa<string>
Chrome 88 ou mais recentePromessas são compatíveis apenas com 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
é disparado em cada script de conteúdo em execução na guia especificada para a extensão atual. Para mais detalhes, consulte Mensagens do script de conteúdo.
Parâmetros
-
tabId
number
-
connectInfo
objeto opcional
-
documentId
string opcional
Chrome 106 ou mais recenteAbra uma porta para um documento específico identificado por
documentId
em vez de todos os frames na guia. -
frameId
número opcional
Abre uma porta para um frame específico identificado por
frameId
em vez de todos os frames na guia. -
nome
string opcional
É transmitido ao onConnect para 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 será disparado se a guia for fechada ou não existir.
create()
chrome.tabs.create(
createProperties: object,
callback?: function,
)
Cria uma nova guia.
Parâmetros
-
createProperties
objeto
-
ativo
booleano opcional
Define se a guia deve se tornar a guia ativa na janela. Não afeta o foco da janela (consulte
windows.update
). O padrão étrue
. -
índice
número opcional
A posição que a guia deve assumir na janela. O valor fornecido está fixado entre zero e o número de guias na janela.
-
openerTabId
número opcional
O ID da guia que abriu a guia. Se especificado, a guia de abertura precisa estar na mesma janela que a guia recém-criada.
-
fixado
booleano opcional
Define se a guia deve ser fixada. O valor padrão é
false
. -
selecionado
booleano opcional
DescontinuadoUse ativo.
Define se a guia deve se tornar a 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.br", e não "www.google.com.br"). Os URLs relativos são relativos à página atual na extensão. O padrão é a página "Nova guia".
-
windowId
número opcional
A janela em que a nova guia será criada. O padrão é a janela atual.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tab: Tab) => void
-
.
A guia criada.
-
Retorna
-
Promise<Tab>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
detectLanguage()
chrome.tabs.detectLanguage(
tabId?: number,
callback?: function,
)
Detecta o idioma principal do conteúdo em uma guia.
Parâmetros
-
tabId
número opcional
O padrão é a guia ativa da janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(language: string) => void
-
language
string
Um código de idioma ISO, como
en
oufr
. Para uma lista completa de idiomas suportados por esse método, consulte kLanguageInfoTable. A segunda a quarta colunas são verificadas e o primeiro valor não NULL é retornado, exceto para chinês simplificado, para o qualzh-CN
é retornado. Para idioma desconhecido/indefinido,und
é retornado.
-
Retorna
-
Promessa<string>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
discard()
chrome.tabs.discard(
tabId?: number,
callback?: function,
)
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 opcional
O ID da guia a ser descartada. Se especificada, a guia é descartada, a menos que esteja ativa ou já tenha sido descartada. Se omitida, o navegador descarta a guia menos importante. Isso pode falhar se não houver guias descartáveis.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tab?: Tab) => void
-
.
Guia opcional
A guia descartada, se tiver sido descartada com sucesso. Caso contrário, é indefinida.
-
Retorna
-
Promise<Tab | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
duplicate()
chrome.tabs.duplicate(
tabId: number,
callback?: function,
)
Duplica uma guia.
Parâmetros
-
tabId
number
O ID da guia a ser duplicada.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tab?: Tab) => void
Retorna
-
Promise<Tab | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
executeScript()
chrome.tabs.executeScript(
tabId?: number,
details: InjectDetails,
callback?: function,
)
Substituído por scripting.executeScript
no Manifesto V3.
Injeta código JavaScript em uma página. Para mais detalhes, consulte a seção sobre injeção programática do documento de scripts de conteúdo.
Parâmetros
-
tabId
número opcional
O ID da guia na qual executar o script; o padrão é a guia ativa da janela atual.
-
detalhes
Detalhes do script a ser executado. O código ou a propriedade do arquivo precisam ser definidos, mas não podem ser definidos ao mesmo tempo.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result?: any[]) => void
-
resultado
qualquer[] opcional
Resultado do script em cada frame injetado.
-
Retorna
-
Promessa<qualquer[] | indefinida>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
get()
chrome.tabs.get(
tabId: number,
callback?: function,
)
Recupera detalhes sobre a guia especificada.
Parâmetros
-
tabId
number
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tab: Tab) => void
-
.
-
Retorna
-
Promise<Tab>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getAllInWindow()
chrome.tabs.getAllInWindow(
windowId?: number,
callback?: function,
)
Use tabs.query
{windowId: windowId}
.
Recebe detalhes sobre todas as guias na janela especificada.
Parâmetros
-
windowId
número opcional
O padrão é a janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tabs: Tab[]) => void
-
guias
Guia[]
-
Retorna
-
Promise<Tab[]>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getCurrent()
chrome.tabs.getCurrent(
callback?: function,
)
Extrai a guia da qual esta chamada de script está sendo feita. Retorna undefined
se chamado de um contexto que não seja de guia (por exemplo, uma página em segundo plano ou uma visualização pop-up).
Parâmetros
Retorna
-
Promise<Tab | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getSelected()
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 optional
O parâmetro
callback
tem esta aparência:(tab: Tab) => void
-
.
-
Retorna
-
Promise<Tab>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getZoom()
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 da qual obter o fator de zoom atual. O padrão é a guia ativa da janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(zoomFactor: number) => void
-
zoomFactor
number
O fator de zoom atual da guia.
-
Retorna
-
Prometer<número>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getZoomSettings()
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
)
Recebe as configurações atuais de zoom de uma guia especificada.
Parâmetros
-
tabId
número opcional
O ID da guia da qual se obtém as configurações de zoom atuais. O padrão é a guia ativa da janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(zoomSettings: ZoomSettings) => void
-
zoomSettings
As configurações de zoom atuais da guia.
-
Retorna
-
Promise<ZoomSettings>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
goBack()
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 navegar de volta; o padrão é a guia selecionada da janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
goForward()
chrome.tabs.goForward(
tabId?: number,
callback?: function,
)
Siga para a próxima página, se houver uma disponível.
Parâmetros
-
tabId
número opcional
O ID da guia para avançar. O padrão é a guia selecionada da janela atual.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
group()
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 determinadas a um grupo recém-criado.
Parâmetros
-
do modelo.
objeto
-
createProperties
objeto opcional
Configurações para criar um grupo. Não será possível usar se o 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 ao qual as guias serão adicionadas. Caso não seja especificado, um novo grupo será criado.
-
tabIds
número | [número, ...número[]]
O ID da guia ou a lista de IDs de guias a serem adicionados ao grupo especificado.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(groupId: number) => void
-
groupId
number
O ID do grupo ao qual as guias foram adicionadas.
-
Retorna
-
Prometer<número>
Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
highlight()
chrome.tabs.highlight(
highlightInfo: object,
callback?: function,
)
Destaca as guias fornecidas e foca na primeira do grupo. Aparecerá que não faz nada se a guia especificada estiver ativa no momento.
Parâmetros
-
highlightInfo
objeto
-
guias
número | número[]
Um ou mais índices de guia para destacar.
-
windowId
número opcional
A janela que contém as guias.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(window: Window) => void
-
janela
Contém detalhes sobre a janela cujas guias foram destacadas.
-
Retorna
-
Promise<windows.Window>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
insertCSS()
chrome.tabs.insertCSS(
tabId?: number,
details: InjectDetails,
callback?: function,
)
Substituído por scripting.insertCSS
no Manifesto 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 sobre injeção programática do documento de scripts de conteúdo.
Parâmetros
-
tabId
número opcional
O ID da guia na qual inserir o CSS. O padrão é a guia ativa da janela atual.
-
detalhes
Detalhes do texto CSS a ser inserido. O código ou a propriedade do arquivo precisam ser definidos, mas não podem ser definidos ao mesmo tempo.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
move()
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
número | número[]
O ID da guia ou a lista de IDs de guias a serem movidos.
-
moveProperties
objeto
-
índice
number
A posição para a qual a janela será movida. Use
-1
para colocar a guia no fim da janela. -
windowId
número opcional
O padrão é a janela em que a guia está no momento.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tabs: Tab | Tab[]) => void
Retorna
-
Chrome 88 ou mais recente
Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
query()
chrome.tabs.query(
queryInfo: object,
callback?: function,
)
Recebe todas as guias que têm as propriedades especificadas ou todas as guias, se nenhuma propriedade foi especificada.
Parâmetros
-
queryInfo
objeto
-
ativo
booleano opcional
Se as guias estão ativas nas janelas delas.
-
Audible
booleano opcional
Chrome 45 ou mais recenteDefine se as guias são audíveis.
-
autoDiscardable
booleano opcional
Chrome 54 ou mais recenteDefine se as guias podem ser descartadas automaticamente pelo navegador quando os recursos estão baixos.
-
currentWindow
booleano opcional
Indica se as guias estão na janela atual.
-
descartou
booleano opcional
Chrome 54 ou mais recenteIndica se as guias serão descartadas. Uma guia descartada é aquela que tem o conteúdo descarregado da memória, mas ainda está visível na barra de guias. O conteúdo será recarregado na próxima vez em que for ativado.
-
groupId
número opcional
Chrome 88 ou mais recenteO ID do grupo em que as guias estão ou
tabGroups.TAB_GROUP_ID_NONE
para guias não agrupadas. -
em destaque
booleano opcional
Indica se as guias estão destacadas.
-
índice
número opcional
A posição das guias nas janelas.
-
lastFocusedWindow
booleano opcional
Indica se as guias estão na última janela em foco.
-
silenciado
booleano opcional
Chrome 45 ou mais recenteIndica se as guias estão silenciadas.
-
fixado
booleano opcional
Indica se as guias estão fixadas.
-
status
TabStatus opcional
Status de carregamento da guia.
-
title
string opcional
Combine títulos de páginas com um padrão. Essa propriedade será ignorada se a extensão não tiver a permissão
"tabs"
. -
url
string | string[] opcional
Relacione as guias a um ou mais padrões de URL. Os identificadores de fragmento não são correspondentes. Essa propriedade será ignorada se a extensão não tiver a permissão
"tabs"
. -
windowId
número opcional
O ID da janela mãe ou
windows.WINDOW_ID_CURRENT
da janela atual. -
windowType
WindowType (opcional)
O tipo de janela em que as guias estão.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: Tab[]) => void
-
resultado
Guia[]
-
Retorna
-
Promise<Tab[]>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
reload()
chrome.tabs.reload(
tabId?: number,
reloadProperties?: object,
callback?: function,
)
Atualizar uma guia.
Parâmetros
-
tabId
número opcional
O ID da guia a ser atualizada. O padrão é a guia selecionada da janela atual.
-
reloadProperties
objeto opcional
-
bypassCache
booleano opcional
Define se o armazenamento em cache local deve ser ignorado. O valor padrão é
false
.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
remove()
chrome.tabs.remove(
tabIds: number | number[],
callback?: function,
)
Fecha uma ou mais guias.
Parâmetros
-
tabIds
número | número[]
O ID da guia ou a lista de IDs da guia a ser fechada.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
removeCSS()
chrome.tabs.removeCSS(
tabId?: number,
details: DeleteInjectionDetails,
callback?: function,
)
Substituído por scripting.removeCSS
no Manifesto V3.
Remove o 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 da qual remover o CSS. O padrão é a guia ativa da janela atual.
-
detalhes
Detalhes do texto CSS a ser removido. O código ou a propriedade do arquivo precisam ser definidos, mas não podem ser definidos ao mesmo tempo.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
sendMessage()
chrome.tabs.sendMessage(
tabId: number,
message: any,
options?: object,
callback?: function,
)
Envia uma única mensagem aos scripts de conteúdo na guia especificada, com um retorno de chamada opcional para ser executado quando uma resposta for reenviada. 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
number
-
mensagem
qualquer um
A mensagem a ser enviada. Essa mensagem deve ser um objeto compatível com JSON.
-
do modelo.
objeto opcional
-
callback
função optional
Chrome 99 ou mais recenteO parâmetro
callback
tem esta aparência:(response: any) => void
-
resposta
qualquer um
O objeto de resposta JSON enviado pelo gerenciador da mensagem. Se ocorrer um erro durante a conexão com a guia especificada, o callback será chamado sem argumentos, e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Prometa<qualquer>
Chrome 99 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
sendRequest()
chrome.tabs.sendRequest(
tabId: number,
request: any,
callback?: function,
)
Use runtime.sendMessage
.
Envia uma única solicitação aos scripts de conteúdo na guia especificada, com um retorno de chamada opcional para ser executado quando uma resposta for enviada de volta. O evento extension.onRequest
é disparado em cada script de conteúdo em execução na guia especificada para a extensão atual.
Parâmetros
-
tabId
number
-
request
qualquer um
-
callback
função optional
Chrome 99 ou mais recenteO parâmetro
callback
tem esta aparência:(response: any) => void
-
resposta
qualquer um
O objeto de resposta JSON enviado pelo gerenciador da solicitação. Se ocorrer um erro durante a conexão com a guia especificada, o callback será chamado sem argumentos, e
runtime.lastError
será definido como a mensagem de erro.
-
Retorna
-
Prometa<qualquer>
Chrome 99 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setZoom()
chrome.tabs.setZoom(
tabId?: number,
zoomFactor: number,
callback?: function,
)
Aplica zoom a 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 com o fator de zoom padrão atual. Valores superiores a0
especificam um fator de zoom (possivelmente não padrão) para a guia. -
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setZoomSettings()
chrome.tabs.setZoomSettings(
tabId?: number,
zoomSettings: ZoomSettings,
callback?: function,
)
Define as configurações de zoom para uma guia especificada, definindo como as mudanças de zoom são tratadas. Essas configurações são redefinidas para o padrão durante a navegação na guia.
Parâmetros
-
tabId
número opcional
O ID da guia para a qual alterar as configurações de zoom; o padrão é a guia ativa da janela atual.
-
zoomSettings
Define como as mudanças de zoom são processadas e em qual escopo.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
ungroup()
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 da guia ou a lista de IDs a serem removidos dos respectivos grupos.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
update()
chrome.tabs.update(
tabId?: number,
updateProperties: object,
callback?: function,
)
Modifica as propriedades de uma guia. As propriedades não especificadas no updateProperties
não são modificadas.
Parâmetros
-
tabId
número opcional
O padrão é a guia selecionada da janela atual.
-
updateProperties
objeto
-
ativo
booleano opcional
Se a guia deve estar ativa. Não afeta o foco da janela (consulte
windows.update
). -
autoDiscardable
booleano opcional
Chrome 54 ou mais recenteDefine se a guia deve ser descartada automaticamente pelo navegador quando os recursos estiverem baixos.
-
em destaque
booleano opcional
Adiciona ou remove a guia da seleção atual.
-
silenciado
booleano opcional
Chrome 45 ou mais recenteIndica se o som da guia deve ser desativado.
-
openerTabId
número opcional
O ID da guia que abriu a guia. Se especificado, a guia de abertura precisa estar na mesma janela que essa guia.
-
fixado
booleano opcional
Define se a guia deve ser fixada.
-
selecionado
booleano opcional
DescontinuadoUse os destacados.
Define se a guia deve ser selecionada.
-
url
string opcional
Um URL para navegar na guia. Os URLs de JavaScript não são compatíveis. Use
scripting.executeScript
.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(tab?: Tab) => void
Retorna
-
Promise<Tab | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
Eventos
onActivated
chrome.tabs.onActivated.addListener(
callback: function,
)
Dispara quando a guia ativa em uma janela é alterada. O URL da guia pode não estar definido no momento em que esse evento é disparado, mas é possível detectar eventos onUpdated para ser notificado quando um URL for definido.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(activeInfo: object) => void
-
activeInfo
objeto
-
tabId
number
O ID da guia que se tornou ativa.
-
windowId
number
O ID da janela na qual a guia ativa foi alterada.
-
-
onActiveChanged
chrome.tabs.onActiveChanged.addListener(
callback: function,
)
Use tabs.onActivated
.
Dispara quando a guia selecionada em uma janela é alterada. O URL da guia pode não estar definido no momento em que esse evento é disparado, mas é possível detectar eventos tabs.onUpdated
para receber uma notificação quando um URL for definido.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(tabId: number, selectInfo: object) => void
-
tabId
number
-
selectInfo
objeto
-
windowId
number
O ID da janela em que a guia selecionada foi alterada.
-
-
onAttached
chrome.tabs.onAttached.addListener(
callback: function,
)
Disparado quando uma guia é anexada a uma janela, por exemplo, porque ela foi movida entre janelas.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(tabId: number, attachInfo: object) => void
-
tabId
number
-
attachInfo
objeto
-
newPosition
number
-
newWindowId
number
-
-
onCreated
chrome.tabs.onCreated.addListener(
callback: function,
)
Disparado quando uma guia é criada. O URL da guia e a associação do grupo de guias podem não estar definidos no momento em que esse evento é acionado, mas é possível detectar eventos onUpdated para receber uma notificação quando um URL for definido ou a guia for adicionada a um grupo de guias.
onDetached
chrome.tabs.onDetached.addListener(
callback: function,
)
Disparado quando uma guia é removida de uma janela, por exemplo, porque ela foi movida entre janelas.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(tabId: number, detachInfo: object) => void
-
tabId
number
-
detachInfo
objeto
-
oldPosition
number
-
oldWindowId
number
-
-
onHighlightChanged
chrome.tabs.onHighlightChanged.addListener(
callback: function,
)
Use tabs.onHighlighted
.
Disparado quando as guias destacadas ou selecionadas em uma janela são alteradas.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(selectInfo: object) => void
-
selectInfo
objeto
-
tabIds
Número[]
Todas as guias destacadas na janela.
-
windowId
number
A janela cujas guias foram alteradas.
-
-
onHighlighted
chrome.tabs.onHighlighted.addListener(
callback: function,
)
Disparado quando as guias destacadas ou selecionadas em uma janela são alteradas.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(highlightInfo: object) => void
-
highlightInfo
objeto
-
tabIds
Número[]
Todas as guias destacadas na janela.
-
windowId
number
A janela cujas guias foram alteradas.
-
-
onMoved
chrome.tabs.onMoved.addListener(
callback: function,
)
Disparado quando uma guia é movida dentro de uma janela. Somente um evento de movimento é disparado, representando a guia movida diretamente pelo usuário. Os eventos de movimentação não são acionados para as outras guias que precisam se mover em resposta à guia movida manualmente. Este evento não é acionado quando uma guia é movida entre as janelas. Para acessar detalhes, consulte tabs.onDetached
.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(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 esta aparência:(tabId: number, removeInfo: object) => void
-
tabId
number
-
removeInfo
objeto
-
isWindowClosing
boolean
Verdadeiro quando a guia foi fechada porque a janela principal foi fechada.
-
windowId
number
A janela cuja guia está fechada.
-
-
onReplaced
chrome.tabs.onReplaced.addListener(
callback: function,
)
Disparado quando uma guia é substituída por outra devido a uma pré-renderização ou um processo instantâneo.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(addedTabId: number, removedTabId: number) => void
-
addedTabId
number
-
removedTabId
number
-
onSelectionChanged
chrome.tabs.onSelectionChanged.addListener(
callback: function,
)
Use tabs.onActivated
.
Dispara quando a guia selecionada em uma janela é alterada.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(tabId: number, selectInfo: object) => void
-
tabId
number
-
selectInfo
objeto
-
windowId
number
O ID da janela em que a guia selecionada foi alterada.
-
-
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
number
-
changeInfo
objeto
-
Audible
booleano opcional
Chrome 45 ou mais recenteNovo estado audível da guia.
-
autoDiscardable
booleano opcional
Chrome 54 ou mais recenteNovo estado de descarte automático da guia.
-
descartou
booleano opcional
Chrome 54 ou mais recenteO novo estado descartado da guia.
-
favIconUrl
string opcional
O novo URL do favicon da guia.
-
groupId
número opcional
Chrome 88 ou mais recenteO novo grupo da guia.
-
mutedInfo
MutedInfo opcional
Chrome 46 ou mais recenteO novo estado silenciado da guia e o motivo da alteração.
-
fixado
booleano opcional
Novo estado fixado da guia.
-
status
TabStatus opcional
Status de carregamento da guia.
-
title
string opcional
Chrome 48 ou mais recenteO novo título da guia.
-
url
string opcional
O URL da guia, se tiver sido alterado.
-
-
.
-
onZoomChange
chrome.tabs.onZoomChange.addListener(
callback: function,
)
Disparado quando uma guia é ampliada.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(ZoomChangeInfo: object) => void
-
ZoomChangeInfo
objeto
-
newZoomFactor
number
-
oldZoomFactor
number
-
tabId
number
-
zoomSettings
-
-