This is an archived page. It's not actively maintained.

tabs

Stable

Abre, manipula, e acessa tabs, e recebe eventos de tabs

Uso

Abrir uma tab

Você pode abrir uma nova tab, especificando várias propriedades incluindo localização:

var tabs = require("sdk/tabs");
tabs.open("http://www.Exemplo.com");

Rastrear tabs

Voc√™ pode registrar eventos de escuta para ser notificado quando a tabs abre, fecha, termina o carregamento de conte√ļdo DOM, ou tornam-se ativa ou inativa:

var tabs = require("sdk/tabs");

// Listen for tab openings.
tabs.on('open', function onOpen(tab) {
  myOpenTabs.push(tab);
});

// Listen for tab content loads.
tabs.on('ready', function(tab) {
  console.log('tab is loaded', tab.title, tab.url);
});

Accessar tabs

O módulo por ele mesmo pode ser usado como uma lista de todas as tabs abertas em todos os navegadores. Em particular, você pode enumerá-las:

var tabs = require('sdk/tabs');
for (let tab of tabs)
  console.log(tab.title);

Você também pode acessar tabs individual pelo índice:

var tabs = require('sdk/tabs');

tabs.on('ready', function () {
  console.log('first: ' + tabs[0].title);
  console.log('last: ' + tabs[tabs.length-1].title);
});

Você pode acessar a tab ativa atualmente:

var tabs = require('sdk/tabs');

tabs.on('activate', function () {
  console.log('active: ' + tabs.activeTab.url);
});

Rastrear uma √ļnica tab

Dada uma tab, você pode registrar escutas para eventos serem notificados quando a tab é fechada, ativada ou desativada, ou quando a página hospedad pela tab é carregada ou recuperada do "back-forward cache":

var tabs = require("sdk/tabs");

function onOpen(tab) {
  console.log(tab.url + " is open");
  tab.on("pageshow", logShow);
  tab.on("activate", logActivate);
  tab.on("deactivate", logDeactivate);
  tab.on("close", logClose);
}

function logShow(tab) {
  console.log(tab.url + " is loaded");
}

function logActivate(tab) {
  console.log(tab.url + " is activated");
}

function logDeactivate(tab) {
  console.log(tab.url + " is deactivated");
}

function logClose(tab) {
  console.log(tab.url + " is closed");
}

tabs.on('open', onOpen);

Manipular uma tab

Voc√™ pode conseguir e configurar v√°rias propriedades de tabs (mas note que propriedades relacionadas ao conte√ļdo da tab, tal como URL, n√£o conter√£o valores v√°lidos at√© depois do evento ready disparar). Pela configura√ß√£o da propriedade url voc√™ pode carregar uma nova p√°gina na tab:

var tabs = require("sdk/tabs");
tabs.on('activate', function(tab) {
  tab.url = "http://www.Exemplo.com";
});

Execute scripts em um tab

Voc√™ pode anexar um script de conte√ļdo a p√°gina hospedad na tab, e usar aquele para acessar e manipular o conte√ļdo da p√°gina (veja o tutorial Modifying the Page Hosted by a Tab):

var tabs = require("sdk/tabs");

tabs.on('activate', function(tab) {
  var worker = tab.attach({
    contentScript: 'self.port.emit("html", document.body.innerHTML);'
  });
  worker.port.on("html", function(message) {
    console.log(message)
  })
});

Observe que tab.attach √© centrado na tab: se o usu√°rio navegar para uma nova p√°gina na mesma tab, ent√£o o trabalho e scripts de conte√ļdo ser√£o reanexados √° nova p√°gina.

Anexação de stylesheets

Novo no Firefox 34.

Voc√™ n√£o pode anexar folhas de estilo para uma tab usando tab.attach(), mas do Firefox 34 em diante voc√™ pode anexar e desanexa-los usando APIs de baixo n√≠vel  stylesheet/style e content/mod. Aqui est√° um add-on que usa bot√Ķes alternados para anexar uma folha de estilo a tab ativa, e desanexar novamente. A folha de estilo √© chamada "style.css" e est√° localizada no diret√≥rio "data":

