此页面由 Cloud Translation API 翻译。

chrome.contentSettings

说明

您可以使用 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

Chrome 113 及更高版本

枚举

"允许"

“屏蔽”

CameraContentSetting

Chrome 46 及更高版本

枚举

"允许"

“屏蔽”

"问"

ClipboardContentSetting

Chrome 121 及更高版本

枚举

"允许"

“屏蔽”

"问"

ContentSetting

属性

清除

void

<ph type="x-smartling-placeholder"></ph> 承诺

清除此扩展程序设置的所有内容设置规则。

clear 函数如下所示：
```
(details: object, callback?: function) => {...}
```
- 详细信息
  
  对象
  - 范围
    
    范围（可选）
    
    清除设置的位置（默认值：常规）。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
() => void
```
- 返回
  承诺<void>
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
get

void

<ph type="x-smartling-placeholder"></ph> 承诺

获取给定一对网址的当前内容设置。

get 函数如下所示：
```
(details: object, callback?: function) => {...}
```
- 详细信息
  
  对象
  - 无痕模式
    
    布尔值（可选）
    
    是否检查无痕会话的内容设置。（默认值为 false）
  - primaryUrl
    
    字符串
    
    要为其检索内容设置的主网址。请注意，主网址的含义取决于内容类型。
  - resourceIdentifier
    
    ResourceIdentifier（选填）
    
    要检索其设置的内容类型的更具体的标识符。
  - secondaryUrl
    
    字符串（可选）
    
    应检索其内容设置的辅助网址。默认为主网址。请注意，辅助网址的含义取决于内容类型，并非所有内容类型都会使用辅助网址。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
(details: object) => void
```
  - 详细信息
    
    对象
    
    设置
    
    T
    
    内容设置。有关可能的值，请参阅各个 ContentSetting 对象的说明。
- 返回
  Promise<object>
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getResourceIdentifiers

void

<ph type="x-smartling-placeholder"></ph> 承诺

getResourceIdentifiers 函数如下所示：
```
(callback?: function) => {...}
```
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
(resourceIdentifiers?: ResourceIdentifier[]) => void
```
  - resourceIdentifiers
    
    ResourceIdentifier[] 选填
    
    此内容类型的资源标识符列表；如果此内容类型不使用资源标识符，则为 undefined。
- 返回
  Promise<ResourceIdentifier[]>ResourceIdentifier
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
set

void

<ph type="x-smartling-placeholder"></ph> 承诺

应用新的内容设置规则。

set 函数如下所示：
```
(details: object, callback?: function) => {...}
```
- 详细信息
  
  对象
  - primaryPattern
    
    字符串
    
    主网址的格式。要详细了解格式格式，请参阅内容设置格式。
  - resourceIdentifier
    
    ResourceIdentifier（选填）
    
    内容类型的资源标识符。
  - 范围
    
    范围（可选）
    
    在何处设置该设置（默认值：常规）。
  - secondaryPattern
    
    字符串（可选）
    
    辅助网址的格式。默认为匹配所有网址。要详细了解格式格式，请参阅内容设置格式。
  - 设置
    
    任意
    
    此规则应用的设置。有关可能的值，请参阅各个 ContentSetting 对象的说明。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
() => void
```
- 返回
  承诺<void>
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

CookiesContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

"session_only"

FullscreenContentSetting

Chrome 44 及更高版本

值

"允许"

ImagesContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

JavascriptContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

LocationContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

"问"

MicrophoneContentSetting

Chrome 46 及更高版本

枚举

"允许"

“屏蔽”

"问"

MouselockContentSetting

Chrome 44 及更高版本

值

"允许"

MultipleAutomaticDownloadsContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

"问"

NotificationsContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

"问"

PluginsContentSetting

Chrome 44 及更高版本

值

“屏蔽”

PopupsContentSetting

Chrome 44 及更高版本

枚举

"允许"

“屏蔽”

PpapiBrokerContentSetting

Chrome 44 及更高版本

值

“屏蔽”

ResourceIdentifier

唯一使用资源标识符的内容类型是 contentSettings.plugins。如需了解详情，请参阅资源标识符。

属性

说明

字符串（可选）

人类可读的资源说明。
id

字符串

给定内容类型的资源标识符。

Scope

Chrome 44 及更高版本

ContentSetting 的范围。以下之一： regular：常规个人资料的设置（如果未在其他地方替换，则无痕个人资料会继承此设置） incognito\_session\_only：为无痕模式个人资料指定的设置，只能在无痕式会话期间设置，并且在无痕式会话结束时被删除（覆盖常规设置）。

枚举

"regular"

“audience_session_only”

