chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

说明

使用 chrome.declarativeContent API 可根据网页内容采取相应行动，而无需获得读取网页内容的权限。

权限

declarativeContent

用法

借助 Declarative Content API，您可以根据网页的网址或 CSS 选择器是否与网页上的元素匹配来启用扩展程序的操作，而无需添加主机权限或注入内容脚本。

使用 activeTab 权限在用户点击扩展程序的操作后与网页互动。

规则

规则由条件和操作组成。如果满足任何条件，系统都会执行所有操作。相应操作为 setIcon 和 showAction。

当且仅当满足所有列出的条件时，PageStateMatcher 才会匹配网页。它可以匹配网页网址、CSS 复合选择器或网页的添加为书签状态。以下规则可在 Google 网页上存在密码字段时启用扩展程序的相应操作：

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

如需针对包含视频的 Google 网站也启用扩展程序的相应操作，您可以添加第二个条件，因为每个条件都足以触发所有指定的操作：

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

onPageChanged 事件用于测试是否有任何规则至少满足一个条件，并执行相应操作。规则在浏览会话之间保持不变；因此，在扩展程序安装时，您应先使用 removeRules 清除之前安装的规则，然后使用 addRules 注册新规则。

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

获得 activeTab 权限后，扩展程序不会显示任何权限警告，并且当用户点击扩展程序操作时，扩展程序只会运行在相关网页上。

网页网址匹配

当满足网址条件时，PageStateMatcher.pageurl 会匹配。最常见的条件是主机、路径或网址的串联，后跟“包含”“等于”“前缀”或“后缀”。下表列出了一些示例：

条件 组合
{ hostSuffix: 'google.com' } 所有 Google 网址
{ pathPrefix: '/docs/extensions' } 扩展程序文档网址
{ urlContains: 'developer.chrome.com' } 所有 Chrome 开发者文档网址

所有条件都区分大小写。如需查看条件的完整列表，请参阅 UrlFilter。

CSS 匹配

PageStateMatcher.css 条件必须是复合选择器，这意味着您不能在选择器中添加空格或“>”等组合器。这有助于 Chrome 更高效地匹配选择器。

复合选择器（确定） 复杂选择器（不正常）
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

CSS 条件仅匹配显示的元素：如果与选择器匹配的元素为 display:none 或其某个父元素为 display:none，则不会导致条件匹配。使用 visibility:hidden 设置样式的元素、位于屏幕外的元素或被其他元素隐藏的元素仍可使您的条件匹配。

书签状态匹配

PageStateMatcher.isBookmarked 条件允许匹配用户个人资料中当前网址的书签状态。如需使用此条件，必须在扩展程序清单中声明“书签”权限。

类型

类型

ImageData

PageStateMatcher

根据各种条件匹配网页的状态。

属性

  • 构造函数

    void

    constructor 函数如下所示： 

    (arg: PageStateMatcher) => {...}

  • css

    string[] 可选

    如果数组中的所有 CSS 选择器都与框架中显示的元素（与网页的主框架具有相同的来源）匹配，则匹配。此数组中的所有选择器都必须是复合选择器，以加快匹配速度。注意：列出数百个 CSS 选择器或列出每个网页匹配数百次的 CSS 选择器可能会导致网站速度变慢。

  • isBookmarked

    布尔值 （可选）

    Chrome 45 及更高版本

    如果网页的已添加书签状态等于指定值，则匹配。需要书签权限。

  • pageUrl

    UrlFilter（可选）

    如果网页的顶级网址满足 UrlFilter 的条件，则匹配。

RequestContentScript

用于注入内容脚本的声明性事件操作。

警告：此操作仍处于实验阶段，Chrome 的稳定 build 不支持此操作。

属性

  • 构造函数

    void

    constructor 函数如下所示： 

    (arg: RequestContentScript) => {...}

  • allFrames

    布尔值 （可选）

    内容脚本是在匹配网页的所有框架中运行，还是仅在顶部框架中运行。默认值为 false。

  • css

    string[] 可选

    要作为内容脚本的一部分注入的 CSS 文件的名称。

  • js

    string[] 可选

    要作为内容脚本的一部分注入的 JavaScript 文件的名称。

  • matchAboutBlank

    布尔值 （可选）

    是否在 about:blank 和 about:srcdoc 上插入内容脚本。默认值为 false。

SetIcon

声明性事件操作，用于在满足相应条件时，为扩展程序的网页操作或浏览器操作设置 n-dip 正方形图标。此操作可在没有主机权限的情况下使用，但扩展程序必须具有页面操作或浏览器操作。

必须且只能指定 imageData 和 path 中的一个。两者都是将像素数映射到图片表示形式的字典。imageData 中的图片表示形式是 ImageData 对象（例如来自 canvas 元素），而 path 中的图片表示形式是相对于扩展程序清单的图片文件路径。如果 scale 屏幕像素可以容纳在一个与设备无关的像素中，则使用 scale * n 图标。如果缺少该比例，系统会将另一张图片调整为所需大小。

属性

  • 构造函数

    void

    constructor 函数如下所示： 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | 对象 可选

    要设置的图标，可以是 ImageData 对象，也可以是表示图标的字典 {size -> ImageData}。如果图标指定为字典，则所用图片会根据屏幕的像素密度来选择。如果一个屏幕空间单位中可容纳的图片像素数为 scale，则选择大小为 scale * n 的图片，其中 n 是界面中图标的大小。必须至少指定一张图片。请注意，details.imageData = foo 等同于 details.imageData = {'16': foo}。

ShowAction

Chrome 97 及更高版本

一种声明性事件操作，用于在满足相应条件时将扩展程序的工具栏操作设置为启用状态。此操作无需主机权限即可使用。如果扩展程序具有 activeTab 权限，则点击网页操作会授予对当前有效标签页的访问权限。

在不满足条件的网页上，扩展程序的工具栏操作将显示为灰度，点击该操作将打开上下文菜单，而不是触发操作。

属性

ShowPageAction

自 Chrome 97 起已弃用

请使用 declarativeContent.ShowAction。

一种声明性事件操作，可在满足相应条件时将扩展程序的网页操作设置为启用状态。此操作可在没有主机权限的情况下使用，但扩展程序必须具有页面操作。如果扩展程序具有 activeTab 权限，则点击网页操作会授予对当前有效标签页的访问权限。

在不满足条件的网页上，扩展程序的工具栏操作将显示为灰度，点击该操作将打开上下文菜单，而不是触发操作。

属性

事件

onPageChanged

提供由 addRules、removeRules 和 getRules 组成的声明式事件 API。

条件

PageStateMatcher

操作

RequestContentScript

SetIcon

ShowPageAction

ShowAction