chrome.events

refresh date: 2026-09-25 robots: noindex

説明

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

chrome.alarms.onAlarm.addListener(function(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 Web Request API や Declarative 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 の 3 つの関連メソッドがあります。

ルールの追加

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

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

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

ルールの削除

ルールを削除するには、removeRules() 関数を呼び出します。最初のパラメータとしてルール識別子の配列（省略可）、2 番目のパラメータとしてコールバック関数を受け取ります。

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]);

prefer:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

従来の方法:

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

prefer:

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]);

prefer:

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