Descripción
Usa la API de chrome.scripting
para ejecutar la secuencia de comandos en diferentes contextos.
Permisos
scripting
Disponibilidad
Manifest
Para usar la API de chrome.scripting
, declara el permiso "scripting"
en el manifiesto, además de los permisos de host para las páginas en las que se insertarán secuencias de comandos. Usa la clave "host_permissions"
o el permiso "activeTab"
, que otorga permisos de host temporales. En el siguiente ejemplo, se usa el permiso activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Conceptos y uso
Puedes usar la API de chrome.scripting
para insertar JavaScript y CSS en sitios web. Esto es similar a lo que puedes hacer con las secuencias de comandos de contenido. Sin embargo, mediante el uso del espacio de nombres chrome.scripting
, las extensiones pueden tomar decisiones durante el tiempo de ejecución.
Objetivos de inyección
Puedes usar el parámetro target
para especificar un objetivo en el que se insertará JavaScript o CSS.
El único campo obligatorio es tabId
. De forma predeterminada, se ejecutará una inyección en el marco principal de la pestaña especificada.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Para que se ejecute en todos los marcos de la pestaña especificada, puedes configurar el booleano allFrames
como true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
También puedes insertar elementos en marcos específicos de una pestaña especificando IDs de marcos individuales. Para obtener más información sobre los IDs de fotogramas, consulta la API de chrome.webNavigation
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Código insertado
Las extensiones pueden especificar el código que se insertará a través de un archivo externo o una variable de entorno de ejecución.
Archivos
Los archivos se especifican como cadenas que son rutas de acceso relativas al directorio raíz de la extensión. Con el siguiente código, se insertará el archivo script.js
en el marco principal de la pestaña.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Funciones de entorno de ejecución
Cuando insertas JavaScript con scripting.executeScript()
, puedes especificar una función para que se ejecute en lugar de un archivo. Esta función debe ser una variable
de función disponible para el contexto de la extensión actual.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Para solucionar este problema, usa la propiedad args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Cadenas de tiempo de ejecución
Si insertas CSS en una página, también puedes especificar una cadena para usar en la propiedad css
. Esta opción solo está disponible para scripting.insertCSS()
. No puedes ejecutar una cadena con scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Controla los resultados
Los resultados de la ejecución de JavaScript se pasan a la extensión. Se incluye un solo resultado por fotograma. Se garantiza que el marco principal sea el primer índice del array resultante; todos los demás marcos están en un orden no determinista.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
no muestra ningún resultado.
Promesas
Si el valor resultante de la ejecución de la secuencia de comandos es una promesa, Chrome esperará a que esta se establezca y muestre el valor resultante.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Ejemplos
Cancelar el registro de todas las secuencias de comandos de contenido dinámico
El siguiente fragmento contiene una función que cancela el registro de todas las secuencias de comandos de contenido dinámico que la extensión registró anteriormente.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Para probar la API de chrome.scripting
, instala la muestra de secuencia de comandos del repositorio de muestras de extensión de Chrome.
Tipos
ContentScriptFilter
Propiedades
-
ids
string[] opcional
Si se especifica,
getRegisteredContentScripts
solo mostrará secuencias de comandos con un ID especificado en esta lista.
CSSInjection
Propiedades
-
css
cadena opcional
Es una cadena que contiene la CSS que se insertará. Se debe especificar solamente uno de los valores
files
ocss
. -
archivos
string[] opcional
Es la ruta de acceso de los archivos CSS que se insertarán, en relación con el directorio raíz de la extensión. Se debe especificar solamente uno de los valores
files
ocss
. -
origin
StyleOrigin opcional
El origen del estilo de la inserción. La configuración predeterminada es
'AUTHOR'
. -
objetivo
Detalles que especifican el destino en el que se insertará el CSS.
ExecutionWorld
El mundo de JavaScript en el que se ejecuta una secuencia de comandos.
Enum
“ISOLATED”
Especifica el mundo aislado, que es el entorno de ejecución exclusivo de esta extensión.
"MAIN"
Especifica el mundo principal del DOM, que es el entorno de ejecución compartido con el código JavaScript de la página de host.
InjectionResult
Propiedades
-
documentId
cadena
Chrome 106 y versiones posterioresEl documento asociado con la inserción.
-
frameId
número
Chrome 90 y versiones posterioresMarco asociado con la inyección.
-
resultado
cualquier opcional
El resultado de la ejecución de la secuencia de comandos.
InjectionTarget
Propiedades
-
allFrames
booleano opcional
Indica si la secuencia de comandos debe insertarse en todos los marcos de la pestaña. La configuración predeterminada es "false". Esto no debe ser verdadero si se especifica
frameIds
. -
documentIds
string[] opcional
Chrome 106 y versiones posterioresLos ID de documentIds específicos para insertar. No se debe establecer si se configura
frameIds
. -
frameIds
number[] opcional
Los ID de marcos específicos en los que se insertará.
-
tabId
número
El ID de la pestaña en la que se insertará.
RegisteredContentScript
Propiedades
-
allFrames
booleano opcional
Si se especifica como verdadero, se insertará en todos los fotogramas, incluso si no es el que se encuentra en la parte superior de la pestaña. Cada marco se comprueba de forma independiente para los requisitos de URL; no se insertará en marcos secundarios si no se cumplen los requisitos de URL. El valor predeterminado es falso, lo que significa que solo coincide el marco superior.
-
css
string[] opcional
La lista de archivos CSS que se insertarán en las páginas coincidentes. Estos se insertan en el orden en que aparecen en este array, antes de que se construya un DOM o se muestre para la página.
-
excludeMatches
string[] opcional
Excluye las páginas en las que se insertaría esta secuencia de comandos de contenido. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas strings.
-
id
cadena
El ID de la secuencia de comandos del contenido, que se especifica en la llamada a la API. No debe comenzar con “_”, ya que está reservado como prefijo para los IDs de secuencias de comandos que se generan.
-
js
string[] opcional
La lista de archivos JavaScript que se insertarán en las páginas coincidentes. Estos se insertan en el orden en que aparecen en este array.
-
matchOriginAsFallback
booleano opcional
Chrome 119 y versiones posterioresIndica si la secuencia de comandos se puede insertar en marcos en los que la URL contiene un esquema no compatible; específicamente: about:, data:, BLOB: o Filestore. En estos casos, se verifica el origen de la URL para determinar si se debe insertar la secuencia de comandos. Si el origen es
null
(como sucede con los datos: URLs), el origen utilizado es el marco que creó el marco actual o el que inició la navegación a este marco. Ten en cuenta que puede que este no sea el marco superior. -
coincide con
string[] opcional
Especifica en qué páginas se insertará esta secuencia de comandos de contenido. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas strings. Se debe especificar para
registerContentScripts
. -
persistAcrossSessions
booleano opcional
Especifica si esta secuencia de comandos de contenido se conservará en sesiones futuras. El valor predeterminado es verdadero.
-
runAt
RunAt opcional
Especifica cuándo se insertan archivos JavaScript en la página web. El valor preferido y predeterminado es
document_idle
. -
internacionales
ExecutionWorld opcional
Chrome 102 y versiones posterioresEl “mundo” de JavaScript en el que se ejecutará la secuencia de comandos. La configuración predeterminada es
ISOLATED
.
ScriptInjection
Propiedades
-
args
any[] opcional
Chrome 92 y versiones posterioresLos argumentos que se pasarán a la función proporcionada. Solo es válido si se especifica el parámetro
func
. Estos argumentos se deben poder serializar con JSON. -
archivos
string[] opcional
Es la ruta de acceso de los archivos JS o CSS que se insertarán, en relación con el directorio raíz de la extensión. Se debe especificar solamente uno de los valores
files
ofunc
. -
injectImmediately
booleano opcional
Chrome 102 y versiones posterioresSi la inyección se debe activar en el destino lo antes posible. Ten en cuenta que esto no garantiza que la inyección ocurra antes de que se cargue la página, dado que es posible que esta ya se haya cargado cuando la secuencia de comandos llegue al destino.
-
objetivo
Detalles que especifican el destino en el que se insertará la secuencia de comandos.
-
internacionales
ExecutionWorld opcional
Chrome 95 y versiones posterioresEl “mundo” de JavaScript en el que se ejecutará la secuencia de comandos. La configuración predeterminada es
ISOLATED
. -
func
void opcional
Chrome 92 y versiones posterioresUna función de JavaScript para insertar Esta función se serializará y, luego, se deserializará para la inyección. Esto significa que se perderán los parámetros vinculados y el contexto de ejecución. Se debe especificar solamente uno de los valores
files
ofunc
.La función
func
se ve de la siguiente manera:() => {...}
StyleOrigin
El origen de un cambio de diseño. Consulta los orígenes del diseño para obtener más información.
Enum
"AUTHOR"
Métodos
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Inyecta una secuencia de comandos en un contexto objetivo. De forma predeterminada, la secuencia de comandos se ejecutará en document_idle
o de inmediato si la página ya se cargó. Si se configura la propiedad injectImmediately
, la secuencia de comandos se insertará sin esperar, incluso si la página no terminó de cargarse. Si la secuencia de comandos se evalúa como una promesa, el navegador esperará a que esta se establezca y muestre el valor resultante.
Parámetros
-
Inyección
Los detalles de la secuencia de comandos que se insertará.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(results: InjectionResult[]) => void
-
resultados
-
Devuelve
-
Promise<InjectionResult[]>
Chrome 90 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Muestra todas las secuencias de comandos de contenido registradas de forma dinámica para esta extensión que coinciden con el filtro determinado.
Parámetros
-
filter
ContentScriptFilter opcional
Un objeto para filtrar las secuencias de comandos registradas de forma dinámica de la extensión.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(scripts: RegisteredContentScript[]) => void
-
secuencias de comandos
-
Devuelve
-
Promise<RegisteredContentScript[]>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Inserta una hoja de estilo CSS en un contexto de destino. Si se especifican varios fotogramas, se ignoran las inyecciones fallidas.
Parámetros
-
Inyección
Los detalles de los estilos que se insertarán.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 90 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Registra una o más secuencias de comandos del contenido para esta extensión.
Parámetros
-
secuencias de comandos
Contiene una lista de secuencias de comandos que se registrarán. Si se producen errores durante el análisis de la secuencia de comandos o la validación de archivos, o si los ID especificados ya existen, no se registra ninguna secuencia de comandos.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Quita una hoja de estilo CSS que esta extensión insertó anteriormente desde un contexto de destino.
Parámetros
-
Inyección
Los detalles de los diseños que se quitarán. Ten en cuenta que las propiedades
css
,files
yorigin
deben coincidir exactamente con la hoja de estilo insertada a través deinsertCSS
. Intentar quitar una hoja de estilo que no existe no es una operación. -
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Cancela el registro de las secuencias de comandos del contenido para esta extensión.
Parámetros
-
filter
ContentScriptFilter opcional
Si se especifica, solo se cancelará el registro de las secuencias de comandos de contenido dinámico que coincidan con el filtro. De lo contrario, no se registrarán todas las secuencias de comandos del contenido dinámico de la extensión.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Actualiza una o más secuencias de comandos del contenido para esta extensión.
Parámetros
-
secuencias de comandos
Contiene una lista de secuencias de comandos que se actualizarán. Una propiedad solo se actualiza para la secuencia de comandos existente si se especifica en este objeto. Si hay errores durante el análisis de la secuencia de comandos o la validación de archivos, o si los ID especificados no corresponden a una secuencia de comandos completamente registrada, no se actualizará ninguna secuencia de comandos.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.