WritableStreamDefaultWriter: WritableStreamDefaultWriter() コンストラクター - Web API

WritableStreamDefaultWriter: WritableStreamDefaultWriter() コンストラクター
===================================================================

**`WritableStreamDefaultWriter()`** コンストラクターは、新しい `WritableStreamDefaultWriter` オブジェクトのインスタンスを作成します。

**メモ:** 通常、このコンストラクターを手動で使用することはありません。 代わりに、`WritableStream.getWriter()` メソッドを使用します。

構文
--

```js
new WritableStreamDefaultWriter(stream)
```

### 引数

`stream`

書き込む `WritableStream`。

### 返値

`WritableStreamDefaultWriter` オブジェクトのインスタンス。

### 例外

`TypeError`

提供された `stream` 値は `WritableStream` ではないか、すでに別のライターにロックされている場合。

例
-

次の例は、カスタムのシンクと API 提供のキューイング戦略を使用した `WritableStream` の作成を示しています。 次に、`sendMessage()` という関数を呼び出し、新しく作成されたストリームと文字列を渡します。 この関数内で、`WritableStreamDefaultWriter` のインスタンスを返すストリームの `getWriter()` メソッドを呼び出します。 `forEach()` 呼び出しを使用して、文字列の各チャンクをストリームに書き込みます。 最後に、`write()` および `close()` は、チャンクとストリームの成功または失敗に対処するための promise を返します。

```js
const list = document.querySelector("ul");

function sendMessage(message, writableStream) {
  // defaultWriter は WritableStreamDefaultWriter 型です
  const defaultWriter = writableStream.getWriter();
  const encoder = new TextEncoder();
  const encoded = encoder.encode(message, { stream: true });
  encoded.forEach((chunk) => {
    defaultWriter.ready
      .then(() => defaultWriter.write(chunk))
      .then(() => {
        console.log("Chunk written to sink.");
      })
      .catch((err) => {
        console.log("Chunk error:", err);
      });
  });
  // ライターを閉じる前にすべてのチャンクが
  // 確実に書き込まれるように、ready を再度呼び出します。
  defaultWriter.ready
    .then(() => {
      defaultWriter.close();
    })
    .then(() => {
      console.log("All chunks written");
    })
    .catch((err) => {
      console.log("Stream error:", err);
    });
}

const decoder = new TextDecoder("utf-8");
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });
let result = "";
const writableStream = new WritableStream(
  {
    // シンクの実装
    write(chunk) {
      return new Promise((resolve, reject) => {
        const buffer = new ArrayBuffer(1);
        const view = new Uint8Array(buffer);
        view[0] = chunk;
        const decoded = decoder.decode(view, { stream: true });
        const listItem = document.createElement("li");
        listItem.textContent = `Chunk decoded: ${decoded}`;
        list.appendChild(listItem);
        result += decoded;
        resolve();
      });
    },
    close() {
      const listItem = document.createElement("li");
      listItem.textContent = `[MESSAGE RECEIVED] ${result}`;
      list.appendChild(listItem);
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);

sendMessage("Hello, world.", writableStream);
```

完全なコードは、単純なライターの例にあります。

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-constructor① |

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

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


WritableStreamDefaultWriter: abort() メソッド - Web API

WritableStreamDefaultWriter: abort() メソッド
=========================================

**`abort()`** は `WritableStreamDefaultWriter` インターフェイスのメソッドで、ストリームを中止し、プロデューサーがストリームに正常に書き込むことができなくなり、キューに書き込まれた書き込みを破棄してすぐにエラー状態に移行することを通知します。

ライターがアクティブな場合、`abort()` メソッドは、関連するストリーム（`WritableStream.abort()`）と同じように振る舞います。 そうでない場合、拒否されたプロミスを返します。

構文
--

```js
abort()
abort(reason)
```

### 引数

`reason` 省略可

文字列で、人間が読むことができる中止の理由を表します。

### 返値

`Promise` です。 `reason` 引数で指定された値で履行されます。

### 例外

`TypeError`

中止しようとしているストリームが `WritableStream` ではないか、ロックされている場合。

例
-

```js
const writableStream = new WritableStream(
  {
    write(chunk) {
      // ...
    },
    close() {
      // ...
    },
    abort(err) {
      // ...
    },
  },
  queuingStrategy,
);

// ...

const writer = writableStream.getWriter();

// ...

// 必要に応じてストリームを中止します
writer.abort.then((reason) => {
  console.log(reason);
});
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-abort④ |

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

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


WritableStreamDefaultWriter: ready プロパティ - Web API

WritableStreamDefaultWriter: ready プロパティ
========================================

**`ready`** は `WritableStreamDefaultWriter` インターフェイスの読み取り専用プロパティで、ストリームの内部キューの目的のサイズが非正から正に移行したときに解決する `Promise` を返し、背圧が適用されなくなったことを通知します。

値
-

`Promise` です。

例
-

次の例は、`ready` プロパティの 2 つの使用法を示しています。 最初は `ready` を使用して、`WritableStream` が書き込みを完了し、バイナリチャンクを送信する前にデータを受信できるようにします。 2 番目も、`WritableStream` の書き込みが完了しているかどうかをチェックしますが、今度はライターを閉じる前に書き込みを終了する必要があるためです。

```js
function sendMessage(message, writableStream) {
  // defaultWriter は WritableStreamDefaultWriter 型です
  const defaultWriter = writableStream.getWriter();
  const encoder = new TextEncoder();
  const encoded = encoder.encode(message, { stream: true });
  encoded.forEach((chunk) => {
    // ストリームとそのライターがデータを
    // 受信できることを確認します。
    defaultWriter.ready
      .then(() => defaultWriter.write(chunk))
      .then(() => {
        console.log("Chunk written to sink.");
      })
      .catch((err) => {
        console.error(`Chunk error: ${err}`);
      });
    // ライターを閉じる前にすべてのチャンクが
    // 確実に書き込まれるように、ready を再度呼び出します。
    defaultWriter.ready
      .then(() => defaultWriter.close())
      .then(() => {
        console.log("All chunks written");
      })
      .catch((err) => {
        console.error(`Stream error: ${err}`);
      });
  });
}
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-ready⑨ |

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

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


WritableStreamDefaultWriter: desiredSize プロパティ - Web API

WritableStreamDefaultWriter: desiredSize プロパティ
==============================================

**`desiredSize`** は `WritableStreamDefaultWriter` インターフェイスの読み取り専用プロパティで、ストリームの内部キューを埋めるために必要な希望サイズを返します。

値
-

整数。 キューがいっぱいになった場合、これは負になる可能性があることに注意してください。

値は、（エラーが発生したか、中止がキューに入れられたために）ストリームに正常に書き込むことができない場合、 `null` になり、ストリームが閉じられると `0` になります。

### 例外

`TypeError`

ライターのロックが解除されてた場合。

例
-

```js
const writableStream = new WritableStream(
  {
    write(chunk) {
      // ...
    },
    close() {
      // ...
    },
    abort(err) {
      // ...
    },
  },
  queuingStrategy,
);

// ...

const writer = writableStream.getWriter();

// ...

// ストリームの希望サイズを返します
let size = writer.desiredSize;
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-desired-size⑥ |

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

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


WritableStreamDefaultWriter: releaseLock() メソッド - Web API

WritableStreamDefaultWriter: releaseLock() メソッド
===============================================

**`releaseLock()`** は `WritableStreamDefaultWriter` インターフェイスのメソッドで、対応するストリームのライターのロックを解除します。 ロックを解除すると、ライターはアクティブではなくなります。 ロックを解除したときに関連するストリームにエラーが発生した場合、ライターはこれ以降同じようにエラーが発生したように見えます。 そうでない場合、ライターは閉じられたように見えます。

構文
--

```js
releaseLock()
```

### 引数

なし。

### 返値

なし (`undefined`)。

例
-

```js
const writableStream = new WritableStream(
  {
    write(chunk) {
      // ...
    },
    close() {
      // ...
    },
    abort(err) {
      // ...
    },
  },
  queuingStrategy,
);

// ...

const writer = writableStream.getWriter();

// ...

// 必要に応じて、ストリームのライターのロックを解除します
writer.releaseLock();
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-release-lock② |

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

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


WritableStreamDefaultWriter: write() メソッド - Web API

WritableStreamDefaultWriter: write() メソッド
=========================================

**`write()`** は `WritableStreamDefaultWriter` インターフェイスのメソッドで、渡されたデータのチャンクを `WritableStream` とその基になるシンクに書き込み、その後、書き込み操作の成功または失敗を示すために解決される `Promise` を返します。

「成功」の意味は、基になるシンク次第であることに注意してください。 単にチャンクが受け入れられたことを示しているだけで、必ずしも最終的な宛先に安全に保存されているとは限りません。

構文
--

```js
write(chunk)
```

### 引数

`chunk`

`WritableStream` に渡すバイナリデータのブロック。

### 返値

`Promise` です。 書き込みが成功すると `undefined` で満たされ、書き込みプロセスが開始される前に書き込みが失敗するかストリームがエラーになると拒否されます。

### 例外

`TypeError`

対象のストリームは書き込み可能なストリームではないか、オーナーがない場合。

例
-

次の例は、カスタムのシンクと API 提供のキューイング戦略を使用した `WritableStream` の作成を示しています。 次に、`sendMessage()` という関数を呼び出し、新しく作成されたストリームと文字列を渡します。 この関数内で、`WritableStreamDefaultWriter` のインスタンスを返すストリームの `getWriter()` メソッドを呼び出します。 `forEach()` 呼び出しを使用して、文字列の各チャンクをストリームに書き込みます。 最後に、`write()` および `close()` は、チャンクとストリームの成功または失敗に対処するためのプロミスを返します。

```js
const list = document.querySelector("ul");

function sendMessage(message, writableStream) {
  // defaultWriter は WritableStreamDefaultWriter 型です
  const defaultWriter = writableStream.getWriter();
  const encoder = new TextEncoder();
  const encoded = encoder.encode(message, { stream: true });
  encoded.forEach((chunk) => {
    defaultWriter.ready
      .then(() => defaultWriter.write(chunk))
      .then(() => {
        console.log("Chunk written to sink.");
      })
      .catch((err) => {
        console.log("Chunk error:", err);
      });
  });
  // ライターを閉じる前にすべてのチャンクが
  // 確実に書き込まれるように、ready を再度呼び出します。
  defaultWriter.ready
    .then(() => {
      defaultWriter.close();
    })
    .then(() => {
      console.log("All chunks written");
    })
    .catch((err) => {
      console.log("Stream error:", err);
    });
}

const decoder = new TextDecoder("utf-8");
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });
let result = "";
const writableStream = new WritableStream(
  {
    // シンクの実装
    write(chunk) {
      return new Promise((resolve, reject) => {
        const buffer = new ArrayBuffer(1);
        const view = new Uint8Array(buffer);
        view[0] = chunk;
        const decoded = decoder.decode(view, { stream: true });
        const listItem = document.createElement("li");
        listItem.textContent = `Chunk decoded: ${decoded}`;
        list.appendChild(listItem);
        result += decoded;
        resolve();
      });
    },
    close() {
      const listItem = document.createElement("li");
      listItem.textContent = `[MESSAGE RECEIVED] ${result}`;
      list.appendChild(listItem);
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);

sendMessage("Hello, world.", writableStream);
```

完全なコードは、単純なライターの例にあります。

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-default-writer-write①② |

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

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


IntersectionObserverEntry: time プロパティ - Web API

IntersectionObserverEntry: time プロパティ
=====================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`time`** プロパティは、 `DOMHighResTimeStamp` で、文書の作成時刻を基準とする交差状態が発生した時刻を示します。

値
-

`DOMHighResTimeStamp` で、 `target` 要素がこの `IntersectionObserverEntry` で示す交差状態の変化を検出した時刻を表します。時刻はそれを含む文書が作成されてからのミリ秒単位で指定します。

例
-

`time` プロパティを使用して、要素がユーザーに表示されている時間を追跡する完全な例については、交差オブザーバー API による要素の表示時間設定を参照してください。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-time |

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

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


IntersectionObserverEntry: isIntersecting プロパティ - Web API

IntersectionObserverEntry: isIntersecting プロパティ
===============================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`isIntersecting`** プロパティは、対象要素が交差オブザーバーのルートと交差している場合に `true` になる論理値です。この値が `true` の場合、 `IntersectionObserverEntry` は交差状態への変わり目にあります。 `false` の場合、交差ありから交差なしへの変わり目であることがわかります。

値
-

論理値で、 `target` 要素が交差状態に遷移したか (`true`) または交差状態から脱したか (`false`) を示します。

例
-

この単純な例では、交差コールバックを使用して、現在いくつの対象となる要素が交差ルートと交差しているかのカウンターを更新します。

```js
function intersectionCallback(entries) {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      intersectingCount += 1;
    } else {
      intersectingCount -= 1;
    }
  });
}
```

より具体的な例については、交差状態の変化の扱いをご覧ください。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-isintersecting |

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

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


IntersectionObserverEntry: rootBounds プロパティ - Web API

IntersectionObserverEntry: rootBounds プロパティ
===========================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`rootBounds`** プロパティは `DOMRectReadOnly` であり、この `target` のルート耕作系に対応します。指定されていれば、 `IntersectionObserver.rootMargin` によるオフセットを含みます。

値
-

`DOMRectReadOnly` で、ルート交差矩形を表します。 `Document` のビューポートであるルートの場合、この矩形は文書全体の境界矩形となります。そうでない場合は、ルート要素の境界となります。

この矩形のオフセットは `IntersectionObserver.rootMargin` の値で指定します。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-rootbounds |

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

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


IntersectionObserverEntry: intersectionRatio プロパティ - Web API

IntersectionObserverEntry: intersectionRatio プロパティ
==================================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`intersectionRatio`** プロパティは、対象の要素が現在どの程度見えているかを、ルートの交差比率で 0.0 から 1.0 の間の値で示します。

値
-

 0.0 から 1.0 の間の数値で、対象要素がルートの交差矩形内で実際にどの程度表示されているかを示します。
 より正確には、この値は交差矩形の面積 (`intersectionRect`) と対象の外接矩形の面積 (`boundingClientRect`) の比になります。

対象の外接矩形の面積が 0 の場合、 `isIntersecting` が `true` ならば 1、そうでないならば 0 が返されます。

例
-

この単純な例では、交差コールバックはそれぞれの対象要素の `opacity` を、その要素とルートとの交差比率に設定します。

```js
function intersectionCallback(entries) {
  entries.forEach((entry) => {
    entry.target.style.opacity = entry.intersectionRatio;
  });
}
```

より具体的な例については、交差状態の変化の扱いをご覧ください。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-intersectionratio |

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

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


IntersectionObserverEntry: boundingClientRect プロパティ - Web API

IntersectionObserverEntry: boundingClientRect プロパティ
===================================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`boundingClientRect`** プロパティは、簡単にいえば、対象要素全体を含む最小の矩形を記述した `DOMRectReadOnly` を返します。

値
-

`DOMRectReadOnly` で、交差状態の変化を記述している対象要素のすべての部分を含む、最小の矩形を記述します。この値は `Element.getBoundingClientRect()` と同じアルゴリズムで取得されるので、この矩形を得るために何が行われ、何がその境界内に含まれ、何が含まれないかという正確な内容については、その記事を参照してください。

