Ejemplo: Insertador de imágenes con un script de contenido

En este ejemplo se usa código JavaScript para insertar la stars.jpeg imagen en la parte superior de la página web actual, dentro del <body> elemento. La ventana emergente de la extensión contiene un título y un botón HTML con la etiqueta Insertar imagen. Al hacer clic en el botón Insertar imagen , el código JavaScript de la extensión envía un mensaje desde el elemento emergente del icono de la extensión e inserta dinámicamente JavaScript que se ejecuta en la pestaña del explorador.

Este ejemplo muestra las siguientes características de extensión:

• Insertar bibliotecas de JavaScript en una extensión.
• Exponer recursos de extensión a las pestañas del explorador.
• Incluir páginas web de contenido en pestañas de explorador existentes.
• Hacer que las páginas web de contenido escuchen los mensajes de los elementos emergentes y respondan.

Vista previa de la muestra

Instalará la extensión de ejemplo mediante la pestaña Administrar extensiones del explorador, hará clic en el botón Extensiones () para mostrar la lista de extensiones instaladas y, a continuación, hará clic en esta extensión de muestra:

La extensión muestra una pequeña página web HTML en un elemento emergente, que contiene un título, un botón Insertar imagen e instrucciones:

Al hacer clic en el botón Insertar imagen , el código JavaScript se inserta stars.jpeg temporalmente en la parte superior de la página web actual, empujando hacia abajo el contenido de la página web hasta debajo de la imagen. El contenido insertado establece el elemento image para mostrar la imagen stars.jpeg estática en la parte superior de la página web actual:

Al hacer clic en la imagen, el JavaScript insertado quita la imagen del árbol del DOM y de la página web.

Obtenga, instale y ejecute el ejemplo como se indica a continuación.

Clonar el repositorio de MicrosoftEdge-Extensions

Puede usar varias herramientas para clonar un repositorio de GitHub. Puede descargar un directorio seleccionado o clonar el repositorio completo.

Clone el repositorio MicrosoftEdge-Extensions en la unidad local y, a continuación, cambie a una rama en funcionamiento, como se indica a continuación.

Instalar el ejemplo localmente (instalación de prueba)

En lugar de instalar el ejemplo desde el sitio web de complementos de Microsoft Edge , instalará el ejemplo localmente para que pueda modificarlo y probar rápidamente los cambios. Instalar localmente a veces se denomina instalación de prueba de una extensión.

