chrome.declarativeContent

Descripción

Permisos

Conceptos y uso

La API de contenido declarativo te permite habilitar la acción de tu extensión según la URL de una página web o si un selector CSS coincide con un elemento de la página, sin necesidad de agregar permisos de host ni de insertar 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 de favorito 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() ]
};

Para habilitar también 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 prueba si alguna regla tiene al menos una condición completada y ejecuta las acciones. Las reglas persisten en todas las sesiones de navegación. Por lo tanto, durante el tiempo de instalación de la extensión, primero debes usar removeRules para borrar las reglas instaladas anteriormente y, luego, usar addRules para registrar otras nuevas.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Con el permiso activeTab, tu 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 URLs de página

PageStateMatcher.pageurl coincide cuando se cumplen los criterios de URL. Los criterios más comunes son una concatenación de host, ruta de acceso o URL, seguida de Contiene, Igual, Prefijo o Sufijo. La siguiente tabla contiene algunos ejemplos:

Criterios	Combinaciones
{ hostSuffix: 'google.com' }	Todas las URLs de Google
{ pathPrefix: '/docs/extensions' }	URLs de la documentación de la extensión
{ urlContains: 'developer.chrome.com' }	Todas las URLs de documentos para desarrolladores de Chrome

Todos los criterios distinguen mayúsculas de minúsculas. Para obtener una lista completa de los criterios, consulta UrlFilter.

Coincidencia de CSS

Las condiciones PageStateMatcher.css deben ser selectores compuestos, lo que significa que no puedes incluir combinatores, como espacios en blanco o ">", en tus selectores. Esto ayuda a Chrome a hacer coincidir los selectores de forma más eficiente.

Selectores compuestos (OK)	Selectores complejos (no aceptables)
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 tu selector es display:none o uno de sus elementos superiores es display:none, no hace que la condición coincida. Los elementos con diseño visibility:hidden, posicionados fuera de la pantalla o ocultos por otros elementos pueden hacer que tu condición coincida.

Coincidencia de estado de 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 manifest de la extensión.