chrome.declarativeContent

描述

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

Permissions

declarativeContent

# 用法

声明性内容 API 允许您根据网页的 URL 和与其内容匹配的 CSS 选择器显示扩展程序的page action，无需获得host permission或注入内content script。使用 activeTab 权限以便在用户单击您的页面操作后能够与页面交互。

如果您需要更精确地控制页面操作出现的时间，或者需要在用户单击它之前更改其外观以匹配当前选项卡，则必须继续使用 pageAction API。

# Rules(规则)

作为声明性 API(declarative API)，此 API 允许您在 onPageChanged 事件(event)对象上注册规则，当满足一组条件（表示为 PageStateMatcher）时，这些规则会执行操作（ShowPageAction 和 SetIcon）。

当且仅当满足所有列出的条件时，PageStateMatcher 才匹配网页。当“https://www.google.com/”上的页面存在密码字段时，以下规则将显示页面操作：

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

注意：所有条件和操作都是通过构造函数创建的，如上例所示。

为了还显示带有视频的网站的页面操作，您可以添加第二个条件，因为每个条件都足以触发所有指定的操作：

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

添加的规则(Added rules)会在浏览器重新启动时保存，因此请按如下方式注册它们：

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

注意：您应该始终批量注册或取消注册规则，而不是单独注册或取消注册，因为这些操作中的每一个都会重新创建内部数据结构。这种重新创建在计算上是昂贵的，但有利于更快的匹配算法。

将上述规则与 activeTab 权限结合起来，创建一个不需要任何安装时权限的扩展但可以邀请用户在相关页面上单击其页面操作，并且可以在用户单击页面操作时在这些页面上运行。

# CSS Matching(CSS 匹配)

PageStateMatcher.css 条件必须是复合选择器(compound selectors)，这意味着您不能在选择器中包含像空格或“>”这样的组合符(combinators)。这有助于 Chrome 更有效地匹配选择器。

CSS 条件仅匹配显示的元素：如果与您的选择器匹配的元素是 display:none 或其父元素之一是 display:none，则不会导致条件匹配。具有可见性样式的visibility:hidden、位于屏幕外或被其他元素隐藏(positioned off-screen, or hidden)仍然可以使您的条件匹配。

# Bookmarked State Matching(书签状态匹配)

PageStateMatcher.isBookmarked 条件允许匹配用户配置文件中当前 URL 的书签状态。要使用此条件，必须在扩展清单中声明“书签(bookmarks)”权限。

Summary

• Types

  ImageDataType

  PageStateMatcher

  RequestContentScript

  SetIcon

  ShowAction

  ShowPageAction

• Events

  onPageChanged

Types

ImageDataType

See https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

TYPE

ImageData

PageStateMatcher

根据各种标准匹配网页的状态。

PROPERTIES

• constructor

  function

  The constructor function looks like:

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

  • arg

    PageStateMatcher

  • returns

    PageStateMatcher

• css

  string[] optional

  如果数组中的所有 CSS 选择器都匹配与页面主框架具有相同来源的框架中的显示元素，则匹配。此数组中的所有选择器都必须是复合选择器(compound selectors)以加快匹配速度。注意：列出数百个 CSS 选择器或列出每页匹配数百次的 CSS 选择器会降低网站速度。

• isBookmarked

  boolean optional

  Chrome 45+

  如果页面的书签状态等于指定值，则匹配。需要书签权限(bookmarks permission)。

• pageUrl

  UrlFilter optional

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

RequestContentScript

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

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

PROPERTIES

• constructor

  function

  The constructor function looks like:

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

  • arg

    RequestContentScript

  • returns

    RequestContentScript

• allFrames

  boolean optional

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

• css

  string[] optional

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

• js

  string[] optional

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

• matchAboutBlank

  boolean optional

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

SetIcon

声明性事件操作，在满足相应条件时为扩展程序的页面操作（page action）或浏览器操作（browser action）设置 n-dip 方形图标。无需主机权限即可使用此操作，但扩展程序必须具有页面或浏览器操作。

必须指定 imageData 或 path 中的一个。两者都是将多个像素映射到图像表示的字典。 imageData 中的图像表示是一个 ImageData 对象；例如，来自画布canvas元素，而路径path中的图像表示是相对于扩展程序清单的图像文件的路径。如果scale缩放屏幕像素适合与设备无关的像素，则使用scale * n 图标。如果缺少该比例，则会将另一张图像调整为所需的大小。

PROPERTIES

• constructor

  function

  The constructor function looks like:

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

  • arg

    SetIcon

  • returns

    SetIcon

• imageData

  ImageData | object optional

  ImageData 对象或字典 {size -> ImageData} 表示要设置的图标。如果将图标指定为字典，则根据屏幕的像素密度选择使用的图像。如果适合一个屏幕空间单位的图像像素数等于 scale，则选择大小为 scale * n 的图像，其中 n 是 UI 中图标的大小。必须至少指定一张图片。注意 details.imageData = foo 等价于 details.imageData = {'16': foo}。

ShowAction

Pending

声明性事件操作，在满足相应条件时显示扩展程序的工具栏操作（页面操作( page action)或浏览器操作(browser action)）。无需主机权限(host permissions)即可使用此操作。如果扩展程序具有 activeTab 权限，单击页面操作将授予对活动选项卡的访问权限。

PROPERTIES

• constructor

  function

  The constructor function looks like:

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

  • arg

    ShowAction

  • returns

    ShowAction

ShowPageAction

已弃用

使用 declarativeContent.ShowAction.

声明性事件操作，在满足相应条件时显示扩展程序的页面操作(page action)。此操作可以在没有主机权限(host permissions)的情况下使用，但扩展程序必须具有页面操作。如果扩展程序具有 activeTab 权限，单击页面操作将授予对活动选项卡的访问权限。

PROPERTIES

• constructor

  function

  The constructor function looks like:

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

  • arg

    ShowPageAction

  • returns

    ShowPageAction

By.一粒技术服务