Primeros pasos

Las extensiones constan de componentes diferentes, pero cohesivos. Los componentes pueden incluir secuencias de comandos en segundo plano, secuencias de comandos de contenido, una página de opciones, elementos de IU y varios archivos lógicos. Los componentes de las extensiones se crean con tecnologías de desarrollo web: HTML, CSS y JavaScript. Los componentes de una extensión dependerán de su funcionalidad y es posible que no requieran todas las opciones.

En este instructivo, se creará una extensión que le permita al usuario cambiar el color de fondo de cualquier página en developer.chrome.com. Se usarán muchos componentes principales para brindar una demostración introductoria de sus relaciones.

Para comenzar, crea un directorio nuevo que contenga los archivos de la extensión.

Puede encontrar la extensión completa aquí.

Crea el manifiesto

Las extensiones comienzan con su manifiesto. Crea un archivo llamado manifest.json y, luego, incluye el siguiente código.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "manifest_version": 2
}

El directorio que contiene el archivo de manifiesto se puede agregar como una extensión en el modo de desarrollador en su estado actual.

  1. Navega a chrome://extensions para abrir la página Administración de extensiones.
    • También puedes abrir la página Administración de extensiones. Para ello, haz clic en el menú de Chrome, coloca el cursor sobre Más herramientas y selecciona Extensiones.
  2. Para habilitar el modo de desarrollador, haz clic en el interruptor junto a Modo de desarrollador.
  3. Haz clic en el botón LOAD UNPACKED y selecciona el directorio de la extensión.

Cargar extensión

¡Charán! La extensión se instaló correctamente. Como no se incluyeron íconos en el manifiesto, se creará un ícono genérico de barra de herramientas para la extensión.

Agregar instrucción

Aunque la extensión se instaló, no tiene instrucciones. Introduce una secuencia de comandos en segundo plano. Para ello, crea un archivo llamado background.js y colócalo dentro del directorio de la extensión.

Las secuencias de comandos en segundo plano y muchos otros componentes importantes deben registrarse en el manifiesto. Registrar una secuencia de comandos en segundo plano en el manifiesto le indica a la extensión a qué archivo hacer referencia y cómo debe comportarse.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

La extensión ahora sabe que incluye una secuencia de comandos en segundo plano no persistente y analizará el archivo registrado en busca de eventos importantes que necesita escuchar.

Esta extensión necesitará información de una variable persistente apenas se instale. Comienza por incluir un evento de escucha para runtime.onInstalled en la secuencia de comandos en segundo plano. Dentro del objeto de escucha onInstalled, la extensión establecerá un valor con la API de storage. Esto permitirá que varios componentes de la extensión accedan a ese valor y lo actualicen.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log("The color is green.");
  });
});

La mayoría de las APIs, incluida la API de storage, deben registrarse en el campo "permissions" del manifiesto para que la extensión las use.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

Vuelve a la página de administración de extensiones y haz clic en el vínculo Volver a cargar. Un nuevo campo, Inspeccionar vistas, estará disponible con un vínculo azul, página en segundo plano.

Inspeccionar vistas

Haz clic en el vínculo para ver el registro de la consola de la secuencia de comandos en segundo plano, "The color is green.".

Presentar una interfaz de usuario

Las extensiones pueden tener muchas formas de interfaz de usuario, pero esta usará una ventana emergente. Crea y agrega un archivo llamado popup.html al directorio. Esta extensión usa un botón para cambiar el color de fondo.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
      }
    </style>
  </head>
  <body>
    <button id="changeColor"></button>
  </body>
</html>

Al igual que la secuencia de comandos en segundo plano, este archivo debe designarse como una ventana emergente en el manifiesto en page_action.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html"
  },
  "manifest_version": 2
}

La designación de los íconos de la barra de herramientas también se incluye en la sección page_action del campo default_icons. Descarga la carpeta de imágenes aquí, descomprímela y colócala en el directorio de la extensión. Actualiza el manifiesto para que la extensión sepa cómo usar las imágenes.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "manifest_version": 2
}

Las extensiones también muestran imágenes en la página de administración de extensiones, la advertencia de permisos y el ícono de página. Estas imágenes se designan en el manifiesto en icons.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "icons": {
    "16": "images/get_started16.png",
    "32": "images/get_started32.png",
    "48": "images/get_started48.png",
    "128": "images/get_started128.png"
  },
  "manifest_version": 2
}

Si la extensión se vuelve a cargar en esta etapa, incluirá un ícono de escala de grises, pero no contendrá ninguna diferencia de funcionalidad. Como page_action se declara en el manifiesto, corresponde a la extensión indicarle al navegador cuándo el usuario puede interactuar con popup.html.

Agrega reglas declaradas a la secuencia de comandos en segundo plano con la API de declarativeContent dentro del evento de objeto de escucha runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log('The color is green.');
  });
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([{
      conditions: [new chrome.declarativeContent.PageStateMatcher({
        pageUrl: {hostEquals: 'developer.chrome.com'},
      })
      ],
          actions: [new chrome.declarativeContent.ShowPageAction()]
    }]);
  });
});