1. En Microsoft Edge, haga clic en el botón Extensiones (), junto a la barra de direcciones, si se muestra este icono. O bien, selecciona Configuración y más (>Extensiones. Se abre la ventana emergente Extensiones :

   

2. Haga clic en Administrar extensiones. La página de administración de extensiones se abre en una nueva pestaña:

   

3. Active el botón de alternancia del modo de desarrollador .

4. Al instalar la extensión de muestra por primera vez, haga clic en el botón Cargar desempaquetado ( Se abre el cuadro de diálogo Seleccionar el directorio de extensión .

5. Seleccione el directorio que contiene los archivos de origen de la extensión, como manifest.json.

   Ruta de ejemplo:

   C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

6. Haga clic en el botón Seleccionar carpeta .

   Se cierra el cuadro de diálogo Seleccionar el directorio de extensión.

   La extensión se instala en el explorador, de forma similar a una extensión que se instala desde el sitio web de complementos de Microsoft Edge:

   

Ejecutar el ejemplo

1. Vaya a una página web, como la aplicación TODO, en una nueva ventana o pestaña. La pestaña no debe estar vacía y no debe ser la página Administrar extensiones, ya que este ejemplo inserta contenido en la página web actual.

2. Actualice la página web. A veces, esto es necesario después de recargar una extensión.

3. En Microsoft Edge, a la derecha de la barra de direcciones, si se muestra este icono, haga clic en el botón Extensiones (). O bien, seleccione Configuración y más (>Extensiones.

   Se abre la ventana emergente Extensiones :

   

4. Haz clic en el icono o nombre de la extensión (insertador de imágenes con script de contenido).

   Se abre la extensión y el icono de la extensión se agrega junto a la barra de direcciones y al icono de Extensiones ().

   Se abre un elemento emergente que contiene una pequeña página web HTML con un título, un botón Insertar imagen e instrucciones:

   

5. Haga clic en el botón Insertar imagen . stars.jpeg se inserta en la parte superior de la página web actual en la pestaña actual, empujando el contenido de la página web hacia abajo debajo de la imagen:

   

6. Haga clic en la stars.jpeg imagen que rellena la parte superior de la página web. Ese elemento de imagen se quita del árbol DOM y de la página web, y la página web actual se restaura, cambiando su contenido de nuevo a la parte superior de la pestaña.

La extensión envía un mensaje desde el elemento emergente del icono de la extensión e inserta dinámicamente JavaScript que se ejecuta como contenido en la pestaña del explorador. El contenido inyectado establece el elemento de imagen para que se muestre stars.jpeg en la parte superior de la página web actual y, a continuación, quita la imagen al hacer clic en la imagen.

Vea también:

• Transferir localmente una extensión para instalarla y probarla localmente

Estudiar la muestra

En las secciones siguientes, estudiará la muestra. Después de eso, para desarrollar su propia extensión de Microsoft Edge, puede copiar y modificar el directorio de la muestra, e instalar y probar la extensión resultante.

Files and directories

El ejemplo tiene la siguiente estructura de directorios y archivos.

Ruta de ejemplo para el ejemplo:

C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

Directorios y archivos del /picture-inserter-content-script/ directorio:

/content-scripts/
   content.js
/icons/
   extension-icon16x16.png
   extension-icon32x32.png
   extension-icon48x48.png
   extension-icon128x128.png
/images/
   stars.jpeg
/popup/
   popup.html
   popup.js
manifest.json

• El /content-scripts/ directorio contiene content.js, que es el script que se inserta en la página web actual.
• El /icons/ directorio contiene versiones de un .png archivo que se usa para representar la extensión cerca de la barra de direcciones del explorador, en la ventana emergente Extensiones y en la página de administración de extensiones .
• El /images/ directorio contiene stars.jpeg, que se muestra en el menú emergente de la extensión.
• El /popup/ directorio contiene los archivos:
  • popup.html Define el contenido de la página web emergente inicial de la extensión (un título, un botón e instrucciones).
  • popup.js Para la página web emergente inicial, se envía un mensaje al script de contenido (content.js) que se ejecuta en la página de pestañas, especificando qué archivo de imagen se mostrará.
• manifest.json Contiene información básica sobre la extensión.

Estrategia para actualizar la página web para insertar la imagen en la parte superior (stars.jpeg)

Este ejemplo incluye un script de contenido que se inserta en la página web que se carga en la pestaña actual del explorador.

1. Cuando ejecuta el ejemplo de extensión, se muestra la página HTML emergente inicial (popup.html), que muestra un título, instrucciones y el botón Insertar imagen .

2. Al hacer clic en el botón Insertar imagen , el JavaScript (popup.js) de la página emergente inicial envía un mensaje al script de contenido (content.js) que se ejecuta en la página de pestaña. El mensaje especifica qué archivo de imagen mostrar.

3. El script de contenido (content.js) que se ejecuta en la página de la pestaña recibe el mensaje y muestra el archivo de imagen especificado (stars.jpeg).

La página web emergente inicial (popup.html)

/popup/popup.html se especifica en el archivo de manifiesto como la página web que se mostrará en el elemento emergente inicial de la extensión. El archivo de manifiesto contiene el campo "default_popup": "popup/popup.html"de clave . El archivo de popup.html este ejemplo es una página web pequeña que contiene un título, un botón Insertar imagen e instrucciones.

popup.html:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <style>
            body {
                width: 500px;
            }
            button {
                background-color: #336dab;
                border: none;
                color: white;
                padding: 15px 32px;
                text-align: center;
                font-size: 16px;
            }
        </style>
    </head>
    <body>
        <h1>Picture inserter using a content script</h1>
        <button id="sendmessageid">Insert picture</button>
        <script src="popup.js"></script>
        <p>Click the displayed image to remove it from the webpage.</p>
    </body>
</html>

JavaScript (popup.js) de la página emergente inicial, para enviar un mensaje al JavaScript insertado

/popup/popup.js Envía un mensaje al script de contenido (content.js) que se inserta temporalmente en la pestaña del explorador. Para ello, popup.js agrega un onclick evento al botón Insertar imagen de la página web emergente, que tiene el ID sendmessageid:

popup.js (porción):

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        ...
    };
}

En popup.js, chrome.tabs.query busca la pestaña del explorador actual y, a continuación chrome.tabs.sendMessage , envía un mensaje a esa pestaña. La muestra pasa en el identificador de la pestaña actual. El mensaje debe incluir la dirección URL de la imagen que se mostrará.

Debe enviar un identificador único para asignarlo a la imagen insertada, con el fin de volver a encontrar el elemento de imagen más tarde y eliminarlo. Para enviar un identificador único y asignarlo a la imagen insertada, se genera popup.js el identificador único y se pasa al script de contenido.

popup.js (completo):

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
            chrome.tabs.sendMessage(
                tabs[0].id,
                {
                    url: chrome.runtime.getURL("images/stars.jpeg"),
                    imageDivId: crypto.randomUUID(),
                    tabId: tabs[0].id
                },
                function(response) {
                    window.close();
                }
            );
        });
    };
}

El cliente de escucha del mensaje de script de contenido (content.js)

Este es el archivo que se inyecta en cada página de pestaña del content-scripts\content.js explorador. Este archivo figura en la content-scripts sección de manifest.json.

content.js (completo):

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
});

