説明
chrome.events
名前空間には、何か興味深いことが起こったときに通知を受け取るためにイベントをディスパッチする API が使用する一般的な型が含まれています。
コンセプトと使用方法
Event
は、何かが発生したときに通知を受け取ることができるオブジェクトです。chrome.alarms.onAlarm
イベントを使用して、アラーム時間が経過するたびに通知する例を次に示します。
chrome.alarms.onAlarm.addListener((alarm) => {
appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});
例に示すように、addListener()
を使用して通知に登録します。addListener()
の引数は、常にイベントを処理するために定義した関数ですが、関数のパラメータは処理するイベントによって異なります。alarms.onAlarm
のドキュメントを確認すると、この関数に 1 つのパラメータ(経過時間のアラームの詳細を含む alarms.Alarm
オブジェクト)があることがわかります。
イベントを使用する API の例: alarms、i18n、identity、runtime。ほとんどの Chrome API で可能です。
宣言型イベント ハンドラ
宣言型のイベント ハンドラでは、宣言型の条件とアクションで構成されるルールを定義できます。条件は JavaScript エンジンではなくブラウザで評価されるため、ラウンドトリップ レイテンシが短縮され、非常に効率的です。
宣言型のイベント ハンドラは、宣言型 Content API などで使用します。このページでは、すべての宣言型イベント ハンドラの基本的なコンセプトについて説明します。
ルール
最もシンプルなルールは、1 つ以上の条件と 1 つ以上のアクションで構成されます。
const rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
いずれかの条件が満たされると、すべてのアクションが実行されます。
条件とアクションに加えて、各ルールに識別子(以前に登録されたルールの登録解除を簡素化)とルール間の優先順位を定義する優先度を指定できます。優先度は、ルールが競合する場合、または特定の順序で実行する必要がある場合にのみ考慮されます。アクションは、ルールの優先度が高い順に実行されます。
const rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
イベント オブジェクト
イベント オブジェクトはルールをサポートする場合があります。これらのイベント オブジェクトは、イベント発生時にコールバック関数を呼び出さず、登録済みのルールに 1 つ以上の満たされた条件があるかどうかをテストし、このルールに関連付けられたアクションを実行します。宣言型 API をサポートするイベント オブジェクトには、events.Event.addRules()
、events.Event.removeRules()
、events.Event.getRules()
の 3 つの関連するメソッドがあります。
ルールの追加
ルールを追加するには、イベント オブジェクトの addRules()
関数を呼び出します。このメソッドは、最初のパラメータとしてルール インスタンスの配列を受け取り、完了時に呼び出されるコールバック関数を受け取ります。
const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});
ルールが正常に挿入された場合、details
パラメータには、渡された rule_list
と同じ順序で挿入されるルールの配列が含まれ、オプション パラメータ id
と priority
には生成された値が入力されます。無効な条件またはアクションが含まれるなど、ルールが無効である場合、ルールは追加されず、コールバック関数が呼び出されたときに runtime.lastError 変数が設定されます。rule_list
の各ルールには、別のルールで使用されていない一意の識別子、または空の識別子が含まれている必要があります。
ルールを削除
ルールを削除するには、removeRules()
関数を呼び出します。オプションとして、1 つ目のパラメータとしてルール識別子の配列を、2 つ目のパラメータとしてコールバック関数を指定できます。
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
rule_ids
が識別子の配列の場合、配列にリストされている識別子を持つすべてのルールが削除されます。rule_ids
に不明な識別子が含まれている場合、この識別子は通知なく無視されます。rule_ids
が undefined
の場合、この拡張機能の登録済みルールがすべて削除されます。ルールが削除されると、callback()
関数が呼び出されます。
ルールを取得する
登録済みのルールのリストを取得するには、getRules()
関数を呼び出します。removeRules()
と同じセマンティクスを持つルール識別子の配列(省略可能)とコールバック関数を受け入れます。
const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});
callback()
関数に渡される details
パラメータは、入力されたオプション パラメータを含むルールの配列を参照します。
パフォーマンス
パフォーマンスを最大化するには、次のガイドラインに留意してください。
ルールの一括登録と登録解除を行います。登録または登録解除のたびに、Chrome は内部データ構造を更新する必要があります。この更新は負荷の高いオペレーションです。
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
events.UrlFilter 内の正規表現よりも部分文字列の一致を優先します。 部分文字列ベースのマッチングは非常に高速です。
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
同じアクションを共有するルールが多数ある場合は、ルールを 1 つに統合します。ルールは、1 つの条件が満たされるとすぐにアクションをトリガーします。これにより、マッチングが高速化され、重複するアクション セットのメモリ消費量が削減されます。
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule1 = { conditions: [condition1], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; const rule2 = { conditions: [condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule = { conditions: [condition1, condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule]);
フィルタされたイベント
フィルタされたイベントは、リスナーが関心のあるイベントのサブセットを指定できるメカニズムです。フィルタを使用するリスナーは、フィルタを渡さないイベントに対しては呼び出されないため、リスニング コードが宣言型かつ効率的になります。重要でないイベントを処理するために Service Worker を起動する必要はありません。
フィルタされたイベントは、手動のフィルタリング コードからの移行を可能にするためのものです。
chrome.webNavigation.onCommitted.addListener((event) => { if (hasHostSuffix(event.url, 'google.com') || hasHostSuffix(event.url, 'google.com.au')) { // ... } });
chrome.webNavigation.onCommitted.addListener((event) => { // ... }, {url: [{hostSuffix: 'google.com'}, {hostSuffix: 'google.com.au'}]});
イベントは、そのイベントにとって意味のある特定のフィルタをサポートしています。イベントでサポートされているフィルタのリストは、そのイベントのドキュメント内の「フィルタ」セクションに記載されています。
(上記の例のように)URL を照合する場合、イベント フィルタは、スキームとポートの照合を除いて、events.UrlFilter
で表現できるものと同じ URL 照合機能をサポートします。
型
Event
Chrome イベントのリスナーを追加、削除できるようにするオブジェクト。
プロパティ
-
addListener
void
イベント リスナー callback をイベントに登録します。
addListener
関数は次のようになります。(callback: H) => {...}
-
callback
H
イベントが発生したときに呼び出されます。この関数のパラメータは、イベントのタイプによって異なります。
-
-
addRules
void
イベントを処理するルールを登録します。
addRules
関数は次のようになります。(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
現在登録されているルールを返します。
getRules
関数は次のようになります。(ruleIdentifiers?: string[], callback: function) => {...}
-
hasListener
void
hasListener
関数は次のようになります。(callback: H) => {...}
-
callback
H
登録ステータスがテストされるリスナー。
-
戻り値
boolean
callback がイベントに登録されている場合は true。
-
-
hasListeners
void
hasListeners
関数は次のようになります。() => {...}
-
戻り値
boolean
イベント リスナーがイベントに登録されている場合は true。
-
-
removeListener
void
イベントからイベント リスナー callback の登録を解除します。
removeListener
関数は次のようになります。(callback: H) => {...}
-
callback
H
登録を解除するリスナー。
-
-
removeRules
void
現在登録されているルールの登録を解除します。
removeRules
関数は次のようになります。(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] 省略可
配列が渡されると、この配列に含まれる識別子を持つルールのみが登録されません。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
Rule
イベントを処理するための宣言型ルールの説明。
プロパティ
-
措置
任意 []
いずれかの条件が満たされた場合にトリガーされるアクションのリスト。
-
conditions
任意 []
アクションをトリガーできる条件のリスト。
-
id
string(省略可)
このルールの参照を許可する識別子(省略可)。
-
優先度
number(省略可)
このルールの優先度(省略可)。デフォルトは 100 です。
-
tags
string[] 省略可
タグを使用すると、ルールにアノテーションを付けたり、ルールセットに対するオペレーションを実行したりできます。
UrlFilter
さまざまな条件で URL をフィルタします。イベントのフィルタリングをご覧ください。すべての条件で大文字と小文字が区別されます。
プロパティ
-
cidrBlocks
string[] 省略可
Chrome 123 以降URL のホスト部分が IP アドレスで、配列で指定された CIDR ブロックのいずれかに含まれている場合に一致します。
-
hostContains
string(省略可)
URL のホスト名に指定された文字列が含まれている場合に一致します。ホスト名コンポーネントに接頭辞「foo」があるかどうかをテストするには、hostContains: 「.foo」を使用します。ホスト名の先頭に暗黙的にドットが追加されるため、「www.foobar.com」および「foo.com」と一致します。同様に、hostContains は、コンポーネント サフィックス(「foo.」)との照合や、コンポーネント(「.foo.」)との完全一致照合に使用できます。最後のコンポーネントの接尾辞と完全一致は、hostSuffix を使用して個別に行う必要があります。これは、ホスト名の末尾に暗黙的なドットが追加されないためです。
-
hostEquals
string(省略可)
URL のホスト名が、指定された文字列と等しい場合に一致します。
-
hostPrefix
string(省略可)
URL のホスト名が、指定された文字列で始まる場合に一致します。
-
hostSuffix
string(省略可)
URL のホスト名が指定された文字列で終わる場合に一致します。
-
originAndPathMatches
string(省略可)
クエリ セグメントとフラグメント識別子のない URL が、指定された正規表現と一致する場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。正規表現では RE2 構文を使用します。
-
pathContains
string(省略可)
URL のパスセグメントに指定された文字列が含まれている場合に一致します。
-
pathEquals
string(省略可)
URL のパスセグメントが指定された文字列と等しい場合に一致します。
-
pathPrefix
string(省略可)
URL のパスセグメントが指定された文字列で始まる場合に一致します。
-
pathSuffix
string(省略可)
URL のパスセグメントが指定された文字列で終わる場合に一致します。
-
ports
(数値 | 数値 [])[] 省略可
URL のポートが、指定されたポートリストのいずれかに含まれている場合に一致します。たとえば、
[80, 443, [1000, 1200]]
は、ポート 80、443、および 1000 ~ 1200 の範囲のすべてのリクエストに一致します。 -
queryContains
string(省略可)
URL のクエリ セグメントに指定された文字列が含まれている場合に一致します。
-
queryEquals
string(省略可)
URL のクエリ セグメントが指定された文字列と等しい場合に一致します。
-
queryPrefix
string(省略可)
URL のクエリ セグメントが指定された文字列で始まる場合に一致します。
-
querySuffix
string(省略可)
URL のクエリ セグメントが指定された文字列で終わる場合に一致します。
-
schemes
string[] 省略可
URL のスキームが、配列で指定されたいずれかのスキームと等しい場合に一致します。
-
urlContains
string(省略可)
URL(フラグメント識別子なし)に指定された文字列が含まれている場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。
-
urlEquals
string(省略可)
URL(フラグメント識別子なし)が、指定された文字列と等しい場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。
-
urlMatches
string(省略可)
URL(フラグメント識別子なし)が、指定された正規表現と一致する場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。正規表現では RE2 構文を使用します。
-
urlPrefix
string(省略可)
URL(フラグメント識別子なし)が指定された文字列で始まる場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。
-
urlSuffix
string(省略可)
URL(フラグメント識別子なし)が指定された文字列で終わる場合に一致します。デフォルトのポート番号と一致する場合、ポート番号は URL から削除されます。