chrome.events

説明

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)=> {...}

    • rules

      ルール<任意>[]

      登録するルール。これらの設定は、以前に登録されたルールに置き換わるものではありません。

    • callback

      関数（省略可）

      callback パラメータは次のようになります。 

      (rules: Rule<anyany>[])=>void

      • rules

        ルール<任意>[]

        登録されているルール。オプション パラメータには値が入力されます。

  • getRules

    void

    現在登録されているルールを返します。

    getRules 関数は次のようになります。 

    (ruleIdentifiers?: string[],callback: function)=> {...}

    • ruleIdentifiers

      string[] 省略可

      配列が渡された場合は、この配列に含まれる識別子を持つルールのみが返されます。

    • callback

      機能

      callback パラメータは次のようになります。 

      (rules: Rule<anyany>[])=>void

      • rules

        ルール<任意>[]

        登録されているルール。オプション パラメータには値が入力されます。

  • 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（省略可）

    このルールの参照を許可する識別子（省略可）。

  • priority

    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

    (number|number[])[] 省略可

    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 から削除されます。