chrome.contentSettings

Description

使用 chrome.contentSettings API 更改控制网站是否可以使用 cookie、JavaScript 和插件等功能的设置。更一般地说，内容设置允许您基于每个站点而不是全局自定义 Chrome 的行为。

Permissions

contentSettings

# Manifest

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

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

# Content setting patterns(内容设置模式)

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

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

# Pattern precedence(模式优先级)

当多个内容设置规则应用于给定站点时，具有更具体模式的规则优先。

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

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

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

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

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

1. https://www.example.com:*/* 指定主机名和方案。
2. *:/www.example.com:123/* 没有那么高，因为虽然指定了主机名，但是没有指定scheme。
3. https://*.example.com:123/* 较低，因为虽然它指定了端口和方案，但它在主机名中有一个通配符。

# Primary and secondary patterns(主要和次要模式)

在决定应用哪个内容设置时考虑的 URL 取决于内容类型。例如，对于 contentSettings.notifications，设置基于多功能框中显示的 URL。此 URL 称为“主”URL。

某些内容类型可以考虑其他 URL。例如，是否允许站点设置 contentSettings.cookies 取决于 HTTP 请求的 URL（在这种情况下是主 URL）以及多功能框中显示的 URL（称为“辅助 URL”）。 "网址）。

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

# Resource identifiers(资源标识符)

资源标识符允许您为内容类型的特定子类型指定内容设置。目前，唯一支持资源标识符的内容类型是 contentSettings.plugins，其中资源标识符标识特定插件。应用内容设置时，首先检查特定插件的设置。如果没有找到特定插件的设置，则会检查插件的常规内容设置。

例如，如果内容设置规则具有资源标识符 adobe-flash-player 和模式 <all_urls>，它优先于没有资源标识符和模式 https://www.example.com/* 的规则，即使该模式更具体。

您可以通过调用 contentSettings.ContentSetting.getResourceIdentifiers 方法来获取内容类型的资源标识符列表。返回的列表可能会随着用户机器上安装的插件集而变化，但 Chrome 会尝试在插件更新时保持标识符稳定。

# Examples(例子)

您可以在示例页面上找到此 API 的示例。

Summary

• Types

  CameraContentSetting

  ContentSetting

  CookiesContentSetting

  FullscreenContentSetting

  ImagesContentSetting

  JavascriptContentSetting

  LocationContentSetting

  MicrophoneContentSetting

  MouselockContentSetting

  MultipleAutomaticDownloadsContentSetting

  NotificationsContentSetting

  PluginsContentSetting

  PopupsContentSetting

  PpapiBrokerContentSetting

  ResourceIdentifier

  Scope

• Properties

  automaticDownloads

  camera

  cookies

  fullscreen

  images

  javascript

  location

  microphone

  mouselock

  notifications

  plugins

  popups

  unsandboxedPlugins

Types

CameraContentSetting

Chrome 46+

TYPE

"allow", "block", or "ask"

ContentSetting

PROPERTIES

• clear

  function

  Promise

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

  The clear function looks like:

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

  • details

    object

    • scope

      Scope optional

      在哪里清除设置（默认：regular）。

• callback

  function optional

  The callback parameter looks like:

  () => void

  • returns

  Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

• get

  function

  Promise

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

  The get function looks like:

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

  • details

    object

    • incognito

      boolean optional

      是否检查隐身会话的内容设置。 （默认为false）

    • primaryUrl

      string

      应为其检索内容设置的主 URL。请注意，主 URL 的含义取决于内容类型。

    • resourceIdentifier

      ResourceIdentifier optional

      应为其检索设置的内容类型的更具体标识符。

    • secondaryUrl

      string optional

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

• callback

  function optional

  The callback parameter looks like:

  (details: object) => void

  • details

    object

    • setting

      T

      内容设置。有关可能的值，请参阅各个 ContentSetting 对象的描述。

• returns

  Promise<object>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

• getResourceIdentifiers

  function

  Promise

  The getResourceIdentifiers function looks like:

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

  • callback

    function optional

    The callback parameter looks like:

    (resourceIdentifiers?: ResourceIdentifier[]) => void

    • resourceIdentifiers

      ResourceIdentifier[] optional

      此内容类型的资源标识符列表，如果此内容类型不使用资源标识符，则未定义。

• returns

  Promise<ResourceIdentifier[]>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

• set

  function

  Promise

  应用新的内容设置规则。

  The set function looks like:

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

  • details

    object

    • primaryPattern

      string

      主 URL 的模式。有关模式格式的详细信息，请参阅内容设置模式Content Setting Patterns。

    • resourceIdentifier

      ResourceIdentifier optional

      内容类型的资源标识符。

    • scope

      Scope optional

      在哪里设置设置（默认： regular)。

    • secondaryPattern

      string optional

      辅助 URL 的模式。默认匹配所有 URL。有关模式格式的详细信息，请参阅 Content Setting Patterns.

    • setting

      any

      此规则应用的设置。有关可能的值，请参阅各个 ContentSetting 对象的描述。

• callback

  function optional

  The callback parameter looks like:

  () => void

  • returns

  Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

CookiesContentSetting

Chrome 44+

TYPE

"allow", "block", or "session_only"

FullscreenContentSetting

Chrome 44+

VALUE

"allow"

ImagesContentSetting

Chrome 44+

TYPE

"allow", or "block"

JavascriptContentSetting

Chrome 44+

TYPE

"allow", or "block"

LocationContentSetting

Chrome 44+

TYPE

"allow", "block", or "ask"

MicrophoneContentSetting

Chrome 46+

TYPE

"allow", "block", or "ask"

MouselockContentSetting

Chrome 44+

VALUE

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44+

TYPE

"allow", "block", or "ask"

NotificationsContentSetting

Chrome 44+

TYPE

"allow", "block", or "ask"

PluginsContentSetting

Chrome 44+

VALUE

"block"

PopupsContentSetting

Chrome 44+

TYPE

"allow", or "block"

PpapiBrokerContentSetting

Chrome 44+

TYPE

"allow", "block", or "ask"

ResourceIdentifier

唯一使用资源标识符的内容类型是 contentSettings.plugins。有关更多信息，请参阅资源标识符Resource Identifiers。

PROPERTIES

• description

  string optional

  人类可读的资源描述

• id

  string

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

Scope

Chrome 44+

ContentSetting 的范围。regular之一：常规配置文件的设置（如果没有在其他地方覆盖，则由隐身配置文件继承），incognito\_session\_only：隐身配置文件的设置，只能在隐身会话期间设置，并在隐身会话结束时删除（覆盖常规设置）。

TYPE

"regular", or "incognito_session_only"

Properties

automaticDownloads

是否允许站点自动下载多个文件。allow之一：允许站点自动下载多个文件，block：不允许站点自动下载多个文件，ask：询问站点何时要在第一个文件之后自动下载文件。默认是ask。主 URL 是顶级框架的 URL。不使用辅助 URL。

TYPE

ContentSetting<MultipleAutomaticDownloadsContentSetting>

camera

Chrome 46+

是否允许站点访问摄像头。allow之一：允许站点访问摄像头，block：不允许站点访问摄像头，ask：询问站点何时要访问摄像头。默认是ask。主 URL 是请求访问相机的文档的 URL。不使用辅助 URL。注意：如果两个模式都是 ''，则 'allow' 设置无效。

TYPE

ContentSetting<CameraContentSetting>

cookies

是否允许网站设置 cookie 和其他本地数据。allow之一：接受 cookie，block：阻止 cookie， session\_only：仅接受当前会话的 cookie。默认为allow。主 URL 是表示 cookie 来源的 URL。二级 URL 是顶级框架的 URL。

TYPE

ContentSetting<CookiesContentSetting>

fullscreen

已弃用。不再有任何影响。现在会自动为所有站点授予全屏权限。值总是allow的。

TYPE

ContentSetting<FullscreenContentSetting>

images

是否显示图片。allow之一：显示图像，block：不显示图像。默认为allow。主 URL 是顶级框架的 URL。辅助(secondary) URL 是图像的 URL。

TYPE

ContentSetting<ImagesContentSetting>

javascript

是否运行 JavaScript。allow之一：运行 JavaScript，block：不运行 JavaScript。默认为allow。主 URL 是顶级框架的 URL。不使用辅助 URL。

TYPE

ContentSetting<JavascriptContentSetting>

location

是否允许地理定位。allow之一：允许站点跟踪您的物理位置，block：不允许站点跟踪您的物理位置，ask：在允许站点跟踪您的物理位置之前询问。默认是ask。主 URL 是请求位置数据的文档的 URL。辅助 URL 是顶级框架的 URL（可能与请求 URL 不同，也可能不同）。

TYPE

ContentSetting<LocationContentSetting>

microphone

Chrome 46+

是否允许站点访问麦克风。allow之一：允许站点访问麦克风，block：不允许站点访问麦克风，ask：询问站点何时要访问麦克风。默认是ask。主 URL 是请求麦克风访问的文档的 URL。不使用辅助 URL。注意：如果两个模式都是 ''，则 'allow' 设置无效。

TYPE

ContentSetting<MicrophoneContentSetting>

mouselock

已弃用。不再有任何影响。现在会自动为所有站点授予鼠标锁定权限。值总是allow的。

TYPE

ContentSetting<MouselockContentSetting>

notifications

是否允许站点显示桌面通知。allow之一：允许站点显示桌面通知，block：不允许站点显示桌面通知，ask：询问站点何时想要显示桌面通知。默认是ask.主 URL 是要显示通知的文档的 URL。不使用辅助 URL。

TYPE

ContentSetting<NotificationsContentSetting>

plugins

已弃用。在 Chrome 88 中删除 Flash 支持后，此权限不再有效。值总是block。对 set() 和 clear() 的调用将被忽略。

TYPE

ContentSetting<PluginsContentSetting>

popups

是否允许网站显示弹出窗口。allow之一：允许站点显示弹出窗口，block：不允许站点显示弹出窗口。默认为block。主 URL 是顶级框架的 URL。不使用辅助 URL。

TYPE

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

是否允许站点运行未经过沙盒处理的插件。allow之一：允许站点运行未经沙箱的插件，block：不允许站点运行未经沙箱的插件，ask：当站点想要运行未经沙箱的插件时询问。默认是ask。主 URL 是顶级框架的 URL。不使用辅助 URL。

TYPE

ContentSetting<PpapiBrokerContentSetting>

By.一粒技术服务