属性

automaticDownloads

是否允许网站自动下载多个文件。以下之一： allow：允许网站自动下载多个文件； block：不允许网站自动下载多个文件； ask：当网站想在下载第一个文件后自动下载文件时询问您。默认值为 ask。主网址是顶级框架的网址。未使用辅助网址。

类型

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 及更高版本

是否允许网站使用 Private State Tokens API。以下之一： allow：允许网站使用 Private State Tokens API。 block：禁止网站使用 Private State Tokens API。默认值为 allow。主网址是顶级框架的网址。未使用辅助网址。注意：调用 set() 时，主要模式必须为。

类型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 及更高版本

是否允许网站使用摄像头。以下之一： allow：允许网站使用摄像头； block：不允许网站使用摄像头； ask：在网站想使用摄像头时询问您。默认值为 ask。主网址是请求相机访问权限的文档的网址。未使用辅助网址。注意：“允许”规则如果两种格式均为 ''，则设置无效。

类型

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 及更高版本

是否允许网站通过 Async Clipboard API 的高级功能访问剪贴板。“高级”功能包括除在用户手势后写入内置格式（即读取、写入自定义格式以及无需用户手势即可撰写）之外的所有功能。以下之一： allow：允许网站使用高级剪贴板功能； block：不允许网站使用高级剪贴板功能； ask：在网站想使用高级剪贴板功能时询问您。默认值为 ask。主网址是请求剪贴板访问权限的文档的网址。未使用辅助网址。

类型

ContentSetting<ClipboardContentSetting>

cookies

是否允许网站设置 Cookie 和其他本地数据。以下之一： allow：接受 Cookie； block：屏蔽 Cookie session\_only：仅接受当前会话的 Cookie。默认值为 allow。主网址是表示 Cookie 来源的网址。次要网址是顶级框架的网址。

类型

ContentSetting<CookiesContentSetting>

fullscreen

已弃用。不再有任何作用。现在，系统会自动为所有网站授予全屏权限。值始终为 allow。

类型

ContentSetting<FullscreenContentSetting>

images

是否显示图片。以下之一： allow：显示图片； block：不显示图片。默认值为 allow。主网址是顶级框架的网址。辅助网址是图片的网址。

类型

ContentSetting<ImagesContentSetting>

javascript

是否运行 JavaScript。以下之一： allow：运行 JavaScript。 block：不运行 JavaScript。默认值为 allow。主网址是顶级框架的网址。未使用辅助网址。

类型

ContentSetting<JavascriptContentSetting>

location

是否允许地理定位。以下之一： allow：允许网站跟踪您的地理位置。 block：不允许网站跟踪您的地理位置。 ask：需先询问，得到许可后才允许网站跟踪您的地理位置。默认值为 ask。主网址是请求位置数据的文档的网址。辅助网址是顶级框架的网址（可能与请求网址不同，也可能没有不同）。

类型

ContentSetting<LocationContentSetting>

microphone

Chrome 46 及更高版本

是否允许网站使用麦克风。以下之一： allow：允许网站使用麦克风， block：不允许网站使用麦克风。 ask：在网站想使用麦克风时询问您。默认值为 ask。主网址是请求麦克风访问权限的文档的网址。未使用辅助网址。注意：“允许”规则如果两种格式均为 ''，则设置无效。

类型

ContentSetting<MicrophoneContentSetting>

mouselock

已弃用。不再有任何作用。现在，系统会自动为所有网站授予鼠标锁定权限。值始终为 allow。

类型

ContentSetting<MouselockContentSetting>

notifications

是否允许网站显示桌面通知。以下之一： allow：允许网站显示桌面通知； block：不允许网站显示桌面通知； ask：在网站要显示桌面通知时询问您。默认值为 ask。主网址是想要显示通知的文档的网址。未使用辅助网址。

类型

ContentSetting<NotificationsContentSetting>

plugins

已弃用。Chrome 88 中取消了对 Flash 的支持，因此此权限不再有效。值始终为 block。对 set() 和 clear() 的调用将被忽略。

类型

ContentSetting<PluginsContentSetting>

popups

是否允许网站显示弹出式窗口。以下之一： allow：允许网站显示弹出式窗口； block：不允许网站显示弹出式窗口。默认值为 block。主网址是顶级框架的网址。未使用辅助网址。

类型

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

已弃用。以前，该权限控制是否允许网站运行未经过沙盒屏蔽的插件，但是现在，Chrome 88 中移除了 Flash 代理进程，因此此权限不再有效。值始终为 block。对 set() 和 clear() 的调用将被忽略。

类型

ContentSetting<PpapiBrokerContentSetting>