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