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 网址，路径必须完全指定，且不得包含通配符。
  • 与匹配模式不同，内容设置模式可以指定端口号。如果指定了端口号，则该模式只会与使用该端口的网站匹配。如果未指定端口号，则该模式将与所有端口匹配。

模式优先级

如果有多个内容设置规则适用于给定网站，则优先级较高的规则（即模式更具体的规则）会应用于该网站。

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

  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，设置基于 Omnibox 中显示的网址。此网址称为“主要”网址。

某些内容类型可能会考虑其他网址。例如，网站是否可以设置 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 及更高版本

枚举

"allow"

"block"

CameraContentSetting

Chrome 46 及更高版本

枚举

"allow"

"block"

“ask”

ClipboardContentSetting

Chrome 121 及更高版本

枚举

"allow"

"block"

“ask”

ContentSetting

属性

  • 清除

    void

    prometido

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

    clear 函数如下所示： 

    (details: object, callback?: function) => {...}

    • 详细信息

      对象

      • 范围

        范围（可选）

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

    • callback

      函数（可选）

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<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 对象的说明。

    • 返回

      Promise<object>

      Chrome 96 及更高版本

      清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

  • getResourceIdentifiers

    void

    prometido

    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

    • 返回

      Promise<void>

      Chrome 96 及更高版本

      清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

CookiesContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 及更高版本

值

"allow"

ImagesContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

JavascriptContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

LocationContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

“ask”

MicrophoneContentSetting

Chrome 46 及更高版本

枚举

"allow"

"block"

“ask”

MouselockContentSetting

Chrome 44 及更高版本

值

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

“ask”

NotificationsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

“ask”

PluginsContentSetting

Chrome 44 及更高版本

值

"block"

PopupsContentSetting

Chrome 44 及更高版本

枚举

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 及更高版本

值

"block"

ResourceIdentifier

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

属性

  • 说明

    字符串（选填）

    资源的直观易懂的说明。

  • id

    字符串

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

Scope

Chrome 44 及更高版本

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

枚举

“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>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>