La extensión necesitará permiso para acceder a la API de declarativeContent en su manifiesto.

{
  "name": "Getting Started Example",
...
  "permissions": ["declarativeContent", "storage"],
...
}

Ventana emergente

Ahora, el navegador mostrará un ícono de acción de la página a todo color en la barra de herramientas del navegador cuando los usuarios naveguen a una URL que contenga "developer.chrome.com". Cuando el ícono es a todo color, los usuarios pueden hacer clic en él para ver ventana emergente.html.

El último paso de la IU emergente es agregar color al botón. Crea y agrega un archivo llamado popup.js con el siguiente código al directorio de la extensión.

let changeColor = document.getElementById('changeColor');

chrome.storage.sync.get('color', function(data) {
  changeColor.style.backgroundColor = data.color;
  changeColor.setAttribute('value', data.color);
});

Este código toma el botón de popup.html y solicita el valor de color del almacenamiento. Luego, aplica el color como fondo del botón. Incluye una etiqueta de secuencia de comandos en popup.js en popup.html.

<!DOCTYPE html>
<html>
...
  <body>
    <button id="changeColor"></button>
    <script src="popup.js"></script>
  </body>
</html>

Vuelve a cargar la extensión para ver el botón verde.

Lógica de capas

Ahora, la extensión sabe que la ventana emergente debería estar disponible para los usuarios en developer.chrome.com y muestra un botón de color, pero necesita lógica para continuar con la interacción del usuario. Actualiza popup.js para incluir el siguiente código.

let changeColor = document.getElementById('changeColor');
...
changeColor.onclick = function(element) {
  let color = element.target.value;
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.executeScript(
        tabs[0].id,
        {code: 'document.body.style.backgroundColor = "' + color + '";'});
  });
};

El código actualizado agrega un evento onclick al botón, que activa una secuencia de comandos de contenido insertada de manera programática. De esta manera, el color de fondo de la página será el mismo que el del botón. El uso de la inyección programática permite que las secuencias de comandos de contenido que invoque el usuario, en lugar de insertar automáticamente código no deseado en las páginas web.

El manifiesto necesitará el permiso activeTab para permitir que la extensión acceda de forma temporal a la API de tabs. Esto permite que la extensión llame a tabs.executeScript.

{
  "name": "Getting Started Example",
...
  "permissions": ["activeTab", "declarativeContent", "storage"],
...
}

La extensión ya es totalmente funcional. Vuelve a cargar la extensión, actualiza esta página, abre la ventana emergente y haz clic en el botón para que se vuelva verde. Sin embargo, es posible que algunos usuarios quieran cambiar el color del fondo.

Brindar opciones a los usuarios

Actualmente, la extensión solo permite que los usuarios cambien el fondo a verde. Incluir una página de opciones brinda a los usuarios más control sobre la funcionalidad de la extensión, lo que personaliza aún más su experiencia de navegación.

Para comenzar, crea un archivo en el directorio llamado options.html e incluye el siguiente código.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
        margin: 10px;
      }
    </style>
  </head>
  <body>
    <div id="buttonDiv">
    </div>
    <div>
      <p>Choose a different background color!</p>
    </div>
  </body>
  <script src="options.js"></script>
</html>

Luego, registra la página de opciones en el manifiesto

{
  "name": "Getting Started Example",
  ...
  "options_page": "options.html",
  ...
  "manifest_version": 2
}

Vuelve a cargar la extensión y haz clic en DETALLES.

Inspeccionar vistas

Desplázate hacia abajo en la página de detalles y selecciona Opciones de extensión para ver la página de opciones, aunque aparecerá en blanco.

Opciones de extensión

El último paso es agregar la lógica de opciones. Crea un archivo llamado options.js en el directorio de la extensión con el siguiente código.

let page = document.getElementById('buttonDiv');
const kButtonColors = ['#3aa757', '#e8453c', '#f9bb2d', '#4688f1'];
function constructOptions(kButtonColors) {
  for (let item of kButtonColors) {
    let button = document.createElement('button');
    button.style.backgroundColor = item;
    button.addEventListener('click', function() {
      chrome.storage.sync.set({color: item}, function() {
        console.log('color is ' + item);
      })
    });
    page.appendChild(button);
  }
}
constructOptions(kButtonColors);

Se proporcionan cuatro opciones de color y, luego, se generan como botones en la página de opciones con objetos de escucha de eventos onClick. Cuando el usuario hace clic en un botón, se actualiza el valor del color en el almacenamiento global de la extensión. Dado que todos los archivos de la extensión extraen la información de color del almacenamiento global, no es necesario actualizar otros valores.

Da el siguiente paso

¡Felicitaciones! El directorio ahora contiene una extensión de Chrome totalmente funcional, aunque sencilla.

¿Qué sigue?