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
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.
- Para ir a la página Extensiones, ingresa
chrome://extensions
en una pestaña nueva. (Por su 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.
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.
-
js
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
ocode
. -
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
ocode
.
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()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Configura el entorno de ejecución `USER_SCRIPT`
.
Parámetros
-
properties
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()
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
-
secuencias de comandos
-
Devuelve
-
Promise<RegisteredUserScript[]>
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()
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 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()
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()
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 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.