content.js registra un agente de escucha mediante el método de la API de chrome.runtime.onMessage.addListener extensión. Este agente de escucha espera el mensaje que se envía cuando popup.js se llama chrome.tabs.sendMessage

En content.js, el addListener método toma un único parámetro que es una función. El primer parámetro de esa función, request, contiene los detalles del mensaje que se está pasando.

En content.js, cuando el agente de escucha procesa un evento, se ejecuta la función de agente de escucha que se pasa addListener . El primer parámetro de la función de escucha pasada es un request objeto que tiene atributos asignados por sendMessage.

En popup.js, para la llamada al chrome.tabs.sendMessage método, los atributos del segundo parámetro para sendMessage son url, imageDivId, y tabId.

Esta es la función de escucha aislada que se pasa a addListener:

content.js (porción)

function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
}

Las primeras cinco líneas de la función de escucha agregan un img elemento inmediatamente debajo del body elemento en la pestaña del navegador.

La segunda línea de la función de escucha, img.id = request.imageDivId;, establece el identificador del img elemento en el imageDivId de la solicitud pasada.

En la función de escucha, la addEventListener llamada agrega una click función de escucha de eventos que cubre toda la imagen, lo que permite al usuario hacer clic en cualquier lugar de la imagen. Al hacer clic en la imagen insertada, la línea quita la imagen de la página web actual por la línea img.remove();, y el agente de escucha de eventos también se quita, especificando { once: true }.

Cómo stars.jpeg está disponible desde cualquier pestaña del explorador

Para que esté images/stars.jpeg disponible desde cualquier pestaña del explorador:

• popup.js (arriba) usa la chrome.runtime.getURL API.
• El manifiesto (a continuación) especifica que web_accessible_resources los tipos .jpeg coinciden con todas las direcciones URL.

El ejemplo inserta la imagen mediante el src atributo del img elemento en la página de contenido. La página de contenido se ejecuta en un subproceso único que no es el mismo que el subproceso que ejecuta la extensión. El archivo de imagen estática debe exponerse como un recurso web para que funcione correctamente.

Se agrega otra entrada en el manifest.json archivo para declarar que la imagen está disponible para todas las pestañas del explorador:

/manifest.json (porción):

"web_accessible_resources": [
    {
      "resources": ["images/*.jpeg"],
      "matches": ["<all_urls>"]
    }
  ]

El código del popup.js archivo envía un mensaje a la página de contenido que está incrustada en la página de pestaña activa actual.

Cómo se enumeran los recursos en el manifiesto (manifest.json)

El ejemplo crea e inserta la página de contenido que está incrustada en la página de pestaña activa actual. manifest.json Incluye el content-scripts y web_accessible_resources, de la siguiente manera:

/manifest.json (completo):

{
    "name": "Picture inserter using content script",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "description": "A browser extension that uses JavaScript to insert an image at the top of the current webpage.",
    "icons": {
        "16": "icons/extension-icon16x16.png",
        "32": "icons/extension-icon32x32.png",
        "48": "icons/extension-icon48x48.png",
        "128": "icons/extension-icon128x128.png"
    },
    "action": {
        "default_popup": "popup/popup.html"
    },
    "content_scripts": [
        {
            "matches": [
              "<all_urls>"
            ],
            "js": ["content-scripts/content.js"]
        }
    ],
    "web_accessible_resources": [
        {
            "resources": ["images/*.jpeg"],
            "matches": ["<all_urls>"]
        }
    ]
}

La sección del content_scripts manifiesto inserta JavaScript en todas las pestañas del explorador

En la content_scripts sección de claves del archivo de manifiesto, el matches atributo se establece en <all_urls>, lo que significa que .js los archivos (o .css) que se especifican en la sección de claves se inyectan en todas las páginas de pestañas del content_scripts navegador cuando se carga cada pestaña. Los tipos de archivos permitidos que se pueden inyectar son JavaScript (.js) y CSS (.css).

El manifiesto de este ejemplo especifica un único script de contenido, content-scripts/content.js.

Cada script de contenido se ejecuta en su propio subproceso, en un espacio aislado

Cada página de pestaña (y extensión) se ejecuta en su propio subproceso. Incluso si la pestaña del explorador contiene una página web que ejecuta código JavaScript, el content.js script que la extensión inserta en esa pestaña del explorador no tiene acceso a ese código JavaScript. El script de contenido insertado solo tiene acceso al DOM de la página web.

Pasos siguientes

Para desarrollar su propia extensión de Microsoft Edge, puede copiar y modificar el directorio del ejemplo, e instalar y probar la extensión resultante.

Vea también

• Ejemplo: Página web emergente del visor de imágenes
• Transferir localmente una extensión para instalarla y probarla localmente
• Ejemplos de extensiones de Microsoft Edge

GitHub:

• Repositorio MicrosoftEdge-Extensions .
  • /picture-inserter-content-script/ : código fuente de este ejemplo.