Se usó la API de Cloud Translation para traducir esta página.

Incorporar secuencias de comandos en la pestaña activa

Haz clic en el ícono de la barra de herramientas de extensiones para simplificar el estilo de la página actual.

Descripción general

En este instructivo, se compila una extensión que simplifica el estilo de la extensión de Chrome y de las páginas de documentación de Chrome Web Store para que sean más fáciles de leer.

En esta guía, explicaremos cómo hacer lo siguiente:

Usa el service worker de extensión como coordinador de eventos.
Conserva la privacidad del usuario mediante el permiso "activeTab".
Ejecuta el código cuando el usuario haga clic en el ícono de la barra de herramientas de extensiones.
Insertar y quitar una hoja de estilo con la API de Scripting
Usa una combinación de teclas para ejecutar el código.

Antes de comenzar

En esta guía, se da por sentado que tienes experiencia básica en desarrollo web. Te recomendamos consultar Hello World para obtener una introducción al flujo de trabajo de desarrollo de extensiones.

Compila la extensión

Para comenzar, crea un directorio nuevo llamado focus-mode que contenga los archivos de la extensión. Si lo prefieres, puedes descargar el código fuente completo desde GitHub.

Paso 1: Agrega los datos y los íconos de la extensión

Crea un archivo llamado manifest.json y, luego, incluye el siguiente código.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

Para obtener más información sobre estas claves de manifiesto, consulta el tutorial "Cómo ejecutar secuencias de comandos en cada pestaña", donde se explican los metadatos e íconos de la extensión en más detalle.

Crea una carpeta images y, luego, descarga los íconos en ella.

Paso 2: Inicializa la extensión

Las extensiones pueden supervisar los eventos del navegador en segundo plano con el service worker de la extensión. Los service workers son entornos especiales de JavaScript que controlan eventos y finalizan cuando no son necesarios.

Para comenzar, registra el service worker en el archivo manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

Crea un archivo llamado background.js y agrega el siguiente código:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

El primer evento que detectará nuestro service worker es runtime.onInstalled(). Este método permite que la extensión establezca un estado inicial o complete algunas tareas durante la instalación. Las extensiones pueden usar la API de Storage y IndexedDB para almacenar el estado de la aplicación. Sin embargo, en este caso, como solo se muestran dos estados, usaremos el texto de la insignia de acción para realizar un seguimiento de si la extensión está "ACTIVADA" o "DESACTIVADA".

Paso 3: Habilita la acción de extensión

La acción de extensión controla el ícono de la barra de herramientas de la extensión. Por lo tanto, cuando el usuario haga clic en el ícono de la extensión, se ejecutará algún código (como en este ejemplo) o se mostrará una ventana emergente. Agrega el siguiente código para declarar la acción de extensión en el archivo manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

Usa el permiso activeTab para proteger la privacidad del usuario

El permiso activeTab le otorga a la extensión la capacidad temporal de ejecutar código en la pestaña activa. También permite el acceso a propiedades sensibles de la pestaña actual.

Este permiso se habilita cuando el usuario invoca la extensión. En este caso, el usuario invoca la extensión haciendo clic en la acción de la extensión.

💡 ¿Qué otras interacciones del usuario habilitan el permiso activeTab en mi propia extensión?

Presionar una combinación de combinación de teclas
Seleccionar un elemento del menú contextual
Aceptar una sugerencia del cuadro multifunción.
Abrir una ventana emergente de una extensión

El permiso "activeTab" les permite a los usuarios elegir intencionalmente ejecutar la extensión en la pestaña enfocada; de esta manera, protege la privacidad del usuario. Otro beneficio es que no activa una advertencia de permiso.

Para usar el permiso "activeTab", agrégalo al array de permisos del manifiesto:

{
  ...
  "permissions": ["activeTab"],
  ...
}

Paso 4: Realiza un seguimiento del estado de la pestaña actual

Después de que el usuario haga clic en la acción de extensión, la extensión verificará si la URL coincide con una página de documentación. A continuación, verificará el estado de la pestaña actual y establecerá el estado siguiente. Agrega el siguiente código a background.js:

const extensions = 'https://developer.chrome.com/docs/extensions'
const webstore = 'https://developer.chrome.com/docs/webstore'

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON'

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

Paso 5: Agrega o quita la hoja de estilo

Ahora es el momento de cambiar el diseño de la página. Crea un archivo llamado focus-mode.css y, luego, incluye el siguiente código:

body > .scaffold > :is(top-nav, navigation-rail, side-nav, footer),
main > :not(:last-child),
main > :last-child > navigation-tree,
main .toc-container {
  display: none;
}

main > :last-child {
  margin-top: min(10vmax, 10rem);
  margin-bottom: min(10vmax, 10rem);
}

Inserta o quita la hoja de estilo con la API de Scripting. Comienza por declarar el permiso "scripting" en el manifiesto:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}

Por último, en background.js, agrega el siguiente código para cambiar el diseño de la página:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 ¿Puedo usar la API de Scripting para insertar código en lugar de una hoja de estilo?

Sí. Puedes usar scripting.executeScript() para insertar JavaScript.

Opcional: Asigna una combinación de teclas

Solo por diversión, agrega una combinación de teclas para habilitar o inhabilitar el modo sin distracciones fácilmente. Agrega la clave "commands" al manifiesto.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

La tecla "_execute_action" ejecuta el mismo código que el evento action.onClicked(), por lo que no se necesita código adicional.

Prueba que funcione

Verifica que la estructura de archivos de tu proyecto se vea de la siguiente manera:

El contenido de la carpeta de modo de enfoque: manifest.json, background.js, foco-mode.css y la carpeta de imágenes

Carga la extensión de forma local

Para cargar una extensión sin empaquetar en modo de desarrollador, sigue los pasos que se indican en Hello World.

Prueba la extensión en una página de documentación

Primero, abre cualquiera de las siguientes páginas:

Luego, haz clic en la acción de la extensión. Si configuraste una combinación de teclas, puedes presionar Ctrl + B o Cmd + B para probarla.

Debería provenir de esto:

Extensión del Modo sin distracciones DESACTIVADA — Extensión del Modo sin distracciones desactivada

A esto:

Extensión del Modo sin distracciones ACTIVADA — Extensión del Modo sin distracciones activada

🎯 Posibles mejoras

En función de lo que aprendiste hoy, intenta realizar alguna de las siguientes acciones:

Mejora la hoja de estilo CSS.
Asigna otra combinación de teclas.
Cambiar el diseño de tu blog o sitio de documentación favorito

Sigue creando

Felicitaciones por terminar este instructivo 🎉. Para seguir mejorando tus habilidades, completa otros instructivos de esta serie:

Extensión	Qué aprenderás
Tiempo de lectura	Para insertar automáticamente un elemento en un conjunto específico de páginas.
Administrador de pestañas	Para crear una ventana emergente que administre las pestañas del navegador.

Sigue explorando

Esperamos que hayas disfrutado la creación de esta extensión de Chrome y nos entusiasma continuar con tu recorrido de aprendizaje de desarrollo de extensiones. Recomendamos las siguientes rutas de aprendizaje:

La guía para desarrolladores contiene decenas de vínculos adicionales a documentación relevante para la creación avanzada de extensiones.
Las extensiones tienen acceso a APIs potentes más allá de lo que está disponible en la Web abierta. En la documentación de las API de Chrome se explica cada API.