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 deseas 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 secuencias de comandos o las descargan de un repositorio de secuencias de comandos o una extensión de secuencia de comandos de usuario.

Modo de desarrollador para usuarios de extensiones

Como desarrollador de extensiones, ya tienes habilitado el modo de desarrollador en tu instalación de Chrome. En el caso de las extensiones de secuencia de comandos del usuario, los usuarios también deberán habilitar el modo de desarrollador. Estas son 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 diseño, las URLs de chrome:// no se pueden vincular).

  2. Para habilitar el modo de desarrollador, haz clic en el interruptor de activación 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

Las secuencias de comandos del usuario y del contenido se pueden ejecutar en un mundo aislado o en el mundo principal. Un mundo aislado es un entorno de ejecución al que no puede 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 host ni las secuencias de comandos de usuario y contenido de otras extensiones. Por el contrario, la página host o las secuencias de comandos del usuario y del contenido de otras extensiones no pueden ver las secuencias de comandos del usuario ni del contenido. Las páginas host y otras extensiones pueden acceder a las secuencias de comandos que se ejecutan en el mundo principal y pueden verlas. 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 de 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 la pantalla, las secuencias de comandos de usuario se comunican con otras partes de una extensión mediante mensajería (es decir, 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 denominan runtime.onUserScriptMessage y runtime.onUserScriptConnect. Los controladores dedicados facilitan la identificación de mensajes de 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 agregarlos, ejecuta código en el controlador de eventos runtime.onInstalled en el trabajador del servicio de la extensión. Responde solo al motivo "update" que se pasa a la devolución de llamada del evento.

Ejemplo

Este ejemplo es del ejemplo 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í.

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

Tipos

ExecutionWorld

Es el mundo de JavaScript en el que se ejecuta 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 código JavaScript de la página host.

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

RegisteredUserScript

Propiedades

  • allFrames

    booleano opcional

    Si es verdadero, se insertará en todos los fotogramas, incluso si el fotograma no es el más alto de la pestaña. Cada marco se verifica de forma independiente para los requisitos de la URL. No se insertará en marcos secundarios si no se cumplen los requisitos de la URL. El valor predeterminado es "false", 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 otro modo, 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 una "_", ya que está reservada como prefijo para los IDs de secuencia 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 especifique, 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`.

ScriptSource

Propiedades

  • código

    cadena opcional

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

  • 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 exactamente uno de file o code.

UserScriptFilter

Propiedades

  • ids

    string[] opcional

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

WorldProperties

Propiedades

  • csp

    cadena opcional

    Especifica el csp mundial. El valor predeterminado es el csp mundial `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 de `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

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 muestra solo las secuencias de comandos del usuario que coinciden con él.

  • callback

    función opcional

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

    (scripts: RegisteredUserScript[]) => void

Muestra

  • Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 secuencias de comandos de usuario que se registrarán.

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 anulará el registro de las secuencias de comandos del usuario que coincidan.

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 IDs 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

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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.