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 のドキュメントを確認します。 この関数には、単一のパラメータ（詳細を含む 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 で表現可能な機能を提供します。

型

Event

Chrome イベントのリスナーの追加と削除を可能にするオブジェクト。

プロパティ

  • addListener

    void

    イベント リスナーのコールバックをイベントに登録します。

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

    (callback: H) => {...}

    • callback

      H

      イベントが発生したときに呼び出されます。この関数のパラメータは、イベントの種類によって異なります。

  • addRules

    void

    イベントを処理するルールを登録します。

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

    (rules: Rule<anyany>[], callback?: function) => {...}

    • ルール

      ルール<任意>[]

      登録するルール。すでに登録済みのルールに代わるものではありません。

    • callback

      関数（省略可）

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

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

      • ルール

        ルール<任意>[]

        登録済みのルールがある場合、省略可能なパラメータには値が入力されます。

  • getRules

    void

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

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

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

    • ruleIdentifiers

      文字列 [] 省略可

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

    • callback

      関数

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

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

      • ルール

        ルール<任意>[]

        登録済みのルールがある場合、省略可能なパラメータには値が入力されます。

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