しかし、一般的なケースでは、これを対象要素の外接矩形と考えるのが無難でしょう。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-boundingclientrect |

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

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


IntersectionObserverEntry: target プロパティ - Web API

IntersectionObserverEntry: target プロパティ
=======================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`target`** プロパティは、交差ルートとの交差量が変化したのがどの対象要素であるかを `Element` で示します。

値
-

`IntersectionObserverEntry` の `target` プロパティは、以前に `IntersectionObserver.observe()` を呼び出して対象とした `Element` の中で、ルートとの交差量が変化したものを示します。

例
-

この単純な例では、対象となるそれぞれの要素の `opacity` が、その `intersectionRatio` に設定されます。

```js
function intersectionCallback(entries) {
  entries.forEach((entry) => {
    entry.target.style.opacity = entry.intersectionRatio;
  });
}
```

より具体的な例については、交差状態の変化の扱いをご覧ください。

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-target |

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

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


IntersectionObserverEntry: intersectionRect プロパティ - Web API

IntersectionObserverEntry: intersectionRect プロパティ
=================================================

`IntersectionObserverEntry` インターフェイスの読み取り専用の **`intersectionRect`** プロパティは `DOMRectReadOnly` オブジェクトで、交差ルート内に現在表示されている対象要素の部分全体を含む、最小の矩形を記述したものです。

値
-

`DOMRectReadOnly` で、対象要素のうち、ルートの交差矩形内に現在表示されている部分を表します。

この矩形は `boundingClientRect` と `target` の各先祖のクリップ矩形の交差部分をとって算出されます。ただし、交差ルート (`root`) 自体を除きます。

例
-

この単純な例では、交差コールバックは、対象要素のコンテンツを描画するコードが後で使用するために交差矩形を格納し、可視領域のみが再描画されるようにしています。

```js
function intersectionCallback(entries) {
  entries.forEach((entry) => {
    refreshZones.push({
      element: entry.target,
      rect: entry.intersectionRect,
    });
  });
}
```

仕様書
---

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserverentry-intersectionrect |

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

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


Worklet.addModule() - Web API

Worklet.addModule()
===================

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

**`addModule()`** は `Worklet` インターフェイスのメソッドで、指定した JavaScript ファイルで定義されるモジュールを現在の `Worklet` に読み込みます。

構文
--

```js
addModule(moduleURL);
addModule(moduleURL, options);
```

### 引数

`moduleURL`

文字列で、追加するモジュールの JavaScript ファイルの URL を指定します。

`options` 省略可

次のオプションを指定するためのオブジェクトです。

`credentials`

モジュールをロードする際に、資格情報（例: Cookie や HTTP 認証）を送信するかどうかを指定する `Request.credentials` 値です。 `"omit"`, `"same-origin"`, `"include"` のいずれかを指定することができます。既定値は `"same-origin"` です。 `Request.credentials` も参照してください。

返値
--

指定された URL のモジュールが追加されると解決される `Promise` です。このプロミスは値を返しません。

### 例外

`addModule()` が失敗した場合、プロミスを拒否し、以下のいずれかのエラーを拒否ハンドラーに送出します。

`AbortError` `DOMException`

指定されたスクリプトが無効であるか、または読み込むことができませんでした。

`SyntaxError` `DOMException`

指定された `moduleURL` が無効です。

例
-

### AudioWorklet の例

```js
const audioCtx = new AudioContext();
const audioWorklet = audioCtx.audioWorklet;
audioWorklet.addModule("modules/bypassFilter.js", {
  credentials: "omit",
});
```

### PaintWorklet の例

```js
CSS.paintWorklet.addModule(
  "https://mdn.github.io/houdini-examples/cssPaint/intro/worklets/hilite.js",
);
```

`paintWorklet` (en-US) がインクルードされると、 CSS の `image/paint()` 関数を使用して、ワークレットが作成した画像を引用することができます。

```css
@supports (background-image: paint(id)) {
  h1 {
    background-image: paint(hollowHighlights, filled, 3px);
  }
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-worklet-addmodule-dev |

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

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


CSSPseudoElement: element プロパティ - Web API

CSSPseudoElement: element プロパティ
===============================

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

**`element`** は `CSSPseudoElement` インターフェイスの読み取り専用のプロパティで、擬似要素の元要素、言い換えれば親要素への参照を返します。

値
-

この擬似要素の元要素を表す `Element` です。

例
-

下記の例は、 `CSSPseudoElement.element` と `Element.pseudo()` の関係を示しています。

```js
const myElement = document.querySelector("q");
const cssPseudoElement = myElement.pseudo("::after");
const originatingElement = cssPseudoElement.element;

console.log(myElement === originatingElement); // true を出力
console.log(myElement.parentElement === originatingElement); // false を出力
console.log(myElement.lastElementChild === cssPseudoElement); // false を出力
console.log(myElement.lastChild === cssPseudoElement); // false を出力
console.log(myElement.nextElementSibling === cssPseudoElement); // false を出力
console.log(myElement.nextSibling === cssPseudoElement); // false を出力
```

仕様書
---

| Specification |
| --- |
| CSS Pseudo-Elements Module Level 4 # dom-csspseudoelement-element |

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

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

関連情報
----

* `Element.pseudo()`


CSSPseudoElement: type プロパティ - Web API

CSSPseudoElement: type プロパティ
============================

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

**`type`** は `CSSPseudoElement` インターフェイスの読み取り専用プロパティで、擬似要素の型を CSS セレクターの形の文字列で表します。

値
-

以下の値のいずれかを格納する文字列です。

* `"::before"`
* `"::after"`
* `"::marker"`
例
-

下記の例は、 `CSSPseudoElement.type` と `Element.pseudo()` の関係を示しています。

```js
const myElement = document.querySelector("q");
const mySelector = "::after";
const cssPseudoElement = myElement.pseudo(mySelector);
const typeOfPseudoElement = cssPseudoElement.type;

console.log(mySelector === typeOfPseudoElement); // true を出力
```

仕様書
---

| Specification |
| --- |
| CSS Pseudo-Elements Module Level 4 # dom-csspseudoelement-type |

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

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

関連情報
----

* `Element.pseudo()`
* 標準的な擬似要素の索引


Storage Access API の使用 - Web API

Storage Access API の使用
======================

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

埋め込まれたクロスオリジンの文書で Storage Access API を使用して、ファーストパーティストレージにアクセスできるかどうかを確認し、そうでない場合はアクセスを要求する必要があります。 一般的なストレージアクセスのシナリオについて簡単に説明します。

使用上の注意
------

Storage Access API は、ユーザーのブラウザーがすべてのサードパーティのクッキーをブロックするように設定されている場合にブロックされるストレージへのアクセスを埋め込まれたコンテンツが要求できるように設計されています。 埋め込まれたコンテンツはユーザーが使用しているストレージポリシーを認識しないため、ストレージからの読み取りまたは書き込みを試みる前に、常に埋め込まれたフレームにストレージアクセスがあるかどうかを確認するのが最善です。 これは、`Document.cookie` へのアクセスの場合に特に当てはまります。 サードパーティのクッキーがブロックされると、ブラウザーはしばしば空のクッキージャーを返すためです。

埋め込まれたクロスオリジン iframe でユーザーのクッキーにアクセスする
--------------------------------------

この例では、埋め込まれたクロスオリジン `<iframe>` が、サードパーティのクッキーをブロックするストレージアクセスポリシーの下でユーザーのクッキーにアクセスする方法を示します。

まず、`<iframe>` がサンドボックス化されている場合、次のように、埋め込まれたウェブサイトは `allow-storage-access-by-user-activation` sandbox トークンを追加して、ストレージアクセス要求が成功することを許可するとともに、`allow-scripts` と `allow-same-origin` を使用して API の呼び出しを許可し、クッキーを持つことができるオリジンで実行します。

```html
<iframe
 sandbox="allow-storage-access-by-user-activation
 allow-scripts
 allow-same-origin">
  ...
</iframe>
```

次に、埋め込まれた文書内で実行されるコードに進みます。 現在ストレージにアクセスできるかどうかはわからないため、最初に `Document.hasStorageAccess()` を呼び出す必要があります。 その呼び出しが `false` を返す場合、`Document.requestStorageAccess()` を呼び出すことができます。 それが返した結果は、前の Promise 呼び出しにチェーンできます。 最後の `then` では、ファーストパーティストレージへのアクセスが可能になります。

```js
document
  .hasStorageAccess()
  .then((hasAccess) => {
    if (!hasAccess) {
      return document.requestStorageAccess();
    }
  })
  .then((\_) => {
    // これで、ファーストパーティストレージにアクセスできます！

    // ファーストパーティのクッキージャーからいくつかのアイテムにアクセスしましょう
    document.cookie = "foo=bar"; // クッキーを設定
    localStorage.setItem("username", "John"); // localStorage エントリにアクセス
  })
  .catch((\_) => {
    // ストレージアクセスの取得エラー。
  });
```

埋め込まれたコンテンツがタップやクリックなどのユーザージェスチャーを現在処理していない限り、アクセス要求は自動的に拒否されることに注意してください。 このコードは、例えば、次のようなユーザージェスチャーベースのイベントハンドラー内で実行する必要があります。

```js
btn.addEventListener("click", () => {
  // ここでコードを実行します
});
```


序文 - Web API

序文
==

序文
--

W3C 標準で気付かされる流行の一つは、スタイルからコンテンツを分ける努力がなされていることです。これにより、同じスタイルを複数のコンテンツで再利用することができ、簡単なメンテナンスでコンテンツの外観を (一つのファイルの修正のみで) すばやく変更することができます。

CSS (Cascade Style Sheets) は W3C によって最初に提唱された方法の一つでした。CSS は簡単な方法でスタイルルールをウェブ文書に適用します。これらのスタイルルールは、文書（その中のコンテンツ）のレイアウトを定義します。しかしながら、プログラミング構造や複雑なレイアウトモデルの作成能力に欠陥があるなどいくつかの制限があります。CSS はまた、要素の配置の変更のサポートも制限されています。

XSL (Extensible Stylesheet Language) 変換は二つの部分で構成されています。 XML ツリーを他のマークアップツリーおよび XPath へ変換可能にする XSL 要素、ツリーのための選択言語。XSLT は XML 文書（そのコンテンツ）を取得し、XSL スタイルシートの規則によって新しい文書を生成します。XSLT によって、オリジナルの XML 文書から要素を追加、削除、再構成することができるため、結果的に文書構造をより細かく制御することができます。

XSLT による変換は、テンプレートからなる規則を基にしています。各テンプレート (XPath を使用) は入力する XML 文書の断片に一致すると、新しい文書を生成するため、テンプレートをその断片の代わりとなる部分に適用します。


HTML の生成 - Web API

HTML の生成
========

ブラウザーにおける XSLT のよくある活用法の一つが、クライアント上で XML を HTML へと変換することです。この例は、記事についての情報を含む文書 (example2.xml) を入力し、HTML 文書へ変換します。

記事の `<body>` 要素は HTML 要素（`<b>` および `<u>` タグ）を含んでいます。この XML 文書は HTML 要素と XML 要素の両方を含んでいますが、必要な名前空間は XML 要素のための名前空間 1 つだけです。HTML には名前空間が無く、XHTML 名前空間を使用すると HTML 文書のように動作しない XML 文書を XSL に生成させてしまうため、XSL スタイルシート内の `xsl:output` によって結果の文書が HTML として扱われるようにします。XML 要素については、独自の名前空間 `http://devedge.netscape.com/2002/de` と、それによって与えられる myNS 接頭辞 `(xmlns:myNS="http://devedge.netscape.com/2002/de")` が必要です。

XML ファイル
--------

```xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="example2.xsl"?>
  <myNS:Article xmlns:myNS="http://devedge.netscape.com/2002/de">
    <myNS:Title>My Article</myNS:Title>
    <myNS:Authors>
      <myNS:Author company="Foopy Corp.">Mr. Foo</myNS:Author>
      <myNS:Author>Mr. Bar</myNS:Author>
    </myNS:Authors>
    <myNS:Body>
      The <b>rain</b> in <u>Spain</u> stays mainly in the plains.
    </myNS:Body>
  </myNS:Article>
```

XSL スタイルシートには 2 つの名前空間が必要です。1 つは XSLT 要素のため、もう 1 つは独自の XML 要素を XML 文書内で使用するためのものです。XSL スタイルシートの出力を `HTML` に設定するために `xsl:output` 要素を使用します。出力を HTML に設定すると結果的に要素（青色の部分）が名前空間を持たないため、これらの要素は HTML 要素とみなされます。

2 つの名前空間を持つ XSL スタイルシート
-----------------------

```xml
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:myNS="http://devedge.netscape.com/2002/de">

  <xsl:output method="html"/>
  …
</xsl:stylesheet version="1.0">
```

XML 文書のルートノードに一致するテンプレートは、基本的な HTML ページの構造を生成するために作成し、使用されます。

基本的な HTML 文書の生成
---------------

```xml
…
<xsl:template match="/">
<html>

  <head>

    <title>
      <xsl:value-of select="/myNS:Article/myNS:Title"/>
    </title>

    <style>
      .myBox {margin:10px 155px 0 50px; border: 1px dotted #639ACE; padding:0 5px 0 5px;}
    </style>

  </head>

  <body>
    <p class="myBox">
      <span class="title">
        <xsl:value-of select="/myNS:Article/myNS:Title"/>
      </span> </br>

      Authors:   <br />
        <xsl:apply-templates select="/myNS:Article/myNS:Authors/myNS:Author"/>
    </p>

    <p class="myBox">
      <xsl:apply-templates select="//myNS:Body"/>
    </p>

  </body>

</html>
</xsl:template>
…
```

例を完成するには、さらに 3 つの `xsl:template` が必要です。最初の `xsl:template` は、2 番目のテンプレートが body ノードを処理する間、author ノードに使用されます。3 番目のテンプレートは、任意のノードや任意の属性に対応する一般的な対応規則を持っています。これは XML 文書内で、HTML 要素のすべてに対応し、変換生成される HTML 文書にコピーする要素を予約しておくために必要です。

最終的な 3 つのテンプレート
---------------

```xml
…
<xsl:template match="myNS:Author">
    --   <xsl:value-of select="." />

  <xsl:if test="@company">
    ::   <b>  <xsl:value-of select="@company" />  </b>
  </xsl:if>

  <br />
</xsl:template>
```

```xml
<xsl:template match="myNS:Body">
  <xsl:copy>
    <xsl:apply-templates select="@\*|node()"/>
  </xsl:copy>
</xsl:template>

<xsl:template match="@\*|node()">
  <xsl:copy>
    <xsl:apply-templates select="@\*|node()"/>
  </xsl:copy>
</xsl:template>
…
```

最終的な XSLT スタイルシートは次のようになります。

最終的な XSLT スタイルシート
-----------------

