説明
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 のマッチング
URL の条件が満たされた場合、PageStateMatcher.pageurl
が一致します。最も一般的な条件は、ホスト、パス、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 のブックマークされた状態を照合できます。この条件を使用するには、拡張機能のマニフェストで「ブックマーク」権限を宣言する必要があります。
型
ImageDataType
https://developer.mozilla.org/en-US/docs/Web/API/ImageData をご覧ください。
タイプ
ImageData
PageStateMatcher
さまざまな条件に基づいて、ウェブページの状態を照合します。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: PageStateMatcher) => {...}
-
css
string[] 省略可
配列内のすべての CSS セレクタが、ページのメインフレームと同じオリジンのフレーム内に表示された要素と一致する場合に一致します。マッチングを高速化するため、この配列内のセレクタはすべて複合セレクタである必要があります。注: 何百もの CSS セレクタや 1 ページに何百回も一致する 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
の画像表現は canvas
要素の ImageData オブジェクトですが、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
対応する条件が満たされている間、拡張機能のツールバーのアクションを有効状態に設定する宣言型イベント アクション。この操作は、ホストの権限がなくても使用できます。拡張機能に activeTab 権限がある場合、ページ操作をクリックすると、アクティブなタブへのアクセス権が付与されます。
条件を満たしていないページでは、拡張機能のツールバー アクションがグレースケールになります。アクションをクリックすると、アクションがトリガーされる代わりにコンテキスト メニューが開きます。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: ShowAction) => {...}
-
引数
-
戻り値
-
ShowPageAction
declarativeContent.ShowAction
を使用してください。
対応する条件が満たされている間に、拡張機能のページ アクションを有効状態に設定する宣言型イベント アクション。このアクションはホスト権限がなくても使用できますが、拡張機能にはページ アクションが必要です。拡張機能に activeTab 権限がある場合、ページ操作をクリックすると、アクティブなタブへのアクセス権が付与されます。
条件を満たしていないページでは、拡張機能のツールバー アクションがグレースケールになります。アクションをクリックすると、アクションがトリガーされる代わりにコンテキスト メニューが開きます。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: ShowPageAction) => {...}
イベント
onPageChanged
addRules
、removeRules
、getRules
で構成される宣言型イベント API を提供します。