var tabs = require("sdk/tabs");
var { attach, detach } = require('sdk/content/mod');
var { Style } = require('sdk/stylesheet/style');
var { ToggleButton } = require("sdk/ui/button/toggle");

var style = Style({
  uri: './style.css'
});

var button = ToggleButton({
  id: "stylist",
  label: "stylist",
  icon: "./icon-16.png",
  onChange: function(state) {
    if (state.checked) {
      attach(style, tabs.activeTab);
    }
    else {
      detach(style, tabs.activeTab);
    }
  }
});

Janelas Privadas

Se o seu add-on não optou por entrar em navegação privada, então você não verá quaisquer tabs pela janela de navegação privada.

Tabs hospedadas por janelas em navegação privada não serão vista se você enumerar o módulo tab por si mesmo, e você não receberá quaisquer eventos deles.

Para aprender mais sobre janelas privadas, como optar por entrar em navegação privada, e como suportar navegação privada, dirija-se à documentação do módulo para private-browsing.

Converção para XUL tabs

Para converter de um objeto Tab de alto nível usando esta API para um objeto XUL tab de baixo nível usado na API tabs/utils e por add-ons tradicionais, use a função viewFor() exportada pelo móduloa viewFor.

Para converter de volta, de uma tab XUL para um objeto Tab de alto nível, use a função modelFor(), exportada pelo módulo modelFor.

Aqui está um exemplo covertendo de uma Tab de alto nível para uma tab XUL e então converte de volta:

var { modelFor } = require("sdk/model/core");
var { viewFor } = require("sdk/view/core");

var tabs = require("sdk/tabs");
var tab_utils = require("sdk/tabs/utils");

function mapHighLevelToLowLevel(tab) {
  // get the XUL tab that corresponds to this high-level tab
  var lowLevelTab = viewFor(tab);
  // now we can, for Exemplo, access the tab's content directly
  var browser = tab_utils.getBrowserForTab(lowLevelTab);
  console.log(browser.contentDocument.body.innerHTML);
  // get the high-level tab back from the XUL tab
  var highLevelTab = modelFor(lowLevelTab);
  console.log(highLevelTab.url);
}

tabs.on("ready", mapHighLevelToLowLevel);

Observe que acessar objetos XUL diretamente e conte√ļdo web como este significa que voc√™ n√£o est√° protegido pelas garantias de compatibilidades feitas pelas APIs de alto n√≠vel do SDK. Em particular, seu c√≥digo n√£o deve trabalhar com multiprocess Firefox.

Globais

Fun√ß√Ķes

open(op√ß√Ķes)

Abre uma nova tab. A nova tab abrirá na janela ativa ou na nova janela, dependendo da opção inNewWindow.

Examplo

var tabs = require("sdk/tabs");

// Open a new tab on active window and make tab active.
tabs.open("http://www.mysite.com");

// Open a new tab in a new window and make it active.
tabs.open({
  url: "http://www.mysite.com",
  inNewWindow: true
});

// Open a new tab on active window in the background.
tabs.open({
  url: "http://www.mysite.com",
  inBackground: true
});

// Open a new tab as an app tab and do something once it's open.
tabs.open({
  url: "http://www.mysite.com",
  isPinned: true,
  onOpen: function onOpen(tab) {
    // do stuff like listen for content
    // loading.
  }
});
Par√Ęmetros

opção: object
Op√ß√Ķes necess√°rias:

Name Type  
url string

URL a ser aberta na nova tab. Esta é uma propriedade necessária.

Op√ß√Ķes opcionais:

Name Type  
isPrivate boolean

Boolean que determinará se a nova tab deve ser privada ou não. Se seu add-on não suporta navegação privada isto não terá efeito. Veja a documentação de navegação privada para mais informação. O padrão é false.

inNewWindow boolean

Se presente e true, uma nova janela de navegação será aberta e na primeira tab naquela janela. Esta é uma propriedade opcional.