```xml
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:myNS="http://devedge.netscape.com/2002/de">

  <xsl:output method="html" />

  <xsl:template match="/">
    <html>

      <head>

        <title>
          <xsl:value-of select="/myNS:Article/myNS:Title"/>
        </title>

        <style>
          .myBox {margin:10px 155px 0 50px; border: 1px dotted #639ACE; padding:0 5px 0 5px;}
        </style>

      </head>

      <body>
        <p class="myBox">
          <span class="title">
            <xsl:value-of select="/myNS:Article/myNS:Title"/>
          </span> <br />

          Authors:   <br />
            <xsl:apply-templates select="/myNS:Article/myNS:Authors/myNS:Author"/>
          </p>

        <p class="myBox">
          <xsl:apply-templates select="//myNS:Body"/>
        </p>

      </body>

    </html>
  </xsl:template>

  <xsl:template match="myNS:Author">
      --   <xsl:value-of select="." />

    <xsl:if test="@company">
      ::   <b>  <xsl:value-of select="@company" />  </b>
    </xsl:if>

    <br />
  </xsl:template>

  <xsl:template match="myNS:Body">
    <xsl:copy>
      <xsl:apply-templates select="@\*|node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@\*|node()">
      <xsl:copy>
        <xsl:apply-templates select="@\*|node()"/>
      </xsl:copy>
  </xsl:template>
</xsl:stylesheet>
```


XSLT の基本的な例 - Web API

XSLT の基本的な例
===========

 この最初の例では、ブラウザーで XSLT 変換を設定する基本を示します。
 この例では、記事に関する情報（タイトル、著者の一覧、本文）を含む XML 文書を取り込み、それを人間が読める形式で表示します。

XML 文書 (**example.xml**) は次の通りです。

```xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="example.xsl"?>
<Article>
  <Title>My Article</Title>
  <Authors>
    <Author>Mr. Foo</Author>
    <Author>Mr. Bar</Author>
  </Authors>
  <Body>This is my article text.</Body>
</Article>
```

この XML ファイルの `?xml-stylesheet` 処理命令により、その `href` 属性で適用する XSLT スタイルシートを指定します。

XSL スタイルシートファイル (**example.xsl**) は次の通りです。

```xml
<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:output method="text"/>

  <xsl:template match="/">
    Article - <xsl:value-of select="/Article/Title"/>
    Authors: <xsl:apply-templates select="/Article/Authors/Author"/>
  </xsl:template>

  <xsl:template match="Author">
    - <xsl:value-of select="." />
  </xsl:template>

</xsl:stylesheet>
```

 XSLT スタイルシートは、最終的な出力を生成するためのすべてのテンプレートを含む、`xsl:stylesheet` 要素で始まります。
 この例には 2 つのテンプレートがあります。一つはルートノードに対応し、一つは Author ノードに対応します。
 ルートノードが出力する記事のタイトルにテンプレートが一致すると、（`apply-templates` を通して） Authors ノードの子の、すべての Author ノードに対応するテンプレートが処理されます。

例を試してみましょう。

1. ファイルシステム上にディレクトリーを作成し、その中に上記の `example.xml` と `example.xsl` を作成します。
2. ファイルのあるディレクトリーでローカルサーバーを起動します。
 これにより、あたかもインターネット上でホスティングされているかのように、ディレクトリー内のファイルを閲覧することができます。

**警告:** ファイルシステムからスタイルシートを読み込むことはオリジン間リクエストであり、既定で許可されないためです。
 XML とスタイルシートを同じローカルサーバーでホスティングすることで、同一のオリジンになることが保証されます。
3. ブラウザーから **example.xml** を開きます。
4. ブラウザーの出力は次のようになります。
```

Browser Output :

    Article - My Article
    Authors:
    - Mr. Foo
    - Mr. Bar
```


ウェブアニメーション API の使用 - Web API

ウェブアニメーション API の使用
==================

ウェブアニメーション API により、JavaScript でアニメーションを構築したり、再生を制御したりすることができます。この記事では「ふしぎの国のアリス」を利用した楽しいデモとチュートリアルで正しい利用方法を説明します。

ウェブアニメーション API との出会い
--------------------

ウェブアニメーション API は、ブラウザー内のアニメーションエンジンを開発者に効果しい、JavaScript で操作します。この API は CSS アニメーションと CSS トランジションの両方の実装基盤となるように設計されており、将来のアニメーション効果への扉を開いた状態にしています。これは、ハックや強制、`Window.requestAnimationFrame()` なしで、ブラウザーに自分自身で内部最適化をさせる、ウェブ上でアニメーションするためのほとんどのパフォーマンスの高い方法の 1 つです。

ウェブアニメーション API を使うと、インタラクティブなアニメーションをスタイルシートから JavaScript に移し、表示と動作を分離することができます。再生方向を制御するために、CSS プロパティを書いたり、要素にクラスをスコープしたりといった、DOM を酷使する技法に頼る必要はなくなりました。また、純粋な宣言型の CSS とは異なり、JavaScript ではプロパティから継続時間まで動的に値を設定することもできます。カスタムアニメーションライブラリーを作成したり、対話するアニメーションを作成したりするのに、ウェブアニメーション API は最適かもしれません。何ができるか見てみましょう！

ウェブアニメーション API を利用して CSS アニメーションを構築する
-------------------------------------

ウェブアニメーション API を学習するためのより身近な手法は、多くのウェブ開発者が以前に使用したことのある CSS アニメーションから始めることです。CSS アニメーションには馴染みのある構文があり、そのためデモ用にうまく分解することができます。

### CSS バージョン

アリスがうさぎの穴から落ちてワンダーランドに導かれる様子を示した CSS で書かれている転がり落ちるアニメーションです（完全な Codepen のコードを参照してください）。

![ウサギの穴に転がり落ちるアリス。](/ja/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/tumbling-alice_optimized.gif)

背景が移動しながら、アリスが回転し、回転からのオフセットで色が変化することに注目してください。このチュートリアルでは、アリスのみに焦点を当てます。アリスのアニメーションを制御する簡単な CSS は次のとおりです。

```css
#alice {
  animation: aliceTumbling infinite 3s linear;
}

@keyframes aliceTumbling {
  0% {
    color: #000;
    transform: rotate(0) translate3D(-50%, -50%, 0);
  }
  30% {
    color: #431236;
  }
  100% {
    color: #000;
    transform: rotate(360deg) translate3D(-50%, -50%, 0);
  }
}
```

これによって、アリスの色とトランスフォーム回転が 3 秒間にわたって一定に（線形で）変化し、それを無限にループします。@keyframes ブロックで、各ループの 30%（約 0.9 秒）でアリスの色が黒から濃いワイン色に変わり、ループが終わるときにもとに戻ることが分かります。

### JavaScript への移行

次にウェブアニメーション API を利用して同じアニメーションを作成してみましょう。

#### キーフレームの表現

最初に必要なことは、CSS の @keyframes ブロックに対応する Keyframe オブジェクト を作成することです。

```js
const aliceTumbling = [
  { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
  { color: "#431236", offset: 0.3 },
  { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
];
```

ここでは、複数のオブジェクトを含む配列を使用しています。それぞれのオブジェクトは元の CSS のキーを表します。しかし、CSS とは異なり、ウェブアニメーション API は各キーがアニメーションに沿って現れるパーセント値を明示的に指示する必要はありません。与えたキーの数に応じて、アニメーションが自動的に等分割されます。つまり、3 つのキーを持つ Keyframe オブジェクトは、特に指定がない限り、アニメーションの各ループの 50% で中央のキーを再生するということです。

キーのオフセットを他のキーから明示的に設定する場合は、カンマで CSS キーの宣言と区切ったオフセットを直接オブジェクトに指定できます。上記の例では、色の変化に対してアリスの色が 30%（50% ではない）で変化するために `offset: 0.3` を指定しています。

少なくとも 2 つのキーフレーム（アニメーションシーケンスの開始状態・終了状態の 2 つを示す）を指定する必要があります。ブラウザーによっては、キーフレームリストの項目が 1 つしかない場合、更新されるまで `Element.animate()` で `NotSupportedError` `DOMException` が発生することがあります。

という具合に、キーにオフセットを指定しない限り、キーは既定で等間隔に配置されます。便利でしょう？

#### タイミングプロパティの表現

アリスのアニメーションの値に対応するタイミングプロパティのオブジェクトも作成する必要があります。

```js
const aliceTiming = {
  duration: 3000,
  iterations: Infinity,
};
```

CSS にこける同等の値の表し方とは異なる形で表現されていることにお気づきでしょう。

* 1 つ目は間隔時間はミリ秒単位で表現されています。3 秒という指定ではなく、3000 ミリ秒です。`setTimeout()` や `Window.requestAnimationFrame()` と同じように、ウェブアニメーション API はミリ秒でしか値を取りません。
* もう 1 つは `iteration-count` ではなく `iterations` ということです。

**メモ:** CSS アニメーションで使用される用語とウェブアニメーションで利用される用語とではいくつか小さな違いがあります。例えば、ウェブアニメーションは `"infinite"` という文字列を利用しない代わりに JavaScript の予約語である `Infinity` を利用します。そして、 `timing-function` の代わりに `easing` を利用します。既定の animation-timing-function が簡単な `ease` である CSS アニメーションとは異なり、Web Animation API ではデフォルトのイージングは `linear` (線形)であるため、ここではイージング値をリストにしていません。

#### パーツをまとめる

次は `Element.animate()` メソッドを利用して今までの 2 つの要素をまとめます。

```js
document.getElementById("alice").animate(aliceTumbling, aliceTiming);
```

アニメーションの再生が開始されます（Codepen の完成バージョンを参照してください）。

`animate()` メソッドは、CSS でアニメーションできる DOM 要素に対して呼び出すことができます。そして、それはいくつかの方法で書くことが出来ます。キーフレームとタイミングプロパティを作成する代わりに、次のように直接渡すことが出来ます。

```js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
  ],
  {
    duration: 3000,
    iterations: Infinity,
  },
);
```

さらに、アニメーションの間隔時間のみを指定し、繰り返さないアニメーションを指定する場合、ミリ秒だけを指定することができます（既定ではアニメーションを 1 回だけ実行します）。

```js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
  ],
  3000,
);
```

play(), pause(), reverse(), updatePlaybackRate() を用いた再生制御
---------------------------------------------------------

ウェブアニメーション API を使用して CSS アニメーションを作成することが可能ですが、API が本当に役立つ時はアニメーションの再生を制御するときです。ウェブアニメーション API は、再生を制御するための便利ないくつかのメソッドを提供しています。アリスが拡大/縮小するゲームで、アニメーションの一時停止と再生を見てみましょう（Codepen の完全なコードをご覧ください）。

![アリスと大きくなったり小さくなったりするゲーム](/ja/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/growing-shrinking_article_optimized.gif)

このゲームでは、アリスは小さくなったり大きくなったりするアニメーションがあり、ボトルとカップケーキで制御します。どちらにも独自のアニメーションがあります。

### アニメーションの一時停止と再生

アリスのアニメーションについては後で詳しく説明します。まずはカップケーキのアニメーションを見てみましょう。

```js
const nommingCake = document
  .getElementById("eat-me\_sprite")
  .animate(
    [{ transform: "translateY(0)" }, { transform: "translateY(-80%)" }],
    {
      fill: "forwards",
      easing: "steps(4, end)",
      duration: aliceChange.effect.getComputedTiming().duration / 2,
    },
  );
```

`Element.animate()` メソッドは、呼び出された直後に実行されます。ユーザーがクリックする前にケーキが食べられないように、次のように定義された `Animation.pause()` をすぐに呼び出します。

```js
nommingCake.pause();
```

`Animation.play()` メソッドを用いて準備出来たらいつでもアニメーションを実行できます。

```js
nommingCake.play();
```

具体的には、カップケーキが食べられるにつれて、アリスのアニメーションにリンクしてアリスが大きくなるようにします。

```js
const growAlice = () => {
  // Play Alice's animation.
  aliceChange.play();

  // Play the cake's animation.
  nommingCake.play();
};
```

ユーザーがマウスを押したままにするか、指でタッチ画面上のケーキを押すと、`growAlice` を呼び出してアニメーションを再生できるようにしました。

```js
cake.addEventListener("mousedown", growAlice, false);
cake.addEventListener("touchstart", growAlice, false);
```

### その他の便利なメソッド

一時停止と再生に加えて、次のアニメーションメソッドを利用することが出来ます。

