chrome.scripting

Descripción

Usa la API de chrome.scripting para ejecutar la secuencia de comandos en diferentes contextos.

Permisos

scripting

Disponibilidad

Chrome 88 y versiones posteriores MV3 y versiones posteriores

Manifiesto

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 los secuencias de comandos. Usa la clave "host_permissions" o el permiso "activeTab", que otorgan 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, si usas el espacio de nombres chrome.scripting, las extensiones pueden tomar decisiones durante el tiempo de ejecución.

Objetivos de inserción

Puedes usar el parámetro target para especificar un destino en el que se insertará JavaScript o CSS.

El único campo obligatorio es tabId. De forma predeterminada, una inyección se ejecutará 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 ejecutar en todos los fotogramas de la pestaña especificada, puedes establecer el valor booleano allFrames en 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 código en marcos específicos de una pestaña si especificas 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 tiempo de ejecución.

Archivos

Los archivos se especifican como cadenas que son rutas relativas al directorio raíz de la extensión. El siguiente código 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 tiempo 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 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 entorno 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"));

Cómo controlar 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 fotograma principal será el primer índice del array resultante. Todos los demás fotogramas se encuentran en un orden no determinístico.

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 devuelve ningún resultado.

Promesas

Si el valor resultante de la ejecución del script es una promesa, Chrome esperará a que se resuelva y devolverá 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

Anula el registro de todas las secuencias de comandos de contenido dinámico

El siguiente fragmento contiene una función que anula el registro de todos los secuencias de comandos de contenido dinámico que la extensión haya registrado anteriormente.

