chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

説明

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） 複雑なセレクタ（不可）
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 のブックマーク状態を照合できます。この条件を利用するには、拡張機能のマニフェストで「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 省略可

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

プロパティ

  • コンストラクタ

    void

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

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

  • imageData

    ImageData | object 省略可

    設定するアイコンを表す 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 で構成される宣言型イベント API を提供します。

条件

PageStateMatcher

操作

RequestContentScript

SetIcon

ShowPageAction

ShowAction