* `Animation.finish()` はアニメーションの最後までスキップします。
* `Animation.cancel()` はアニメーションを中止し、その効果を削除します。
* `Animation.reverse()` を実行すると (`Animation.playbackRate` に負数を設定し、アニメーションの再生方向を逆方向にします。

最初に `playbackRate` を見てみましょう。playbackRate を府にするとはアニメーションを逆に実行させます。アリスがボトルから飲むと彼女は小さくなります。これは、ボトルが彼女のアニメーションの playbackRate を 1 から -1 に変更するためです。

```js
const shrinkAlice = () => {
  aliceChange.playbackRate = -1;
  aliceChange.play();
};

bottle.addEventListener("mousedown", shrinkAlice, false);
bottle.addEventListener("touchstart", shrinkAlice, false);
```

鏡の国のアリスでは、アリスは走り続けなければならない世界に移動します。レッドクイーンのレースの例では、アリスとレッドクイーンが所定の位置にとどまっています（Codepen の 完全なコードを参照してください）。

![アリスと赤の女王が次のマスを取得するために競争します。](/ja/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/red-queen-race_optimized.gif)

小さな子どもは疲れやすいので、おもちゃのチェスの駒と違って、アリスは常に減速しています。これはアニメーションの `playbackRate` を減少させることで実現します。`updatePlaybackRate()` を使用することと、playbackRate を直接設定することなく、スムーズに更新することができます。

```js
setInterval(() => {
  // Make sure the playback rate never falls below .4
  if (redQueen_alice.playbackRate > 0.4) {
    redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate \* 0.9);
  }
}, 3000);
```

しかし、クリックまたはタップして彼女らを励ますと、playbackRate を乗算しているのでスピードアップします。

```js
const goFaster = () => {
  redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate \* 1.1);
};

document.addEventListener("click", goFaster);
document.addEventListener("touchstart", goFaster);
```

また、背景要素にはクリックまたはタップしたときに影響を受ける `playbackRate` を設定しています。アリスとレッドクイーンを 2 倍早く走らせたらどうなると思いますか？速度を落とすとどうなると思いますか？

アニメーションのスタイル維持
--------------

要素をアニメーションさせるとき、アニメーションが完了した後に、最終的な状態を維持したいことがよくあります。このために、アニメーションの fill モード (en-US)を `forwards` に設定するという方法がときどき使われます。しかし、2 つの理由から、アニメーションの効果を無期限に維持するために fill モードを使用することは推奨されません。

* アニメーションがアクティブなままであり、ブラウザーがその状態を維持しなければならないため、アニメーションが終了してもアニメーションがリソースを消費し続けます。なお、これは満了したアニメーションの自動削除をすることでいくらか緩和されます。
* アニメーションで適用されたスタイルは、指定されたスタイルよりカスケードにおいて高い優先度を持つため、必要に応じて上書きすることが困難になる場合があります。

より良い方法は、`Animation.commitStyles()` メソッドを使うことです。これはこのアニメーションの現在のスタイルを、対象要素の `style` 属性に書き込むので、その後は通常にスタイル設定しなおすことができます。

満了したアニメーションの自動削除
----------------

同じ要素に多数のアニメーションを発生させることが可能です。それらが不定である場合（つまり前方満了）、アニメーションリストが巨大になり、メモリーリークが発生する可能性があります。このためブラウザーは、新しいアニメーションに置き換わった後、開発者が明示的にアニメーションを残すように指定しない限り、満了したアニメーションを自動的に削除します。

アニメーションは、以下がすべて真の場合に削除されます。

* アニメーションが満了している（`fill` は前方再生であれば `forwards`、逆再生の場合は `backwards`、両方の場合は `both` です）。
* アニメーションが完了している。（`fill` のため、まだ有効であることに注意してください。）
* アニメーションのタイムラインが単調に増加している。（これは `DocumentTimeline` (en-US) では常に真です。`scroll-timeline` のようなタイムラインは逆方向に動作することがあります。）
* アニメーションが CSS のような宣言的なマークアップによって制御されていない。
* アニメーションの `AnimationEffect` のスタイル設定がすべて、上記の条件をすべて満たす別のアニメーションによって上書きされている。（通常、2 種類のアニメーションが同じ要素の同じスタイルプロパティを設定した場合、最後に作成されたアニメーションが他のアニメーションを上書きします。）

最初の 4 つの条件は、JavaScript コードによる介入なしに、アニメーションの効果が変化したり終わったりしないことを保証します。最後の条件は、アニメーションが実際に何かの要素のスタイル設定に影響しないことを保証します。

アニメーションが自動的に解除されると、そのアニメーションに `remove` イベントが発行されます。

ブラウザーがアニメーションを自動的に削除することを防ぐには、そのアニメーションの `persist()` メソッドを呼び出してください。

アニメーションの `animation.replaceState` プロパティは、アニメーションが削除された場合は `removed`、アニメーションに `persist()` が呼び出された場合は `persisted`、そうでない場合は `active` になります。

アニメーションからの情報の取得
---------------

前庭障害のあるユーザーのアクセシビリティを改善するなど、サイト全体のアニメーションを遅くすることを、playbackRate 以外の方法で行うことを想像してみてください。すべての CSS ルールで期間を再計算することなく CSS で全てを行うことは不可能ですが、ウェブアニメーション API では、次の `Document.getAnimations` メソッドを使用して、次のようにページ上の各アニメーションをループして `playbackRate` を半分にすることができます。

```js
document.getAnimations().forEach((animation) => {
  animation.updatePlaybackRate(animation.playbackRate \* 0.5);
});
```

ウェブアニメーション API を利用すると、変更する必要があるのは 1 つの小さなプロパティだけです！

CSS アニメーションだけでは難しいのは、他のアニメーションが提供する値に依存するときです。例えばアリスの拡大/縮小ゲームの例では、ケーキの時間について奇妙なことに気づいたかもしれません。

```js
document.getElementById("eat-me\_sprite").animate([], {
  duration: aliceChange.effect.timing.duration / 2,
});
```

ここで何がおこっているか理解するために、アリスのアニメーションを見てみましょう。

```js
const aliceChange = document
  .getElementById("alice")
  .animate(
    [
      { transform: "translate(-50%, -50%) scale(.5)" },
      { transform: "translate(-50%, -50%) scale(2)" },
    ],
    {
      duration: 8000,
      easing: "ease-in-out",
      fill: "both",
    },
  );
```

アリスのアニメーションでは、8 秒かけてサイズが半分から 2 倍になります。その後、彼女の効果を停止します。

```js
aliceChange.pause();
```

もしアニメーションの始めに一時停止させたままにしておくと、ボトル全部を飲み干したかのように、半分の大きさから始まることになります。アニメーションの "playhead" を中央に設定し、アニメーションがすでに半分終わっている状態にしたいと思います。`Animation.currentTime` を 4 秒に設定したいので、次のようにします。

```js
aliceChange.currentTime = 4000;
```

しかし、このアニメーションで作業している間、アリスの再生時間を何度も変更するかもしれません。彼女の `currentTime` を動的に設定すれば、時刻を 2 回更新する必要はないでしょう？実際、aliceChange の `Animation.effect` プロパティを参照することで、アリスに有効なエフェクトの詳細をすべて格納したオブジェクトを返すことができます。

```js
aliceChange.currentTime = aliceChange.effect.getComputedTiming().duration / 2;
```

`effect` を利用すると、アニメーションのキーフレームとタイミングのプロパティにアクセスできます。`aliceChange.effect.getComputedTiming()` はアリスのタイミングオブジェクトを示します。これには `duration` (en-US) が含まれています。
 アニメーションのタイムラインの中間点を取得するには、アリスの再生時間を半分に分割し、通常の身長に設定します。これで、アリスのアニメーションをそれぞれの方向に巻き戻したり再生したりすると、小さくしたり、大きくしたりすることができます。

また、ボトルとケーキの再生時間を設定するときにも同じことが出来ます。

```js
const drinking = document
  .getElementById("liquid")
  .animate([{ height: "100%" }, { height: "0" }], {
    fill: "forwards",
    duration: aliceChange.effect.getComputedTiming().duration / 2,
  });
drinking.pause();
```

これで、3 つのアニメーションがすべて 1 つの再生時間上に繋がり、1 つの場所から簡単に変更することが出来ます。

ウェブアニメーション API を利用して、アニメーションの現在の時刻を把握することも出来ます。ケーキを食べてなくなったり、ボトルが空になったりするとゲームが終了します。アリスが大きすぎてドアを通らなくなるか、小さすぎてドアノブに届かなくなるかはアリスのアニメーションによって表現されプレイヤーの操作に依存します。アリスのアニメーションの `currentTime` を取得して、彼女の `activeDuration` で割ることで彼女の大きさを把握できます。

```js
const endGame = () => {
  // アリスのタイムラインの再生位置を取得
  const alicePlayhead = aliceChange.currentTime;
  const aliceTimeline = aliceChange.effect.getComputedTiming().activeDuration;

  // アリスやその他のアニメーションを停止
  stopPlayingAlice();

  // 3 つのどれに入るかを判断
  const aliceHeight = alicePlayhead / aliceTimeline;

  if (aliceHeight <= 0.333) {
    // アリスが小さくなる
    // …
  } else if (aliceHeight >= 0.666) {
    // アリスが大きくなる
    // …
  } else {
    // アリスの大きさはあまり変わらない
    // …
  }
};
```

**メモ:** `getAnimations()` と `effect` は、この記事を書いている時点ではすべてのブラウザーで対応しているわけではありませんが、ポリフィルでは対応しています。

コールバックとプロミス
-----------

CSS アニメーションとトランジションには独自のイベントリスナーがあり、これらはウェブアニメーション API でも利用可能です。

* `onfinish` は終了イベントハンドラーであり、`finish()` メソッドを使用すると手動で起動することができます。
* `oncancel` は `cancel` のイベントハンドラーであり、`cancel()` メソッドを使用すると起動することができます。

ここでは、ケーキ、ボトル、アリスのコールバックを設定して、`endGame` 関数を起動します。

```js
// ケーキやボトルがなくなった時
nommingCake.onfinish = endGame;
drinking.onfinish = endGame;

// アリスのアニメーションが終わりに達した時
aliceChange.onfinish = endGame;
```

さらに良いことに、ウェブアニメーション API ではアニメーション終了時に解決されるか、またはキャンセル時に拒否される `finished` プロミスを提供しています。

まとめ
---

以上がウェブアニメーション API の基本的な機能です。これで、ブラウザーでのアニメーションという「ウサギの穴に飛び込む」準備ができ、自分自身でアニメーションの実験を書く準備ができたはずです。

関連情報
----

* 不思議の国のアリスの全体 (CodePen) を動作させたり、 フォークやシェアを行うことができます。
* Element.animate を気にせずにアニメーションする方法 (2016): ウェブアニメーション API の背景と、なぜ API が複数のウェブアニメーションメソッドよりもパフォーマンスが高いのかについて説明します。


キーフレームの形式 - Web API

キーフレームの形式
=========

`Element.animate()`、`KeyframeEffect()` (en-US)、`KeyframeEffect.setKeyframes()` (en-US) はいずれも、一連のキーフレームを表す形式のオブジェクトを受け入れます。この形式にはいくつかのオプションがあり、以下で説明します。

構文
--

キーフレームの形式には、2 つの異なる方法があります。

1. 反復処理するプロパティと値からなるオブジェクト（キーフレーム）の配列 (`array`) です。これは `getKeyframes()` (en-US) メソッドが返す正規の形式です。

```js
element.animate(
  [
    {
      // from
      opacity: 0,
      color: "#fff",
    },
    {
      // to
      opacity: 1,
      color: "#000",
    },
  ],
  2000,
);
```

各キーフレームのオフセットは `offset` 値を提供することで指定します。

```js
element.animate(
  [{ opacity: 1 }, { opacity: 0.1, offset: 0.7 }, { opacity: 0 }],
  2000,
);
```

**メモ:** `offset` 値は指定された場合、0.0 から 1.0 の間で昇順に並んでいなければなりません。

すべてのキーフレームにオフセットを指定する必要はありません。オフセットを指定しないキーフレームは、隣接するキーフレーム間で等間隔に配置されます。
 キーフレーム間に適用するイージングは、下記で示すように `easing` 値を提供することで指定します。

```js
element.animate(
  [
    { opacity: 1, easing: "ease-out" },
    { opacity: 0.1, easing: "ease-in" },
    { opacity: 0 },
  ],
  2000,
);
```

この例では、指定したイージングは指定したキーフレームから次のキーフレームまでしか適用されません。しかし、引数 `options` で指定した `easing` 値は、アニメーションの単一の反復、つまり再生時間全体に適用されます。
2. オブジェクト (`object`) で、アニメーションさせるプロパティと、反復する値の配列 (`array`) からなるキーと値のペアを格納します。

```js
element.animate(
  {
    opacity: [0, 1], // [ from, to ]
    color: ["#fff", "#000"], // [ from, to ]
  },
  2000,
);
```

この形式を使用した場合、配列のそれぞれの要素数は同じである必要はありません。指定された値はそれぞれ独立した空間となります。

```js
element.animate(
  {
    opacity: [0, 1], // offset: 0, 1
    backgroundColor: ["red", "yellow", "green"], // offset: 0, 0.5, 1
  },
  2000,
);
```

特別なキーである `offset`、`easing`、`composite`（下記で記述）をプロパティ値の横に並べて指定することができます。

```js
element.animate(
  {
    opacity: [0, 0.9, 1],
    offset: [0, 0.8], // Shorthand for [ 0, 0.8, 1 ]
    easing: ["ease-in", "ease-out"],
  },
  2000,
);
```

プロパティ値のリストから適切なキーフレームの集合を生成した後、指定されたオフセットがそれぞれ対応するキーフレームに適用されます。値が足りない場合、またはリストに `null` 値が格納されている場合、オフセットを指定していないキーフレームは、記述されている配列形式と同様に等間隔に配置されます。
 もし `easing` や `composite` の値がいくつかある場合、対応するリストは必要に応じて繰り返されます。
### 暗黙の to/from キーフレーム

新しいバージョンのブラウザーでは、アニメーションの始まりや終わりの状態のみ（つまり、単一のキーフレーム）を設定することができます。例えば、この単純なアニメーションを考えてみましょう。キーフレームオブジェクトは次のようになります、

```js
let rotate360 = [{ transform: "rotate(360deg)" }];
```

アニメーションの終わりの状態を指定しただけで、始めの状態は暗黙的に指定されています。

属性
--

キーフレームは、`animatable CSS properties`のいずれかのプロパティと値のペアを指定します。プロパティ名はキャメルケースを使用して指定しますので、例えば `background-color` は `backgroundColor` となり、`background-position-x` は `backgroundPositionX` となります。`margin` のような一括指定も使用できます。

例外的な CSS プロパティが 2 つあります。

* `float` は `cssFloat` と書く必要があります。"float" は JavaScript で予約語であるためです。ここでは参考程度のものです。"float" はアニメーション可能な CSS プロパティではなく、アニメーションには影響しないからです。
* `offset` は `cssOffset` と書く必要があります。"offset" は下記の通り、キーフレームのオフセットを表すからです。

以下の特殊な属性を指定することもできます。

offset

キーフレームのオフセットを `0.0` から `1.0` の間の数値、または `null` で指定します。これは CSS スタイルシートで `@keyframes` を使用して始まりと終わりの状態をパーセントで指定するのと同じです。この値が `null` または存在しない場合、キーフレームは隣接するキーフレーム間で等間隔に配置されます。

easing

連なった次のキーフレームまでの間で使用されるタイミング関数です。

composite

このキーフレームで指定した値と基底値を合成するために用いる `KeyframeEffect.composite` (en-US) 演算子です。効果に指定した合成処理を使用している場合は `auto` になります。

関連情報
----

* ウェブアニメーション API
* `Element.animate()`
* `KeyframeEffect()` (en-US)
* `KeyframeEffect.setKeyframes()` (en-US)


ウェブアニメーション API の概念 - Web API

ウェブアニメーション API の概念
==================

ウェブアニメーション API (Web Animations API, WAAPI) は、JavaScript 開発者にブラウザーのアニメーションエンジンへのアクセスを提供し、ブラウザー間でどのようにアニメーションが実装されるべきかを記述します。この記事では、WAAPI の背後にある重要な概念を紹介し、WAAPI をエフェクト的に使用することができるように、WAAPI の動作方法を理論的に理解できるように提供します。この API を使用する方法については、姉妹記事であるウェブアニメーション API の使用をご覧ください。

ウェブアニメーション API は宣言的な CSS のアニメーションやトランジションと、動的な JavaScript アニメーションの間のギャップを埋めます。つまり、あらかじめ定義した状態から別の状態に移行する CSS のようなアニメーションを作成したり操作したりするために使用することもできますし、変数、ループ、コールバックを使用して、変化する入力に応答するインタラクティブなアニメーションを作成することもできます。

歴史
--

10 年以上前、SMIL (Synchronized Multimedia Integration Language) （「スマイル」と読む）は SVG にアニメーションをもたらしました。当時は、ブラウザーが気にしなければならない唯一のアニメーションエンジンでした。5 つのブラウザーのうち 4 つのブラウザーが SMIL に対応していましたが、SMIL は SVG 要素のアニメーションのみで、CSS を使用することができず、非常に複雑で、実装上の不整合につながることが多かったのです。10 年後、Safari チームは CSS アニメーションと CSS トランジションの仕様を導入しました。

Internet Explorer チームは、すべてのブラウザーでアニメーション機能を統合し、正規化するアニメーション API をリクエストしました。こうして、Mozilla Firefox と Google Chrome の開発者の間で、すべてを支配する単一のアニメーション仕様、ウェブアニメーション API を作成する取り組みが本格的に始まりました。これで、現在および将来的なアニメーション仕様のためのWAAPIを獲得し、これらの仕様が一貫性を保ち、うまく連携できるようになりました。また、現在利用できる仕様で、すべてのブラウザーが準拠することができる参照ポイントも提供します。

![ウェブアニメーション API が CSS のトランジションやアニメーションを支配していることを示す図と、将来のアニメーション仕様を表す 3 つ目のカテゴリーにクエスチョンマークを付けたもの。](/ja/docs/Web/API/Web_Animations_API/Web_Animations_API_Concepts/waapi_diagram_white.png)

2 つのモデル: タイミングとアニメーション
----------------------

ウェブアニメーション API は 2 つのモデルの上で動作します。1 つは時間を処理するモデル（タイミング）、もう 1 つは時間の経過による視覚的な変化を処理するモデル（アニメーション）です。タイミングモデルは、設定された時間軸のどのあたりまで来たかを予定します。アニメーションモデルは、指定された時刻にアニメーションオブジェクトがどのように見えるかを決定します。

### タイミング

タイミングモデルは WAAPI で作業するためのバックボーンです。それぞれの文書には中心となるタイムラインである `Document.timeline` があり、ページが読み込まれた瞬間から永遠、またはウィンドウが閉じられるまで広がります。そのタイムラインに沿って、それぞれの時間に応じて展開されるのがアニメーションです。それぞれのアニメーションは、アニメーションの再生が始まる文書のタイムライン上の瞬間を表す `startTime` によってタイムラインのある点に関連付けられます。

アニメーションの再生は、すべてこのタイムラインに基づいています。アニメーションをシークすると、タイムラインに沿ってアニメーションの位置が移動されます。再生速度を遅くしたり速くしたりすると、タイムライン上でのアニメーションの広がりが凝縮されたり展開されたりします。アニメーションを繰り返すと、タイムラインに沿ってさらに反復処理が行われます。ウェブアニメーション API は多くの可能性を開きます。

### アニメーション

アニメーションモデルは、指定された時刻にアニメーションがどのように見えるかのスナップショットの配列と考えることができます。

![アニメーションモデルを、タイムラインに沿って配置された一連のスナップショットとして視覚化する方法を示す図。この場合、チェシャ猫の写真が0秒（ある）から8秒（すべてあるわけではなく、彼の笑顔だけが残っている）まで続きます。](/ja/docs/Web/API/Web_Animations_API/Web_Animations_API_Concepts/waapi_timing_diagram_white.png)

主要概念
----

ウェブアニメーションは、一緒に動作するタイムラインオブジェクト、アニメーションオブジェクト、アニメーションエフェクトオブジェクトで構成されています。これらのオブジェクトを組み合わせることで、自分自身でアニメーションを作成することができます。

### タイムライン

タイムラインオブジェクトは `currentTime` (en-US) という便利なプロパティを提供しており、これでページが開かれてからの時間を知ることができます。これはページが開かれてから始まる文書タイムラインにおける「現在の時刻」を表します。執筆辞典では、タイムラインオブジェクトは 1 種類しかありません。現在の文書のの `timeline` に基づいたものです。将来的には、ページの長さに対応したタイムラインオブジェクト、おそらく `ScrollTimeline` や、それ以外のものが登場するかもしれません。

### アニメーション

アニメーションオブジェクトは、DVD プレーヤーのように捉えることができます。メディアの再生を制御するために使用できますが、再生するメディアがなければ、何もできません。アニメーションオブジェクトは、アニメーションエフェクト（特にキーフレームエフェクト）という形でメディアを受け入れます。DVD プレーヤーのように、アニメーションオブジェクトのメソッドを使用して、再生、一時停止、シーク、アニメーションの再生方向や速度の制御をすることができます。

![DVD プレーヤーが DVD を再生するように、アニメーションが KeyframeEffect を再生する様子を示したものです。](/ja/docs/Web/API/Web_Animations_API/Web_Animations_API_Concepts/waapi_player_diagram_white.png)

### アニメーションエフェクト

アニメーションオブジェクトが DVD プレーヤーだとすると、アニメーションエフェクトや キーフレームエフェクトは、DVD だと考えることができます。キーフレームエフェクトは、最小限のキーの集合と、それらがアニメーションされる時間を含む情報の束です。アニメーションオブジェクトは、この情報を受け取り、タイムラインオブジェクトを使用して、見たり参照したりできる再生可能なアニメーションを組み立てます。

現在、利用できるアニメーションエフェクトの種類は `KeyframeEffect` (en-US) の 1 つだけです。将来的には、すべての種類のアニメーションエフェクトをすべて保有する可能性があります。グループ化やシーケンス化のためのエフェクトであり、例えば、Flash で保有していた機能とは異なります。実際、グループエフェクトとシーケンスエフェクトは、現在進行中のウェブアニメーション API のレベル 2 仕様にすでに概説されています。

### バラバラの断片からアニメーションを組み立てる

これらのピースをすべて組み立てて作業するアニメーションを作成するには、`Animation()` コンストラクターを使用するか、`Element.animate()` ショートカット関数を使用します。（`Element.animate()` の使い方について詳しくは、ウェブアニメーション API の使用を参照してください。）

用途
--

この API を使用すると、CSS が作成するような、よりわかりやすく宣言的なアニメーションだけでなく、その場で更新できる動的なアニメーションも作成することができます。自動テストで使用して、UI アニメーションが正しく実行されていることを確認することができます。これはタイムラインなどのアニメーション開発ツールを構築するためのブラウザーレンダリングエンジンを開くためのものです。また、カスタムまたは商用のアニメーションライブラリーを構築するためのパフォーマンスベースでもあります（Animating like you just don't care with Element.animate を参照）。場合によっては、多くの用途ではバニラ JavaScript が jQuery なしで使用できようになったのと同様に、本格的なライブラリーの必要性を完全に否定することになるかもしれません。

関連情報
----

* ウェブアニメーション API — メインページ
* ウェブアニメーション API の使用 — ガイド
* 不思議の国のアリスの全体のデモ（CodePen）で実行、フォーク、共有が可能
* web-animations-js — ウェブアニメーション API のポリフィル


履歴 API の操作 - Web API

履歴 API の操作
==========

`pushState()` および `replaceState()` メソッドは、それぞれ履歴項目を追加したり変更したりします。これらのメソッドは `popstate` イベントと一緒に動作します。

履歴項目の追加と修正
----------

`pushState()` を使うことで、履歴の状態を変更した後に生成される `XMLHttpRequest` オブジェクトの HTTP ヘッダー中のリファラも変更されます。リファラーは `XMLHttpRequest` オブジェクトが生成された時点での `this` となるウィンドウの持つ文書の URL となります。

### pushState() の例

以下の JavaScript が `https://mozilla.org/foo.html` で実行されると想定してください。

```js
const stateObj = {
  foo: "bar",
};

history.pushState(stateObj, "page 2", "bar.html");
```

これにより URL バーには `https://mozilla.org/bar.html` と表示されますが、ブラウザーは `bar.html` を読み込むことはなくまたその存在をチェックすることはありません。

ユーザーが `https://google.com` へ移動し、それから**戻る**ボタンをクリックしたとします。このとき、 URL バーは `https://mozilla.org/bar.html` を表示し、`history.state` は `stateObj` になります。`popstate` イベントはページが再読み込みされたために発行されません。ページそれ自体は `bar.html` のように見えます。

再び**戻る**ボタンをクリックすると、URL は `https://mozilla.org/foo.html` へ変化し、 `popstate` イベントが発行され、状態は null オブジェクトとなります。ここでもまた、`popstate` イベントを受け取って手動でコンテンツを変更することは可能ですが、戻るという操作によって戻る前のコンテンツが変更されるわけではありません。

### pushState() メソッド

`pushState()` は、 **状態オブジェクト**、**title** （今は無視されます）、（任意で） **URL** の 3 つの引数を使用します。

これら 3 つの引数について詳細に見ていきましょう。

**状態オブジェクト**

 状態オブジェクトは JavaScript のオブジェクトで、 `pushState()` によって作成された新しい履歴項目と関連付けられています。ユーザーが新しい状態に遷移するたびに `popstate` イベントが発行され、そのイベントの `state` プロパティに履歴項目の状態オブジェクトのコピーが格納されます。
 状態オブジェクトはシリアライズ可能なものであれば何でも構いません。Firefox は状態オブジェクトをユーザーのディスクに保存し、ユーザーがブラウザーを再起動した後に復元できるようにするため、状態オブジェクトのシリアライズ表現に 640k 文字というサイズ制限を課しています。もし、シリアライズされた表現がこれより大きい状態オブジェクトを `pushState()` に渡すと、このメソッドは例外を発生します。これ以上の領域が必要な場合は、 `sessionStorage` や `localStorage` を使用することをおすすめします。

**title**

Safari 以外のすべてのブラウザーは、現在この引数を無視しています。ただし、将来的には使用する可能性があります。ここで空文字列を渡せば、将来このメソッドが変更されても安全です。あるいは、移動先の状態を表す短いタイトルを渡すこともできます。

**URL**

新しい履歴項目の URL はこの引数で与えられます。ブラウザーは `pushState()` の呼び出しの後にはこの URL を読み込もうとしませんが、例えばユーザーがブラウザーを再起動した後などには URL を読み込もうとする可能性があることに注意してください。新しい URL は絶対的である必要はありません。相対的である場合、現在の URL に対して相対的に解決されます。新しい URL は現在の URL と同じオリジンでなければなりません。そうでない場合、`pushState()` は例外を発生します。この引数はオプションです。指定しなかった場合、文書の現在の URL が設定されます。

ある意味では、`pushState()` の呼び出しは `window.location = "#foo"` と設定するのと似ています。どちらも、現在の文書に関連する別の履歴項目の生成と有効化を行います。

しかし、 `pushState()` にはいくらかの利点があります。

* 新しい URL は、現在の URL と同じオリジンであればどの URL にもなることができます。対照的に、 `window.location` では同じ `document` のままで、ハッシュの変更のみが可能です。
* 必ずしも URL を変更する必要はありません。逆に、 `window.location = "#foo";` では、現在のハッシュが `#foo` でない場合、新しい履歴項目の作成以外のことはできません。
* 新しい履歴項目に任意のデータを関連付けることができます。ハッシュを基にしたアプローチでは、関連するデータを含めた短い文字列を全てエンコードする必要があります。
* その後、 `title` がブラウザーで使用された場合、このデータを（例えばハッシュとは関係なく）使用することができます。

新しい URL が古い URL とハッシュだけ異なっていても、 `pushState()` は決して `hashchange` イベントを発行させないことに注意してください。

他の文書では、 `null` の名前空間 URI を持つ要素を作成します。

### replaceState() メソッド

`history.replaceState()` はちょうど `history.pushState()` のように動作しますが、 `replaceState()` は新しく履歴項目を作成するのではなく、現在の履歴項目を修正します。ただし、グローバルなブラウザー履歴に新しい項目が作成されるのを防ぐものではありません。

具体的には、何らかのユーザーのアクションを受け、現在の履歴項目の URL または 状態オブジェクトを更新したい場合に `replaceState()` が役立ちます。

### replaceState() の例

`https://mozilla.org/foo.html` で次の JavaScript を実行したとします。

```js
const stateObj = {
  foo: "bar",
};
history.pushState(stateObj, "page 2", "bar.html");
```

上記2行の説明は、上記の *pushState() メソッドの例* の部分で得ることができます。

次に、`https://mozilla.org/bar.html` で次の JavaScript を実行したとします。

```js
history.replaceState(stateObj, "page 3", "bar2.html");
```

これによって URL バーには `https://mozilla.org/bar2.html` が表示されますが、ブラウザーは `bar2.html` の読み込みを行わず、`bar2.html` が存在するかどうかもチェックしません。

仮に今、ユーザーが `https://www.microsoft.com` へ移動し、**戻る**ボタンを押したとします。この時点で URL バーには `https://mozilla.org/bar2.html` が表示されています。もしユーザーが再び**戻る**ボタンを押すと、 URL バーには `https://mozilla.org/foo.html` が表示され、`bar.html` を完全に回避します。

### popstate イベント

アクティブな履歴項目が変更される度にウィンドウへと `popstate` イベントが発行されます。`pushState` の呼び出しまたは `replaceState` の呼び出しの影響によって、アクティベートされた履歴項目が作成された場合、`popstate` イベントの `state` プロパティは履歴項目の 状態オブジェクトのコピーを含みます。

使い方の例は `popstate` を参照してください。

### 現在の状態を読み取る

ページが読み込まれたとき、 ページには null ではない状態オブジェクトがあるかもしれません。これが起こるのは、例えば、（`pushState()` または `replaceState()`) の使用によって）ページに状態オブジェクトが設定されており、ユーザーがブラウザーを再起動した場合です。ページを再読み込みした際にページは `onload` イベントを受け取りますが `popstate` イベントは受け取られません。しかしながら `history.state` プロパティを読み取った場合、`popstate` が発行された際に取得できるであろう状態オブジェクトを得ることができるでしょう。

