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 información.

Manifiesto

Estas son las claves compatibles con "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 cortan automáticamente. La clave "run_at" especifica cuándo se insertará cada archivo.

"css": Array
Opcional. Es un array de rutas de acceso de archivos CSS, inyectadas en el orden de este array, y antes de que se produzca cualquier construcción del DOM o renderización de página.
"js": array,
Opcional. Es un array de rutas de acceso a archivos JavaScript, insertadas en el orden en que aparecen en este array, después de la inserción de 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 cortan automáticamente.

URL de coincidencia

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

"matches": Array
Obligatorio. Especifica en qué patrones de URL se insertarán las secuencias de comandos de contenido. Consulta Patrones de coincidencia para conocer 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 conocer la sintaxis.
"include_globs": Array
Opcional. Se aplica después de las coincidencias para incluir solo las URLs que también coinciden con este glob. Tiene como objetivo emular la palabra clave @include Greasemonkey.
"exclude_globs": Array
Opcional. Se aplica después de las coincidencias para excluir las URLs que coinciden con este glob. Tiene el objetivo de emular la palabra clave @Exclude de Greasemonkey.

Las URLs 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 individual.

La secuencia de comandos del contenido se inserta en una página en los siguientes casos:

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

Ejemplos de coincidencias de URL y globs

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Mostrar coincidencias
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"]
    }
  ],
  ...
}
Mostrar coincidencias
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"]
    }
  ],
  ...
}
Mostrar coincidencias
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"]
    }
  ],
  ...
}
Mostrar coincidencias
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 se debe insertar la secuencia de comandos de contenido en todos los marcos que coincidan con los requisitos de la URL especificados. Si se establece en false, solo se insertará en el marco superior. Se puede usar junto con "match_about_blank" para inyectar en un marco about:blank.

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

Booleano "all_frames"
Opcional. El valor predeterminado es false, lo que significa que solo coincide el fotograma superior. Si se establece como verdadera, se insertará en todos los marcos, incluso si no es el marco superior de la pestaña. Cada marco se verifica de forma independiente para cumplir con los requisitos de URL y no se insertará en marcos secundarios si no se cumplen los requisitos de URL.
"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 coincide 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 insertar o no marcos creados por un origen coincidente, pero cuya URL u origen pueden no coincidir directamente con el patrón. Estos incluyen marcos con diferentes esquemas, como about:, data:, blob: y filesystem:.

Tiempo y entorno de ejecución

De manera predeterminada, las secuencias de comandos de contenido se insertan cuando el documento y todos los recursos terminan de cargarse, y se encuentran en un entorno de ejecución 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. Corresponde a 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. 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 único de la secuencia de comandos de contenido. Si eliges el mundo "MAIN", la secuencia de comandos compartirá el entorno de ejecución con el JavaScript de la página de alojamiento. Consulta Trabaja en mundos aislados para obtener más información.

Ejemplo

Consulta el instructivo Ejecutar en todas las páginas para compilar una extensión que inserte una secuencia de comandos de contenido en el manifiesto.