Gerenciar eventos com scripts de segundo plano

Extensões são programas baseados em eventos usados para modificar ou melhorar a experiência de navegação no Chrome. Eventos são acionadores do navegador, como navegar para uma nova página, remover um favorito ou fechar uma guia. As extensões monitoram esses eventos no script de segundo plano e reagem com instruções específicas.

Uma página de plano de fundo é carregada quando necessário e descarregada quando fica ociosa. Alguns exemplos de incluem:

• A extensão é instalada ou atualizada primeiro para uma nova versão.
• A página de segundo plano estava detectando um evento, e o evento foi enviado.
• Um script de conteúdo ou outra extensão envia uma mensagem.
• Outra visualização na extensão, como um pop-up, chama runtime.getBackgroundPage.

Uma vez carregada, a página de fundo permanecerá em execução enquanto realizar uma ação, como chamar uma API do Chrome ou emitir uma solicitação de rede. Além disso, a página de fundo não descarregar até que todas as visualizações visíveis e todas as portas de mensagens sejam fechadas. Observe que abrir uma visualização não causará o carregamento da página do evento, mas apenas impede que ela seja fechada após o carregamento.

Scripts de segundo plano eficazes permanecem inativos até que um evento detecte incêndios, reaja com instruções específicas e, em seguida, descarregue.

Registrar scripts de segundo plano

Os scripts em segundo plano são registrados no campo "background" do manifesto. São listado em uma matriz após a chave "scripts", e "persistent" precisa ser especificado como falso.

{
  "name": "Awesome Test Extension",
  ...
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  ...
}

Vários scripts de segundo plano podem ser registrados para código modularizado.

{
    "name": "Awesome Test Extension",
    ...
    "background": {
      "scripts": [
        "backgroundContextMenus.js",
        "backgroundOmniBox.js",
        "backgroundOauth.js"
      ],
      "persistent": false
    },
    ...
  }

Se uma extensão estiver usando uma página de segundo plano persistente, consulte Migração em segundo plano guia para instruções sobre como mudar para um modelo não persistente.

Inicializar a extensão

Ouça o evento runtime.onInstalled para inicializar uma extensão na instalação. Usar para definir um estado ou para uma inicialização única, como um menu de contexto.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

Configurar listeners

Estruture scripts de segundo plano com base nos eventos de que a extensão depende. Como definir uma funcionalidade relevante permite que scripts de segundo plano fiquem latentes até que esses eventos sejam acionados e impede que os de perda de gatilhos importantes.

Os listeners precisam ser registrados de forma síncrona desde o início da página.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

// This will run when a bookmark is created.
chrome.bookmarks.onCreated.addListener(function() {
  // do something
});

Não registre listeners de maneira assíncrona, porque eles não serão acionados adequadamente.

chrome.runtime.onInstalled.addListener(function() {
  // ERROR! Events must be registered synchronously from the start of
  // the page.
  chrome.bookmarks.onCreated.addListener(function() {
    // do something
  });
});

As extensões podem remover listeners dos scripts em segundo plano chamando removeListener. Se todos listeners de um evento forem removidos, o Chrome não carregará mais o script de plano de fundo da extensão para desse evento.

chrome.runtime.onMessage.addListener(function(message, sender, reply) {
    chrome.runtime.onMessage.removeListener(event);
});

Filtrar eventos

Usar APIs compatíveis com filtros de evento para restringir listeners aos casos importantes para a extensão Se uma extensão estiver detectando o evento tabs.onUpdated, tente usar o webNavigation.onCompleted com filtros, já que a API de guias não é compatível filtros.

chrome.webNavigation.onCompleted.addListener(function() {
    alert("This is my favorite website!");
}, {url: [{urlMatches : 'https://www.google.com/'}]});

Reagir aos listeners

Os listeners existem para acionar a funcionalidade quando um evento é disparado. Para reagir a um evento, estruture a reação desejada dentro do evento do listener.

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message.data == "setAlarm") {
    chrome.alarms.create({delayInMinutes: 5})
  } else if (message.data == "runLogic") {
    chrome.tabs.executeScript({file: 'logic.js'});
  } else if (message.data == "changeColor") {
    chrome.tabs.executeScript(
        {code: 'document.body.style.backgroundColor="orange"'});
  };
});

Descarregar scripts em segundo plano

Os dados devem ser mantidos periodicamente para que informações importantes não sejam perdidas se uma extensão falha sem receber onSuspend. Use a API storage para ajudar nisso.

chrome.storage.local.set({variable: variableInformation});

Se uma extensão usar a transmissão de mensagens, verifique se todas as portas estão fechadas. O script de plano de fundo não descarregar até que todas as portas de mensagens sejam fechadas. Como detectar o evento runtime.Port.onDisconnect dará insights sobre o fechamento de portas abertas. Feche manualmente com runtime.Port.disconnect (em inglês).

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message == 'hello') {
    sendResponse({greeting: 'welcome!'})
  } else if (message == 'goodbye') {
    chrome.runtime.Port.disconnect();
  }
});

A vida útil de um script em segundo plano pode ser observada ao monitorar quando uma entrada para a extensão aparece e desaparece do gerenciador de tarefas do Chrome.

Abra o gerenciador de tarefas clicando no menu do Google Chrome, passando o mouse sobre mais ferramentas e selecionando "Tarefa Administrador".

Os scripts de segundo plano são descarregados sozinhos após alguns segundos de inatividade. Se houver uma limpeza de última hora é obrigatório, detecte o evento runtime.onSuspend.

chrome.runtime.onSuspend.addListener(function() {
  console.log("Unloading.");
  chrome.browserAction.setBadgeText({text: ""});
});

No entanto, é preferível usar dados persistentes em vez de confiar em runtime.onSuspend. Ela não permitir a limpeza que for necessária e não ajudará em caso de falha.