chrome.declarativeContent

Descripción

Usa la API de chrome.declarativeContent para realizar acciones según el contenido de una página, sin requerir permiso para leer el contenido de la página.

Permisos

declarativeContent

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 Agrega permisos de host o inserta 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 el acción de la extensión.

Reglas

Las reglas constan de condiciones y acciones. Si se cumple alguna de las condiciones, todas las acciones se ejecutado. Las acciones son setIcon() y showAction().

El objeto PageStateMatcher coincide con páginas web solo si se muestran todas de que se cumplan los criterios. Puede coincidir con una URL de página o 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 presente:

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 un segundo , 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 completada y ejecuta las acciones. Las reglas persisten en todas las sesiones de navegación. por lo tanto, durante tiempo de instalación de la extensión, primero debes usar removeRules para borrar reglas instaladas anteriormente y, luego, usa 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á ningún permiso y, cuando el usuario haga clic en la acción de la extensión, esta solo se ejecutará en páginas relevantes.

Coincidencia con la URL de la página

El elemento PageStateMatcher.pageurl coincide cuando se cumplen los criterios de URL. El 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 los documentos de las extensiones
{ urlContains: 'developer.chrome.com' Todas las URLs de la documentación de Chrome Developers

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

Coincidencia de CSS

Las condiciones PageStateMatcher.css deben ser selectores compuestos, lo que significa que no puedes incluir combinadores, como espacios en blanco o “>” en tu selectores. Esto ayuda a Chrome a hacer coincidir los selectores de manera más eficiente.

Selectores compuestos (OK) Selectores complejos (no correctos)
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 se display:none o uno de sus elementos superiores es display:none, no hace que la condición la coincidencia. Elementos con estilo visibility:hidden, ocultos por otros elementos o fuera de la pantalla aún puede hacer que tu condición coincida.

Coincidencia de estado en favoritos

La condición PageStateMatcher.isBookmarked permite la coincidencia de la estado agregado a favoritos de la URL actual en el perfil del usuario. Para aprovechar esta condición, "favoritos" se debe declarar el permiso en el manifiesto de la extensión.

Tipos

Tipo

ImageData

PageStateMatcher

Coincide con el estado de una página web según varios criterios.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] opcional

    Coincide si todos los selectores CSS del array coinciden con los elementos mostrados 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: Crear una lista de cientos de selectores CSS o una lista de selectores CSS que coincidan cientos de veces por página puede ralentizar los sitios web.

  • isBookmarked

    booleano opcional

    Chrome 45 y versiones posteriores

    Coincide si el estado de la página en el marcador es igual al valor especificado. Se 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) => {...}

  • allFrames

    booleano opcional

    Indica si la secuencia de comandos de 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

    Los nombres de los archivos CSS que se insertarán como parte de la secuencia de comandos del contenido.

  • js

    string[] opcional

    Los nombres de los archivos JavaScript que se insertarán como parte de la secuencia de comandos del contenido.

  • matchAboutBlank

    booleano opcional

    Establece si se debe insertar la secuencia de comandos de contenido en about:blank y about:srcdoc. El valor predeterminado es false.

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, siempre que se cumplan las condiciones correspondientes. Esta acción se puede usar sin permisos de host, pero la extensión debe tener una acción de la página o del navegador.

Se debe especificar exactamente uno de imageData o path. Ambos son diccionarios que asignan una cantidad de píxeles a una representación de imagen. La representación de la 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 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 usa el ícono scale * n. Si falta esa escala, otra imagen se cambia al tamaño requerido.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | objeto opcional

    Un objeto ImageData o un diccionario {size -> ImageData}, que representa un ícono que se debe establecer. 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 la imagen que entran en una unidad de espacio de pantalla es igual a scale, se selecciona una imagen con un tamaño de scale * n, donde n es el tamaño del ícono en la IU. Se debe especificar al menos una imagen. Ten en cuenta que details.imageData = foo es equivalente a details.imageData = {'16': foo}.

ShowAction

Chrome 97 y versiones posteriores

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 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 cumplan las condiciones, la acción de la barra de herramientas de la extensión se mostrará en escala de gris y, si se hace clic en ella, se abrirá el menú contextual, en lugar de activar la acción.

Propiedades

ShowPageAction

Obsoleto desde Chrome 97

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 la 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 cumplan las condiciones, la acción de la barra de herramientas de la extensión se mostrará en escala de gris y, si se hace clic en ella, se abrirá el menú contextual, en lugar de activar la acción.

Propiedades

Eventos

onPageChanged

Proporciona la API de Declarative Event, que consta de addRules, removeRules y getRules.

Condiciones

PageStateMatcher

Acciones

RequestContentScript

SetIcon

ShowPageAction

ShowAction