Descripción
Usa la API de chrome.contentSettings
para cambiar la configuración que controla si los sitios web pueden usar funciones como cookies, JavaScript y complementos. En términos más generales, la configuración de contenido te permite personalizar el comportamiento de Chrome para cada sitio en lugar de hacerlo de manera global.
Permisos
contentSettings
Para usar la API, debes declarar el permiso "contentSettings"
en el manifiesto de tu extensión. Por ejemplo:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Conceptos y uso
Patrones de configuración de contenido
Puedes usar patrones para especificar los sitios web a los que afectará cada configuración de contenido. Por ejemplo:
https://*.youtube.com/*
especifica youtube.com y todos sus subdominios. Sintaxis del contenido
establecer patrones es lo mismo que para los patrones de coincidencia, con algunas diferencias:
- Para las URLs
http
,https
yftp
, la ruta de acceso debe ser un comodín (/*
). Para las URLsfile
, la ruta de acceso debe especificarse completamente y no debe contener comodines. - A diferencia de los patrones de coincidencia, los patrones de configuración de contenido pueden especificar un número de puerto. Si un puerto un número, el patrón solo coincide con los sitios web con ese puerto. Si no se indica ningún número de puerto especificado, el patrón coincide con todos los puertos.
Precedencia del patrón
Cuando se aplica más de una regla de configuración de contenido a un sitio determinado, la que tenga la este patrón tiene prioridad.
Por ejemplo, los siguientes patrones se ordenan por prioridad:
https://www.example.com/*
https://*.example.com/*
(coincide con example.com y todos los subdominios)<all_urls>
(coincide con todas las URLs)
Tres tipos de comodines afectan la especificidad de un patrón:
- Comodines en el puerto (por ejemplo,
https://www.example.com:*/*
) - Comodines en el esquema (por ejemplo,
*://www.example.com:123/*
) - Comodines en el nombre de host (por ejemplo,
https://*.example.com:123/*
)
Si un patrón es más específico que otro en una parte, pero menos específico en otra, las diferentes partes se verifican en el siguiente orden: nombre de host, esquema, puerto. Por ejemplo, el los siguientes patrones se ordenan por precedencia:
https://www.example.com:*/*
Especifica el nombre de host y el esquema.*:/www.example.com:123/*
No es tan alto porque, aunque especifica el nombre de host, no especifica el esquema.https://*.example.com:123/*
Es menor porque, aunque especifica el puerto y el esquema, tiene un comodín en el nombre de host.
Patrones primarios y secundarios
La URL que se tiene en cuenta para decidir qué configuración de contenido aplicar depende del tipo de contenido.
Por ejemplo, la configuración de contentSettings.notifications
se basa en la URL que se muestra en la
cuadro multifunción. Esta URL se denomina "principal" URL.
Algunos tipos de contenido pueden tener en cuenta URLs adicionales. Por ejemplo, si un sitio puede
establecer un contentSettings.cookies
se decide en función de la URL de la solicitud HTTP (que es la
URL principal en este caso), así como la URL que se muestra en el cuadro multifunción (que se denomina "secundaria"
URL).
Si varias reglas tienen patrones primarios y secundarios, la regla con el principal más específico este patrón tiene prioridad. Si hay varias reglas con el mismo patrón principal, un patrón secundario más específico tiene prioridad. Por ejemplo, la siguiente lista de Los pares de patrones primario/secundario se ordenan por prioridad:
Prioridad | Patrón principal | Patrón secundario |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://www.moose.com/* , | <all_urls> |
3 | <all_urls> , | https://www.wombat.com/* |
4 | <all_urls> , | <all_urls> |
Identificadores de recursos
Los identificadores de recursos te permiten especificar la configuración de contenido para subtipos específicos de un tipo de contenido.
Actualmente, el único tipo de contenido que admite identificadores de recursos es contentSettings.plugins
,
en la que un identificador de recursos identifica un complemento específico. Cuando apliques la configuración de contenido, primero se
configuración del complemento específico. Si no se encuentran parámetros de configuración
complemento, se verifica la configuración general de contenido para los complementos.
Por ejemplo, si una regla de configuración de contenido tiene el identificador de recursos adobe-flash-player
y el
patrón <all_urls>
, tiene prioridad sobre una regla sin un identificador de recursos y el patrón
https://www.example.com/*
, incluso si ese patrón es más específico.
Puedes obtener una lista de identificadores de recursos para un tipo de contenido si llamas al
contentSettings.ContentSetting.getResourceIdentifiers()
. La lista que se devuelve puede cambiar con
el conjunto de complementos instalados en la máquina del usuario, pero Chrome intenta mantener estables los identificadores
en las actualizaciones de complementos.
Ejemplos
Para probar esta API, instala el ejemplo de la API de contentSettings desde chrome-extension-samples en un repositorio de confianza.
Tipos
AutoVerifyContentSetting
Enum
“allow”
“bloquear”
CameraContentSetting
Enum
“allow”
“bloquear”
“preguntar”
ClipboardContentSetting
Enum
“allow”
“bloquear”
“preguntar”
ContentSetting
Propiedades
-
borrar
void
PromesaBorra todas las reglas de configuración de contenido que estableció esta extensión.
La función
clear
se ve de la siguiente manera:(details: object, callback?: function) => {...}
-
detalles
objeto
-
alcance
Alcance opcional
Dónde borrar el parámetro de configuración (predeterminado: normal)
-
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
-
muestra
Promesa<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
-
-
get
void
PromesaObtiene la configuración de contenido actual para un par de URL determinado.
La función
get
se ve de la siguiente manera:(details: object, callback?: function) => {...}
-
detalles
objeto
-
incógnito
booleano opcional
Establece si se debe verificar la configuración de contenido de una sesión en modo Incógnito. (el valor predeterminado es falso)
-
primaryUrl
string
La URL principal para la que se debe recuperar la configuración de contenido. Ten en cuenta que el significado de una URL principal depende del tipo de contenido.
-
resourceIdentifier
ResourceIdentifier opcional
Un identificador más específico del tipo de contenido para el que se debe recuperar la configuración.
-
secondaryUrl
string opcional
La URL secundaria para la que se debe recuperar la configuración de contenido. El valor predeterminado es la URL principal. Ten en cuenta que el significado de una URL secundaria depende del tipo de contenido, y no todos los tipos de contenido utilizan URLs secundarias.
-
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(details: object) => void
-
detalles
objeto
-
Estableciendo
T
Es la configuración de contenido. Consulta la descripción de los objetos ContentSetting individuales para obtener los valores posibles.
-
-
-
muestra
Promise<object>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
-
-
getResourceIdentifiers
void
PromesaLa función
getResourceIdentifiers
se ve de la siguiente manera:(callback?: function) => {...}
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] opcional
Una lista de identificadores de recursos para este tipo de contenido, o
undefined
si este tipo de contenido no usa identificadores de recursos.
-
-
muestra
Promesa<ResourceIdentifier[]>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
-
-
set
void
PromesaAplica una nueva regla de configuración de contenido.
La función
set
se ve de la siguiente manera:(details: object, callback?: function) => {...}
-
detalles
objeto
-
primaryPattern
string
El patrón de la URL principal. Para obtener detalles sobre el formato de un patrón, consulta Patrones de configuración de contenido.
-
resourceIdentifier
ResourceIdentifier opcional
El identificador de recurso para el tipo de contenido.
-
alcance
Alcance opcional
Dónde establecer la configuración (predeterminado: normal).
-
secondaryPattern
string opcional
El patrón de la URL secundaria. La configuración predeterminada es que coincida con todas las URLs. Para obtener detalles sobre el formato de un patrón, consulta Patrones de configuración de contenido.
-
Estableciendo
cualquiera
El parámetro de configuración que aplica esta regla. Consulta la descripción de los objetos ContentSetting individuales para obtener los valores posibles.
-
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
-
muestra
Promesa<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
-
CookiesContentSetting
Enum
“allow”
“bloquear”
"session_only"
FullscreenContentSetting
Valor
“allow”
ImagesContentSetting
Enum
“allow”
“bloquear”
JavascriptContentSetting
Enum
“allow”
“bloquear”
LocationContentSetting
Enum
“allow”
“bloquear”
“preguntar”
MicrophoneContentSetting
Enum
“allow”
“bloquear”
“preguntar”
MouselockContentSetting
Valor
“allow”
MultipleAutomaticDownloadsContentSetting
Enum
“allow”
“bloquear”
“preguntar”
NotificationsContentSetting
Enum
“allow”
“bloquear”
“preguntar”
PluginsContentSetting
Valor
“bloquear”
PopupsContentSetting
Enum
“allow”
“bloquear”
PpapiBrokerContentSetting
Valor
“bloquear”
ResourceIdentifier
El único tipo de contenido que usa identificadores de recursos es contentSettings.plugins
. Para obtener más información, consulta Identificadores de recursos.
Propiedades
-
descripción
string opcional
Es una descripción legible del recurso.
-
id
string
Es el identificador de recurso para el tipo de contenido determinado.
Scope
El alcance de ContentSetting. Uno de
regular
: Es la configuración del perfil normal (que hereda el perfil de incógnito si no se anula en otro lugar).
incognito\_session\_only
: Es el parámetro de configuración del perfil en modo Incógnito que solo se puede establecer durante una sesión en modo Incógnito y se borra cuando esta finaliza (se anula la configuración normal).
Enum
“normal”
“ Incógnito_session_only”
Propiedades
automaticDownloads
Indica si se permite que los sitios descarguen varios archivos automáticamente. Uno de
allow
: Permitir que los sitios descarguen varios archivos automáticamente,
block
: No permitir que los sitios descarguen varios archivos automáticamente,
ask
: Preguntar cuando un sitio quiera descargar archivos automáticamente después del primer archivo
El valor predeterminado es ask
.
La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa.
autoVerify
Indica si se permite que los sitios usen la API de Private State Tokens. Uno de
allow
: Permite que los sitios usen la API de Private State Tokens.
block
: Impide que los sitios usen la API de Private State Tokens.
El valor predeterminado es allow
.
La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa. NOTA: Cuando llamas a set()
, el patrón principal debe ser .
Tipo
camera
Indica si se permite el acceso de los sitios a la cámara. Uno de
allow
: Permite que los sitios accedan a la cámara.
block
: No permitir que los sitios accedan a la cámara,
ask
: Preguntar cuando un sitio quiera acceder a la cámara.
El valor predeterminado es ask
.
La URL principal es la URL del documento que solicitó acceso a la cámara. La URL secundaria no se usa.
NOTA: La opción "allow" no es válido si ambos patrones son ''.
Tipo
clipboard
Indica si se permite que los sitios accedan al portapapeles a través de las funciones avanzadas de la API de Async Clipboard. “Avanzado” incluyen cualquier cosa además de la escritura de formatos integrados después de un gesto del usuario, es decir, la capacidad de leer, escribir formatos personalizados y escribir sin un gesto del usuario. Uno de
allow
: Permite que los sitios usen las funciones avanzadas del portapapeles.
block
: No permitir que los sitios usen funciones avanzadas del portapapeles,
ask
: Preguntar cuando un sitio quiera usar las funciones avanzadas del portapapeles.
El valor predeterminado es ask
.
La URL principal es la URL del documento que solicitó acceso al portapapeles. La URL secundaria no se usa.
Tipo
cookies
Indica si se deben permitir o no que los sitios web establezcan cookies y otros datos locales. Uno de
allow
: Aceptar cookies,
block
: Bloquear cookies,
session\_only
: Acepta las cookies solo de la sesión actual.
El valor predeterminado es allow
.
La URL principal es la que representa el origen de la cookie. La URL secundaria es la URL del marco de nivel superior.
Tipo
fullscreen
Obsoleto. Ya no tiene ningún efecto. El permiso de pantalla completa ahora se otorga automáticamente para todos los sitios. El valor es siempre allow
.
Tipo
images
Establece si se deben mostrar las imágenes. Uno de
allow
: Muestra imágenes,
block
: No mostrar imágenes.
El valor predeterminado es allow
.
La URL principal es la URL del marco de nivel superior. La URL secundaria es la URL de la imagen.
Tipo
javascript
Establece si se debe ejecutar JavaScript. Uno de
allow
: Ejecutar JavaScript.
block
: No ejecutas JavaScript.
El valor predeterminado es allow
.
La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa.
Tipo
location
Indica si se debe permitir la ubicación geográfica. Uno de
allow
: Permitir que los sitios hagan un seguimiento de tu ubicación física.
block
: No permitir que los sitios hagan un seguimiento de tu ubicación física,
ask
: Preguntar antes de permitir que los sitios hagan un seguimiento de tu ubicación física
El valor predeterminado es ask
.
La URL principal es la URL del documento que solicitó datos de ubicación. La URL secundaria es la URL del marco de nivel superior (que puede o no diferir de la URL solicitante).
Tipo
microphone
Indica si se permite que los sitios accedan al micrófono. Uno de
allow
: Permite que los sitios accedan al micrófono.
block
: No permitir que los sitios accedan al micrófono,
ask
: Preguntar cuando un sitio quiera acceder al micrófono.
El valor predeterminado es ask
.
La URL principal es la URL del documento que solicitó acceso al micrófono. La URL secundaria no se usa.
NOTA: La opción "allow" no es válido si ambos patrones son ''.
Tipo
mouselock
Obsoleto. Ya no tiene ningún efecto. El permiso de bloqueo del mouse ahora se otorga automáticamente para todos los sitios. El valor es siempre allow
.
Tipo
notifications
Indica si se permite que los sitios muestren notificaciones de escritorio. Uno de
allow
: Permitir que los sitios muestren notificaciones de escritorio,
block
: No permitir que los sitios muestren notificaciones de escritorio,
ask
: Preguntar cuando un sitio quiera mostrar notificaciones de escritorio.
El valor predeterminado es ask
.
La URL principal es la URL del documento que desea mostrar la notificación. La URL secundaria no se usa.
Tipo
plugins
Obsoleto. Como se quitó la compatibilidad con Flash en Chrome 88, este permiso ya no tendrá ningún efecto. El valor es siempre block
. Se ignorarán las llamadas a set()
y clear()
.
Tipo
popups
Indica si se permite que los sitios muestren ventanas emergentes. Uno de
allow
: Permitir que los sitios muestren ventanas emergentes,
block
: No permitir que los sitios muestren ventanas emergentes.
El valor predeterminado es block
.
La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa.
Tipo
unsandboxedPlugins
Obsoleto. Anteriormente, se podía controlar si se permitía que los sitios ejecutaran complementos fuera de la zona de pruebas. Sin embargo, dado que se quitó el proceso del agente de Flash en Chrome 88, este permiso ya no tiene ningún efecto. El valor es siempre block
. Se ignorarán las llamadas a set()
y clear()
.