browser.events

説明

コンセプトと使用方法

Event は、関心事が発生したときに通知を受け取ることができるオブジェクトです。アラームが経過するたびに通知されるように browser.alarms.onAlarm イベントを使用する例を次に示します。

browser.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 エンジンではなくブラウザで評価されるため、ラウンドトリップ レイテンシが短縮され、効率が大幅に向上します。

宣言型イベント ハンドラは、たとえば Declarative 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() 関数を呼び出します。最初のパラメータとしてルール識別子のオプションの配列を受け取り、2 番目のパラメータとしてコールバック関数を受け取ります。

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

rule_ids が識別子の配列の場合、配列にリストされている識別子を持つすべてのルールが削除されます。rule_ids に不明な ID がリストされている場合、この ID は通知なく無視されます。rule_ids が undefined の場合、この拡張機能の登録済みルールはすべて削除されます。ルールが削除されると、callback() 関数が呼び出されます。

ルールを取得する

登録済みルールのリストを取得するには、getRules() 関数を呼び出します。この関数は、removeRules() と同じセマンティクスを持つルール識別子の配列（省略可）とコールバック関数を受け取ります。

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

callback() 関数に渡される details パラメータは、入力された省略可能なパラメータを含むルールの配列を参照します。

パフォーマンス

パフォーマンスを最大限に高めるには、次のガイドラインに留意してください。

ルールを一括で登録および登録解除します。登録または登録解除のたびに、Chrome は内部データ構造を更新する必要があります。この更新はコストのかかるオペレーションです。

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter で正規表現よりも部分文字列のマッチングを優先します。部分文字列ベースのマッチングは非常に高速です。

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

同じアクションを共有するルールが多数ある場合は、ルールを 1 つに統合します。ルールは、1 つの条件が満たされるとすぐにアクションをトリガーします。これにより、重複するアクション セットのマッチングが高速化され、メモリ使用量が削減されます。

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

フィルタされたイベント

フィルタされたイベントは、リスナーが関心のあるイベントのサブセットを指定できるメカニズムです。フィルタを使用するリスナーは、フィルタを通過しないイベントに対して呼び出されません。これにより、リスニング コードがより宣言的で効率的になります。Service Workerは、関心のないイベントを処理するために起動する必要はありません。

フィルタされたイベントは、手動フィルタリング コードからの移行を可能にすることを目的としています。

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

イベントは、そのイベントにとって意味のある特定のフィルタをサポートします。イベントがサポートするフィルタのリストは、そのイベントのドキュメントの「フィルタ」セクションに記載されています。

URL の照合（上記の例を参照）では、イベント フィルタは、スキームとポートの照合を除き、events.UrlFilter で表現できるものと同じ URL 照合機能をサポートしています。