async function unregisterAllDynamicContentScripts() {   try {     const scripts = await chrome.scripting.getRegisteredContentScripts();     const scriptIds = scripts.map(script => script.id);     return chrome.scripting.unregisterContentScripts({ ids: 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 el ejemplo de secuencias de comandos del repositorio de ejemplos de extensiones de Chrome.

Tipos

ContentScriptFilter

Chrome 96 y versiones posteriores

Propiedades

  • ids

    string[] opcional

    Si se especifica, getRegisteredContentScripts solo devolverá las secuencias de comandos con un ID especificado en esta lista.

CSSInjection

Propiedades

  • css

    cadena opcional

    Es una cadena que contiene el código CSS que se insertará. Se debe especificar exactamente uno de files y css.

  • archivos

    string[] opcional

    Es la ruta de acceso de los archivos CSS que se insertarán, relativa al directorio raíz de la extensión. Se debe especificar exactamente uno de files y css.

  • origin

    StyleOrigin opcional

    Es el origen del estilo para la inserción. La configuración predeterminada es 'AUTHOR'.

  • objetivo

    InjectionTarget

    Son los detalles que especifican el destino en el que se insertará el CSS.

ExecutionWorld

Chrome 95 y versiones posteriores

Es el entorno de JavaScript en el que se ejecutará un script.

Enum

"ISOLATED"
Especifica el mundo aislado, que es el entorno de ejecución único para esta extensión.

"MAIN"
Especifica el mundo principal del DOM, que es el entorno de ejecución compartido con el JavaScript de la página host.

InjectionResult

Propiedades

  • documentId

    string

    Chrome 106 y versiones posteriores

    Es el documento asociado a la inserción.

  • frameId

    número

    Chrome 90 y versiones posteriores

    Es el marco asociado con la inserción.

  • resultado

    cualquier opción

    Es el resultado de la ejecución de la secuencia de comandos.

InjectionTarget

Propiedades

  • allFrames

    booleano opcional

    Indica si la secuencia de comandos se debe insertar en todos los fotogramas de la pestaña. La configuración predeterminada es "false". No debe ser verdadero si se especifica frameIds.

  • documentIds

    string[] opcional

    Chrome 106 y versiones posteriores

    Son los IDs de los documentIds específicos en los que se insertarán. No se debe establecer si se configuró frameIds.

  • frameIds

    number[] opcional

    Son los IDs de los fotogramas específicos en los que se insertará el contenido.

  • tabId

    número

    ID de la pestaña en la que se insertará el contenido.

RegisteredContentScript

Chrome 96 y versiones posteriores

Propiedades

  • allFrames

    booleano opcional

    Si se especifica como verdadero, se insertará en todos los marcos, incluso si el marco no es el superior de la pestaña. Cada marco se verifica de forma independiente para cumplir con los requisitos de la URL. No se insertará en los marcos secundarios si no se cumplen los requisitos de la URL. El valor predeterminado es falso, lo que significa que solo se hace coincidir el fotograma superior.

  • css

    string[] opcional

    Es la lista de archivos CSS que se insertarán en las páginas coincidentes. Se insertan en el orden en que aparecen en este array, antes de que se construya o muestre cualquier DOM para la página.

  • excludeMatches

    string[] opcional

    Excluye las páginas en las que, de lo contrario, se inyectaría este lenguaje de programación. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas cadenas.

  • id

    string

    Es el ID de la secuencia de comandos de contenido, especificado en la llamada a la API. No debe comenzar con un “_”, ya que se reserva como prefijo para los IDs de secuencias de comandos generados.

  • js

    string[] opcional

    Es la lista de archivos JavaScript que se insertarán en las páginas coincidentes. Se insertan en el orden en que aparecen en este array.

  • matchOriginAsFallback

    booleano opcional

    Chrome 119 y versiones posteriores

    Indica si la secuencia de comandos se puede insertar en marcos en los que la URL contiene un esquema no admitido, específicamente: about:, data:, blob: o filesystem:. 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 en el caso de las URLs de datos), el origen utilizado es el marco que creó el marco actual o el marco que inició la navegación a este marco. Ten en cuenta que es posible que este no sea el fotograma principal.

  • coincide con

    string[] opcional

    Especifica en qué páginas se insertará este script de contenido. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas cadenas. Se debe especificar para registerContentScripts.

  • persistAcrossSessions

    booleano opcional

    Especifica si este script de contenido persistirá en sesiones futuras. El valor predeterminado es verdadero.

  • runAt

    RunAt opcional

    Especifica cuándo se insertan los archivos JavaScript en la página web. El valor preferido y predeterminado es document_idle.

  • mundo

    ExecutionWorld opcional

    Chrome 102 y versiones posteriores

    Es el "mundo" de JavaScript en el que se ejecutará el script. La configuración predeterminada es ISOLATED.

ScriptInjection

Propiedades

  • args

    any[] opcional

    Chrome 92 y versiones posteriores

    Son los argumentos que se pasarán a la función proporcionada. Esto solo es válido si se especifica el parámetro func. Estos argumentos deben poder serializarse en JSON.

  • archivos

    string[] opcional

    Es la ruta de acceso de los archivos JS o CSS que se insertarán, relativa al directorio raíz de la extensión. Se debe especificar exactamente uno de los valores files o func.

  • injectImmediately

    booleano opcional

    Chrome 102 y versiones posteriores

    Indica si la inserción debe activarse en el objetivo lo antes posible. Ten en cuenta que esto no garantiza que la inserción se produzca antes de la carga de la página, ya que es posible que la página ya se haya cargado cuando la secuencia de comandos llegue al destino.

  • objetivo

    InjectionTarget

    Son los detalles que especifican el destino en el que se insertará la secuencia de comandos.

  • mundo

    ExecutionWorld opcional

    Chrome 95 y versiones posteriores

    Es el "mundo" de JavaScript en el que se ejecutará el script. La configuración predeterminada es ISOLATED.

  • func

    void optional

    Chrome 92 y versiones posteriores

    Es una función de JavaScript que se inyectará. Esta función se serializará y, luego, se deserializará para la inserción. Esto significa que se perderán todos los parámetros vinculados y el contexto de ejecución. Se debe especificar exactamente uno de los valores files o func.

    La función func se ve de la siguiente manera: 

    () => {...}

StyleOrigin

Es el origen de un cambio de estilo. Consulta orígenes de los estilos para obtener más información.

Enum

"AUTHOR"

"USER"

Métodos

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Inserta una secuencia de comandos en un contexto de destino. De forma predeterminada, la secuencia de comandos se ejecutará en document_idle o de inmediato si la página ya se cargó. Si se establece 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 se resuelva la promesa y devolverá el valor resultante.

Parámetros

  • Inyección

    ScriptInjection

    Son los detalles de la secuencia de comandos que se insertará.

Muestra

getRegisteredContentScripts()

Chrome 96 y versiones posteriores 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Devuelve todas las secuencias de comandos de contenido registradas de forma dinámica para esta extensión que coinciden con el filtro determinado.

Parámetros

  • filtrar

    ContentScriptFilter opcional

    Es un objeto para filtrar los secuencias de comandos registrados de forma dinámica de la extensión.

Muestra

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Inserta una hoja de diseño CSS en un contexto de destino. Si se especifican varios fotogramas, se ignoran las inserciones que no se realicen correctamente.

Parámetros

  • Inyección

    CSSInjection

    Son los detalles de los estilos que se insertarán.

Muestra

  • Promise<void>

    Chrome 90 y versiones posteriores

registerContentScripts()

Chrome 96 y versiones posteriores 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Registra una o más secuencias de comandos de contenido para esta extensión.

Parámetros

  • secuencias de comandos

    RegisteredContentScript[]

    Contiene una lista de secuencias de comandos que se registrarán. Si hay errores durante el análisis de la secuencia de comandos o la validación de archivos, o si los IDs especificados ya existen, no se registrará ninguna secuencia de comandos.

Muestra

  • Promise<void>

removeCSS()

Chrome 90 y versiones posteriores 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Quita una hoja de estilo CSS que esta extensión insertó previamente en un contexto de destino.

Parámetros

  • Inyección

    CSSInjection

    Son los detalles de los diseños que se quitarán. Ten en cuenta que las propiedades css, files y origin deben coincidir exactamente con la hoja de diseño insertada a través de insertCSS. Si intentas quitar una hoja de cálculo inexistente, no se realizará ninguna operación.

Muestra

  • Promise<void>

unregisterContentScripts()

Chrome 96 y versiones posteriores 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Anula el registro de las secuencias de comandos de contenido de esta extensión.

Parámetros

  • filtrar

    ContentScriptFilter opcional

    Si se especifica, solo anula el registro de las secuencias de comandos de contenido dinámico que coinciden con el filtro. De lo contrario, se anulará el registro de todas las secuencias de comandos de contenido dinámico de la extensión.

Muestra

  • Promise<void>

updateContentScripts()

Chrome 96 y versiones posteriores 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Actualiza uno o más secuencias de comandos de contenido para esta extensión.

Parámetros

  • secuencias de comandos

    RegisteredContentScript[]

    Contiene una lista de los scripts 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 IDs especificados no corresponden a una secuencia de comandos completamente registrada, no se actualizará ninguna secuencia de comandos.

Muestra

  • Promise<void>