说明
使用 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) => {...}
-
css
string[] 可选
若数组中的所有 CSS 选择器均与与网页主框架来源相同的框架中显示的元素匹配,则匹配。为加快匹配速度,此数组中的所有选择器都必须是复合选择器。注意:列出数百个 CSS 选择器或列出在每个网页上可匹配数百个 CSS 选择器,都可能会拖慢网站速度。
-
isBookmarked
布尔值 选填
Chrome 45 及更高版本如果网页的已添加书签状态与指定值相等,则匹配。需要书签权限。
-
pageUrl
UrlFilter 可选
如果针对网页的顶级网址满足
UrlFilter
的条件,则匹配。
RequestContentScript
用于注入内容脚本的声明式事件操作。
警告:此操作仍处在实验阶段,不支持 Chrome 稳定版。
属性
-
构造函数
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
一种声明性事件操作,可在满足相应条件时将扩展程序的工具栏操作设置为启用状态。此操作无需主机权限也可使用。如果此扩展程序具有 activeTab 权限,那么点击相应网页操作会授予对活动标签页的访问权限。
在不符合条件的网页上,扩展程序的工具栏操作会显示灰阶;点击该按钮会打开上下文菜单,而不是触发操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: ShowAction) => {...}
-
参数
-
ShowPageAction
请使用 declarativeContent.ShowAction
。
一种声明性事件操作,可在满足相应条件时将扩展程序的网页操作设为启用状态。此操作无需主机权限即可使用,但扩展程序必须具备网页操作。如果此扩展程序具有 activeTab 权限,那么点击相应网页操作会授予对活动标签页的访问权限。
在不符合条件的网页上,扩展程序的工具栏操作会显示灰阶;点击该按钮会打开上下文菜单,而不是触发操作。
属性
-
构造函数
void
constructor
函数如下所示:(arg: ShowPageAction) => {...}
活动
onPageChanged
提供由 addRules
、removeRules
和 getRules
组成的声明式事件 API。