このように `history.state` プロパティを用いることで、 `popstate` イベントを待つことなく現在の履歴項目の状態を読み取ることができます。

```js
const currentState = history.state;
```

関連情報
----

* 履歴 API
* 履歴ナビゲーションの例
* `history` グローバルオブジェクト


端末の方向と 3D 座標変換の使用 - Web API

端末の方向と 3D 座標変換の使用
=================

 この記事では、 CSS の 3D 変換と組み合わせて端末の方向情報を使用する方法についてのヒントを提供します。
方向を使用して要素を回転
------------

方向に関するデータ を 3D 座標変換 に変換する最も簡単な方法は、基本的に `alpha`、`gamma`、`beta` の値を `rotateZ`、`rotateX`、`rotateY` の値として使用することです。

ただし、端末方向の座標系は、 CSS 座標系とは異なる形で記述されていることに留意する必要があります。すなわち、前者は右手で Y 軸が正の値で上向き、後者は Y 軸が正の値で下向きの左手座標系です。さらに、端末方向の角度の回転は常に Z - X' - Y'' の順序で行われるべきですが、これはいくつかの CSS 座標変換 の順序とは一致しません。このような違いが、現実的な結果をもたらします。

* 角度の回転の順番は重要なので、アルファ、ベータ、ガンマの回転がこの順番で適用されていることを確認してください。
* CSS 座標変換の `rotate3d()` と `DOMMatrixReadOnly.rotate()` と `DOMMatrix. rotateSelf()` 関数は、Z - Y' - X''の順番で角度の回転を適用するので、アルファ、ベータ、ガンマ回転のいずれかを単一の呼び出しで正しい順番に適用することはできません。その代わりに、各軸を正しい順序で個別に回転させる必要があります。
* 上記の座標系の違いにより、原点を見ていくときの回転は、 CSS では時計回りに、端末方向仕様では反時計回りに適用されます。この意味は、アルファとベータは 2 つの座標系で異なる方向を指しているため、（Z と X を中心とした回転を）反転させる必要があることを意味します。しかし、ガンマ（Y 周りの回転）はそのままにしておく必要があります。
 コードの例は次の通りです。

```js
const elem = document.getElementById("view3d");

window.addEventListener("deviceorientation", (e) => {
  elem.style.transform = `rotateZ(${-e.alpha}deg) rotateX(${-e.beta}deg) rotateY(${
 e.gamma
 }deg)`;
});
```

`rotate3d()` の角度を `deviceorientation` の角度に変換
--------------------------------------------

rotate3d の軸角を `deviceorientation` で使用する方向オイラー角に変換する必要がある場合は、以下のアルゴリズムを使用することができます。

