此页面由 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 及更高版本

枚举

"allow"

"block"

CameraContentSetting

Chrome 46 及更高版本

枚举

"allow"

"block"

ClipboardContentSetting

Chrome 121 及更高版本

枚举

"allow"

"block"

“ask”

ContentSetting

属性

清除

void

Promise

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

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

void

prometido

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

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

void

Promise

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

void

prometido

应用新的内容设置规则。

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

CookiesContentSetting

Chrome 44 及更高版本

枚举

"allow"

FullscreenContentSetting

Chrome 44 及更高版本

值

ImagesContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

JavascriptContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

LocationContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

MicrophoneContentSetting

Chrome 46 及更高版本

枚举

"allow"

"block"

MouselockContentSetting

Chrome 44 及更高版本

值

MultipleAutomaticDownloadsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

NotificationsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

PluginsContentSetting

Chrome 44 及更高版本

值

PopupsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 及更高版本

值

"block"

ResourceIdentifier

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

属性

说明

字符串（选填）

资源的直观易懂的说明。
id

字符串

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

Scope

Chrome 44 及更高版本

ContentSetting 的范围。regular：常规资料的设置（如果未在其他位置被替换，则会被无痕式资料继承）；incognito\_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>