inBackground boolean

Se presente e true, a nova tab será aberta à direita da tab ativa e não estará ativa. Esta é uma propriedade opcional.

isPinned boolean

Se presente e true, a nova tab ser√° anexada como um app tab.

onOpen function

Uma função que será registrada para o evento 'open'. Esta é uma propriedade opcional.

onClose function

Uma função de callback que será registrada para o evento 'close'. Esta é uma propriedade opcional.

onReady function

Uma função de callback que será registrada para o evento 'ready'. Esta é uma propriedade opcional.

onLoad function

Uma função de callback que será registrada para o evento 'load'. Esta é uma propriedade opcional.

onPageShow function

Uma função de callback que será registrada para o evento 'pageshow'. Esta é uma propriedade opcional.

onActivate function

Uma função de callback que será registrada para o evento 'activate'. Esta é uma propriedade opcional.

onDeactivate function

Uma função de callback que será registrada para o evento 'deactivate'. Esta é uma propriedade opcional.

Propriedades

activeTab

A tab ativa na janela ativa. Esta propriedade é somente leitura. Para ativar um objeto Tab, chame seu método activate.

Exemplo

// Get the active tab's title.
var tabs = require("sdk/tabs");
console.log("title of active tab is " + tabs.activeTab.title);

length

O n√ļmero de tabs abertas em todas as janelas.

Eventos

open

Este evento √© emitido quando uma nova tab √© aberta. Isto n√£o significa que o conte√ļdo carregou, somente que o navegador est√° inteiramente vis√≠vel para o usu√°rio.

Propriedades relacionadas √† conte√ļdo da tab (por exemplo: title, favicon, e url) n√£o ser√£o corrigidas neste ponto. Se voc√™ precisar acessar estas propriedades, escute o evento ready:

var tabs = require("sdk/tabs");
tabs.on('open', function(tab){
  tab.on('ready', function(tab){
    console.log(tab.url);
  });
});
Argumentos

Tab : Escutas s√£o passadas ao objeto tab que acaba de abrir.

close

Este evento é emitido quando a tab é fechada. Quando a janela é fechada este evento será emitido para cada uma das tabs abertas naquela janela.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab que fechou.

ready

Este evento √© emitido quando o DOM para o conte√ļdo da p√°gina estiver preparado. √Č equivalmente ao evento DOMContentLoaded para conte√ļdo da p√°gina dada.

Um √ļnica tab emitir√° este evento toda vez todas √†s vezes que o DOM for carregado: ent√£o ser√° emitido novamente se o endere√ßo da p√°gina mudar ou o conte√ļdo for recarregado.

Depois que este evento for emitido, todas as propriedades relacionadas ao conte√ļdo da p√°gina poder√£o ser usadas.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab que carregou.

activate

Este evento é emitido quando uma tab inativa torna-se ativa.

Argumentos

Tab : Escutas s√£o passadas para o objeto tab que torna-se ativa.

deactivate

Este evento é emitido quando a tab ativa torna-se inativa.

Argumentos

Tab : Escutas s√£o passadas para o objeto tab que tornou-se inativo.

Tab

Uma inst√Ęncia Tab representa um √ļnica tab aberta. Ele cont√©m v√°rias propriedades, v√°rios m√©todos para manipula√ß√£o, assim como registra√ß√£o de evento por tab.

Tabs emitem todos os eventos descritos na seção de Eventos. Escutas são passadas ao objeto Tab que lança eventos.

Métodos

pin()

Anexa a tab como uma app tab.

unpin()

Desanexa esta tab.

close(callback)

Fecha esta tab.

Par√Ęmetros

callback : function
Uma função será chamada quanto a tab termine seu processo de fechamento. Este é uma argumento opcional.

reload()

Recarrega esta tab.

activate()

Torna esta tab ativa, que trar√° esta tab para o primeiro plano.

getThumbnail()

Retorna o dado thumbnail da URI da p√°gina atualmente carregada nesta tab.

