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"]
}
],
...
}
https://www.example.com/foo/bar https://the.example.com/foo/
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"]
}
],
...
}
https://www.example.com/arts/index.html https://www.example.com/jobs/index.html
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"]
}
],
...
}
https://history.example.com https://.example.com/music
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"]
}
],
...
}
https://www.example.com/arts/index.html https://.example.com/jobs/index.html
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 marcoabout: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, comoabout:
,data:
,blob:
yfilesystem:
.
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.