```js
// rotate3d の軸角度を端末方向角度に変換
function orient(aa) {
  const x = aa.x,
    y = aa.y,
    z = aa.z,
    a = aa.a,
    c = Math.cos(aa.a),
    s = Math.sin(aa.a),
    t = 1 - c,
    // 軸角度と回転行列
    rm00 = c + x \* x \* t,
    rm10 = z \* s + y \* x \* t,
    rm20 = -y \* s + z \* x \* t,
    rm01 = -z \* s + x \* y \* t,
    rm11 = c + y \* y \* t,
    rm21 = x \* s + z \* y \* t,
    rm02 = y \* s + x \* z \* t,
    rm12 = -x \* s + y \* z \* t,
    rm22 = c + z \* z \* t,
    TO\_DEG = 180 / Math.PI,
    ea = [],
    n = Math.hypot(rm22, rm20);

  // オイラー角への回転行列
  ea[1] = Math.atan2(-rm21, n);

  if (n > 0.001) {
    ea[0] = Math.atan2(rm01, rm11);
    ea[2] = Math.atan2(rm20, rm22);
  } else {
    ea[0] = 0;
    ea[2] = (rm21 > 0 ? 1 : -1) \* Math.atan2(-rm10, rm00);
  }

  return {
    alpha: -ea[0] \* TO\_DEG - 180,
    beta: -ea[1] \* TO\_DEG,
    gamma: ea[2] \* TO\_DEG,
  };
}
```

関連情報
----

* CSS 座標変換の使用
* 端末の方向の検出


方向および動きとして示されるデータ - Web API

方向および動きとして示されるデータ
=================

方向や動きのイベントを使用するときは、ブラウザーから与えられる値の意味を理解することが重要です。この記事では操作時の座標システムに関する詳細情報と、それらの使い方を説明します。

座標フレームについて
----------

**座標フレーム** (coordinate frame) は、オブジェクトに関する 3 軸 (X, Y, Z) の方向が定義されているシステムです。方向や動きのイベントを使用するときに考慮する座標フレームは 2 つあります。

### 地球座標フレーム

地球座標フレーム (Earth coordinate frame) は、地球の中心に固定されている座標フレームです。すなわち、軸は重力によって引かれる力および標準的な磁北方向に基づいて揃えられます。私たちは大文字 ("X"、"Y"、"Z") を、地球座標フレームの軸を示すために使用します。

* **X** 軸は地面に沿ってたどり、Y 軸と直交します。また、軸の正の方向が東を指します (従って、負の方向は西を指します)。
* **Y** 軸は地面に沿ってたどり、正の方向が真北 (すなわち北極であり、磁北ではありません) を、負の方向が真南を指します。
* **Z** 軸は地面に直交します。これは、端末と地球の中心との間に引かれた線と考えてください。Z 座標の値は正の方向が上向き (地球の中心から遠ざかる)、負の方向が下向き (地球の中心に向かう) です。
### 端末座標フレーム

端末座標フレーム (Device coordinate frame) は、端末の中心に固定された座標フレームです。私たちは小文字 ("x"、"y"、"z") を、端末座標フレームの軸を示すために使用します。

![モバイル端末の 3 軸を表した図](/ja/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/axes.png)

* **x** 軸は画面の水平面にあり、正の方向が右を、負の方向が左を指します。
* **y** 軸は画面の水平面にあり、正の方向が上端側を、負の方向が下端側を指します。
* **z** 軸は画面やキーボードに直交しており、正の方向が画面から外側へ伸びていきます。

**メモ:** 携帯電話やタブレットでは、端末の方向が常に画面の標準的な方向に対して考慮され、これは、ほとんどの端末では「ポートレート」 (縦) の方向になります。ノートパソコンでは、方向はキーボードに対して考慮されます。補正するために端末の方向の変化を検知したい場合は、 `change` (en-US) イベントが使用できます。

回転について
------

回転は、端末座標フレームと地球座標フレームとの度合いの違いという点から各軸で表現され、またそれは度単位で測られます。

### アルファ

z 軸を中心にした回転、すなわち端末をひねるようにすると、 **アルファ** 回転角が変化します。

![正のアルファ値は端末を反時計回りに回転させます。](/ja/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/alpha.png)

アルファ角は端末の上端が地球の北極をまっすぐ向いているときが 0 度であり、端末が左へ回転するのに従って増加します。

### ベータ

X 軸を中心にした回転、すなわち端末を向こう側やユーザー側へ向けて傾けると、 **ベータ** 回転角が変化します。

![正のベータピッチは端末を反時計回りに回転させます。](/ja/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/beta2.png)

ベータ角は端末の上端および下端から地球の表面までの距離がどちらも同じであるときが 0 度であり、端末を前方へ傾けるに従って 180 度まで増加、後方へ傾けるに従って -180 度まで減少します。

### ガンマ

Y 軸を中心にした回転、すなわち端末を左右に傾けると、 **ガンマ** 回転角が変化します。

![正の値のガンマは端末を右に傾けます。](/ja/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/gamma.png)

ガンマ角は端末の左端および右端から地球の表面までの距離がどちらも同じであるときが 0 度であり、端末を右へ傾けるのに従って 90 度まで増加、左へ傾けるのに従って -90 度まで減少します。


端末の方向の検出 - Web API

端末の方向の検出
========

**安全なコンテキスト用:** この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

**安全なコンテキスト用:** この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

次第に、ウェブを利用可能な端末は、自身の**方向**を特定できるようになってきました。つまり端末は、重力との関係による自身の向きの変化を示すデータを報告できます。特に携帯電話のようなハンドヘルド端末は、表示内容が直立し続けるよう自動的に回転させるためにこの情報を使用できます。画面の幅が高さより大きくなるように端末を回転させたときは、ウェブコンテンツをワイドスクリーン表示にします。

方向の情報を制御する JavaScript イベントが 2 つあります。ひとつは `DeviceOrientationEvent` であり、加速度センサーが端末の方向の変化を検出したときに発生します。 orientation イベントが報告するデータを受け取って処理することで、ユーザが端末を動かすことによる方向や高さの変化に対してインタラクティブに応答できるようになります。

もうひとつのイベントは `DeviceMotionEvent` であり、加速度が変化したときに発生します。こちらは方向ではなく加速度の変化を監視することが、`DeviceOrientationEvent` との違いです。一般的に `DeviceMotionEvent` を検出できるセンサーには、可動部があるストレージ装置を保護するためノートパソコンに内蔵するものも含みます。`DeviceOrientationEvent` は、モバイル端末でとても一般的です。

orientation イベントの処理
-------------------

方向の変化を受け取り始めるために必要なことは、 `deviceorientation` イベントを待ち受けすることだけです。

```js
window.addEventListener("deviceorientation", handleOrientation, true);
```

イベントリスナー（この場合は `handleOrientation()` と呼ばれる JavaScript 関数）を登録すると、リスナー関数は定期的に更新された方向データを取得します。

orientation イベントは 4 つの値を持ちます。

* `DeviceOrientationEvent.absolute`
* `DeviceOrientationEvent.alpha`
* `DeviceOrientationEvent.beta`
* `DeviceOrientationEvent.gamma`

イベントハンドラー関数は以下のようなものです。

```js
function handleOrientation(event) {
  const absolute = event.absolute;
  const alpha = event.alpha;
  const beta = event.beta;
  const gamma = event.gamma;

  // 新たな方向データに基づいて処理を行う
}
```

**メモ:** parallax は、モバイル端末の加速度センサーとジャイロスコープのデータを正規化するためのポリフィルです。これは、端末の方向に対する対応の違いを克服するのに有益です。

### 方向として示される値

それぞれの軸で報告される値は、標準座標系の軸を中心にした回転量を表します。これらは方向および動きとして示されるデータの説明の記事で詳しく説明しており、ここでは概要を記載します。

* `DeviceOrientationEvent.alpha` の値は z 軸を中心にした端末の動きを表し、0 以上 360 未満の範囲による度数で表されます。
* `DeviceOrientationEvent.beta` の値は x 軸を中心にした端末の動きを表し、-180 以上 180 未満の範囲の値による度数で表されます。これは端末の前後の動きです。
* `DeviceOrientationEvent.gamma` の値は y 軸を中心にした端末の動きを表し、-90 以上 90 未満の範囲の値による度数で表されます。これは端末の左右の動きです。
### 例

このサンプルは方向を検出可能な端末上で、 `deviceorientation` イベントに対応するブラウザーで実行する場合に動作します。

庭にボールがあると考えてください。

```html
<div class="garden">
  <div class="ball"></div>
</div>
端末を地面に並行に置いてください。 X 軸と Y 軸に沿って回転させ、ボールがそれぞれ上下左右に移動するのを確認しましょう。
<pre class="output"></pre>
```

庭の幅は 200 ピクセルであり（小さな庭です）、ボールは中心にあります。

```css
.garden {
  position: relative;
  width: 200px;
  height: 200px;
  border: 5px solid #ccc;
  border-radius: 10px;
}

.ball {
  position: absolute;
  top: 90px;
  left: 90px;
  width: 20px;
  height: 20px;
  background: green;
  border-radius: 100%;
}
```

端末を動かすと、その動きに応じてボールが移動します。

```js
const ball = document.querySelector(".ball");
const garden = document.querySelector(".garden");
const output = document.querySelector(".output");

const maxX = garden.clientWidth - ball.clientWidth;
const maxY = garden.clientHeight - ball.clientHeight;

function handleOrientation(event) {
  let x = event.beta; // [-180,180) の範囲で角度を表す
  let y = event.gamma; // [-90,90) の範囲で角度を表す

  output.textContent = `beta: ${x}\n`;
  output.textContent += `gamma: ${y}\n`;

  // 端末をひっくり返したくはないため、
  // x の値を [-90,90] の範囲に制限する
  if (x > 90) {
    x = 90;
  }
  if (x < -90) {
    x = -90;
  }

  // 計算を容易にするため、x および y の値の範囲を
  // 0 から 180 に変換する
  x += 90;
  y += 90;

  // 10 は、ボールのサイズの半分である。
  // これにより、配置場所をボールの中心に合わせる
  ball.style.left = `${(maxY \* y) / 180 - 10}px`; // Y 軸を中心に端末を移動させると、ボールが水平に移動
  ball.style.top = `${(maxX \* x) / 180 - 10}px`; // X 軸を中心に端末を移動させると、ボールが垂直に移動
}

window.addEventListener("deviceorientation", handleOrientation);
```

こちらをクリックすると、新しいウィンドウでこの例を開きます。 `deviceorientation` はどのブラウザーでも別オリジンの `<iframe>` では動作しないからです。

motion イベントの処理
--------------

motion イベントは orientation イベントと同じ方法で扱えますが、イベント名は `devicemotion` になります。

```js
window.addEventListener("devicemotion", handleMotion, true);
```

実際どのように変化したかの情報は、 `DeviceMotionEvent` オブジェクトが提供します。これはイベントリスナー（この例では `handleMotion()`）の引数として渡されます。

motion イベントは 4 つのプロパティを持ちます。

* `DeviceMotionEvent.acceleration`
* `DeviceMotionEvent.accelerationIncludingGravity`
* `DeviceMotionEvent.rotationRate`
* `DeviceMotionEvent.interval`
### 動きとして示される値

`DeviceMotionEvent` オブジェクトはウェブ開発者に、端末の位置や方向が変化した速度の情報を提供します。変化量は 3 つの軸 (詳しくは方向および動きとして示されるデータの説明をご覧ください) に沿って表します。

`acceleration` および `accelerationIncludingGravity` で対応する軸は以下のとおりです。

`x`

西から東へ向かう軸を表します。

`y`

南から北へ向かう軸を表します。

`z`

地面から直立する軸を表します。

`rotationRate` では状況が若干異なります。こちらの情報はそれぞれ以下のように対応します:

`alpha`

画面（デスクトップ環境ではキーボード）から直立する軸を表します。

`beta`

画面の表面（デスクトップ環境ではキーボード）の左から右へ向かう軸に沿った回転量を表します。

`gamma`

画面の表面（デスクトップ環境ではキーボード）の下から上へ向かう軸に沿った回転量を表します。

最後に `interval` は、端末からデータを取得する間隔をミリ秒単位で表します。

仕様書
---

| Specification |
| --- |
| DeviceOrientation Event Specification # devicemotion |
| DeviceOrientation Event Specification # deviceorientation |

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

### api.DeviceMotionEvent

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

### api.DeviceOrientationEvent

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

関連情報
----

* `DeviceOrientationEvent`
* `DeviceMotionEvent`
* 方向および動きとして示されるデータの説明
* 3D 座標変換での deviceorientation の使用
* Cyber Orb: 端末の向きを使用した 2D 迷路ゲーム (en-US)


DOMRectReadOnly: DOMRectReadOnly() コンストラクター - Web API

DOMRectReadOnly: DOMRectReadOnly() コンストラクター
===========================================

**`DOMRectReadOnly()`** コンストラクターは新しい `DOMRectReadOnly` オブジェクトを生成します。

構文
--

```js
new DOMRectReadOnly(x, y, width, height)
```

### 引数

`x`

`DOMRectReadOnly` の原点の `x` 座標です。

`y`

`DOMRectReadOnly` の原点の `y` 座標です。

`width`

`DOMRectReadOnly` の幅です。

`height`

`DOMRectReadOnly` の高さです。

例
-

新しい `DOMRectReadOnly` を作成するには、次のようなコード行を実行します。

```js
const myDOMRect = new DOMRectReadOnly(0, 0, 100, 100);
// 'myDOMRect' をコンソールで実行すると、次の行が返ります。
// DOMRectReadOnly { x: 0, y: 0, width: 100, height: 100, top: 0, right: 100, bottom: 100, left: 0 }
```

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-domrectreadonly |

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

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

関連情報
----

* `DOMPoint`
* `DOMRect`


DOMRectReadOnly: height プロパティ - Web API

DOMRectReadOnly: height プロパティ
=============================

**`height`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の高さを表します。

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-height |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: bottom プロパティ - Web API

DOMRectReadOnly: bottom プロパティ
=============================

**`bottom`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の下端の座標値を返します。（`y + height` と同じか、 `height` が負の数であれば `y` と同じ値です。）

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-bottom |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: width プロパティ - Web API

DOMRectReadOnly: width プロパティ
============================

**`width`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の幅を表します。

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-width |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: fromRect() 静的メソッド - Web API

DOMRectReadOnly: fromRect() 静的メソッド
==================================

**`fromRect()`** は `DOMRectReadOnly` オブジェクトの静的メソッドで、指定された位置と大きさで新しい `DOMRectReadOnly` オブジェクトを作成します。

構文
--

```js
DOMRectReadOnly.fromRect()
DOMRectReadOnly.fromRect(rectangle)
```

### 引数

`rectangle` 省略可

矩形の位置と寸法を指定するオブジェクト。すべてのプロパティは既定で `0` です。プロパティは次の通りです。

* `x`: 矩形の左端の座標です。
* `y`: 矩形の上端の座標です。
* `width`: 矩形の幅です。
* `height`: 矩形の高さです。

### 返値