attach(options)

Anexa um ou mais scripts ao documento carregado na tab. Observe que este √© centrado na tab: se o usu√°rio navega para uma nova p√°gina na mesma tab, ent√£o o script de conte√ļdo ser√° reanexado √† nova p√°gina.

Exemplo

var tabs = require("sdk/tabs");

tabs.on('ready', function(tab) {
  var worker = tab.attach({
      contentScript:
        'document.body.style.border = "5px solid red";'
  });
});
Par√Ęmetros

options : objeto
Op√ß√Ķes opcionais:

Name Type  
contentScriptFile string,array

As URLs dos arquivos locais dos scripts de conte√ļdo carregados. Scripts de conte√ļdo especificados por esta op√ß√£o s√£o carregados antes daqueles especificados pela op√ß√£o contentScript. Opcional.

contentScript string,array

Uma string ou uma array de strings do c√≥digo para ser avaliado no contexto. Scripts de conte√ļdo especificados por esta op√ß√£o s√£o carregados depois daqueles especificados pela op√ß√£o contentScriptFile. Opcional.

contentScriptOptions object

Voc√™ pode usar esta op√ß√£o para definir valores somente leitura para seus scripts de conte√ļdo.

A op√ß√£o consiste de uma listagem de objetos literais no formato pares name:value para os valores que voc√™ quer fornecer para o script de conte√ļdo. Por exemplo:

// main.js

const tabs = require("sdk/tabs");

tabs.open({
  url: "./page.html",
  onReady: function(tab) {
    tab.attach({
      contentScriptFile: "./content-script.js",
      contentScriptOptions: {
        a: "blah"
      }
    });
  }
});

Os valores s√£o acess√≠veis ao script de conte√ļdo via propriedade self.options:

// content-script.js

alert(self.options.a);
onMessage function

Uma fun√ß√£o chamada quando o conte√ļdo de trabalho recebe uma mensagem dos scripts de conte√ļdo. Escutas s√£o passadas como um √ļnico argumento, a mensagem postada do script de conte√ļdo.

onError function

Uma fun√ß√£o chamada quando o trabalhador de conte√ļdo recebe um erro dos scripts de conte√ļdo. Escutas s√£o passar como um √ļnico argumento, error, que √© erro postado do script de conte√ļdo e um objeto do tipo Error. Opcional.

Retorno

Worker : O objeto Worker pode ser usado para comunicar com o script de conte√ļdo. Veja o guia de scripts de conte√ļdo para aprender os detalhes.

Propriedades

id

O √ļnico id para a tab. Esta propriedade √© somente leitura.

title

O título da tab (normalmente o título da página atualmente carregada na tab). Esta propriedade pode ser configurada para mudar o título da tab.

url

A URL da p√°gina atualmente carregada na tab. Esta propriedade pode ser configurada para carregar uma URL diferente na tab.

favicon

A URL do favicon para a página atualmente carregada na tab. Esta propriedade é somente para leitura.

Esta propriedade está desatualizada. Da versão 1.15, use a função getFavicon() do módulo favicon ao invés.

contentType

Esta é uma API experimental atualmente, então nós devemos mudar ele em lançamentos futuros.

Retorna o tipo MIME que o documento atualmente tem carregado na tab sendo desenhada. Ele deve vir do cabeçalho do HTTP ou outra fonte de informação MIME, e deve ser afetado pela conversão de tipo automática executada pelo navegador ou extensão. Esta propriedade é somente leitura.

index

O índice da tab relativa a outras tabs na janela da aplicação. Esta propriedade pode ser configurada para mudar sua posição relativa.

isPinned

Se ou não esta tab é anexável como uma app tab. Esta propriedade é somente leitura.

window

O objeto window para esta tab.

readyState

Novo no Firefox 33.

