Descripción
Usa la API de chrome.declarativeContent
para realizar acciones según el contenido de una página, sin solicitar permiso para leer su contenido.
Permisos
declarativeContent
Conceptos y uso
Declarative Content API te permite habilitar la acción de tu extensión según la URL de una página web o si un selector de CSS coincide con un elemento de la página, sin necesidad de agregar permisos de host ni inyectar una secuencia de comandos de contenido.
Usa el permiso activeTab para interactuar con una página después de que el usuario haga clic en la acción de la extensión.
Reglas
Las reglas consisten en condiciones y acciones. Si se cumple alguna de las condiciones, se ejecutan todas las acciones. Las acciones son setIcon()
y showAction()
.
PageStateMatcher
coincide con las páginas web solo si se cumplen todos los criterios enumerados. Puede coincidir con una URL de página, un selector compuesto de CSS o el estado agregado a favoritos de una página. La siguiente regla habilita la acción de la extensión en las páginas de Google cuando hay un campo de contraseña:
let rule1 = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
css: ["input[type='password']"]
})
],
actions: [ new chrome.declarativeContent.ShowAction() ]
};
Si también deseas habilitar la acción de la extensión para los sitios de Google con un video, puedes agregar una segunda condición, ya que cada condición es suficiente para activar todas las acciones especificadas:
let rule2 = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
css: ["input[type='password']"]
}),
new chrome.declarativeContent.PageStateMatcher({
css: ["video"]
})
],
actions: [ new chrome.declarativeContent.ShowAction() ]
};
El evento onPageChanged
comprueba si alguna regla tiene al menos una condición cumplida y ejecuta las acciones. Las reglas persisten en todas las sesiones de navegación. Por lo tanto, durante
el tiempo de instalación de las extensiones, primero debes usar removeRules
para borrar
las reglas instaladas previamente y, luego, usar addRules
para registrar las nuevas.
chrome.runtime.onInstalled.addListener(function(details) {
chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
chrome.declarativeContent.onPageChanged.addRules([rule2]);
});
});
Con el permiso activeTab, la extensión no mostrará ninguna advertencia de permiso, y cuando el usuario haga clic en la acción de la extensión, solo se ejecutará en las páginas relevantes.
Coincidencia de URL de página
El elemento PageStateMatcher.pageurl
coincide cuando se cumplen los criterios de la URL. Los criterios más comunes son una concatenación de host, ruta de acceso o URL, seguida de Contiene, Es igual a, Prefijo o Sufijo. La siguiente tabla contiene algunos ejemplos:
Criterios | Mostrar coincidencias |
---|---|
{ hostSuffix: 'google.com' } |
Todas las URLs de Google |
{ pathPrefix: '/docs/extensions' } |
URLs de documentos de extensiones |
{ urlContains: 'developer.chrome.com' } |
Las URLs de todas las documentos para desarrolladores de Chrome |
Todos los criterios distinguen mayúsculas de minúsculas. Para obtener una lista completa de criterios, consulta UrlFilter.
Coincidencias de CSS
Las condiciones de PageStateMatcher.css
deben ser selectores compuestos, lo que significa que no puedes incluir combinadores como espacios en blanco o “>
” en tus selectores. Esto ayuda a Chrome a hacer coincidir los selectores de manera más eficiente.
Selectores compuestos (Aceptar) | Selectores complejos (no aceptable) |
---|---|
a |
div p |
iframe.special[src^='http'] |
p>span.highlight |
ns|* |
p + ol |
#abcd:checked |
p::first-line |
Las condiciones de CSS solo coinciden con los elementos que se muestran: si un elemento que coincide con el selector es display:none
o uno de sus elementos superiores es display:none
, no hace que la condición coincida. Los elementos con estilo visibility:hidden
, ubicados fuera de la pantalla, o bien ocultos por otros elementos, aún pueden hacer que tu condición coincida.
Coincidencia de estados agregados a favoritos
La condición PageStateMatcher.isBookmarked
permite hacer coincidir el estado agregado a favoritos de la URL actual en el perfil del usuario. Para usar esta condición, se debe declarar el permiso "bookmarks" en el manifiesto de la extensión.
Tipos
ImageDataType
Consulta https://developer.mozilla.org/en-US/docs/Web/API/ImageData.
Tipo
ImageData
PageStateMatcher
Coincide con el estado de una página web según diversos criterios.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: PageStateMatcher) => {...}
-
argumento
-
resultados
-
-
css
string[] opcional
Coincide si todos los selectores CSS del array coinciden con los elementos que se muestran en un marco con el mismo origen que el marco principal de la página. Todos los selectores de este array deben ser selectores compuestos para acelerar la coincidencia. Nota: Agregar cientos de selectores CSS o mostrar selectores CSS que coinciden cientos de veces por página puede ralentizar los sitios web.
-
isBookmarked
booleano opcional
Chrome 45 y versiones posterioresCoincide si el estado de la página agregado a favoritos es igual al valor especificado. Requiere el permiso de favoritos.
-
pageUrl
UrlFilter opcional
Coincide si se cumplen las condiciones de
UrlFilter
para la URL de nivel superior de la página.
RequestContentScript
Acción de evento declarativa que inserta una secuencia de comandos de contenido.
ADVERTENCIA: Esta acción aún es experimental y no se admite en compilaciones estables de Chrome.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RequestContentScript) => {...}
-
argumento
-
resultados
-
-
allFrames
booleano opcional
Indica si la secuencia de comandos del contenido se ejecuta en todos los marcos de la página coincidente o solo en el marco superior. El valor predeterminado es
false
. -
css
string[] opcional
Son los nombres de los archivos CSS que se insertarán como parte de la secuencia de comandos de contenido.
-
js
string[] opcional
Son los nombres de los archivos JavaScript que se insertarán como parte de la secuencia de comandos del contenido.
-
matchAboutBlank
booleano opcional
Indica si se debe insertar la secuencia de comandos de contenido en
about:blank
yabout:srcdoc
. El valor predeterminado esfalse
.
SetIcon
Acción de evento declarativa que establece el ícono cuadrado n-dip para la acción de página o la acción del navegador de la extensión cuando se cumplen las condiciones correspondientes. Esta acción se puede usar sin permisos de host, pero la extensión debe tener una acción de página o del navegador.
Se debe especificar solamente uno de los valores imageData
o path
. Ambos son diccionarios que asignan una cantidad de píxeles a una representación de imagen. La representación de imagen en imageData
es un objeto ImageData; por ejemplo, desde un elemento canvas
, mientras que la representación de imagen en path
es la ruta de acceso a un archivo de imagen relacionado con el manifiesto de la extensión. Si los píxeles de pantalla scale
caben en un píxel independiente del dispositivo, se utilizará el ícono scale * n
. Si falta esa escala, se cambia el tamaño de otra imagen al requerido.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: SetIcon) => {...}
-
argumento
-
resultados
-
-
imageData
ImageData | objeto opcional
Un objeto
ImageData
o un diccionario {size -> ImageData} que representa un ícono que se configurará. Si el ícono se especifica como un diccionario, la imagen que se usa se elige según la densidad de píxeles de la pantalla. Si la cantidad de píxeles de imagen que caben en una unidad de espacio de pantalla es igual ascale
, se seleccionará una imagen con el tamañoscale * n
, donde n es el tamaño del ícono en la IU. Se debe especificar al menos una imagen. Ten en cuenta quedetails.imageData = foo
es equivalente adetails.imageData = {'16': foo}
.
ShowAction
Una acción de evento declarativa que establece la acción de la barra de herramientas de la extensión en un estado habilitado mientras se cumplen las condiciones correspondientes. Esta acción se puede usar sin los permisos de host. Si la extensión tiene el permiso activeTab, hacer clic en la acción de la página otorga acceso a la pestaña activa.
En las páginas donde no se cumplen las condiciones, la acción de la barra de herramientas de la extensión será de escala de grises. Si haces clic en ella, se abrirá el menú contextual en lugar de activar la acción.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: ShowAction) => {...}
-
argumento
-
resultados
-
ShowPageAction
Usa declarativeContent.ShowAction
.
Una acción de evento declarativa que establece la acción de página de la extensión en un estado habilitado mientras se cumplen las condiciones correspondientes. Esta acción se puede usar sin permisos de host, pero la extensión debe tener una acción de página. Si la extensión tiene el permiso activeTab, hacer clic en la acción de la página otorga acceso a la pestaña activa.
En las páginas donde no se cumplen las condiciones, la acción de la barra de herramientas de la extensión será de escala de grises. Si haces clic en ella, se abrirá el menú contextual en lugar de activar la acción.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: ShowPageAction) => {...}
-
argumento
-
resultados
-
Eventos
onPageChanged
Proporciona la API de declarative Event que consta de addRules
, removeRules
y getRules
.