tabs

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("https://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 = "https://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

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("https://www.mysite.com");

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

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

// Open a new tab as an app tab and do something once it's open.
tabs.open({
  url: "https://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:

Opções opcionais:

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:

// main.js

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

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

// content-script.js

alert(self.options.a);

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.

contentType

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

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 load e ready, 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.