browser.userScripts

Descripción

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

Permisos

userScripts

Para usar la API de User Scripts, browser.userScripts, agrega el permiso "userScripts" a tu manifest.json y "host_permissions" para los sitios en los que quieras 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 browser.* desde Chrome 148 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. A diferencia de otras funciones de extensión, como las secuencias de comandos de contenido y la API de browser.scripting, la API de secuencias de comandos del usuario te permite ejecutar código arbitrario. Esta API es obligatoria para las extensiones que ejecutan secuencias de comandos proporcionadas por el usuario que no se pueden enviar como parte del paquete de la extensión.

Habilita el uso de la API de userScripts

Después de que tu extensión reciba el permiso para usar la API de userScripts, los usuarios deberán habilitar un botón de activación específico para permitir que tu extensión use la API. El parámetro de activación específico requerido y el comportamiento de la API cuando está inhabilitada varían según la versión de Chrome.

Usa la siguiente verificación para determinar qué botón de activación debe habilitar el usuario, por ejemplo, durante la integración de un usuario nuevo:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

En las siguientes secciones, se describen los diferentes parámetros de configuración y cómo habilitarlos.

Versiones de Chrome anteriores a la 138 (botón de activación del modo de desarrollador)

Como desarrollador de extensiones, ya tienes habilitado el modo de desarrollador en tu instalación de Chrome. Tus usuarios también deben habilitar el modo de desarrollador.

