chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Descripción

Usa la API de chrome.declarativeContent para tomar medidas según el contenido de una página, sin necesidad de permiso para leer el contenido de la página.

Permisos

declarativeContent

Uso

La API de Declarative Content 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 constan de condiciones y acciones. Si se cumple alguna de las condiciones, se ejecutan todas las acciones. Las acciones son setIcon y showAction.

El PageStateMatcher coincide con las páginas web si y solo si se cumplen todos los criterios indicados. 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 en los sitios de Google Sites que tengan 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 cumplida y ejecuta las acciones. Las reglas persisten en 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 las 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áginas

El 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 Contains, Equals, Prefix o Suffix. En la siguiente tabla, se incluyen 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 la documentación para desarrolladores de Chrome

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 tus selectores. Esto ayuda a Chrome a hacer coincidir los selectores de manera más eficiente.

Selectores compuestos (correcto) Selectores complejos (no recomendados)
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 de visibility:hidden, posicionados fuera de la pantalla o que otros elementos ocultan pueden hacer que tu condición coincida.

Coincidencia de estado de favoritos

La condición PageStateMatcher.isBookmarked permite que coincida el estado de favorito 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

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: Incluir cientos de selectores CSS o 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 marcador de la página 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

Es la acción de evento declarativo que inserta una secuencia de comandos de contenido.

ADVERTENCIA: Esta acción aún es experimental y no se admite en las 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

    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 de contenido.

  • matchAboutBlank

    booleano opcional

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

SetIcon

Es una acción de evento declarativa que establece el ícono cuadrado de n-dip para la acción de página o la acción del navegador de la extensión 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 o de navegador.

Se debe especificar exactamente 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 la imagen en imageData es un objeto ImageData, por ejemplo, de un elemento canvas, mientras que la representación de la imagen en path es la ruta de acceso a un archivo de imagen relacionado con el manifiesto de la extensión. Si scale píxeles de pantalla caben en un píxel independiente del dispositivo, se usa el ícono scale * n. Si falta esa escala, se cambia el tamaño de otra imagen 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 establecerá. Si el ícono se especifica como un diccionario, la imagen utilizada 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 a scale, se selecciona una imagen con el tamaño 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 equivale a details.imageData = {'16': foo}.

ShowAction

Chrome 97 y versiones posteriores

Es 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 página otorga acceso a la pestaña activa.

En las páginas en las que no se cumplan las condiciones, la acción de la barra de herramientas de la extensión se mostrará en escala de grises y, si haces clic en ella, se abrirá el menú contextual en lugar de activar la acción.

Propiedades

ShowPageAction

Obsoleto desde Chrome 97

Usa declarativeContent.ShowAction.

Es 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 página otorga acceso a la pestaña activa.

En las páginas en las que no se cumplan las condiciones, la acción de la barra de herramientas de la extensión se mostrará en escala de grises y, si haces clic en ella, se abrirá el menú contextual en lugar de activar la acción.

Propiedades

Eventos

onPageChanged

Proporciona la API de eventos declarativos, que consta de addRules, removeRules y getRules.

Condiciones

PageStateMatcher

Acciones

RequestContentScript

SetIcon

ShowPageAction

ShowAction