chrome.events

説明

コンセプトと使用方法

Event は、何か興味深いことが起きたときに通知を受け取ることができるオブジェクトです。こちらが chrome.alarms.onAlarm イベントを使用して、アラームが経過するたびに通知されるようにする例:

chrome.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

例に示すように、addListener() を使用して通知の登録を行います。この引数は、 addListener() は常にユーザーがイベントを処理するために定義する関数ですが、 関数によって異なります。alarms.onAlarm のドキュメントを確認します。 この関数には、単一のパラメータ（詳細を含む 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()。

ルールの追加

ルールを追加するには、イベント オブジェクトの addRules() 関数を呼び出します。ルール インスタンスの配列を を最初のパラメータとして指定し、完了時に呼び出されるコールバック関数を渡します。

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

ルールが正常に挿入された場合は、挿入されたルールの配列が details パラメータに含まれます。 渡された rule_list と同じ順序で表示されます。ここで、省略可能なパラメータ id と priority には生成された値が入力されています。ルールのいずれかが無効な場合（例: ルールに 無効な条件またはアクションの場合、どのルールも追加されず、runtime.lastError 変数 コールバック関数が呼び出されたときに設定されます。rule_list の各ルールには、一意の ID 値を含む 別のルールで使用されていない、または空の識別子です。

ルールを削除

ルールを削除するには、removeRules() 関数を呼び出します。必要に応じて、ルール ID の配列を指定します。 コールバック関数を渡します。

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 を照合する場合、イベント フィルタでは同じ URL 照合がサポートされます。 スキームとポートのマッチングを除き、events.UrlFilter で表現可能な機能を提供します。