chrome.declarativeContent

説明

chrome.declarativeContent API を使用すると、ページのコンテンツの読み取り権限がなくても、ページのコンテンツに応じてアクションを実行できます。

権限

declarativeContent

コンセプトと使用方法

Declarative Content API を使用すると、 また、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 サイトでも拡張機能の動作を有効にするには、 指定されたすべてのアクションをトリガーするのには各条件が満たされるからです。

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 の一致

URL の条件が満たされると、PageStateMatcher.pageurl が一致します。「 最も一般的な条件は、ホスト、パス、URL のいずれかを連結し、その後に Contains、Equals、Prefix、または 接尾辞。次の表に例を示します。

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

すべての条件で大文字と小文字が区別されます。条件の一覧については、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 またはその親要素の 1 つが display:none である場合、条件は 一致します。visibility:hidden でスタイルが設定された要素、画面外に配置された要素、他の要素によって非表示になっている要素 引き続き条件を一致させることができます

ブックマーク状態の一致

PageStateMatcher.isBookmarked 条件を使用すると、 ユーザーのプロフィールの現在の URL のブックマーク状態。この条件を利用するには "ブックマーク"拡張機能のマニフェストで権限を宣言する必要があります。

型

ImageDataType

詳しくは、https://developer.mozilla.org/en-US/docs/Web/API/ImageData をご覧ください。

タイプ

ImageData

PageStateMatcher

さまざまな条件に基づいて、ウェブページの状態を照合します。

プロパティ

  • コンストラクタ

    void

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

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

  • css

    文字列 [] 省略可

    配列内のすべての CSS セレクタが、ページのメインフレームと同じ起点を持つフレーム内の表示要素と一致する場合に一致します。マッチングを高速化するには、この配列内のすべてのセレクタを複合セレクタにする必要があります。注: 数百の CSS セレクタを記載したり、1 ページあたり数百回一致する CSS セレクタのリストを作成したりすると、ウェブサイトの速度が遅くなる可能性があります。

  • isBookmarked

    ブール値（省略可）

    Chrome 45 以降

    ページのブックマーク状態が指定された値と等しい場合に一致します。ブックマーク権限が必要です。

  • pageUrl

    UrlFilter 省略可

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

RequestContentScript

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

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

プロパティ

  • コンストラクタ

    void

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

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

  • allFrames

    ブール値（省略可）

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

  • css

    文字列 [] 省略可

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

  • JS

    文字列 [] 省略可

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

  • matchAboutBlank

    ブール値（省略可）

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

SetIcon

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

imageData または path のいずれかを指定する必要があります。どちらも複数のピクセルを画像表現にマッピングする辞書です。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

<ph type="x-smartling-placeholder"></ph> Chrome 97 以降非推奨

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

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

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

プロパティ

イベント

onPageChanged

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

条件

PageStateMatcher

操作

RequestContentScript

SetIcon

ShowPageAction

ShowAction