chrome.declarativeContent

说明

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

权限

declarativeContent

用法

声明式 Content API 可让您根据 或者 CSS 选择器与页面上的某个元素匹配,无需 添加主机权限或注入内容脚本

使用 activeTab 权限,以在用户点击 操作。

规则

规则由条件和操作组成。如果满足任一条件,则所有操作 。这些操作包括 setIconshowAction

当且仅当所有网页都列出时,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 条件允许匹配 用户个人资料中当前网址的书签状态。要使用此条件 "书签"权限必须在扩展程序清单中声明。

类型

类型

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:blankabout:srcdoc 中插入内容脚本。默认值为 false

SetIcon

声明式事件操作,在满足相应条件时,为扩展程序的网页操作浏览器操作设置 n-dip 方形图标。此操作无需主机权限即可使用,但必须对扩展程序执行网页或浏览器操作。

必须且只能指定 imageDatapath 中的一个。两者都是将多个像素映射到图像表示的字典。imageData 中的图片表示形式是一个 ImageData 对象;,而 path 中的图片表示形式是图片文件相对于扩展程序清单的路径。canvas如果 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

<ph type="x-smartling-placeholder"></ph> 自 Chrome 97 起弃用

请使用 declarativeContent.ShowAction

一种声明式事件操作,可在满足相应条件时将扩展程序的网页操作设为启用状态。此操作无需主机权限也可使用,但扩展程序必须包含网页操作。如果扩展程序具有 activeTab 权限,点击网页操作即可授予对活动标签页的访问权限。

在不符合这些条件的网页上,扩展程序的工具栏操作会变为灰度模式,点击该按钮会打开上下文菜单,而不会触发操作。

属性

事件

onPageChanged

提供由 addRulesremoveRulesgetRules 组成的声明式事件 API