chrome.userScripts

Descripción

Usa la API de userScripts para ejecutar secuencias de comandos de usuario en el contexto de secuencias de comandos de usuario.

Permisos

userScripts

Para usar la API de chrome.userScripts, agrega el permiso "userScripts" a tu manifest.json y "host_permissions" para los sitios en los que desees ejecutar secuencias de comandos.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Disponibilidad

Chrome 120 y versiones posteriores MV3 y versiones posteriores

Conceptos y uso

Una secuencia de comandos del usuario es un fragmento de código que se inserta en una página web para modificar su apariencia o comportamiento. Los usuarios crean las secuencias de comandos, o bien las descargan de un repositorio o una extensión de secuencias de comandos del usuario.

Modo de desarrollador para usuarios de extensiones

Como desarrollador de extensiones, ya habilitaste el modo de desarrollador en la instalación de Chrome. En el caso de las extensiones de secuencias de comandos del usuario, los usuarios también deberán habilitar el modo de desarrollador. Estas son las instrucciones que puedes copiar y pegar en tu propia documentación.

  1. Para ir a la página Extensiones, ingresa chrome://extensions en una pestaña nueva. (Por su diseño, las URLs de chrome:// no se pueden vincular).

  2. Para habilitar el modo de desarrollador, haz clic en el interruptor junto a Modo de desarrollador.

    Página Extensiones

    Página Extensiones (chrome://extensions)

Para determinar si el modo de desarrollador está habilitado, verifica si chrome.userScripts arroja un error. Por ejemplo:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Trabajar en mundos aislados

Tanto las secuencias de comandos de usuario como las del contenido pueden ejecutarse en un mundo aislado o en el mundo principal. Un mundo aislado es un entorno de ejecución al que no pueden acceder una página host ni otras extensiones. Esto permite que una secuencia de comandos de usuario cambie su entorno de JavaScript sin afectar la página de host ni las secuencias de comandos de usuario y del contenido de otras extensiones. Por el contrario, las secuencias de comandos del usuario (y las del contenido) no son visibles para la página de alojamiento o para el usuario y las secuencias de comandos del contenido de otras extensiones. Las páginas de alojamiento y otras extensiones pueden acceder a las secuencias de comandos que se ejecutan en el mundo principal, y las páginas host y otras extensiones pueden verlas. Para seleccionar el mundo, pasa "USER_SCRIPT" o "MAIN" cuando llames a userScripts.register().

Si deseas configurar una política de seguridad de contenido para el mundo USER_SCRIPT, llama a userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Mensajería

Al igual que las secuencias de comandos de contenido y los documentos fuera de pantalla, las secuencias de comandos del usuario se comunican con otras partes de una extensión mediante mensajes (lo que significa que pueden llamar a runtime.sendMessage() y runtime.connect() como lo haría cualquier otra parte de una extensión). Sin embargo, se reciben mediante controladores de eventos dedicados (es decir, no usan onMessage ni onConnect). Estos controladores se llaman runtime.onUserScriptMessage y runtime.onUserScriptConnect. Los controladores dedicados facilitan la identificación de mensajes de las secuencias de comandos de usuario, que son un contexto menos confiable.

Antes de enviar un mensaje, debes llamar a configureWorld() con el argumento messaging establecido en true. Ten en cuenta que los argumentos csp y messaging se pueden pasar al mismo tiempo.

chrome.userScripts.configureWorld({
  messaging: true
});

Actualizaciones de extensiones

Las secuencias de comandos del usuario se borran cuando se actualiza una extensión. Para volver a agregarlas, ejecuta el código en el controlador de eventos runtime.onInstalled del service worker de extensiones. Responde únicamente al motivo "update" que se pasó a la devolución de llamada del evento.

Ejemplo

Este ejemplo es de la muestra de userScript en nuestro repositorio de muestras.

Registra una secuencia de comandos

En el siguiente ejemplo, se muestra una llamada básica a register(). El primer argumento es un array de objetos que define las secuencias de comandos que se registrarán. Hay más opciones de las que se muestran aquí.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Tipos

ExecutionWorld

El mundo de JavaScript en el que se ejecuta una secuencia de comandos de usuario.

Enum

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

"USER_SCRIPT"
Especifica el entorno de ejecución específico de las secuencias de comandos del usuario y que está exento de la CSP de la página.

RegisteredUserScript

Propiedades

  • allFrames

    booleano opcional

    Si es verdadero, se inyectará en todos los fotogramas, incluso si no es el marco 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.

  • excludeGlobs

    string[] opcional

    Especifica los patrones de comodines para las páginas en las que NO se insertará esta secuencia de comandos del usuario.

  • excludeMatches

    string[] opcional

    Excluye las páginas en las que se insertaría esta secuencia de comandos de usuario. 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 usuario especificada en la llamada a la API. Esta propiedad no debe comenzar con “_”, ya que está reservada como prefijo para los IDs de secuencias de comandos generados.

  • includeGlobs

    string[] opcional

    Especifica los patrones de comodín para las páginas en las que se insertará esta secuencia de comandos del usuario.

  • La lista de objetos ScriptSource que definen las fuentes de las secuencias de comandos que se insertarán en las páginas coincidentes.

  • coincide con

    string[] opcional

    Especifica en qué páginas se insertará esta secuencia de comandos del usuario. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas strings. Se debe especificar esta propiedad para ${ref:register}.

  • 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

    El entorno de ejecución de JavaScript en el que se ejecutará la secuencia de comandos. El valor predeterminado es `USER_SCRIPT`.

ScriptSource

Propiedades

  • código

    cadena opcional

    Es una cadena que contiene el código JavaScript que se insertará. Se debe especificar solamente uno de los valores file o code.

  • en el archivo.

    cadena opcional

    Es la ruta de acceso del archivo JavaScript que se insertará en relación con el directorio raíz de la extensión. Se debe especificar solamente uno de los valores file o code.

UserScriptFilter

Propiedades

  • ids

    string[] opcional

    getScripts solo muestra secuencias de comandos con los IDs especificados en esta lista.

WorldProperties

Propiedades

  • CSS

    cadena opcional

    Especifica el csp del mundo. El valor predeterminado es el csp de mundo `ISOLATED`.

  • mensajería

    booleano opcional

    Especifica si se exponen las APIs de mensajería. El valor predeterminado es false.

Métodos

configureWorld()

Promesa 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configura el entorno de ejecución `USER_SCRIPT`.

Parámetros

  • properties

    WorldProperties

    Contiene la configuración del mundo de la secuencia de comandos del usuario.

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

getScripts()

Promesa 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Muestra todas las secuencias de comandos de usuario registradas de forma dinámica para esta extensión.

Parámetros

  • filter

    UserScriptFilter opcional

    Si se especifica, este método solo muestra las secuencias de comandos de usuario que coinciden.

  • callback

    Función opcional

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

    (scripts: RegisteredUserScript[])=>void

Devuelve

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

register()

Promesa 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Parámetros

  • secuencias de comandos

    RegisteredUserScript

    Contiene una lista de las secuencias de comandos de usuario que se registrará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.

unregister()

Promesa 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Cancela el registro de todas las secuencias de comandos de usuario registradas de forma dinámica para esta extensión.

Parámetros

  • filter

    UserScriptFilter opcional

    Si se especifica, este método solo cancela el registro de las secuencias de comandos de usuario que coincidan con él.

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

update()

Promesa 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Actualiza una o más secuencias de comandos de usuario para esta extensión.

Parámetros

  • secuencias de comandos

    RegisteredUserScript

    Contiene una lista de secuencias de comandos de usuario 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.