说明
chrome.contentSettings
API 可用于更改相关设置,以控制网站是否可以使用 Cookie、JavaScript 和插件等功能。一般来说,通过内容设置,您可以按网站(而非全局)自定义 Chrome 的行为。
权限
contentSettings
清单
您必须在扩展程序的清单中声明“contentSettings”权限,才能使用该 API。例如:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
内容设置模式
您可以使用模式来指定每项内容设置影响的网站。例如,https://*.youtube.com/*
指定 youtube.com 及其所有子网域。内容设置模式的语法与匹配模式的语法相同,但存在一些差异:
- 对于
http
、https
和ftp
网址,路径必须是通配符 (/*
)。对于file
网址,必须完整指定路径,且不得包含通配符。 - 与匹配模式相反,内容设置模式可以指定端口号。如果指定了端口号,则格式仅匹配使用该端口的网站。如果未指定端口号,则模式匹配所有端口。
模式优先级
如果有多个内容设置规则适用于给定网站,则格式更具体的规则优先。
例如,以下格式按优先级排序:
https://www.example.com/*
https://*.example.com/*
(匹配 example.com 及所有子网域)<all_urls>
(与每个网址匹配)
以下三种通配符会影响模式的具体程度:
- 端口中的通配符(例如
https://www.example.com:*/*
) - 架构中的通配符(例如
*://www.example.com:123/*
) - 主机名中的通配符(例如
https://*.example.com:123/*
)
如果某个模式在某一部分比另一部分更具体,但在另一部分不太具体,则按以下顺序检查不同的部分:主机名、架构、端口。例如,以下格式按优先级排序:
https://www.example.com:*/*
指定主机名和架构。*:/www.example.com:123/*
不太高,因为虽然它指定了主机名,但并未指定架构。https://*.example.com:123/*
更低,因为它虽然指定了端口和架构,但主机名中却包含通配符。
主要模式和次要模式
决定应用哪些内容设置时要考虑的网址取决于内容类型。
例如,contentSettings.notifications
设置基于多功能框中显示的网址。此网址称为“主要”网址。
某些内容类型可能会包含其他网址。例如,是否允许网站设置 contentSettings.cookies
取决于 HTTP 请求的网址(在本例中为主要网址)以及多功能框中显示的网址(称为“辅助”网址)。
如果多条规则具有主要模式和次要模式,则主要模式更具体的规则优先。如果多条规则具有相同的主要格式,则以更具体的次要格式规则为准。例如,以下主要/次要模式对列表按优先级排序:
优先级 | 主要格式 | 次要格式 |
---|---|---|
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> |
资源标识符
通过资源标识符,您可以为某个内容类型的特定子类型指定内容设置。目前,唯一支持资源标识符的内容类型是 contentSettings.plugins
,其中资源标识符用于标识特定插件。应用内容设置时,首先会检查特定插件的设置。如果未找到特定插件的设置,则检查插件的常规内容设置。
例如,如果内容设置规则包含资源标识符 adobe-flash-player
和格式 <all_urls>
,则该规则优先于不含资源标识符和格式 https://www.example.com/*
的规则,即使该格式更为具体也是如此。
您可以通过调用 contentSettings.ContentSetting.getResourceIdentifiers
方法来获取某种内容类型的资源标识符列表。返回的列表可能会因用户计算机上已安装的插件集而发生变化,但 Chrome 会尝试让标识符在插件更新后保持稳定。
示例
如需试用此 API,请从 chrome-extension-samples 代码库安装 contentSettings API 示例。
类型
AutoVerifyContentSetting
枚举
"block"
CameraContentSetting
枚举
"block"
ClipboardContentSetting
枚举
"block"
ContentSetting
属性
-
清除
void
Promise清除此扩展程序设置的所有内容设置规则。
clear
函数如下所示:(details: object, callback?: function) => {...}
-
明细
对象
-
范围
范围(可选)
清除设置的位置(默认:常规)。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
-
-
get
void
Promise获取给定对网址的当前内容设置。
get
函数如下所示:(details: object, callback?: function) => {...}
-
明细
对象
-
无痕模式
布尔值 选填
是否查看无痕模式会话的内容设置。(默认值为 false)
-
primaryUrl
string
应检索内容设置的主要网址。请注意,主要网址的含义取决于内容类型。
-
resourceIdentifier
一个更具体的标识符,表示应检索其设置的内容类型。
-
secondaryUrl
字符串(可选)
应检索内容设置的辅助网址。默认为主网址。请注意,辅助网址的含义取决于内容类型,并非所有内容类型都使用辅助网址。
-
-
callback
函数(可选)
callback
参数如下所示:(details: object) => void
-
明细
对象
-
设置
T
内容设置。请参阅各个 ContentSetting 对象的说明,了解可能的值。
-
-
-
返回
Promise<object>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
-
-
getResourceIdentifiers
void
PromisegetResourceIdentifiers
函数如下所示:(callback?: function) => {...}
-
callback
函数(可选)
callback
参数如下所示:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] 可选
此内容类型的资源标识符列表,如果此内容类型不使用资源标识符,则为
undefined
。
-
-
返回
Promise<ResourceIdentifier[]>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
-
-
set
void
Promise应用新的内容设置规则。
set
函数如下所示:(details: object, callback?: function) => {...}
-
返回
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
-
CookiesContentSetting
枚举
"block"
"session_only"
FullscreenContentSetting
值
ImagesContentSetting
枚举
"block"
JavascriptContentSetting
枚举
"block"
LocationContentSetting
枚举
"block"
MicrophoneContentSetting
枚举
"block"
MouselockContentSetting
值
MultipleAutomaticDownloadsContentSetting
枚举
"block"
NotificationsContentSetting
枚举
"block"
PluginsContentSetting
值
"block"
PopupsContentSetting
枚举
"block"
PpapiBrokerContentSetting
值
"block"
ResourceIdentifier
唯一使用资源标识符的内容类型是 contentSettings.plugins
。如需了解详情,请参阅资源标识符。
属性
-
说明
字符串(可选)
直观易懂的资源说明。
-
id
string
指定内容类型的资源标识符。
Scope
ContentSetting 的范围。regular
:常规个人资料的设置(如果未在其他地方替换,则会被无痕个人资料沿用);incognito\_session\_only
:无痕模式个人资料的设置,只能在无痕会话期间设置,且会在无痕模式会话结束时删除(覆盖常规设置)。
枚举
属性
automaticDownloads
是否允许网站自动下载多个文件。allow
:允许网站自动下载多个文件;block
:不允许网站自动下载多个文件;ask
:在网站想在下载第一个文件后自动下载文件时询问您。
默认值为 ask
。
主要网址是顶级框架的网址。而不会使用辅助网址。
autoVerify
是否允许网站使用 Private State Tokens API。allow
:允许网站使用 Private State Tokens API;block
:禁止网站使用 Private State Tokens API。默认值为 allow
。
主要网址是顶级框架的网址。而不会使用辅助网址。注意:调用 set()
时,主要格式必须为 。
camera
是否允许网站使用摄像头。以下各项中的一项:allow
:允许网站使用摄像头;block
:不允许网站使用摄像头;
ask
:在网站想使用摄像头时询问您。
默认值为 ask
。
主要网址是请求相机访问权限的文档的网址。而不会使用辅助网址。
注意:如果两种模式均为 '',则 'allow' 设置无效。
clipboard
是否允许网站通过 Async Clipboard API 的高级功能访问剪贴板。“高级”功能包括在用户手势后写入内置格式之外的任何内容,即读取功能、编写自定义格式的功能以及无需用户手势即可书写的功能。以下各项之一:allow
:允许网站使用高级剪贴板功能;
block
:不允许网站使用高级剪贴板功能;
ask
:在网站想使用高级剪贴板功能时询问。
默认值为 ask
。
主要网址是请求剪贴板访问权限的文档的网址。而不会使用辅助网址。
cookies
是否允许网站设置 Cookie 和其他本地数据。以下各项中的一项:allow
:接受 Cookie;block
:阻止 Cookie;session\_only
:仅接受当前会话的 Cookie。
默认值为 allow
。
主要网址是代表 Cookie 来源的网址。辅助网址是顶级框架的网址。
fullscreen
已弃用。不再有任何效果。现在,系统会自动为所有网站授予全屏权限。值始终为 allow
。
images
是否显示图片。allow
:显示图片;block
:不显示图片。默认值为 allow
。
主要网址是顶级框架的网址。次要网址是图片的网址。
javascript
是否运行 JavaScript。allow
:运行 JavaScript;block
:不运行 JavaScript。默认值为 allow
。
主要网址是顶级框架的网址。而不会使用辅助网址。
location
是否允许地理定位。allow
:允许网站跟踪您的实际位置;block
:不允许网站跟踪您的地理位置;ask
:在允许网站跟踪您的实际位置之前询问您。
默认值为 ask
。
主要网址是请求位置数据的文档的网址。辅助网址是顶级框架的网址(可能与请求网址不同,也可能不同)。
microphone
是否允许网站使用麦克风。以下各项之一:allow
:允许网站使用麦克风;
block
:不允许网站使用麦克风;
ask
:当网站想使用麦克风时询问您。
默认值为 ask
。
主要网址是请求麦克风使用权限的文档的网址。而不会使用辅助网址。
注意:如果两种模式均为 '',则 'allow' 设置无效。
mouselock
已弃用。不再有任何效果。现在,系统会自动为所有网站授予鼠标锁定权限。值始终为 allow
。
notifications
是否允许网站显示桌面通知。allow
:允许网站显示桌面通知;block
:不允许网站显示桌面通知;ask
:在网站要显示桌面通知时询问。
默认值为 ask
。
主网址是要显示通知的文档的网址。而不会使用辅助网址。
plugins
已弃用。Chrome 88 不再支持 Flash,因此此权限不再有效。值始终为 block
。对 set()
和 clear()
的调用将被忽略。
popups
是否允许网站显示弹出式窗口。allow
:允许网站显示弹出式窗口;block
:不允许网站显示弹出式窗口。默认值为 block
。
主要网址是顶级框架的网址。而不会使用辅助网址。
unsandboxedPlugins
已弃用。之前,这种权限控制着是否允许网站在未经过沙盒屏蔽的情况下运行插件,但是,随着 Chrome 88 中的 Flash 代理进程被移除,此权限不再有效。值始终为 block
。对 set()
和 clear()
的调用将被忽略。