BackgroundFetchRegistration
===========================

**Experimental:** **これは実験的な機能です。**  
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

Background Fetch API の **`BackgroundFetchRegistration`** インターフェイスは個々のバックグラウンドフェッチを表します。

`BackgroundFetchRegistration` インスタンスは、`BackgroundFetchManager.fetch()` メソッド、または `BackgroundFetchManager.get()` メソッドによって返されるため、コンストラクターは存在しません。

EventTarget

BackgroundFetchRegistrationプロパティ
-----

以下のプロパティは、`BackgroundFetchRegistration` インスタンスからコピーされた便利なプロパティとして、同期的に利用できます。

`BackgroundFetchRegistration.id` 読取専用  
Experimental

バックグラウンドフェッチのIDを示す文字列。

`BackgroundFetchRegistration.uploadTotal` 読取専用  
Experimental

アップロードされる総バイト数を表す `number`。

`BackgroundFetchRegistration.uploaded` 読取専用  
Experimental

送信に成功したバイト数を表す `number`。初期値は `0`。

`BackgroundFetchRegistration.downloadTotal` 読取専用  
Experimental

ダウンロード全体のバイト数を表す `number`。これはバックグラウンドフェッチの登録時に設定される値です。設定されなかった場合は `0` となります。

`BackgroundFetchRegistration.downloaded` 読取専用  
Experimental

今までにダウンロードされたバイト数を表す `number`。初期値は `0`。

`BackgroundFetchRegistration.result` 読取専用  
Experimental

初期状態では空文字列。完了時には `"success"` または `"failure"` という文字列。

`BackgroundFetchRegistration.failureReason` 読取専用  
Experimental

下記文字列のいずれかの値をとります。

`""`

バックグラウンドフェッチが完了していない、もしくは成功したとき。

`"aborted"`

ユーザーによって操作がキャンセルされたとき、または `abort()` が呼び出されたとき。

`"bad-status"`

応答ステータスが OK ではないとき ( 200 ~ 299 の範囲外のとき)

`"fetch-error"`

その他の理由によりフェッチが失敗したとき。例えば、CORS 違反や、ネットワーク障害が理由の場合です。

`"quota-exceeded"`

途中でストレージ容量の上限に達したとき。

`"download-total-exceeded"`

バックグラウンドフェッチの登録時に指定された `downloadTotal` を超過したとき。


`BackgroundFetchRegistration.recordsAvailable` 読取専用  
Experimental

`recordsAvailable` フラグが設定されているかどうかを表す `boolean`。

メソッド
----

`BackgroundFetchRegistration.abort()` 
Experimental

バックグラウンドフェッチを中止します。フェッチの中止が成功したときに `true` で解決される `Promise` を返します。

`BackgroundFetchRegistration.match()` 
Experimental

引数に対して最初にマッチした `BackgroundFetchRecord` オブジェクトを 1 つ返します。

`BackgroundFetchRegistration.matchAll()` 
Experimental

リクエストと応答を含む `BackgroundFetchRecord` オブジェクトの配列で解決される `Promise` を返します。

イベント
----

`addEventListener()` を用いて、または、このインターフェイスの `oneventname` プロパティにイベントリスナーを割り当てて、これらイベントの発生を待ち受けてください。

`progress` 
Experimental

 次のプロパティのいずれかに変化があったとき、発火されます。:
 `uploaded` 、
 `downloaded` 、
 `result` または
 `failureReason` 。


例
-

以下のコードは、`"my-fetch"` という `id` を持つ `BackGroundFetchRegistration` を `bgFetch` として作成しています。


```js
navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.fetch(
    "my-fetch",
    ["/ep-5.mp3", "ep-5-artwork.jpg"],
    {
      title: "Episode 5: Interesting things.",
      icons: [
        {
          sizes: "300x300",
          src: "/ep-5-icon.png",
          type: "image/png",
        },
      ],
      downloadTotal: 60 \* 1024 \* 1024,
    },
  );
});
```


`id` をコンソールにログ出力すると、`"my-fetch"` が出力されます。


```js
console.log(bgFetch.id); // "my-fetch"
```


`match()` メソッドを使って、registration の要素である `BackgroundFetchRecord` から特定の 1 つを探すことができます。


```js
bgFetch.match("/ep-5.mp3").then(async (record) => {
  if (!record) {
    console.log("レコードは見つかりませんでした。");
    return;
  }

  console.log(`リクエスト： `, record.request);
  const response = await record.responseReady;
  console.log(`応答： `, response);
});
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-registration |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.