Manifiesto: secuencias de comandos de contenido

La clave "content_scripts" especifica un archivo JavaScript o CSS cargado de forma estática que se usará cada vez que se abra una página que coincida con un patrón de URL determinado. Las extensiones también pueden insertar secuencias de comandos de contenido de manera programática. Consulta Cómo insertar secuencias de comandos para obtener más detalles.

Manifiesto

Estas son las claves admitidas para "content_scripts". Solo se requieren la clave "matches" y "js" o "css".

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

Archivos

Cada archivo debe contener una ruta de acceso relativa a un recurso en el directorio raíz de la extensión. Las barras iniciales (/) se recortan automáticamente. La clave "run_at" especifica cuándo se insertará cada archivo.

"css": Array
Opcional. Un array de rutas de acceso de archivos CSS, insertadas en el orden de este array y antes de que se produzca cualquier construcción del DOM o renderización de la página.
"js": Array
Opcional. Es un array de rutas de acceso de archivos JavaScript, que se insertan en el orden en que aparecen en este array, después de que se insertan los archivos CSS. Cada cadena del array debe ser una ruta de acceso relativa a un recurso en el directorio raíz de la extensión. Las barras iniciales ('/') se recortan automáticamente.

Coincidencia con URLs

Solo se requiere la propiedad "matches". Luego, puedes usar "exclude_matches", "include_globs" y "exclude_globs" para personalizar las URLs en las que se insertará el código. La clave "matches" activará una advertencia.

"matches": Array
Obligatorio. Especifica en qué patrones de URL se deben insertar las secuencias de comandos de contenido. Consulta Patrones de coincidencia para ver la sintaxis.
"exclude_matches": Array
Opcional. Excluye los patrones de URL en los que se insertarán las secuencias de comandos de contenido. Consulta Patrones de coincidencia para ver la sintaxis.
"include_globs": Array
Opcional. Se aplica después de las coincidencias para incluir solo las URLs que también coincidan con este glob. Está diseñada para emular la palabra clave @include de Greasemonkey.
"exclude_globs": Array
Opcional. Se aplica después de las coincidencias para excluir las URLs que coinciden con este glob. Está diseñada para emular la palabra clave @exclude de Greasemonkey.

Las URLs de glob son aquellas que contienen "comodines" * y signos de interrogación. El comodín * coincide con cualquier cadena de cualquier longitud, incluida una cadena vacía, mientras que el signo de interrogación ? coincide con cualquier carácter.

La secuencia de comandos de contenido se inserta en una página si se cumplen las siguientes condiciones:

  • Su URL coincide con cualquier patrón "matches" y "include_globs".
  • Y la URL no coincide con los patrones "exclude_matches" ni "exclude_globs".

Ejemplos de coincidencias de globs y URLs

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Combinaciones
https://www.example.com/foo/bar
https://the.example.com/foo/
No coincide
https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Combinaciones
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
No coincide
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Combinaciones
https://history.example.com
https://.example.com/music
No coincide
https://science.example.com
https://www.example.com/science

Ejemplo de personalización avanzada

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Combinaciones
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
No coincide
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Marcos

La clave "all_frames" especifica si la secuencia de comandos de contenido se debe insertar en todos los marcos que coincidan con los requisitos de URL especificados. Si se establece en false, solo se insertará en el marco superior. Se puede usar junto con "match_about_blank" para insertarlo en un marco de about:blank.

Para insertar en otros marcos, como data:, blob: y filesystem:, establece "match_origin_as_fallback" en true. Para obtener más detalles, consulta Cómo insertar en marcos relacionados.

"all_frames" Booleano
Opcional. El valor predeterminado es false, lo que significa que solo se hace coincidir el marco superior. Si se establece como verdadero, se insertará en todos los marcos, incluso si el marco no es el más alto de la pestaña. Cada marco se verifica de forma independiente para comprobar si cumple con los requisitos de las URLs. No se insertará en los marcos secundarios si no se cumplen estos requisitos.
"match_about_blank": Booleano
Opcional. La configuración predeterminada es false. Indica si la secuencia de comandos debe insertarse en un marco about:blank en el que la URL superior coincida con uno de los patrones declarados en "matches".
"match_origin_as_fallback": Booleano
Opcional. La configuración predeterminada es false. Indica si la secuencia de comandos debe insertarse en marcos creados por un origen coincidente, pero cuya URL u origen podrían no coincidir directamente con el patrón. Esto incluye marcos con diferentes esquemas, como about:, data:, blob: y filesystem:.

Tiempo de ejecución y entorno de ejecución

De forma predeterminada, las secuencias de comandos de contenido se insertan cuando el documento y todos los recursos terminan de cargarse, y se ejecutan en un entorno privado y aislado al que no pueden acceder la página ni otras extensiones. Puedes cambiar estos valores predeterminados en las siguientes claves:

"run_at" - document_start | document_end | document_idle
Opcional. Especifica cuándo se debe insertar la secuencia de comandos en la página. Se corresponde con los estados de carga de Document.readyState:
  • "document_start": El DOM aún se está cargando.
  • "document_end": Los recursos de la página aún se están cargando.
  • "document_idle": El DOM y los recursos terminaron de cargarse. Esta es la opción predeterminada.
"world" - ISOLATED | MAIN
Opcional. Es el mundo de JavaScript en el que se ejecutará una secuencia de comandos. El valor predeterminado es "ISOLATED", que es el entorno de ejecución exclusivo de la secuencia de comandos de contenido. Elegir el mundo "MAIN" significa que la secuencia de comandos compartirá el entorno de ejecución con el JavaScript de la página host. Consulta Trabaja en entornos aislados para obtener más información.

Ejemplo

Consulta el instructivo Ejecuta en cada página para compilar una extensión que inserte una secuencia de comandos de contenido en el manifiesto.