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

Cómo insertar secuencias de comandos en la pestaña activa

Para simplificar el diseño de la página actual, haz clic en el ícono de la barra de herramientas de la extensión.

Descripción general

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

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

Usa el trabajador del servicio de extensión como coordinador de eventos.
Preserva la privacidad del usuario con el permiso "activeTab".
Ejecuta código cuando el usuario hace clic en el ícono de la barra de herramientas de la extensión.
Inserta y quita 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 que consultes 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 de 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 instructivo "Cómo ejecutar secuencias de comandos en cada pestaña", en el que se explican los metadata y los íconos de la extensión con 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 trabajador de servicio de la extensión. Los trabajadores de servicio son entornos especiales de JavaScript que controlan los eventos y finalizan cuando no son necesarios.

Comienza por registrar 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 nuestro trabajador de servicio escuchará 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 controlamos dos estados, usaremos el texto de la insignia de la acción para hacer un seguimiento de si la extensión está "ACTIVADA" o "DESACTIVADA".

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

La acción de la extensión controla el ícono de la barra de herramientas de la extensión. Por lo tanto, cada vez que 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 otorga a la extensión la capacidad temporal de ejecutar código en la pestaña activa. También permite el acceso a las propiedades sensibles de la pestaña actual.

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

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

Presiona una combinación de teclas.
Seleccionar un elemento del menú contextual
Aceptar una sugerencia de la barra omni.
Abrir una ventana emergente de la extensión

El permiso "activeTab" permite que los usuarios de forma intencional elijan ejecutar la extensión en la pestaña enfocada. De esta manera, se 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: Haz un seguimiento del estado de la pestaña actual

Después de que el usuario haga clic en la acción de la extensión, esta 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 siguiente estado. 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 momento de cambiar el diseño de la página. Crea un archivo llamado focus-mode.css y, luego, incluye el siguiente código:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

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 un atajo para facilitar la habilitación o inhabilitación del modo sin distracciones. Agrega la clave "commands" al manifiesto.

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

La clave "_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 del modo de enfoque: manifest.json, background.js, focus-mode.css y la carpeta de imágenes

Carga tu extensión de forma local

Para cargar una extensión sin comprimir en el 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 configuras una combinación de teclas, puedes probarla presionando Ctrl + B o Cmd + B.

Debería pasar de lo siguiente:

Extensión del modo sin distracciones DESACTIVADA — La extensión del modo sin distracciones está desactivada

A esto:

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

🎯 Mejoras potenciales

En función de lo que aprendiste hoy, intenta hacer lo siguiente:

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

Sigue creando.

¡Felicitaciones por completar este instructivo! 🎉 Continúa mejorando tus habilidades completando otros instructivos de esta serie:

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

Sigue explorando

Esperamos que hayas disfrutado de la compilación de esta extensión de Chrome y que te entusiasme continuar tu recorrido de aprendizaje para su desarrollo. Te recomendamos las siguientes rutas de aprendizaje:

La guía para desarrolladores tiene decenas de vínculos adicionales a documentación relevante para la creación de extensiones avanzadas.
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 APIs de Chrome, se explica cada API.