chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Descripción

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

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

La PageStateMatcher coincide con las páginas web si y 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 marcador 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 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 pertinentes.

Coincidencia de URLs de páginas

El PageStateMatcher.pageurl coincide cuando se cumplen los criterios de URL. Los criterios más comunes son una concatenación del host, la ruta o la URL, seguida de Contiene, Es igual a, Prefijo o Sufijo. 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 los criterios, consulta UrlFilter.

CSS Matching

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 (OK) 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 tu selector es display:none o uno de sus elementos principales es display:none, no se genera la coincidencia de la condición. Los elementos diseñados con visibility:hidden, posicionados fuera de la pantalla o ocultos por otros elementos aún pueden hacer que coincida tu condición.

Coincidencia de estado de favoritos

La condición PageStateMatcher.isBookmarked permite que se coincida con el estado de la URL actual guardada en los marcadores del 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

    cadena[] opcional

    Coincide si todos los selectores de CSS del array coinciden con los elementos mostrados en un iframe con el mismo origen que el iframe 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 la página guardada en marcadores 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 una acción de evento declarativa que inyecta 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

    cadena[] opcional

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

  • js

    cadena[] opcional

    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 relativa al manifiesto de la extensión. Si los píxeles de la pantalla scale 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

    Puede ser un objeto ImageData o un diccionario {tamaño -> ImageData} que represente un ícono que se 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 caben en una unidad de espacio de pantalla es igual a scale, se selecciona una imagen con un tamaño de scale * n, en la que 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

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 cumplen las condiciones, la acción de la barra de herramientas de la extensión estará en escala de grises, y, si se hace clic en ella, se abrirá el menú contextual en lugar de activarse 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 cumplen las condiciones, la acción de la barra de herramientas de la extensión estará en escala de grises, y, si se hace clic en ella, se abrirá el menú contextual en lugar de activarse 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