browser.contentSettings

说明

使用 chrome.contentSettings API 可更改用于控制网站是否可以使用 Cookie、JavaScript 和插件等功能的设置。更笼统地说，内容设置可让您针对每个网站（而非全局）自定义 Chrome 的行为。

权限

contentSettings

您必须在扩展程序的清单中声明 "contentSettings" 权限，才能使用该 API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

概念和用法

内容设置模式

您可以使用模式来指定每项内容设置会影响哪些网站。例如，https://*.youtube.com/* 指定 youtube.com 及其所有子网域。内容设置模式的语法与匹配模式相同，但有一些区别：

  • 对于 http、https 和 ftp 网址，路径必须是通配符 (/*)。对于 file 网址，必须完整指定路径，并且不得包含通配符。
  • 与匹配模式不同，内容设置模式可以指定端口号。如果指定了端口号，则该格式仅匹配具有该端口的网站。如果未指定端口号，则该模式会匹配所有端口。

模式优先级

如果有多条内容设置规则适用于某个网站，则采用格式更具体的规则。

例如，以下模式按优先级排序：

  1. https://www.example.com/*
  2. https://*.example.com/*（匹配 example.com 和所有子网域）
  3. <all_urls>（匹配每个网址）

有三种通配符会影响模式的具体程度：

  • 端口中的通配符（例如 https://www.example.com:*/*）
  • 协议中的通配符（例如 *://www.example.com:123/*）
  • 主机名中的通配符（例如 https://*.example.com:123/*）

如果一个模式在某一部分比另一个模式更具体，但在另一部分不那么具体，则会按以下顺序检查不同的部分：主机名、架构、端口。例如，以下模式按优先级排序：

  1. https://www.example.com:*/* 指定主机名和架构。
  2. *:/www.example.com:123/* 不高，因为虽然它指定了主机名，但未指定架构。
  3. https://*.example.com:123/* 较低，因为虽然它指定了端口和 scheme，但主机名中包含通配符。

主要模式和次要模式

在决定应用哪项内容设置时，系统会根据内容类型来考虑网址。 例如，对于 contentSettings.notifications，设置取决于多功能框中显示的网址。此网址称为“主要”网址。

某些内容类型可以考虑其他网址。例如，是否允许网站设置 contentSettings.cookies 是根据 HTTP 请求的网址（在本例中为主网址）以及多功能框中显示的网址（称为“次要”网址）来决定的。

如果多条规则具有主要和次要格式，则主要格式更具体的规则优先。如果多条规则具有相同的主要格式，则具有更具体次要格式的规则优先。例如，以下主要/次要模式对列表按优先级排序：

优先级主要图案次要模式
1https://www.moose.com/*、https://www.wombat.com/*
2https://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 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

CameraContentSetting

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

ContentSetting

属性

  • 清除

    void

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

    clear 函数如下所示： 

    (details: object) => {...}

    • 详细信息

      对象

      • 范围

        Scope 可选

        清除设置的位置（默认：常规）。

    • 返回

      承诺<void>

      Chrome 96 及更高版本 browser.*（自 Chrome 148 起）
  • get

    void

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

    get 函数如下所示： 

    (details: object) => {...}

    • 详细信息

      对象

      • 无痕模式

        布尔值 （可选）

        是否检查无痕式会话的内容设置。（默认值为 false）

      • primaryUrl

        字符串

        要检索的内容设置所对应的主网址。请注意，主要网址的含义取决于内容类型。

      • resourceIdentifier

        ResourceIdentifier 可选

        更具体的内容类型标识符，用于指定应检索哪些内容的设置。

      • secondaryUrl

        字符串 可选

        应检索其内容设置的次要网址。默认为主网址。请注意，次要网址的含义取决于内容类型，并且并非所有内容类型都使用次要网址。

    • 返回

      Promise<object>

      Chrome 96 及更高版本 browser.*（自 Chrome 148 起）
  • getResourceIdentifiers

    void

    getResourceIdentifiers 函数如下所示： 

    () => {...}

    • 返回

      Promise<ResourceIdentifier[]>

      Chrome 96 及更高版本 browser.*（自 Chrome 148 起）
  • set

    void

    应用新的内容设置规则。

    set 函数如下所示： 

    (details: object) => {...}

    • 详细信息

      对象

      • primaryPattern

        字符串

        主要网址的格式。如需详细了解格式，请参阅内容设置格式。

      • resourceIdentifier

        ResourceIdentifier 可选

        内容类型的资源标识符。

      • 范围

        Scope 可选

        设置的范围（默认：regular）。

      • secondaryPattern

        字符串 可选

        辅助网址的格式。默认情况下，此政策会匹配所有网址。如需详细了解格式，请参阅内容设置格式。

      • 设置

        任意

        此规则应用的设置。如需了解可能的值，请参阅各个 ContentSetting 对象的说明。

    • 返回

      承诺<void>

      Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

CookiesContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

值

"allow"

ImagesContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

JavascriptContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

LocationContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

值

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

值

"block"

PopupsContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

值

"block"

ResourceIdentifier

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

属性

  • 说明

    字符串 可选

    资源的人类可读说明。

  • id

    字符串

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

Scope

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

ContentSetting 的范围。regular：常规个人资料的设置（如果未在其他位置被覆盖，则由无痕式个人资料继承）； incognito\_session\_only：无痕式个人资料的设置，只能在无痕式会话期间设置，并在无痕式会话结束时删除（会覆盖常规设置）。

枚举

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141 及更高版本 browser.*（自 Chrome 148 起）

枚举

"allow"

"block"

属性

automaticDownloads

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

类型

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 及更高版本 browser.*（自 Chrome 148 起）

是否允许网站使用 Private State Tokens API。allow：允许网站使用 Private State Tokens API block：禁止网站使用 Private State Tokens API 默认值为 allow。 调用 set() 时，主网址格式必须为 <all_urls>。系统不会使用辅助网址。

类型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

是否允许网站使用摄像头。allow：允许网站使用摄像头 block：不允许网站使用摄像头 ask：当网站想要使用摄像头时询问用户 默认值为 ask。 主要网址是请求相机访问权限的文档的网址。不使用辅助网址。 注意：如果两个模式均为“<all_urls>”，则“allow”设置无效。

类型

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 及更高版本 browser.*（自 Chrome 148 起）

是否允许网站通过 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 及更高版本 browser.*（自 Chrome 148 起）

是否允许网站访问麦克风。allow：允许网站使用麦克风 block：不允许网站使用麦克风 ask：当网站想要使用麦克风时询问用户 默认值为 ask。 主要网址是指请求麦克风访问权限的文档的网址。不使用辅助网址。 注意：如果两个模式都是“<all_urls>”，则“allow”设置无效。

类型

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>