chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

说明

使用 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 及更高版本

枚举

"allow"

"block"

CameraContentSetting

Chrome 46 及更高版本

枚举

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 及更高版本

枚举

"allow"

"block"

"ask"

ContentSetting

属性

  • 清除

    void

    Promise

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

    clear 函数如下所示： 

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

    • 详细信息

      对象

      • 范围

        Scope 可选

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

    • callback

      函数可选

      callback 参数如下所示： 

      () => void

    • 返回

      承诺<void>

      Chrome 96 及更高版本

      只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • get

    void

    Promise

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

    get 函数如下所示： 

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

    • 详细信息

      对象

      • 无痕模式

        布尔值 （可选）

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

      • primaryUrl

        字符串

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

      • resourceIdentifier

        ResourceIdentifier 可选

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

      • secondaryUrl

        字符串 可选

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

    • callback

      函数可选

      callback 参数如下所示： 

      (details: object) => void

      • 详细信息

        对象

        • 设置

          T

          内容设置。如需了解可能的值，请参阅各个 ContentSetting 对象的说明。

    • 返回

      Promise<object>

      Chrome 96 及更高版本

      只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • getResourceIdentifiers

    void

    Promise

    getResourceIdentifiers 函数如下所示： 

    (callback?: function) => {...}

    • callback

      函数可选

      callback 参数如下所示： 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] 可选

        此内容类型的资源标识符列表；如果此内容类型不使用资源标识符，则为 undefined。

    • 返回

      Promise<ResourceIdentifier[]>

      Chrome 96 及更高版本

      只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • set

    void

    Promise

    应用新的内容设置规则。

    set 函数如下所示： 

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

    • 详细信息

      对象

      • primaryPattern

        字符串

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

      • resourceIdentifier

        ResourceIdentifier 可选

        内容类型的资源标识符。

      • 范围

        Scope 可选

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

      • secondaryPattern

        字符串 可选

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

      • 设置

        任意

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

    • callback

      函数可选

      callback 参数如下所示： 

      () => void

    • 返回

      承诺<void>

      Chrome 96 及更高版本

      只有 Manifest V3 及更高版本支持 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"

SoundContentSetting

Chrome 141 及更高版本

枚举

"allow"

"block"

属性

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() 时，主网址格式必须为 <all_urls>。系统不会使用辅助网址。

类型

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 及更高版本

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