chrome.declarativeContent

更新日: 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 である場合、またはその親要素の 1 つが 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 セレクタをリストしたり、1 ページに何百回も一致する CSS セレクタをリストしたりすると、ウェブサイトの速度が低下する可能性があります。

  • isBookmarked

    boolean 省略可

    Chrome 45 以降

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

  • pageUrl

    UrlFilter 省略可

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

RequestContentScript

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

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

プロパティ

  • コンストラクタ

    void

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

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

  • allFrames

    boolean 省略可

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

  • css

    string[] 省略可

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

  • js

    string[] 省略可

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

  • matchAboutBlank

    boolean 省略可

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

SetIcon

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

imageData または path のいずれか 1 つのみを指定する必要があります。どちらも、ピクセル数を画像表現にマッピングする辞書です。imageData の画像表現は ImageData オブジェクト（canvas 要素など）ですが、path の画像表現は拡張機能のマニフェストを基準とした画像ファイルへのパスです。scale 個の画面ピクセルが 1 つのデバイス非依存ピクセルに収まる場合は、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