Chrome で標準化された browser.* 名前空間がサポートされるようになりました（Chrome 148 以降で利用可能）。ドキュメントは順次更新されます。詳しくは、移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

browser.events

説明

chrome.events 名前空間には、関心事が発生したときに通知するイベントをディスパッチする API で使用される共通の型が含まれています。

コンセプトと使用方法

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 に不明な識別子がリストされている場合、この識別子は無視されます。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]);

フィルタされたイベント

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

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

非推奨

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 照合機能と同じ機能をサポートします。

型

Event

Chrome イベントのリスナーを追加および削除できるオブジェクト。

プロパティ

addListener

void

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

addListener 関数は次のようになります。
```
(callback: H) => {...}
```
- callback
  
  H
  
  イベントが発生したときに呼び出されます。この関数のパラメータは、イベントの種類によって異なります。
addRules

void

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

addRules 関数は次のようになります。
```
(rules: Rule<anyany>[], callback?: function) => {...}
```
- ルール
  
  Rule<anyany>[]
  
  登録するルール。これらは、以前に登録されたルールを置き換えるものではありません。
- callback
  
  function 省略可
  
  callback パラメータは次のようになります。
```
(rules: Rule<anyany>[]) => void
```
  - ルール
    
    Rule<anyany>[]
    
    登録されたルール。オプションのパラメータに値が入力されます。
getRules

void

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

getRules 関数は次のようになります。
```
(ruleIdentifiers?: string[], callback: function) => {...}
```
- ruleIdentifiers
  
  string[] 省略可
  
  配列が渡された場合、この配列に含まれる識別子を持つルールのみが返されます。
- callback
  
  関数
  
  callback パラメータは次のようになります。
```
(rules: Rule<anyany>[]) => void
```
  - ルール
    
    Rule<anyany>[]
    
    登録されたルール。オプションのパラメータに値が入力されます。
hasListener

void

hasListener 関数は次のようになります。
```
(callback: H) => {...}
```
- callback
  
  H
  
  登録ステータスをテストするリスナー。
- 戻り値
  ブール値
  
  callback がイベントに登録されている場合は true。
hasListeners

void

hasListeners 関数は次のようになります。
```
() => {...}
```
- 戻り値
  ブール値
  
  イベントにイベントリスナーが登録されている場合は true。
removeListener

void

イベントからイベントリスナーの callback の登録を解除します。

removeListener 関数は次のようになります。
```
(callback: H) => {...}
```
- callback
  
  H
  
  登録を解除するリスナー。
removeRules

void

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

removeRules 関数は次のようになります。
```
(ruleIdentifiers?: string[], callback?: function) => {...}
```
- ruleIdentifiers
  
  string[] 省略可
  
  配列が渡された場合、この配列に含まれる識別子を持つルールのみが登録解除されます。
- callback
  
  function 省略可
  
  callback パラメータは次のようになります。
```
() => void
```

Rule

イベントを処理する宣言型ルールの説明。

プロパティ

actions

any[]

いずれかの条件が満たされた場合にトリガーされるアクションのリスト。
conditions

any[]

アクションをトリガーできる条件のリスト。
id

文字列省略可

このルールを参照できるようにするオプションの識別子。
priority

number 省略可

このルールの優先度（省略可）。デフォルトは 100 です。
tags

string[] 省略可

タグを使用すると、ルールにアノテーションを付けたり、ルールのセットに対してオペレーションを実行したりできます。

UrlFilter

さまざまな条件で URL をフィルタします。イベントフィルタリングをご覧ください。すべての条件で大文字と小文字が区別されます。

プロパティ

cidrBlocks

string[] 省略可

Chrome 123 以降 Chrome 148 以降の browser.*

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 のパスセグメントが指定された文字列で終わる場合に一致します。
ポート

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

URL のポートが、指定されたポートリストのいずれかに含まれている場合に一致します。たとえば、[80, 443, [1000, 1200]] は、ポート 80、443、1000 ～ 1200 の範囲のすべてのリクエストに一致します。
queryContains

文字列省略可

URL のクエリセグメントに指定された文字列が含まれている場合に一致します。
queryEquals

文字列省略可

URL のクエリセグメントが指定された文字列と等しい場合に一致します。
queryPrefix

文字列省略可

URL のクエリセグメントが指定された文字列で始まる場合に一致します。
querySuffix

文字列省略可

URL のクエリセグメントが指定された文字列で終わる場合に一致します。
スキーム

string[] 省略可

URL のスキームが、配列で指定されたスキームのいずれかと一致する場合に一致します。
urlContains

文字列省略可

URL（フラグメント識別子を除く）に指定された文字列が含まれている場合に一致します。ポート番号がデフォルトのポート番号と一致する場合、URL からポート番号が削除されます。
urlEquals

文字列省略可

URL（フラグメント識別子なし）が指定された文字列と等しい場合に一致します。ポート番号がデフォルトのポート番号と一致する場合、URL からポート番号が削除されます。
urlMatches

文字列省略可

URL（フラグメント識別子なし）が指定された正規表現と一致する場合に一致します。ポート番号がデフォルトのポート番号と一致する場合、URL から削除されます。正規表現では RE2 構文を使用します。
urlPrefix

文字列省略可

URL（フラグメント識別子を除く）が指定された文字列で始まる場合に一致します。ポート番号がデフォルトのポート番号と一致する場合、URL からポート番号が削除されます。
urlSuffix

文字列省略可

URL（フラグメント識別子を除く）が指定された文字列で終わる場合に一致します。ポート番号がデフォルトのポート番号と一致する場合、URL からポート番号が削除されます。

browser.events コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

コンセプトと使用方法

宣言型イベント ハンドラ

ルール

イベント オブジェクト

ルールの追加

ルールを削除する

ルールを取得する

パフォーマンス

フィルタされたイベント

型

Event

プロパティ

Rule

プロパティ

UrlFilter

プロパティ

browser.events

宣言型イベントハンドラ

イベントオブジェクト