Puedes copiar y pegar las siguientes instrucciones en la documentación de tu extensión para tus usuarios

  1. Ingresa chrome://extensions en una pestaña nueva para ir a la página Extensiones. (Por 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.

    La página de extensiones de Chrome con el botón de activación del modo de desarrollador destacado

    Página de extensiones (chrome://extensions)

Chrome 138 y versiones posteriores (botón de activación Permitir secuencias de comandos del usuario)

El botón de activación Permitir secuencias de comandos de usuario se encuentra en la página de detalles de cada extensión (por ejemplo, chrome://extensions/?id=YOUR_EXTENSION_ID).

Puedes copiar y pegar las siguientes instrucciones en la documentación de tu extensión para los usuarios:

  1. Ingresa chrome://extensions en una pestaña nueva para ir a la página Extensiones. (Por diseño, las URLs de chrome:// no se pueden vincular).
  2. Haz clic en el botón "Detalles" de la tarjeta de la extensión para ver información detallada sobre ella.
  3. Haz clic en el interruptor junto a Permitir secuencias de comandos del usuario.
El botón de activación Permitir secuencias de comandos del usuario en la página de detalles de la extensión
Botón de activación Permitir secuencias de comandos del usuario (chrome://extensions/?id=abc...)

Verifica la disponibilidad de la API

Te recomendamos que realices la siguiente verificación para determinar si la API de userScripts está habilitada, ya que funciona en todas las versiones de Chrome. Esta verificación intenta llamar a un método browser.userScripts() que siempre debería tener éxito cuando la API está disponible. Si esta llamada arroja un error, la API no está disponible:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Trabaja en mundos aislados

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

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

browser.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 de usuario se comunican con otras partes de una extensión a través de la mensajería (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 con 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 los 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.

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

Actualizaciones de extensiones

Las secuencias de comandos del usuario se borran cuando se actualiza una extensión. Puedes volver a agregarlos ejecutando código en el controlador de eventos runtime.onInstalled en el service worker de la extensión. Responde solo al motivo "update" que se pasa a la devolución de llamada del evento.

Ejemplo

Este ejemplo proviene 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 definen las secuencias de comandos que se registrarán. Hay más opciones de las que se muestran aquí.

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

Tipos

ExecutionWorld

Es el mundo de JavaScript en el que se ejecutará una secuencia de comandos del usuario.

Enum

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

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

InjectionResult

Chrome 135 y versiones posteriores browser.* desde Chrome 148

Propiedades

  • documentId

    string

    Es el documento asociado con la inserción.

  • error

    string opcional

    El error, si lo hay. error y result son mutuamente excluyentes.

  • frameId

    número

    Es el marco asociado con la inserción.

  • resultado

    any optional

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

InjectionTarget

Chrome 135 y versiones posteriores browser.* desde Chrome 148

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

    Son los IDs de documentIds específicos en los que se insertarán los datos. No se debe configurar si se establece frameIds.

  • frameIds

    number[] opcional

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

  • tabId

    número

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

RegisteredUserScript

Propiedades

  • allFrames

    booleano opcional

    Si es verdadero, se insertará en todos los marcos, incluso si el marco no es el que está más arriba en la pestaña. Cada marco se verifica de forma independiente para comprobar si cumple con los requisitos de las URLs. No se insertará en los marcos secundarios si no se cumplen estos requisitos. El valor predeterminado es falso, lo que significa que solo se hace coincidir el marco superior.

  • excludeGlobs

    string[] opcional

    Especifica patrones de comodín 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, de lo contrario, se insertaría esta secuencia de comandos del usuario. 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 usuario especificada en la llamada a la API. Esta propiedad no debe comenzar con un "_", ya que está reservado como prefijo para los IDs de secuencias de comandos generados.

  • includeGlobs

    string[] opcional

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

  • js

    ScriptSource[] opcional

    Es la lista de objetos ScriptSource que definen las fuentes de las secuencias de comandos que se insertarán en las páginas coincidentes. Esta propiedad se debe especificar para ${ref:register} y, cuando se especifica, debe ser un array no vacío.

  • 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 cadenas. Esta propiedad se debe especificar para ${ref:register}.

  • 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

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

  • worldId

    string opcional

    Chrome 133 y versiones posteriores browser.* desde Chrome 148

    Especifica el ID del entorno de la secuencia de comandos del usuario en el que se ejecutará. Si se omite, la secuencia de comandos se ejecutará en el entorno de secuencias de comandos de usuario predeterminado. Solo es válido si se omite world o si es USER_SCRIPT. Los valores con guiones bajos iniciales (_) están reservados.

ScriptSource

Propiedades

  • código

    string opcional

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

  • archivo

    string opcional

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

UserScriptFilter

Propiedades

  • ids

    string[] opcional

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

UserScriptInjection

Chrome 135 y versiones posteriores browser.* desde Chrome 148

Propiedades

  • injectImmediately

    booleano opcional

    Indica si la inserción se debe activar en el destino 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.

  • Es la lista de objetos ScriptSource que definen las fuentes de las secuencias de comandos que se insertarán en el destino.

  • objetivo

    InjectionTarget

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

  • mundo

    ExecutionWorld opcional

    Es el "mundo" de JavaScript en el que se ejecutará la secuencia de comandos. El valor predeterminado es USER_SCRIPT.

  • worldId

    string opcional

    Especifica el ID del entorno de la secuencia de comandos del usuario en el que se ejecutará. Si se omite, la secuencia de comandos se ejecutará en el entorno de secuencias de comandos de usuario predeterminado. Solo es válido si se omite world o si es USER_SCRIPT. Los valores con guiones bajos iniciales (_) están reservados.

WorldProperties

Propiedades

  • csp

    string opcional

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

  • mensajería

    booleano opcional

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

  • worldId

    string opcional

    Chrome 133 y versiones posteriores browser.* desde Chrome 148

    Especifica el ID del entorno de secuencias de comandos de usuario específico que se actualizará. Si no se proporciona, actualiza las propiedades del entorno de secuencias de comandos del usuario predeterminado. Los valores con guiones bajos iniciales (_) están reservados.

Métodos

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Configura el entorno de ejecución de `USER_SCRIPT`.

Parámetros

  • propiedades

    WorldProperties

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

Muestra

  • Promise<void>

    Es una promesa que se resuelve una vez que se configura el mundo.

execute()

Chrome 135 y versiones posteriores browser.* desde Chrome 148 
browser.userScripts.execute(
  injection: UserScriptInjection,
): 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 y devolverá el valor resultante.

Parámetros

Muestra

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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 devuelve las secuencias de comandos del usuario que coinciden con él.

Muestra

  • Es una promesa que se resuelve con las secuencias de comandos registradas. La promesa se rechazará si se produce un error.

getWorldConfigurations()

Chrome 133 y versiones posteriores browser.* desde Chrome 148 
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Recupera todas las configuraciones de mundo registradas.

Muestra

  • Promise<WorldProperties[]>

    Es la promesa que se resuelve con las configuraciones de mundo registradas.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Registra 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 registrarán.

Muestra

  • Promise<void>

    Es una promesa que se resuelve una vez que las secuencias de comandos se registraron por completo. La promesa se rechazará si se produce un error.

resetWorldConfiguration()

Chrome 133 y versiones posteriores browser.* desde Chrome 148 
browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

Restablece la configuración de un entorno de secuencias de comandos del usuario. Cualquier secuencia de comandos que se inserte en el entorno con el ID especificado usará la configuración predeterminada del entorno.

Parámetros

  • worldId

    string opcional

    Es el ID del entorno de la secuencia de comandos del usuario que se restablecerá. Si se omite, se restablece la configuración del mundo predeterminado.

Muestra

  • Promise<void>

    Es una promesa que se resuelve cuando se restablece la configuración.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

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 del usuario que coincidan con él.

Muestra

  • Promise<void>

    Es la promesa que se resuelve una vez que se cancela por completo el registro de las secuencias de comandos. La promesa se rechazará si se produce un error.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

Actualiza una o más secuencias de comandos del 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 se producen errores durante el análisis de la secuencia de comandos o la validación del archivo, o si los IDs especificados no corresponden a una secuencia de comandos completamente registrada, no se actualizará ninguna secuencia de comandos.

Muestra

  • Promise<void>

    Es la promesa que se resuelve una vez que las secuencias de comandos se actualizan por completo. La promesa se rechazará si se produce un error.