`DOMRectReadOnly` のインスタンスです。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-fromrect |

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

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


DOMRectReadOnly: x プロパティ - Web API

DOMRectReadOnly: x プロパティ
========================

**`x`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、 `DOMRect` の原点の X 座標を表します。

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-x |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: left プロパティ - Web API

DOMRectReadOnly: left プロパティ
===========================

**`left`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の左端の座標を返します。（`x` と同じ、または `width` が負の数であれば `x + width` と同じです。）

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-left |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: top プロパティ - Web API

DOMRectReadOnly: top プロパティ
==========================

**`top`** は **`DOMRectReadOnly`** の読み取り専用インターフェイスで、 `DOMRect` の上端の座標値を返します。（`y` と同じ、または `height` が負の数の場合は `y + height` と同じです。）

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-top |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: y プロパティ - Web API

DOMRectReadOnly: y プロパティ
========================

**`y`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の原点の Y 座標を表します。

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-y |

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

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

関連情報
----

* `DOMRect`


DOMRectReadOnly: right プロパティ - Web API

DOMRectReadOnly: right プロパティ
============================

**`right`** は **`DOMRectReadOnly`** インターフェイスの読み取り専用プロパティで、この `DOMRect` の右側の座標値を返します。（`x + width` と同じ、または `width` が負の数の場合は `x` と同じです。）

値
-

倍精度浮動小数点値です。

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrectreadonly-right |

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

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

関連情報
----

* `DOMRect`


GPUAdapterInfo: architecture プロパティ - Web API

GPUAdapterInfo: architecture プロパティ
==================================

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

`GPUAdapterInfo` インターフェイスの読み取り専用プロパティ **`architecture`** は、アダプターが属している GPU のファミリーまたはクラスの名前を返します。取得できない場合は空文字列を返します。

値
-

文字列です。

例
-

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const adapterInfo = await adapter.requestAdapterInfo();
  console.log(adapterInfo.architecture);

  // ...
}
```

仕様書
---

| Specification |
| --- |
| WebGPU # dom-gpuadapterinfo-architecture |

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

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

関連情報
----

* WebGPU API


GPUAdapterInfo: vendor プロパティ - Web API

GPUAdapterInfo: vendor プロパティ
============================

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

`GPUAdapterInfo` インターフェイスの読み取り専用プロパティ **`vendor`** は、アダプターのベンダーの名前を返します。取得できない場合は空文字列を返します。

値
-

文字列です。

例
-

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const adapterInfo = await adapter.requestAdapterInfo();
  console.log(adapterInfo.vendor);

  // ...
}
```

仕様書
---

| Specification |
| --- |
| WebGPU # dom-gpuadapterinfo-vendor |

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

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

関連情報
----

* WebGPU API


GPUAdapterInfo: description プロパティ - Web API

GPUAdapterInfo: description プロパティ
=================================

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

`GPUAdapterInfo` インターフェイスの読み取り専用プロパティ **`description`** は、アダプターを表現する人間に読める文字列を返します。取得できない場合は空文字列を返します。

値
-

文字列です。

例
-

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const adapterInfo = await adapter.requestAdapterInfo();
  console.log(adapterInfo.description);

  // ...
}
```

仕様書
---

| Specification |
| --- |
| WebGPU # dom-gpuadapterinfo-description |

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

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

関連情報
----

* WebGPU API


GPUAdapterInfo: device プロパティ - Web API

GPUAdapterInfo: device プロパティ
============================

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

`GPUAdapterInfo` インターフェイスの読み取り専用プロパティ **`device`** は、アダプターのベンダー固有の識別子を返します。取得できない場合は空文字列を返します。

値
-

文字列です。

例
-

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const adapterInfo = await adapter.requestAdapterInfo();
  console.log(adapterInfo.device);

  // ...
}
```

仕様書
---

| Specification |
| --- |
| WebGPU # dom-gpuadapterinfo-device |

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

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

関連情報
----

* WebGPU API


Response.formData() - Web API

Response.formData()
===================

**`formData()`** は `Response` インターフェイスのメソッドで、 `Response` のストリームを取得して完全に読み取ります。 `FormData` オブジェクトで解決されるプロミスを返します。

**メモ:** これは主にサービスワーカーに関連しています。 ユーザーがフォームを送信し、サービスワーカーがリクエストに介入した場合を考えてみましょう。 例えば、キーと値のマップを取得するために `formData()` を呼び出し、一部のフィールドを修正した後、フォームをサーバー側に送信 (またはローカルで使用) することができます。

構文
--

```js
formData()
```

### 引数

なし。

### 返値

`FormData` オブジェクトで解決される `Promise`。

例
-

TBD.

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-formdata① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.url - Web API

Response.url
============

**`url`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスの URL を保持します。
 `url` プロパティの値は、あらゆるリダイレクトの後に得られる最終的な URL になります。

値
-

文字列です。

例
-

Fetch Response の例 （Fetch Response のライブ版 を参照）では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

なお、 `fetch()` ブロックの先頭で、レスポンスの `url` 値をコンソールにログ出力していることに注意してください。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.url); // returns https://mdn.github.io/dom-examples/fetch/fetch-response/flowers.jpg
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-url① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.arrayBuffer() - Web API

Response.arrayBuffer()
======================

**`arrayBuffer()`** は `Response` インターフェイスのメソッドで、リクエストの本体を読み取り、 `ArrayBuffer` で解決されるプロミスを返します。

構文
--

```js
arrayBuffer()
```

### 引数

なし。

### 返値

`ArrayBuffer` で解決されるプロミス。

例
-

### 音楽の演奏

fetch array buffer のライブでは、Play ボタンを配置して、押下されると `getData()` 関数が実行されるようになっています。 再生する前に音声ファイル全体をダウンロードすることに注意してください。ダウンロード中に演奏を開始したい (つまりストリーム再生したい) 場合は、次のように `HTMLAudioElement` を使いましょう。

```js
new Audio("music.ogg").play();
```

`getData()` 関数内では、`Request()` コンストラクターを使用して新しいリクエストを作成し、それを使用して OGG 音声トラックを読み取ります。 また、`AudioContext.createBufferSource` を使用して、音声バッファーソースを作成します。 読み取りが成功したら、`arrayBuffer()` を使用してレスポンスから `ArrayBuffer` を読み取り、 `AudioContext.decodeAudioData()` を使用して音声データをデコードし、デコードされたデータを音声バッファーソースのバッファー（`source.buffer`）として設定し、それから `AudioContext.destination` にソースを接続します。

`getData()` の実行が完了すると、`start(0)` で音声ソースの再生を開始し、それから再生中に再度再生ボタンをクリックできないようにするために（これはよくエラーの原因になります）ボタンを無効化しています。

```js
function getData() {
  const audioCtx = new AudioContext();

  return fetch("viper.ogg")
    .then((response) => {
      if (!response.ok) {
        throw new Error(`HTTP error, status = ${response.status}`);
      }
      return response.arrayBuffer();
    })
    .then((buffer) => audioCtx.decodeAudioData(buffer))
    .then((decodedData) => {
      const source = new AudioBufferSourceNode();
      source.buffer = decodedData;
      source.connect(audioCtx.destination);
      return source;
    });
}

// wire up buttons to stop and play audio

play.onclick = () => {
  getData().then((source) => {
    source.start(0);
    play.setAttribute("disabled", "disabled");
  });
};
```

### ファイルを読む

`Response()` コンストラクターは、 `File` と `Blob` を受け入れるため、 `File` を他の形式に読み込むために使用することができます。

```js
function readFile(file) {
  return new Response(file).arrayBuffer();
}
```

```html
<input type="file" onchange="readFile(this.files[0])" />
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-arraybuffer① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.json() - Web API

Response.json()
===============

**`json()`** は `Response` インターフェイスのメソッドで、 `Response` のストリームを取得して完全に読み取ります。本体のテキストを `JSON` として解釈した結果で解決するプロミスを返します。

なお、このメソッドは `json()` という名前であるにもかかわらず、結果は JSON ではありません。入力として JSON を取って解釈し、 JavaScript のオブジェクトを生成します。

構文
--

```js
json()
```

### 引数

なし。

### 返値

JavaScript オブジェクトに解決される `Promise`。 このオブジェクトは、オブジェクト、配列、文字列、数値など、JSON で表現できるものであれば何でもなります。

例
-

fetch json の例（fetch json をライブで実行）では、 `Request()` コンストラクターを使用して新しいリクエストを作成し、それを使用して `.json` ファイルを読み取ります。読み取りに成功したら、`json()` を使用してデータを読み取り、解析し、結果のオブジェクトから期待通りに値を読み出し、それらの値をリスト項目に追加して商品データとして表示します。

```js
const myList = document.querySelector("ul");
const myRequest = new Request("products.json");

fetch(myRequest)
  .then((response) => response.json())
  .then((data) => {
    for (const product of data.products) {
      const listItem = document.createElement("li");
      listItem.appendChild(document.createElement("strong")).textContent =
        product.Name;
      listItem.append(` can be found in ${product.Location}. Cost: `);
      listItem.appendChild(document.createElement("strong")).textContent =
        `£${product.Price}`;
      myList.appendChild(listItem);
    }
  })
  .catch(console.error);
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-json① |

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

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

関連情報
----

* サービスワーカー API
* オリジン間リソース共有 (CORS)
* HTTP


Response.type - Web API

Response.type
=============

**`type`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスの種類を保持します。
 以下のうちの何れかになります。

* `basic`: 通常の、同一ドメインのレスポンスで、 "Set-Cookie" 以外のすべてのヘッダーが公開されます。
* `cors`: レスポンスは有効なオリジン間リクエストで受信しました。特定のヘッダーと本体にアクセスできます。
* `error`: ネットワークエラーです。
 エラーを記述した有益な情報は使用できません。
 レスポンスのステータスは 0 で、ヘッダーは空で不変です。
 これは `Response.error()` から得られる種類のレスポンスです。
* `opaque`: オリジン間リソースへの "no-cors "リクエストに対するレスポンス。
 厳しく制限されています。
* `opaqueredirect`: フェッチリクエストは `redirect: "manual"` で行われました。
 レスポンスのステータスは 0、ヘッダーは空、本体は空、トレーラーは空です。

**メモ:** "error" レスポンスは実際にスクリプトに公開されることはありません。 `fetch()` に対するそのようなレスポンスは、プロミスを拒否します。

値
-

レスポンスの種類を示す `ResponseType` 文字列。

例
-

Fetch Response の例 （Fetch Response のライブ版 を参照）では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

なお、 `fetch()` ブロックの先頭で、レスポンスの `type` 値をコンソールにログ出力していることに注意してください。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.type); // returns basic by default
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-type① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.status - Web API

Response.status
===============

**`status`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスの HTTP ステータスコードを保持します。

例えば、 `200` は成功を、 `404` はリソースが見つからなかったことを表します。

値
-

 符号なし整数です。
 これは HTTP レスポンスステータスコードのうちの一つです。

例
-

Fetch Response の例 （Fetch Response のライブ版 を参照）では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

なお、 `fetch()` ブロックの先頭で、レスポンスの `status` 値をコンソールにログ出力していることに注意してください。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.status); // returns 200
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-status① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.headers - Web API

Response.headers
================

**`headers`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスに関連付けられた `Headers` オブジェクトが含まれています。

### 値

`Headers` オブジェクト

例
-

Fetch Response の例 ( Fetch Response live を参照) では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

`fetch()` ブロックの上部でレスポンス `headers` の値をコンソールに記録している事に注意して下さい。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  // 各レスポンスヘッダーについて、ヘッダー名をキーとする配列をログ出力します。
  console.log(...response.headers);
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-headers① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.bodyUsed - Web API

Response.bodyUsed
=================

**`bodyUsed`** は `Response` インターフェイスの読み取り専用プロパティで、本体が読み取り済みであるかどうかを示す論理値です。

値
-

論理値です。

例
-

フェッチリクエストの例（フェッチリクエストをライブで実行）では、 `Request()` コンストラクターを使用して新しいリクエストを作成し、それを使用して JPG を読み取ります。読み取りが成功したら、`blob()` を使用してレスポンスから `Blob` を読み取り、`URL.createObjectURL` を使用してオブジェクト URL に格納し、その URL を `<img>` 要素のソースとして設定して画像を表示します。

`response.bodyUsed` を `response.blob()` の呼び出し前後にコンソールに記録していることに注目してください。 その時点で本文が読み取られたかによるため、これは呼び出し前では `false` を返し、その後では `true` を返します。

### HTML コンテンツ

```html
<img
 class="my-image"
 src="https://wikipedia.org/static/images/project-logos/frwiki-1.5x.png" />
```

### JS コンテンツ

```js
const myImage = document.querySelector(".my-image");
fetch("https://upload.wikimedia.org/wikipedia/commons/7/77/Delete\_key1.jpg")
  .then((response) => {
    console.log(response.bodyUsed);
    const res = response.blob();
    console.log(response.bodyUsed);
    return res;
  })
  .then((response) => {
    const objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });
```

### 結果

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-bodyused① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.clone() - Web API

Response.clone()
================

**`clone()`** は `Response` インターフェイスのメソッドで、レスポンスオブジェクトの複製を作成します。この複製はあらゆる面で同一ですが、異なる変数に格納されます。

 基礎となる `ReadableStream.tee` api のように、複製された `Response` の `body` は、 2 つの本体のうち *より速い* コンシューマーの速度で背圧を通知し、未読データは制限や背圧なしにより遅く消費された `body` で内部でキューイングされます。
 背圧とは、データのストリーミングコンシューマー（この場合は本体を読むコード）が、アプリケーションで使用されるのを待っているメモリーに大量のデータを読み込まないように、データのプロデューサー（TCP サーバーなど）の速度を低下させるメカニズムを参照することです。
 もし複製された分岐が一つしか消費されない場合、本体全体がメモリーにバッファリングされます。
 したがって、`clone()` はレスポンスを 2 回連続して読み込むための一つの方法ですが、非常に大きな本体を異なる速度で並列に読み込むために使用するべきではありません。

`clone()` は、レスポンス本体が既に使用されている場合は `TypeError` を発生させます。
 実際、`clone()` が存在する主な理由は、本体オブジェクトを複数回使用できるようにするためです（一度しか使用できない場合）。

構文
--

```js
clone()
```

### 引数

なし。

### 返値

`Response` オブジェクトです。

例
-

Fetch Response clone の例（Fetch Response clone のライブ版 を参照）では、 `Request()` コンストラクターで新しい `Request` オブジェクトを作成し、 JPG のパスを渡します。
 そして `fetch()` を使用してこのリクエストを読み込みます。
 フェッチが正常に解決されると、それを複製し、2 つの `Response.blob` 呼び出しを使用して両方のレスポンスから blob を抽出し、 `URL.createObjectURL` を使用して blob からオブジェクト URL を作成し、それらを 2 つの別々の `<img>` 要素で表示します。

