chrome.scripting

Descripción

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

Permisos

scripting

Disponibilidad

Chrome 88 y versiones posteriores MV3+ .

Manifiesto

Para usar la API de chrome.scripting, declara el permiso "scripting" en el manifiesto y los permisos de host para que las páginas inserten 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 el contenido secuencias de comandos. Sin embargo, cuando usas el espacio de nombres chrome.scripting, puede tomar decisiones en el tiempo de ejecución.

Objetivos de inyección

Puedes usar el parámetro target para especificar un destino para insertar JavaScript. CSS.

El único campo obligatorio es tabId. De forma predeterminada, se ejecutará una inyección 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 establecer el valor booleano allFrames. a 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 en marcos específicos de una pestaña especificando los fotogramas individuales de sus IDs. Para obtener más información sobre los IDs de fotograma, consulta la chrome.webNavigation API.

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á con un archivo externo o un archivo entorno de ejecución.

Archivos

Los archivos se especifican como cadenas que son rutas de acceso relativas a la raíz de la extensión . Con el siguiente código, se insertará el archivo script.js en el archivo principal marco 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 un función que se ejecutará en lugar de un archivo. Esta función debe ser una función según el contexto actual de la extensión.

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 la cadena que se usará en la css. Esta opción solo está disponible para scripting.insertCSS(). tú no puede 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. Un solo resultado se incluye por fotograma. Se garantiza que el marco principal sea el primer índice del array resultante; todos los demás fotogramas 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á. para que la promesa se liquide y devuelva 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 todo el contenido dinámico secuencias de comandos 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, haz lo siguiente: instala el ejemplo de secuencias de comandos de las muestras de extensiones de Chrome. en un repositorio de confianza.

Tipos

ContentScriptFilter

Chrome 96 y versiones posteriores

Propiedades

  • ids

    string[] opcional

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

CSSInjection

Propiedades

  • css

    string opcional

    Es una cadena que contiene la CSS que se insertará. Se debe especificar exactamente uno de files o css.

  • 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 exactamente uno de files o css.

  • origin

    StyleOrigin opcional

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

  • objetivo

    InjectionTarget

    Detalles que especifican el destino en el que se insertará el CSS.

ExecutionWorld

Chrome 95 y versiones posteriores

El mundo de JavaScript en el que se ejecutará una secuencia de comandos.

Enum

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

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

InjectionResult

Propiedades

  • documentId

    string

    Chrome 106 y versiones posteriores

    El documento asociado con la inserción.

  • frameId

    número

    Chrome 90 y versiones posteriores

    La trama asociada con la inyección.

  • resultado

    Cualquier opcional

    El resultado de la ejecución de la secuencia de comandos.

InjectionTarget

Propiedades

  • allFrames

    booleano opcional

    Si la secuencia de comandos debe insertarse en todos los marcos dentro 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 posteriores

    Los ID de documentIds específicos en los que se insertará. No se debe establecer si se configura frameIds.

  • frameIds

    number[] opcional

    Los ID de los marcos específicos en los que se va a insertar.

  • tabId

    número

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

RegisteredContentScript

Chrome 96 y versiones posteriores

Propiedades

  • allFrames

    booleano opcional

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

  • css

    string[] opcional

    La lista de archivos CSS que se insertarán en páginas coincidentes. Estos se insertan en el orden en que aparecen en la matriz, antes de que se construya o se muestre cualquier DOM 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 cadenas.

  • id

    string

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

  • 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 posteriores

    Indica si la secuencia de comandos se puede insertar en marcos en los que la URL contiene un esquema no compatible. específicamente: acerca de:, datos:, BLOB: o sistema de archivos:. 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 las URLs de datos), 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 este puede no ser el marco principal.

  • 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 cadenas. Se debe especificar para registerContentScripts.

  • persistAcrossSessions

    booleano opcional

    Especifica si esta secuencia de comandos 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

    El “mundo” de JavaScript para ejecutar la secuencia de comandos. La configuración predeterminada es ISOLATED.

ScriptInjection

Propiedades

  • args

    cualquiera[] opcional

    Chrome 92 y versiones posteriores

    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 ser serializables en JSON.

  • archivos

    string[] opcional

    La ruta 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 exactamente uno de files o func.

  • injectImmediately

    booleano opcional

    Chrome 102 y versiones posteriores

    Indica si la inyección se debe activar en el destino lo antes posible. Ten en cuenta que esto no garantiza que la inyección ocurrirá antes de que se cargue la página, dado que es posible que la página ya se haya cargado cuando la secuencia de comandos alcance el objetivo.

  • objetivo

    InjectionTarget

    Detalles que especifican el destino en el que se insertará la secuencia de comandos.

  • mundo

    ExecutionWorld opcional

    Chrome 95 y versiones posteriores

    El “mundo” de JavaScript para ejecutar la secuencia de comandos. La configuración predeterminada es ISOLATED.

  • func

    void optional

    Chrome 92 y versiones posteriores

    Una 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 exactamente uno de files o func.

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

    () => {...}

StyleOrigin

El origen de un cambio de estilo. Para obtener más información, consulta los orígenes de los estilos.

Enum

“AUTOR”

"USUARIO"

Métodos

executeScript()

Promesa 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Inserta 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 establece la propiedad injectImmediately, la secuencia de comandos 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 la promesa se establezca y mostrará el valor resultante.

Parámetros

  • Inyección

    ScriptInjection

    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

Muestra

  • Promise<InjectionResult[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getRegisteredContentScripts()

Promesa Chrome 96 y versiones posteriores .
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 especificado.

Parámetros

Muestra

  • Promise<RegisteredContentScript[]>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

insertCSS()

Promesa 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Inserta una hoja de estilo CSS en el contexto de destino. Si se especifican varios fotogramas, se ignoran las inyecciones fallidas.

Parámetros

  • Inyección

    CSSInjection

    Los detalles de los estilos que se insertarán.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

registerContentScripts()

Promesa Chrome 96 y versiones posteriores .
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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 para registrar. Si se producen errores durante el análisis de secuencias de comandos o la validación del archivo, o si los IDs 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

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

removeCSS()

Promesa Chrome 90 y versiones posteriores .
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parámetros

  • Inyección

    CSSInjection

    Los detalles de los estilos que se quitarán. Ten en cuenta que las propiedades css, files y origin deben coincidir exactamente con la hoja de estilo insertada mediante insertCSS. Intentar quitar una hoja de estilo que no existe es una no-op.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

unregisterContentScripts()

Promesa Chrome 96 y versiones posteriores .
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Parámetros

  • filter

    ContentScriptFilter opcional

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

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

updateContentScripts()

Promesa Chrome 96 y versiones posteriores .
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Actualiza 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 deben actualizar. Una propiedad solo se actualiza para la secuencia de comandos existente si se especifica en este objeto. No se actualizará ninguna secuencia de comandos si se producen errores durante el análisis de secuencias de comandos o la validación de archivos, o si los ID especificados no corresponden a una secuencia de comandos completamente registrada.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.