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
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.
- Ingresa
chrome://extensions
en una pestaña nueva para ir a la página Extensiones. Por diseño, las URLs dechrome://
no se pueden vincular. Para habilitar el modo de desarrollador, haz clic en el interruptor junto a Modo de desarrollador.
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.
-
js
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
ocode
. -
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
ocode
.
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()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Configura el entorno de ejecución `USER_SCRIPT`
.
Parámetros
-
properties
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()
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
-
secuencias de comandos
-
Muestra
-
Promise<RegisteredUserScript[]>
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()
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
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()
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()
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
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.