```js
const image1 = document.querySelector(".img1");
const image2 = document.querySelector(".img2");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  const response2 = response.clone();

  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    image1.src = objectURL;
  });

  response2.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    image2.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-clone① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.statusText - Web API

Response.statusText
===================

**`statusText`** は `Response` インターフェイスの読み取り専用プロパティで、 `Response.status` にある HTTP ステータスコードに対応するステータスメッセージを保持します。

例えば、ステータスコード `200` に対しては `OK`、 `100` に対しては `Continue`、 `404` に対しては `Not Found` です。

値
-

 文字列で、レスポンスに関連する HTTP ステータスメッセージを保持します。
 既定値は "" です。

 コードと関連するステータスメッセージの一覧は、 HTTP レスポンスステータスコードを参照してください。
 なお、 HTTP/2 はステータスメッセージに対応していません。

例
-

Fetch Response の例 （Fetch Response のライブ版 を参照）では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

なお、 `fetch()` ブロックの先頭で、レスポンスの `statusText` 値をコンソールにログ出力していることに注意してください。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.statusText); // レスポンスが成功した場合は "OK" を返す
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-statustext① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response: body プロパティ - Web API

Response: body プロパティ
====================

**`body`** は `Response` インターフェイスの読み取り専用プロパティで、本体コンテンツの `ReadableStream` です。

値
-

`ReadableStream`、または `Response` オブジェクトが構築時に `body` プロパティが null であった場合、あるいは HTTP レスポンスに本体がなかった場合には `null` になります。

ストリームは読み取り可能なバイトストリームで、 `ReadableStreamBYOBReader` を用いたゼロコピー移譲に対応しています。

**メモ:** 現在のブラウザーは、本体なしのレスポンス（例えば、 `HEAD` リクエストに対するレスポンスや、 `204 No Content` レスポンス）には `body` プロパティを `null` に設定するという仕様に実際には適合していません。

例
-

### 画像の複製

単純なストリームポンプの例では、画像を読み取り、 `response.body` を使用してレスポンスのストリームを公開し、`ReadableStream.getReader()` を使用してリーダーを作成し、そのストリームのチャンクを 2 番目のカスタム読み取り可能なストリームのキューに入れます。画像の同一コピーを効果的に作成します。

```js
const image = document.getElementById("target");

// 元の画像をフェッチ
fetch("./tortoise.png")
  // その body を ReadableStream として取得
  .then((response) => response.body)
  .then((body) => {
    const reader = body.getReader();

    return new ReadableStream({
      start(controller) {
        return pump();

        function pump() {
          return reader.read().then(({ done, value }) => {
            // データを消費する必要がなくなったら、ストリームを閉じます
            if (done) {
              controller.close();
              return;
            }

            // 次のデータチャンクを対象のストリームのキューに入れます
            controller.enqueue(value);
            return pump();
          });
        }
      },
    });
  })
  .then((stream) => new Response(stream))
  .then((response) => response.blob())
  .then((blob) => URL.createObjectURL(blob))
  .then((url) => console.log((image.src = url)))
  .catch((err) => console.error(err));
```

### BYOB リーダーの作成

この例では、 `ReadableStreamBYOBReader` を使用して本体から `ReadableStream.getReader({mode: 'byob'})` を構築します。このリーダーを使用して、レスポンスデータのゼロコピー移譲を実装することができます。

```js
async function getProducts(url) {
  const response = await fetch(url);
  const reader = response.body.getReader({ mode: "byob" });
  // このレスポンスを読む
}

getProducts(
  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",
);
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-body① |

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

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

関連情報
----

* フェッチ API
* ストリーム API
* サービスワーカー API


Response.error() - Web API

Response.error()
================

**`error()`** は `Response` インターフェイスのメソッドで、ネットワークエラーに関連付けられた新規の `Response` オブジェクトを返します。

**メモ:** これは主にサービスワーカーに関連しています。エラーメソッドは、必要に応じてエラーを返す為に使用されます。
 エラーレスポンスの `type` は `error` に設定されています。

**メモ:** "エラー" の `Response` は実際にスクリプトに公開されません。 `fetch()` に対するそのようなレスポンスは、プロミスを拒否します。

構文
--

```js
error()
```

### 引数

なし。

### 返値

`Response` オブジェクト。

例
-

TBD (まだどこでもサポートされていません。)

仕様
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-error① |

ブラウザー実装状況
---------

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.redirect() - Web API

Response.redirect()
===================

**`redirect()`** は `Response` インターフェイスのメソッドで、指定された URL へのリダイレクトをもたらす `Response` を返します。

**メモ:** これは主にサービスワーカー API に関連しています。
 制御するサービスワーカーは、ページのリクエストに介入し、希望通りにリダイレクトすることができます。
 もしサービスワーカーが上流に送信を行うと、実際に本当のリダイレクトが発生します。

構文
--

```js
redirect(url)
redirect(url, status)
```

### 引数

`url`

新しいレスポンスの発信元 URL。

`status` 省略可

response のオプションのステータスコード (例 `302`)

### 返値

`Response` オブジェクト。

### 例外

`RangeError`

指定されたステータスがリダイレクトステータスではない場合。

`TypeError`

指定された URL が不正な場合。

例
-

```js
Response.redirect("https://www.example.com", 302);
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-redirect① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.ok - Web API

Response.ok
===========

**`ok`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスが（ステータスが 200-299 で）成功したかどうかを表す論理値です。

値
-

論理値です。

例
-

Fetch Response の例 （Fetch Response のライブ を参照）では、新しい `Request` オブジェクトを、 `Request()` コンストラクターを使用して作成し、 JPG のパスを渡します。次に `fetch()` を使用してこのリクエストをフェッチし、 `Response.blob` を使用してリクエストから blob を抽出し、 `URL.createObjectURL` を使用してオブジェクト URL を作成し、これを `<img>` に表示します。

**メモ:** `fetch()` ブロックの先頭で、レスポンスの `ok` 値をコンソールにログ出力します。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.ok); // レスポンスが正常に返された場合に true を返します。
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-ok② |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.blob() - Web API

Response.blob()
===============

**`blob()`** は `Response` インターフェイスのメソッドで、 `Response` ストリームを取得して完全に読み込みます。 `Blob` で解決するプロミスを返します。

構文
--

```js
blob()
```

### 引数

なし。

**メモ:** `Response` の `Response.type` が `"opaque"` の場合、結果の `Blob` の `Blob.size` は `0`、`Blob.type` は空文字列 `""` になり、`URL.createObjectURL` のようなメソッドでは*役に立たなく*なります。

### 返値

`Blob` で解決するプロミスです。

例
-

fetch request の例 (fetch request をライブで実行) では、`Request()` コンストラクターを使用して新しいリクエストを作成し、それを使用して JPG を読み取ります。読み取りが成功したら、`blob()` を使用してレスポンスから `Blob` を読み取り、それを `URL.createObjectURL` を使用してオブジェクト URL に入れ、その URL を `<img>` 要素のソースとして設定して画像を表示します。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => response.blob())
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-blob① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.text() - Web API

Response.text()
===============

**`text()`** は `Response` インターフェイスのメソッドで、 `Response` ストリームを取得して完全に読み込みます。 `String` で解決するプロミスを返します。 レスポンスは*常に* UTF-8 としてデコードされます。

構文
--

```js
text()
```

### 引数

なし。

### 返値

`String` で解決するプロミスです。

例
-

fetch text の例（fetch text をライブで実行）には、`<article>` 要素と 3 つのリンク（`myLinks` 配列に格納されています）があります。 最初に、リンクのすべてを反復処理し、それぞれのリンクに、その 1 つをクリックしたとき、 `getData()` 関数がリンクの `data-page` 識別子を引数として実行されるように、`onclick` イベントハンドラーを設定します。

`getData()` が実行されると、`Request()` コンストラクターを使用して新しいリクエストを作成し、それを使用して特定の `.txt` ファイルをフェッチします。 フェッチが成功したら、`text()` を使用してレスポンスから `USVString` (テキスト) オブジェクトを読み取り、`<article>` 要素の `innerHTML` にテキストオブジェクトの値を設定します。

```js
const myArticle = document.querySelector("article");
const myLinks = document.querySelectorAll("ul a");

for (const link of myLinks) {
  link.onclick = (e) => {
    e.preventDefault();
    const linkData = e.target.getAttribute("data-page");
    getData(linkData);
  };
}

function getData(pageId) {
  console.log(pageId);
  const myRequest = new Request(`${pageId}.txt`);
  fetch(myRequest)
    .then((response) => response.text())
    .then((text) => {
      myArticle.innerHTML = text;
    });
}
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-text① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response() - Web API

Response()
==========

**`Response()`** コンストラクターは、新しい `Response` オブジェクトを生成します。

構文
--

```js
new Response()
new Response(body)
new Response(body, options)
```

### 引数

`body` 省略可

レスポンスの本体を定義するオブジェクトです。これは `null` （既定値）か、以下のうちのいずれかです。

* `Blob`
* `ArrayBuffer`
* `TypedArray`
* `DataView`
* `FormData`
* `ReadableStream`
* `URLSearchParams`
* `String`
* 文字列リテラル

`options` 省略可

レスポンスに適用したオプションで、カスタム設定したい場合の可能なオプションは、次のとおりです。:

`status`

このレスポンスのステータスコードです。（例: `200`）

`statusText`

ステータスコードに関連付けられたステータスメッセージです（例: `OK`など)

`headers`

レスポンスに追加したいヘッダーです。`Headers` オブジェクト、または `String` キー/値ペアのオブジェクトリテラルに含まれています（参考として HTTP ヘッダーをご覧ください）。

例
-

Fetch Response の例 （Fetch Response のライブ版を参照）では、コンストラクターを使用して新しい `Response` オブジェクトを作成します。その際、新しい `Blob` を本体として、またカスタム `status` と `statusText` を含む init オブジェクトを渡します。

```js
const myBlob = new Blob();
const myOptions = { status: 200, statusText: "SuperSmashingGreat!" };
const myResponse = new Response(myBlob, myOptions);
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response① |

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

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

関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


Response.redirected - Web API

Response.redirected
===================

**`redirected`** は `Response` インターフェイスの読み取り専用プロパティで、このレスポンスがリダイレクトされたリクエストの結果であるかどうかを示します。

**メモ:** redirected に頼ってリダイレクトをフィルタリングしていると、偽造されたリダイレクトによって、コンテンツが期待通りに動作しなくなることが簡単に起こります。
 その代わり、 `fetch()` を呼び出すときにフィルタリングを行うべきです。
 これを行う例を示したリダイレクトの禁止を参照してください。

値
-

論理値で、レスポンスがリクエストがリダイレクトされたことを示す場合は `true` となります。

例
-

### リダイレクトの検出

 レスポンスがリダイレクトされたものであるかどうかを調べるには、 `Response` オブジェクトのこのフラグをチェックするだけです。
 下記のコードでは、取得処理中にリダイレクトが発生した場合、要素にテキストメッセージが挿入されます。
 ただし、下記のリダイレクトの禁止で記述しているように、予想外のリダイレクトが発生した場合に完全に拒否するほど安全ではないことに注意してください。

```js
fetch("awesome-picture.jpg")
  .then((response) => {
    const elem = document.getElementById("warning-message-box");
    elem.textContent = response.redirected ? "Unexpected redirect" : "";
    return response.blob();
  })
  .then((imageBlob) => {
    const imgObjectURL = URL.createObjectURL(imageBlob);
    document.getElementById("img-element-id").src = imgObjectURL;
  });
```

### リダイレクトの禁止

redirected を使用して手動でリダイレクトをフィルタリングすると、リダイレクトの偽造が可能になるため、代わりに `fetch()` を呼び出す際に `init` 引数でリダイレクトモードを `"error"` に設定する必要があります、例えば次のようにします。

```js
fetch("awesome-picture.jpg", { redirect: "error" })
  .then((response) => response.blob())
  .then((imageBlob) => {
    const imgObjectURL = URL.createObjectURL(imageBlob);
    document.getElementById("img-element-id").src = imgObjectURL;
  });
```

仕様書
---

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-redirected① |

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

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

関連情報
----

* フェッチ API
* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP


CSSValue.cssValueType - Web API

CSSValue.cssValueType
=====================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`cssValueType`** は `CSSValue` インターフェイスの読み取り専用プロパティで、 CSS プロパティの現在の計算値の型を表します。

**メモ:** このインターフェイスは、型付き CSS オブジェクトモデルを作成する試みの一部でした。この試みは放棄され、ほとんどのブラウザーはこのインターフェイスを実装していません。

目的を達成するためには、次のものを利用することができます。

* 型のない CSS オブジェクトモデル、広く対応されています。
* 新しい CSS 型付きオブジェクトモデル API、対応が限られており、実験的と見なされています。

### 値

`unsigned short` で、値の型を定義するコードを表します。可能な値は次のとおりです。

| 定数 | 説明 |
| --- | --- |
| `CSS_CUSTOM` | この値はカスタム値です。 |
| `CSS_INHERIT` | この値は継承したものであり、 `cssText` は `"inherit"` となっています。 |
| `CSS_PRIMITIVE_VALUE` | この値はプリミティブ値であり、`CSSPrimitiveValue` (en-US) インターフェイスのインスタンスは、この `CSSValue` インターフェイスのインスタンスに対してバインディング固有のキャストメソッドを使用することで取得することができます。 |
| `CSS_VALUE_LIST` | この値は `CSSValue` のリストであり、 `CSSValueList` (en-US) インターフェイスのインスタンスは、この `CSSValue` インターフェイスのインスタンスに対してバインディング固有のキャストメソッドを使用して取得することができます。 |

例
-

```js
const styleDeclaration = document.styleSheets[0].cssRules[0].style;
const cssValue = styleDeclaration.getPropertyCSSValue("color");
console.log(cssValue.cssValueType);
```

仕様書
---

この機能は元々 DOM Style Level 2 仕様で定義されていましたが、その後、全ての標準化作業から外されています。

これは、新しい、しかし互換性のない、CSS 型付きオブジェクトモデル API に取って代わられ、標準化路線になりました。

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

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


CSSValue.cssText - Web API

CSSValue.cssText
================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**`cssText`** は `CSSValue` インターフェイスのプロパティで、 CSS プロパティの現在の計算値を表します。

**メモ:** このインターフェイスは、型付き CSS オブジェクトモデルを作成する試みの一部でした。この試みは放棄され、ほとんどのブラウザーはこのインターフェイスを実装していません。

目的を達成するためには、次のものを利用することができます。

* 型のない CSS オブジェクトモデル、広く対応されています。
* 新しい CSS 型付きオブジェクトモデル API、対応が限られており、実験的と見なされています。

値
-

文字列で、現在の CSS プロパティ値を表します。

例
-

```js
const styleDeclaration = document.styleSheets[0].cssRules[0].style;
const cssValue = styleDeclaration.getPropertyCSSValue("color");
console.log(cssValue.cssText);
```

仕様書
---

この機能は元々 DOM Style Level 2 仕様で定義されていましたが、その後、全ての標準化作業から外されています。

これは、新しい、しかし互換性のない、CSS 型付きオブジェクトモデル API に取って代わられ、標準化路線になりました。

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

この機能は元々 DOM Style Level 2 仕様で定義されていましたが、その後、全ての標準化作業から外されています。

これは、新しい、しかし互換性のない、CSS 型付きオブジェクトモデル API に取って代わられ、標準化路線になりました。

関連情報
----

* `CSSStyleDeclaration.getPropertyCSSValue()`