Uma string dizendo a você qual o estado de carga do documento hospedado por esta tab. Isto corresponde diretamente ao Document.readyState. Ele tem um de quatro valores possíveis:

  • "uninitialized": o documento da tab n√£o est√° ainda carregado
  • "loading": o documento da tab est√° ainda em processo de carga
  • "interactive": o documento da tab carregou e est√° analisado, mas os recursos tais como imagens e folhas de escilo devem ainda ser carregados
  • "complete": o documento da tab e todos os recursos est√£o inteiramente carregados

Uma vez que o readyState da tab entrou no "interactive", você pode pegar as propriedades tais como a URL do documento.

Eventos

close

Este evento é emitido quando a tab é fechada. Ele também é emitido quando a janela da tab é fechada.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab.

ready

Este evento √© emitido quando o DOM para o conte√ļdo da tab estiver preparado.  Ele √© equivalente ao evento DOMContentLoaded para o dado conte√ļdo da p√°gina. Neste ponto o documento por si s√≥ est√° inteiramente carreado e analisado, mas recursos tais como folhas de estilo e imagens devem estar ainda carregando.

Uma √ļnica tab emitir√° este evento todas √†s vezes que o DOM estiver carregado: ent√£o ela ser√° emitida novamente se o endere√ßo da tab mudar ou o conte√ļdo for recarregado. Depois deste evento ser emitido, todas as propriedades relacionadas ao conte√ļdo da tab podem ser usadas.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab.

load

Este evento √© emitido quando a p√°gina do conte√ļdo da tab estiver carregada. √Č equivalente ao evento load para o dado conte√ļdo da p√°gina. Neste ponto o documento e seus recursos, tais como imagens e folhas de estilo, terminaram o carregamento.

Este evento pode ser usado por páginas que não tem um evento DOMContentLoaded, como imagens. Para páginas que tem um evento DOMContentLoaded, load é disparado depois do ready.

Uma √ļnica tab emitir√° este evento toda vez que a p√°gina for carregada: ent√£o ele ser√° emitido novamente se o endere√ßo da tab mudar ou o conte√ļdo for recarregado. Depois deste evento ser emitido, todas as propriedades relacionadas ao conte√ļdo da tab podem ser usados

Argumentos

Tab : Escutas s√£o passadas para o objeto tab.

pageshow

O evento pageshow √© emitido quando a p√°gina para o conte√ļdo da tab for carregado. √Č equivalente ao evento pageshow para um dado conte√ļdo da p√°gina.

Este evento √© similar aos eventos loadready, exceto que diferente de load e ready, pageshow √© lan√ßado se a p√°gina for recuperada do bfcache. Isto significa que se o usu√°rio carrega a p√°gina, carrega uma nova p√°gina, ent√£o se move para a p√°gina anterior usando o bot√£o "Back", o evento pageshow √© emitido quando o usu√°rio volta a p√°gina, enquanto os eventos load e ready n√£o s√£o.

Este evento não é emitido quando a tab fica ativa: para conseguir ser notificado sobre isso, você precisa escutar o evento activate.

Depois que este evento foi emitido, todas as propriedades relacionadas ao conte√ļdo da tab podem ser usadas. Ele √© emitido depois do load e ready.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab.

persisted : Escutas s√£o passadas um valor booleano indicando se ou n√£o a p√°gina foi carregada do bfcache.

activate

Este evento é emitido quando a tab torna-se ativa.

Observe que voc√™ n√£o pode garantir que o conte√ļdo da tab, ou mesmo sua url, est√£o inicializados na hora que o activate foi emitido. Isto porque quando uma nova tab √© aberta, seu evento activate pode ser emitido antes do conte√ļdo ser carregado.

Voc√™ pode usar a propriedade readyState da tab para determinar se o conte√ļdo da tab e url est√£o dispon√≠veis: se o readyState est√° uninitialized ou loading, ent√£o voc√™ n√£o pode acessar as propriedades da tab e deve esperar pelo evento ready da tab.

Argumentos

Tab : Escutas s√£o passadas ao objeto.

deactivate

Este evento é emitido quando a tab torna-se inativa.

Argumentos

Tab : Escutas s√£o passadas ao objeto tab.