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

枚举

"block"

CameraContentSetting

Chrome 46 及更高版本

枚举

"block"

ClipboardContentSetting

Chrome 121 及更高版本

枚举

"block"

ContentSetting

属性

清除

void

Promise

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

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

void

Promise

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

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

void

Promise

应用新的内容设置规则。

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

CookiesContentSetting

Chrome 44 及更高版本

枚举

"block"

"session_only"

FullscreenContentSetting

Chrome 44 及更高版本

值

ImagesContentSetting

Chrome 44 及更高版本

枚举

"block"

JavascriptContentSetting

Chrome 44 及更高版本

枚举

"block"

LocationContentSetting

Chrome 44 及更高版本

枚举

"block"

MicrophoneContentSetting

Chrome 46 及更高版本

枚举

"block"

MouselockContentSetting

Chrome 44 及更高版本

值

MultipleAutomaticDownloadsContentSetting

Chrome 44 及更高版本

枚举

"block"

NotificationsContentSetting

Chrome 44 及更高版本

枚举

"block"

PluginsContentSetting

Chrome 44 及更高版本

值

"block"

PopupsContentSetting

Chrome 44 及更高版本

枚举

"block"

PpapiBrokerContentSetting

Chrome 44 及更高版本

值

"block"

ResourceIdentifier

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

属性

说明

字符串（可选）

直观易懂的资源说明。
id

string

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

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。主要网址是请求相机访问权限的文档的网址。而不会使用辅助网址。注意：如果两种模式均为 ''，则 'allow' 设置无效。

类型

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。主要网址是请求麦克风使用权限的文档的网址。而不会使用辅助网址。注意：如果两种模式均为 ''，则 'allow' 设置无效。