此页面由 Cloud Translation API 翻译。

chrome.declarativeContent

说明

使用 chrome.declarativeContent API 可根据网页内容执行操作，而无需读取网页内容的权限。

权限

declarativeContent

概念和用法

借助声明式 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 更高效地匹配选择器。

复合选择器 (OK)	复杂的选择器（不可行）
`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 条件允许匹配用户个人资料中当前网址的书签状态。若要利用此条件，必须在扩展程序清单中声明“bookmarks”权限。

类型

ImageDataType

请参阅 https://developer.mozilla.org/en-US/docs/Web/API/ImageData。

类型

ImageData

PageStateMatcher

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

属性

构造函数

void

constructor 函数如下所示：
```
(arg: PageStateMatcher)=> {...}
```
- 参数
  
  PageStateMatcher
- 返回
  PageStateMatcher
css

string[] 可选

若数组中的所有 CSS 选择器均与与网页主框架来源相同的框架中显示的元素匹配，则匹配。为加快匹配速度，此数组中的所有选择器都必须是复合选择器。注意：列出数百个 CSS 选择器或列出在每个网页上可匹配数百个 CSS 选择器，都可能会拖慢网站速度。
isBookmarked

布尔值选填

Chrome 45 及更高版本

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

UrlFilter 可选

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

RequestContentScript

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

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

属性

构造函数

void

constructor 函数如下所示：
```
(arg: RequestContentScript)=> {...}
```
- 参数
  
  RequestContentScript
- 返回
  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)=> {...}
```
- 参数
  
  SetIcon
- 返回
  SetIcon
imageData

ImageData|对象可选

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