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 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 MV3+ .

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 las descargan desde un repositorio o una extensión de secuencias de comandos del 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. Para las extensiones de secuencia 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. 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.

    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 de 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 de host ni otras extensiones. Esto permite que una secuencia de comandos del usuario cambie el entorno de JavaScript sin afectar la página de alojamiento ni otras extensiones secuencias de comandos de usuario y contenido. Por el contrario, las secuencias de comandos de usuarios (y secuencias de comandos de contenido) no son visibles para la página de alojamiento ni para las secuencias de comandos de usuarios y contenido de otras extensiones. Las secuencias de comandos que se ejecutan en el mundo principal son accesibles para las páginas de alojamiento y otras extensiones, y son visibles para las páginas de alojamiento y para otras extensiones. 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 de los usuarios se comunican con otras partes de una extensión a través de 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 exclusivos (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 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, en el service worker de la extensión. Responde solo al motivo "update" que se pasó a la devolución de llamada del evento.

Ejemplo

Este es un ejemplo del ejemplo de userScript de 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. Existen 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 ejecutará una secuencia de comandos de usuario.

Enum

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

"USER_SCRIPT"
Especifica el entorno de ejecución que es 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 insertará en todos los marcos, incluso si el marco no es el 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.

  • excludeGlobs

    string[] opcional

    Especifica los 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 se insertaría esta secuencia de comandos del usuario de otro modo. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas cadenas.

  • id

    string

    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á reservado 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 secuencias de comandos que se insertarán en páginas coincidentes.

  • coincide con

    string[] opcional

    Especifica en qué páginas se insertará esta secuencia de comandos de usuario. Consulta Patrones de coincidencia para obtener más detalles sobre la sintaxis de estas cadenas. Se debe especificar esta propiedad 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

    string opcional

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

  • archivo

    string opcional

    Es la ruta de acceso del archivo JavaScript que se va a 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 ID especificados en esta lista.

WorldProperties

Propiedades

  • CSS

    string opcional

    Especifica las csp. El valor predeterminado es `ISOLATED` World csp.

  • 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 global de la secuencia de comandos del usuario.

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

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 de usuario que coinciden con él.

  • callback

    función opcional

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

    (scripts: RegisteredUserScript[]) => void

Muestra

  • Promise&lt;RegisteredUserScript[]&gt;

    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.

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 deben registrar.

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

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 cancela el registro solo de las secuencias de comandos de usuario que coinciden con él.

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

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