chrome.declarativeContent

説明

chrome.declarativeContent API を使用すると、ページのコンテンツの読み取り権限を必要とせず、ページのコンテンツに応じた操作を行うことができます。

権限

declarativeContent

コンセプトと使用方法

Declarative Content API を使用すると、ホスト権限を追加したり、コンテンツ スクリプトを挿入したりすることなく、ウェブページの URL に応じて、または CSS セレクタがページ上の要素と一致する場合に、拡張機能のアクションを有効にできます。

activeTab 権限を使用して、ユーザーが拡張機能のアクションをクリックした後にページを操作します。

ルール

ルールは条件とアクションで構成されます。いずれかの条件が満たされると、すべてのアクションが実行されます。アクションは setIcon() と showAction() です。

PageStateMatcher は、リスト内のすべての条件が満たされている場合にのみ、ウェブページに一致します。ページ URL、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 サイトでも拡張機能のアクションを有効にするには、2 つ目の条件を追加します。各条件は、指定されたすべてのアクションをトリガーするのに十分です。

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 イベントは、いずれかのルールで条件が 1 つ以上満たされているかどうかをテストし、アクションを実行します。ルールはブラウジング セッション間で保持されるため、拡張機能のインストール時に、まず removeRules を使用して以前にインストールされたルールを消去し、次に addRules を使用して新しいルールを登録する必要があります。

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

activeTab 権限を使用すると、拡張機能に権限に関する警告は表示されず、ユーザーが拡張機能のアクションをクリックしたときに、関連するページでのみ実行されます。

ページ URL の照合

PageStateMatcher.pageurl は、URL の条件が満たされた場合に一致します。最も一般的な条件は、ホスト、パス、URL の連結に Contains、Equals、Prefix、Suffix のいずれかを追加したものです。次の表に例を示します。

条件 一致
{ hostSuffix: 'google.com' } すべての Google URL
{ pathPrefix: '/docs/extensions' } 拡張機能のドキュメントの URL
{ urlContains: 'developer.chrome.com' } すべての Chrome デベロッパー向けドキュメントの URL

すべての条件で大文字と小文字が区別されます。条件の一覧については、UrlFilter をご覧ください。

CSS マッチング

PageStateMatcher.css 条件は複合セレクタである必要があります。つまり、セレクタに空白文字や「>」などの結合子を含めることはできません。これにより、Chrome はセレクタをより効率的に照合できるようになります。

複合セレクタ（OK） 複雑なセレクタ（NG）
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 条件を使用すると、ユーザーのプロフィール内の現在の URL のブックマーク状態を照合できます。この条件を使用するには、拡張機能のmanifestで「ブックマーク」権限を宣言する必要があります。

型

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 省略可

    ページのトップレベル URL が UrlFilter の条件を満たしている場合に一致します。

RequestContentScript

コンテンツ スクリプトを挿入する宣言型イベント アクション。

警告: この操作はまだ試験運用版であり、Chrome の安定版ではサポートされていません。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • allFrames

    ブール値（省略可）

    コンテンツ スクリプトを一致するページのすべてのフレームで実行するか、最上位のフレームでのみ実行するかを指定します。デフォルトは、false です。

  • css

    string[] 省略可

    コンテンツ スクリプトの一部として挿入される CSS ファイルの名前。

  • js

    string[] 省略可

    コンテンツ スクリプトの一部として挿入される JavaScript ファイルの名前。

  • matchAboutBlank

    ブール値（省略可）

    about:blank と about:srcdoc にコンテンツ スクリプトを挿入するかどうか。デフォルトは false です。

SetIcon

対応する条件が満たされているときに、拡張機能のページ アクションまたはブラウザ アクションに n ディップの正方形のアイコンを設定する宣言型イベント アクション。このアクションはホスト権限なしで使用できますが、拡張機能にページ アクションまたはブラウザ アクションが必要です。

imageData または path のいずれか 1 つを指定する必要があります。どちらも、複数のピクセルを画像表現にマッピングする辞書です。imageData の画像表現は ImageData オブジェクト（canvas 要素など）ですが、path の画像表現は拡張機能のマニフェストに相対的な画像ファイルのパスです。scale 画面ピクセルがデバイス非依存ピクセルに収まる場合は、scale * n アイコンが使用されます。そのスケールがない場合は、別の画像が必要なサイズにサイズ変更されます。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • imageData

    ImageData | オブジェクト 省略可

    設定するアイコンを表す ImageData オブジェクトまたはディクショナリ {size -> ImageData}。アイコンが辞書として指定されている場合、使用される画像は画面のピクセル密度に応じて選択されます。1 つの画面スペース単位に収まる画像ピクセル数が scale の場合、サイズ scale * n の画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。details.imageData = foo は details.imageData = {'16': foo} と同じです。

ShowAction

Chrome 97 以降

対応する条件が満たされている間、拡張機能のツールバー アクションを有効な状態に設定する宣言型イベント アクション。このアクションは、ホスト権限なしで使用できます。拡張機能に activeTab 権限が付与されている場合、ページ アクションをクリックすると、アクティブなタブへのアクセスが許可されます。

条件が満たされていないページでは、拡張機能のツールバー アクションはグレー表示になり、クリックしてもアクションがトリガーされず、コンテキスト メニューが開きます。

プロパティ

ShowPageAction

Chrome 97 で非推奨

declarativeContent.ShowAction を使用してください。

対応する条件が満たされている間、拡張機能のページ アクションを有効な状態に設定する宣言型イベント アクション。このアクションはホストの権限なしで使用できますが、拡張機能にページ アクションが必要です。拡張機能に activeTab 権限が付与されている場合、ページ アクションをクリックすると、アクティブなタブへのアクセスが許可されます。

条件が満たされていないページでは、拡張機能のツールバー アクションはグレー表示になり、クリックしてもアクションがトリガーされず、コンテキスト メニューが開きます。

プロパティ

イベント

onPageChanged

addRules、removeRules、getRules で構成される Declarative Event API を提供します。

条件

PageStateMatcher

操作

RequestContentScript

SetIcon

ShowPageAction

ShowAction