Manifiesto: secuencias de comandos de contenido

La clave "content_scripts" especifica un archivo JavaScript o CSS cargado de forma estática que se utilizará cada vez que se abra una página que coincida con un determinado patrón de URL. 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.

Manifest

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

"css": array
Opcional. Es un array de rutas de acceso a archivos CSS, que se inserta 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. Un array de rutas de acceso a archivos JavaScript, insertados en el orden en que aparecen en este array, después de insertar los archivos CSS. Cada string 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.

Coincidir con las URLs

Solo se requiere la propiedad "matches". Luego, puedes usar "exclude_matches", "include_globs" y "exclude_globs" para personalizar en qué URLs insertar código. La clave "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. Su objetivo es 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. 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.

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

  • Su URL coincide con cualquier patrón "matches" y "include_globs".
  • Además, 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

Frames

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

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

Booleano "all_frames"
Opcional. El valor predeterminado es false, lo que significa que solo coincide el marco superior. Si se establece como verdadera, se insertará en todos los fotogramas, incluso si este no es el superior de la pestaña. Cada marco se verifica de forma independiente para los requisitos de URL; 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 insertarse en marcos creados por un origen coincidente, pero cuya URL u origen no coinciden directamente con el patrón. Entre ellos, se incluyen 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 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. 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": Terminaron de cargarse el DOM y los recursos. Esta es la opción predeterminada.
"world": ISOLATED | MAIN
Opcional. El mundo de JavaScript en el que se ejecuta una secuencia de comandos. El valor predeterminado es "ISOLATED", que es el entorno de ejecución único de la secuencia de comandos del contenido. Si eliges el mundo "MAIN", la secuencia de comandos compartirá el entorno de ejecución con el código JavaScript de la página de host. Consulta Trabaja en mundos aislados para obtener más información.

Ejemplo

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