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

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

**`AudioWorkletNode()`** コンストラクターは新しい `AudioWorkletNode` オブジェクトを作成します。このオブジェクトは、JavaScript の関数により独自の音声処理を行う `AudioNode` を表します。

構文
--

```js
new AudioWorkletNode(context, name)
new AudioWorkletNode(context, name, options)
```

### 引数

`context`

このノードを関連付ける `BaseAudioContext` のインスタンスです。

`name`

 このノードのもととなる `AudioWorkletProcessor` の名前を表す文字列です。
 指定の名前の処理器が `AudioWorkletGlobalScope.registerProcessor()` メソッドで登録されている必要があります。

`options` 省略可

以下の任意のプロパティのうち 0 個以上を持ち、新しいノードの設定をするオブジェクトです。

**メモ:** このオブジェクトに構造化複製アルゴリズムを適用した結果が内部で対応する `AudioWorkletProcessor()` コンストラクターに渡されます。
 これにより、用いるユーザー定義の `AudioWorkletProcessor` の初期化のカスタマイズが可能になります。

`numberOfInputs` 省略可

`numberOfInputs` プロパティを初期化する値です。デフォルト値は 1 です。

`numberOfOutputs` 省略可

`numberOfOutputs` プロパティを初期化する値です。デフォルト値は 1 です。

`outputChannelCount` 省略可

それぞれの出力のチャンネル数を定義する **配列** です。たとえば、`outputChannelCount: [n, m]` は最初の出力のチャンネル数を `n` に、2 番目の出力のチャンネル数を `m` に設定します。配列の長さは `numberOfOutputs` と一致しなければなりません。

`parameterData` 省略可

このノード (の `parameters` プロパティ) の独自の `AudioParam` オブジェクトの初期値を持つオブジェクトです。独自パラメーターの名前をキー、初期値を値とします。

`processorOptions` 省略可

用いる `AudioWorkletProcessor` の初期化のカスタマイズに用いる任意の追加データです。

### 例外

`NotSupportedError` `DOMException`

指定された `options.outputChannelCount` が `0` である、または現在の実装が対応する最大値より大きいとき投げられます。

`options.numberOfInputs` と `options.numberOfOutputs` の両方が 0 であるとき投げられます。

`IndexSizeError` `DOMException`

配列 `options.outputChannelCount` の長さが `options.numberOfOutputs` と一致しないとき投げられます。

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

`options` 引数の値によって、以下の効果があります。

入力の数と出力の数を両方 0 に設定すると、`NotSupportedError` が投げられ、生成処理が中断されます。配列 `outputChannelCount` の長さが `numberOfOutputs` と一致しない場合は、`IndexSizeError` `DOMException` が投げられます。

`outputChannelCount` が指定されておらず、`numberOfInputs` と `numberOfOutputs` がともに 1 の場合は、`AudioWorkletNode` の初期チャンネル数は 1 になります。この場合、出力のチャンネル数を変えることで、入力のチャンネル数と `AudioNode` の `channelCountMode` プロパティの設定に基づき、計算されたチャンネル数を動的に変えることができます。

`outputChannelCount` が指定されており、*かつ* `numberOfInputs` と `numberOfOutputs` がともに 1 の場合、このノードのチャンネル数は `outputChannelCount` の値になります。そうでない場合は、それぞれの出力のチャンネル数は配列 `outputChannelCount` の対応する値に従って設定されます。

例
-

*`AudioWorkletNode` のページに、ユーザー定義の音声処理のデモを行う完全な例があります。*

例外
--

| Specification |
| --- |
| Web Audio API # dom-audioworkletnode-audioworkletnode |

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

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

関連情報
----

* ウェブオーディオ API
* Background audio processing using AudioWorklet (en-US)
* `AudioWorkletNode` インターフェイス


AudioWorkletNode: parameters プロパティ - Web API

AudioWorkletNode: parameters プロパティ
==================================

`AudioWorkletNode` インターフェイスの読み取り専用プロパティ **`parameters`** は、関連付けられた `AudioParamMap` を返します。これは `AudioParam` オブジェクトが入った `Map` のようなコレクションです。中身のオブジェクトは、用いる `AudioWorkletProcessor` の生成時に `parameterDescriptors` 静的ゲッターに沿って生成されます。

値
-

`AudioParam` のインスタンスを持つ `AudioParamMap` オブジェクトです。
 これらはデフォルトの `AudioNode` で行うのと同じ方法で自動化でき、計算された値は自分の `AudioWorkletProcessor` の `process` メソッドで使用できます。

例
-

独自の `AudioParam` の作成と使用のデモを行うため、`AudioWorkletNode` ページにある例を拡張します。このページでは、ホワイトノイズを出力する単純なノードを作成しました。ここでは、独自のゲインパラメーターを追加し、出力の音量を直接変えることができるようにします。(これは `GainNode` を用いてもできますが)

 まず、独自の `AudioWorkletProcessor` を定義して登録する必要があります。
 これは別のファイルで行うことに注意してください。

処理器を拡張し、静的な `parameterDescriptors` ゲッターを追加します。これは `AudioWorkletNode` のコンストラクター内部で `parameters` に生成した `AudioParam` オブジェクトを入れるのに用いられます。

```js
// white-noise-processor.js
class WhiteNoiseProcessor extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [
      {
        name: "customGain",
        defaultValue: 1,
        minValue: 0,
        maxValue: 1,
        automationRate: "a-rate",
      },
    ];
  }

  process(inputs, outputs, parameters) {
    const output = outputs[0];
    output.forEach((channel) => {
      for (let i = 0; i < channel.length; i++) {
        channel[i] =
          (Math.random() \* 2 - 1) \*
          (parameters["customGain"].length > 1
            ? parameters["customGain"][i]
            : parameters["customGain"][0]);
        // メモ: パラメーターは 128 個の値の配列です。(128 サンプルのそれぞれについて 1 個ずつ)
        // ただし、現在自動処理がスケジュールされていない場合、
        // 128 サンプル全てで用いる値が 1 個だけ入っていることがあります。
      }
    });
    return true;
  }
}

registerProcessor("white-noise-processor", WhiteNoiseProcessor);
```

次に、メインスクリプトで処理器を読み込み、処理器の名前を渡して `AudioWorkletNode` のインスタンスを作成し、このノードを音声グラフに接続します。

```js
const audioContext = new AudioContext();
await audioContext.audioWorklet.addModule("white-noise-processor.js");
const whiteNoiseNode = new AudioWorkletNode(
  audioContext,
  "white-noise-processor",
);
whiteNoiseNode.connect(audioContext.destination);
```

すると、ノードのゲインをこのようにして変えることができます。

```js
const gainParam = whiteNoiseNode.parameters.get("customGain");
gainParam.setValueAtTime(0, audioContext.currentTime);
gainParam.linearRampToValueAtTime(0.5, audioContext.currentTime + 0.5);
```

仕様書
---

| Specification |
| --- |
| Web Audio API # dom-audioworkletnode-parameters |

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

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

関連情報
----

* ウェブオーディオ API
* Web Audio API の使用


MediaSource.duration - Web API

MediaSource.duration
====================

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

`MediaSource` インターフェイスの **`duration`** プロパティは、現在表示されているメディアの期間（長さ）を取得および設定します。

構文
--
```

mediaSource.duration = 5.5; // 5.5 seconds

var myDuration = mediaSource.duration;
```

### 値

double 型。 秒単位の値が必要です。

### 例外

このプロパティに新しい値を設定すると、次の例外がスローされる場合があります。

| 例外 | 説明 |
| --- | --- |
| `InvalidAccessError` | 負、または `NaN` の期間値を設定しようとした。 |
| `InvalidStateError` | `MediaSource.readyState` が `open` と等しくないか、`MediaSource.sourceBuffers` の `SourceBuffer` オブジェクトの 1 つ以上が更新されています（つまり、`SourceBuffer.updating` プロパティが `true` です）。 |

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例に基づいています（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
function sourceOpen (\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener('updateend', function (\_) {
      mediaSource.endOfStream();
      mediaSource.duration = 120;
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

...
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-duration |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.activeSourceBuffers - Web API

MediaSource.activeSourceBuffers
===============================

`MediaSource` インターフェイスの **`activeSourceBuffers`** 読み取り専用プロパティは、`sourceBuffers` に含まれる `SourceBuffer` オブジェクトのサブセットを含む `SourceBufferList` オブジェクトを返します。 これは、選択した動画トラック、有効な音声トラック、および表示/非表示のテキストトラックを提供するオブジェクトのリストです。

構文
--
```

var myActiveSourceBuffers = mediaSource.activeSourceBuffers;
```

### 値

アクティブな各トラックの `SourceBuffer` オブジェクトを含む `SourceBufferList`。

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例に基づいています（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
function sourceOpen (\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener('updateend', function (\_) {
      mediaSource.endOfStream();
      console.log(mediaSource.activeSourceBuffers);
      // 動画プレーヤーでの再生用に選択されているため、
      // 上記で追加されたソースバッファーが含まれます。
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

...
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-activesourcebuffers |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.endOfStream() - Web API

MediaSource.endOfStream()
=========================

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

`MediaSource` インターフェイスの **`endOfStream()`** メソッドは、ストリームの終わりを通知します。

構文
--
```

mediaSource.endOfStream(endOfStreamError);
```

### パラメーター

endOfStreamError 省略可

ストリームの終わりに達したときにスローするエラーを表す `DOMString`。 可能な値は次のとおりです。

* `network`: 再生を終了し、ネットワークエラーが発生したことを通知します。 これを使用して、メディアストリームに関連するカスタムエラーハンドラを作成できます。 例えば、他のネットワーク要求とは別に、メディアチャンク要求を処理する関数があるとします。 メディアチャンクに対して XMLHttpRequest 呼び出しを行い、`onabort` または `onerror` がトリガーされた場合、`endOfStream('network')` を呼び出し、UI に説明的なメッセージを表示し、ネットワーク要求をすぐに再試行するか、ネットワークが（何らかのポーリングを介して）復旧するまで待機できます。
* `decode`: 再生を終了し、デコードエラーが発生したことを通知します。 これは、メディアデータの取得中に解析エラーが発生したことを示すために使用できます。 データが破損しているか、ブラウザーがデコード方法を知らないコーデックを使用してエンコードされている可能性があります。

### 戻り値

`undefined`### 例外

| 例外 | 説明 |
| --- | --- |
| `InvalidStateError` | `MediaSource.readyState` が `open` と等しくないか、`MediaSource.sourceBuffers` の `SourceBuffer` オブジェクトの 1 つ以上が更新されています（つまり、`SourceBuffer.updating` プロパティが `true` です） |

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例からのものです（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
var assetURL = "frag\_bunny.mp4";
// Blink はコーデックに関して特定する必要がある
// ./mp4info frag\_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error(
    "サポートされていない MIME タイプまたはコーデック: ",
    mimeCodec,
  );
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-endofstream |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.readyState - Web API

MediaSource.readyState
======================

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

`MediaSource` インターフェイスの **`readyState`** 読み取り専用プロパティは、現在の `MediaSource` の状態を表す列挙を返します。 3 つの可能な値は次のとおりです。

* `closed`: ソースは現在メディア要素にアタッチされていません。
* `open`: ソースはメディア要素にアタッチされ、`SourceBuffer` オブジェクトを受信する準備ができています。
* `ended`: ソースはメディア要素にアタッチされていますが、`MediaSource.endOfStream()` の呼び出しを介してストリームが終了しています。
構文
--
```

var myReadyState = mediaSource.readyState;
```

### 値

`DOMString`。

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例からのものです（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error(
    "サポートされていない MIME タイプまたはコーデック: ",
    mimeCodec,
  );
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-readystate |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.MediaSource() - Web API

MediaSource.MediaSource()
=========================

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

`MediaSource` インターフェイスの **`MediaSource()`** コンストラクタは、ソースバッファが関連付けられていない新しい `MediaSource` オブジェクトを構築して返します。

構文
--
```

var mediaSource = new MediaSource();
```

### パラメーター

なし。

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例から抜粋したものです（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
var video = document.querySelector('video');

var assetURL = 'frag\_bunny.mp4';
// Blink はコーデックに関して特定する必要がある
// ./mp4info frag\_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ('MediaSource' in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource;
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener('sourceopen', sourceOpen);
} else {
  console.error('サポートされていない MIME タイプまたはコーデック: ', mimeCodec);
}

...
```

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.setLiveSeekableRange() - Web API

MediaSource.setLiveSeekableRange()
==================================

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

`MediaSource` インターフェイスの **`setLiveSeekableRange()`** メソッドは、ユーザーがメディア要素でシークできる範囲を設定します。

構文
--
```

mediaSource.setLiveSeekableRange(start, end)
```

### パラメーター

start

ソースの最初から測定された秒単位で設定するシーク可能な範囲の始まり。 メディアソースの期間が正の無限大である場合、`HTMLMediaElement.seekable` プロパティによって返される `TimeRanges` オブジェクトは、この値以下の開始タイムスタンプを持ちます。

end

ソースの最初から測定された秒単位で設定するシーク可能な範囲の終わり。 メディアソースの期間が正の無限大である場合、`HTMLMediaElement.seekable` プロパティによって返される `TimeRanges` オブジェクトは、この値以上の終了タイムスタンプを持ちます。

### 戻り値

`undefined`例
-

```js
// 未定
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-setliveseekablerange |

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

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


MediaSource.isTypeSupported() - Web API

MediaSource.isTypeSupported()
=============================

**`MediaSource.isTypeSupported()`** 静的メソッドは、指定された MIME タイプが現在のユーザーエージェントによってサポートされる*可能性が高い*場合に `true` となる `Boolean` 値を返します。 つまり、その MIME タイプの `SourceBuffer` オブジェクトを正常に作成できる場合です。 返された値が `false` の場合、ユーザーエージェントは、指定された形式のメディアにアクセス*できない*と確信しています。

構文
--
```

var isItSupported = mediaSource.isTypeSupported(mimeType);
```

### パラメーター

`mimeType`

現在のブラウザーでのサポートをテストする MIME メディアタイプ。 これには、ファイル内で使用されるコーデックに関する追加の詳細を提供する `codecs` パラメーターが含まれる場合があります。

### 戻り値

指定されたタイプのメディアを*おそらく*再生できるとブラウザーが感じる場合に `true` になる `Boolean`。 ただし、これは保証*ではなく*、メディアが正しく再生されない可能性に備えてコードを準備する必要があります。 ただし、値 `false` は、指定されたタイプのメディアが再生*されない*ことを保証します。

メディアファイルで動作するすべての Web API は、メディアタイプを使用できるかどうかを判断するときに、「いいえ/多分/おそらく」アプローチ（または、この場合は「いいえまたはおそらく」）を使用します。 これは、メディアファイルが複雑で難解な構造であるため、実際にメディアのコンテンツを使用するまでは、微妙なバリエーションが多すぎて絶対に確実ではないためです。

例
-

次のスニペットは、Nick Desaulniers によって書かれた例からのものです（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
var assetURL = "frag\_bunny.mp4";
// Blink はコーデックに関して特定する必要がある
// ./mp4info frag\_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error(
    "サポートされていない MIME タイプまたはコーデック: ",
    mimeCodec,
  );
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-istypesupported |

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

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

関連情報
----

* Media Source Extensions API
* ウェブ上のメディアタイプとフォーマットのガイド
* 一般的なメディアタイプにおける "codecs" パラメーター (en-US)
* `SourceBuffer`
* `SourceBufferList`


MediaSource.clearLiveSeekableRange() - Web API

MediaSource.clearLiveSeekableRange()
====================================

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

`MediaSource` インターフェイスの **`clearLiveSeekableRange()`** メソッドは、`setLiveSeekableRange()` の呼び出しで以前に設定されたシーク可能な範囲をクリアします。

構文
--
```

mediaSource.clearLiveSeekableRange()
```

### パラメーター

なし。

### 戻り値

`undefined`仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-clearliveseekablerange |

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

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


MediaSource.addSourceBuffer() - Web API

MediaSource.addSourceBuffer()
=============================

`MediaSource` インターフェイスの **`addSourceBuffer()`** メソッドは、指定された MIME タイプの新しい `SourceBuffer` を作成し、`MediaSource` の `sourceBuffers` リストに追加します。 新しい `SourceBuffer` も返されます。

構文
--
```

var sourceBuffer = mediaSource.addSourceBuffer(mimeType);
```

### パラメーター

`mimeType`

`MediaSource` に作成して追加する `SourceBuffer` の MIME タイプを指定する `DOMString`。

### 戻り値

作成され、メディアソースに追加された新しいソースバッファを表す `SourceBuffer` オブジェクト。

### 例外

`InvalidAccessError`

`mimeType` に指定された値は、有効な MIME タイプではなく空の文字列です。

`InvalidStateError`

`MediaSource` の `readyState` は `"open"` でありません。

`NotSupportedError`

指定された `mimeType` はユーザーエージェントでサポートされていないか、メディアソースの `sourceBuffers` リストに既に含まれている他の `SourceBuffer` オブジェクトの MIME タイプと互換性がありません。

`QuotaExceededError`

ユーザーエージェントはこれ以上 `SourceBuffer` オブジェクトを処理できないか、指定された `mimeType` を使用して新しい `SourceBuffer` を作成すると、SourceBuffer の構成がサポートされなくなります。

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例からのものです（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
var assetURL = "frag\_bunny.mp4";
// Blink はコーデックに関して特定する必要がある
// ./mp4info frag\_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error(
    "サポートされていない MIME タイプまたはコーデック: ",
    mimeCodec,
  );
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-addsourcebuffer |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.sourceBuffers - Web API

MediaSource.sourceBuffers
=========================

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

`MediaSource` インターフェイス の **`sourceBuffers`** 読み取り専用プロパティは、この `MediaSource` に関連付けられた `SourceBuffer` オブジェクトのリストを含む `SourceBufferList` オブジェクトを返します。

構文
--
```

var mySourceBuffers = mediaSource.sourceBuffers;
```

### 値

`SourceBufferList`。

例
-

次のスニペットは、Nick Desaulniers によって書かれた簡単な例に基づいています（ライブで完全なデモを見るか、ソースをダウンロードしてさらに調査してください）。

```js
function sourceOpen (\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener('updateend', function (\_) {
      mediaSource.endOfStream();
      console.log(mediaSource.sourceBuffers); // 上で追加されたソースバッファが含まれます
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

...
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-sourcebuffers |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


MediaSource.removeSourceBuffer() - Web API

MediaSource.removeSourceBuffer()
================================

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

`MediaSource` インターフェイスの **`removeSourceBuffer()`** メソッドは、この `MediaSource` オブジェクトに関連付けられた `SourceBuffers` リストから指定された `SourceBuffer` を削除します。

構文
--
```

mediaSource.removeSourceBuffer(sourceBuffer);
```

### パラメーター

sourceBuffer

削除する `SourceBuffer` オブジェクト。

### 戻り値

`undefined`### 例外

| 例外 | 説明 |
| --- | --- |
| `NotFoundError` | 指定された sourceBuffer は `MediaSource.sourceBuffers` に存在しません。 |

例
-

```js
for (i = 0; i < 10; i++) {
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
}

mediaSource.removeSourceBuffer(mediaSource.sourceBuffers[0]);
```

仕様
--

| Specification |
| --- |
| Media Source Extensions™ # dom-mediasource-removesourcebuffer |

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

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

関連情報
----

* `SourceBuffer`
* `SourceBufferList`


NetworkInformation.type - Web API

NetworkInformation.type
=======================

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

**`NetworkInformation.type`** は読み取り専用プロパティで、端末がネットワーク通信に使用している接続の種類を返します。

**注:** この機能は Web Worker 内で利用可能です

### 値

次の値のいずれかである列挙値です。

* `"bluetooth"`
* `"cellular"`
* `"ethernet"`
* `"none`"
* `"wifi"`
* `"wimax"`
* `"other"`
* `"unknown"`
仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-type |

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

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


NetworkInformation.rtt - Web API

NetworkInformation.rtt
======================

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

**`NetworkInformation.rtt`** は読み取り専用のプロパティで、現在の接続の推定有効ラウンドトリップ時間を、25 ミリ秒の倍数に丸めた値で返します。この値は、最近アクティブになった接続のアプリケーション層の RTT 測定値に基づいています。プライベートアドレス空間への接続は除外されます。最近の測定データが利用できない場合、この値は基盤となる接続技術のプロパティに基づきます。

**注:** この機能は Web Worker 内で利用可能です

値
-

数値です。

仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-rtt |

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

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

関連情報
----

* `RTT` (en-US)


NetworkInformation.downlinkMax - Web API

NetworkInformation.downlinkMax
==============================

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

**`NetworkInformation.downlinkMax`** は読み取り専用プロパティで、メガビット毎秒 (Mbps) 単位で、基盤となる接続技術の最大下り速度を返します。

**注:** この機能は Web Worker 内で利用可能です

### 値

基盤となる接続技術の最大下り速度をメガビット毎秒 (Mb/s) で表した `unrestricted double` です。

例
-

次の例は、`change` イベントで接続をモニターして、発生した変更をロギングしています。

```js
function logConnectionType() {
  let connectionType = "not supported";
  let downlinkMax = "not supported";

  if ("connection" in navigator) {
    connectionType = navigator.connection.effectiveType;

    if ("downlinkMax" in navigator.connection) {
      downlinkMax = navigator.connection.downlinkMax;
    }
  }

  console.log(
    `Current connection type: ${connectionType} (downlink max: ${downlinkMax})`,
  );
}

logConnectionType();
navigator.connection.addEventListener("change", logConnectionType);
```

仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-downlinkmax |

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

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


NetworkInformation.downlink - Web API

NetworkInformation.downlink
===========================

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

**`downlink`** は `NetworkInformation` インターフェイスの読み取り専用プロパティで、実効帯域幅の推定値をメガビット毎秒で返し、25キロビット毎秒の最も近い倍数に丸めます。この値は、プライベートアドレス空間への接続を除き、最近アクティブになった接続で最近観測されたアプリケーション層のスループットに基づきます。最近の帯域幅測定データがない場合、属性の値は、基礎となる接続技術のプロパティによって決定されます。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-downlink |

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

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

関連情報
----

* `Downlink` (en-US)


NetworkInformation.effectiveType - Web API

NetworkInformation.effectiveType
================================

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

**`effectiveType`** は `NetworkInformation` インターフェイスの読み取り専用プロパティで、
 このプロパティは、 'slow-2g', '2g', '3g', '4g' のいずれかを意味する接続の有効な種類を返します。この値は、最近観測された、ラウンドトリップ時間とダウンリンク値の組合せを使用して決定されます。

値
-

'slow-2g', '2g', '3g', '4g' の何れかの文字列です。

仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-effectivetype |

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

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

関連情報
----

* 有効接続種別
* `ECT` (en-US)


NetworkInformation.saveData - Web API

NetworkInformation.saveData
===========================

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

**`NetworkInformation.saveData`** は `NetworkInformation` の読み取り専用プロパティで、ユーザーがユーザーエージェントにデータ使用量削減オプションを設定している場合、 `true` を返します。

値
-

論理値です。

仕様書
---

| Specification |
| --- |
| Save Data API # dfn-savedata |

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

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

関連情報
----

* `Save-Data` (en-US)


NetworkInformation: change イベント - Web API

NetworkInformation: change イベント
===============================

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

**`change`** イベントは、接続情報が変更されたときに発行され、 `NetworkInformation` オブジェクトで受信されます。

構文
--

このイベント名を `addEventListener()` 等のメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。

```js
addEventListener("change", (event) => {});

onchange = (event) => {};
```

イベント型
-----

一般的な `Event` です。

例
-

```js
// 接続型の取得
const type = navigator.connection.type;

function changeHandler(e) {
  // ここで接続型の変更を操作する
}

// change イベントの登録
navigator.connection.onchange = changeHandler;

// 他の方法: navigator.connection.addEventListener('change', changeHandler);
```

仕様書
---

| Specification |
| --- |
| Network Information API # dom-networkinformation-onchange |

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

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


CSSKeyframeRule.keyText - Web API

CSSKeyframeRule.keyText
=======================

**`keyText`** は `CSSKeyframeRule` インターフェイスのプロパティで、キーフレーム セレクターをパーセント値のカンマ区切りリストで表します。from と to キーワードは、それぞれ 0% と 100% に割り当てられます。

値
-

文字列です。

### 例外

`SyntaxError`

`keyText` が無効なキーフレームセレクターに更新された場合に発生します。

例
-

 この CSS には keyframes アットルールが記載されています。これは最初の `CSSRule` であり、 `document.styleSheets[0].cssRules` で返されます。
 `myRules[0]` は `CSSKeyframesRule` オブジェクトを返し、その中に各キーフレームに対応する個々の `CSSKeyFrame` オブジェクトが格納されます。

```css
@keyframes slidein {
  from {
    transform: translateX(0%);
  }

  to {
    transform: translateX(100%);
  }
}
```

```js
let myRules = document.styleSheets[0].cssRules;
let keyframes = myRules[0]; // a CSSKeyframesRule
console.log(keyframes[0].keyText); // a string containing 0%
```

仕様書
---

| Specification |
| --- |
| CSS Animations Level 1 # dom-csskeyframerule-keytext |

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

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


WakeLock.request() - Web API

WakeLock.request()
==================

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

**`request()`** は `WakeLock` インターフェイスのメソッドで、画面を暗くしたりロックしたりすることを制御することができる `WakeLockSentinel` で解決するプロミス (`Promise`) を返します。

構文
--

```js
var wakeLock = navigator.wakeLock.request(type);
```

### 引数

*type*

オプションは次の通りです。

* `'screen'`: 画面の起動ロックを要求します。端末の画面が暗くなったりロックされたりすることを防ぎます。

### 返値

`WakeLockSentinel` オブジェクトで解決する `Promise` を返します。

### 例外

`NotAllowedError`

起動ロックが利用できないときに発生します。原因は以下のようなものです。

* 文書が screen-wake-lock ポリシーにより、画面起動ロックを使用することができない。
* 文書が完全にアクティブではない。
* 文書が非表示になっている。
* ユーザーエージェントがプラットフォームの起動ロックを取得できない。

例
-

 以下の非同期関数は、 `WakeLockSentinel` オブジェクトを要求します。
 `request()` メソッドはブラウザーが何らかの理由でリクエストを拒否した場合を想定して、 `try...catch` 文で囲まれています。

```js
const requestWakeLock = async () => {
  try {
    const wakeLock = await navigator.wakeLock.request("screen");
  } catch (err) {
    // 起動ロックの要求に失敗 - 通常は、バッテリー低下などシステムに起因する。

    console.log(`${err.name}, ${err.message}`);
  }
};

requestWakeLock();
```

仕様書
---

| Specification |
| --- |
| Screen Wake Lock API # the-request-method |

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

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

関連情報
----

* `WakeLock`
* `Navigator.wakeLock`


JavaScript で queueMicrotask() によるマイクロタスクの使用 - Web API

JavaScript で queueMicrotask() によるマイクロタスクの使用
===========================================

**マイクロタスク**は、それを作成した関数やプログラムが終了した後、 JavaScript 実行スタックが空の場合にのみ実行され、ユーザーエージェントがスクリプトの実行環境を動かすために使用しているイベントループにコントロールを返す前に実行される短い関数です。

このイベントループは、ブラウザーのメインイベントループか、ウェブワーカーを駆動するイベントループのどちらかです。これにより、他のスクリプトの実行を妨げるリスクなしに与えられた関数を実行することができ、同時に、ユーザーエージェントがマイクロタスクによって行われるアクションに反応する機会を得る前に、マイクロタスクが確実に実行されるようにします。

JavaScript のプロミスと変更監視 API は、どちらもコールバック実行にマイクロタスクキューを使用しますが、現在のイベントループパスがラップされるまで作業を遅延する能力がある他の場合があります。サードパーティのライブラリー、フレームワーク、ポリフィルによってマイクロタスクが使用できるようにするために、 `queueMicrotask()` メソッドが `Window` と `Worker` インターフェイスで公開されています。

タスクとマイクロタスク
-----------

マイクロタスクについて正しく議論するためには、まず JavaScript のタスクとは何か、マイクロタスクはタスクとどう違うのかを知っておくと便利です。これは簡単で単純な説明ですが、より詳細を知りたい場合は、記事 徹底解説: マイクロタスクと JavaScript ランタイム環境 (en-US) の情報を読んでみてください。

### タスク

**タスク**とは、プログラムの初期実行、イベントコールバックの実行、インターバルやタイムアウトの発生など、標準的なメカニズムによって実行がスケジュールされる JavaScript コードのことです。これらはすべて**タスクキュー**にスケジューリングされます。

タスクは、以下の場合にタスクキューに追加されます。

* 新しい JavaScript プログラムやサブプログラムが（コンソールから、あるいは `<script>` 要素内のコードを実行して）直接実行されたとき。
* イベントが発生し、イベントのコールバック関数がタスクキューに追加された場合。
* `setTimeout()` または `setInterval()` で作成したタイムアウトまたはインターバルに達すると、対応するコールバックがタスクキューに追加されます。

コードを駆動するイベントループは、これらのタスクがキューに入れられた順番に次々と処理します。タスクキューで最も古い実行可能なタスクは、イベントループの 1 回の反復の間に実行されます。その後、マイクロタスクはマイクロタスクキューが空になるまで実行され、ブラウザーはレンダリングの更新を選択できます。その後、ブラウザーはイベントループの次の反復処理に移行します。

### マイクロタスク

最初、マイクロタスクとタスクの違いは小さいように見えます。どちらもキューに入れられ、適切なタイミングで実行される JavaScript のコードで構成されています。しかし、イベントループは反復が始まったときにキューに存在したタスクだけを次々と実行するのに対し、マイクロタスクのキューはとても異なる方法で処理されます。

主な違いは 2 つあります。

まず、タスクが終了するたびに、イベントループは、タスクが他の JavaScript コードに制御を返しているかどうかをチェックします。もしそうでなければ、マイクロタスクキューにあるすべてのマイクロタスクを実行します。マイクロタスクキューは、イベントや他のコールバックを処理した後を含め、イベントループの反復ごとに複数回処理されます。

次に、マイクロタスクが `queueMicrotask()` を呼び出してキューにさらにマイクロタスクを追加すると、それらの新しく追加されたマイクロタスクは次のタスクが実行される前に*実行*されます。これは、イベントループが、たとえ追加され続けても、キューに何も残らなくなるまでマイクロタスクを呼び続けるからです。

**警告:** マイクロタスクはそれ自身がさらにマイクロタスクをキューに入れることができ、イベントループはキューが空になるまでマイクロタスクを処理し続けるので、イベントループがマイクロタスクを延々と処理し続けるという現実的なリスクが存在します。再帰的にマイクロタスクを追加する方法には注意が必要です。

マイクロタスクの使用
----------

この話を進める前に、ほとんどの開発者はマイクロタスクをあまり使わないであろうということを、もう一度書いておきます。マイクロタスクは、最近のブラウザーベースの JavaScript 開発における非常に特殊な機能で、ユーザーのコンピューターで発生することを待つ長い一連の作業の中で、他の作業の前にジャンプするコードをスケジュールすることを可能にします。この機能を乱用すると、パフォーマンスの問題につながります。

### マイクロタスクのキュー挿入

そのため、通常、マイクロタスクは他に解決策がない場合、または実装している機能を作るためにマイクロタスクを使う必要があるフレームワークやライブラリーを作る場合にのみ、使用すべきです。これまでもマイクロタスクをキューに挿入するためのトリックはありましたが（すぐに解決するプロミスを作るなど）、`queueMicrotask()` メソッドの追加により、トリックなしで安全にマイクロタスクを導入するための標準的な方法が追加されました。

`queueMicrotask()` を導入することで、マイクロタスクを作成するためにプロミスを使用してこっそり行うときに発生する癖を回避することができます。例えば、マイクロタスクを作成するためにプロミスを使用する場合、コールバックによって投げられた例外は標準的な例外として報告されるのではなく、プロミスが拒否されたものとして報告されます。また、プロミスの作成と破棄は、マイクロタスクを適切にキューに挿入する関数が回避する、時間とメモリの両方において追加のオーバーヘッドを取ります。

コンテキストがマイクロタスクを処理している間に呼び出す JavaScript 関数 (`Function`) を `queueMicrotask()` メソッドに渡します。このメソッドは、現在の実行コンテキストに応じて `Window` または `Worker` インターフェイスによって定義されたグローバルコンテキストで公開されます。

```js
queueMicrotask(() => {
  /\* ここにマイクロタスク内で実行されるコードを置く \*/
});
```

マイクロタスク関数自体は、引数を取らず、値も返しません。

### マイクロタスクを使用すべき時

この節では、マイクロタスクが特に有用であるシナリオを紹介します。一般的には、 JavaScript の実行コンテキストの本体が終了した後、イベントハンドラー、タイムアウトやインターバル、その他のコールバックが処理される前に、結果をキャプチャしたりチェックしたり、クリーンアップを実行したりすることを指します。

それはいつ役に立つのでしょうか？

マイクロタスクを使用する主な理由は次のとおりです。結果やデータが同期的に利用できる場合でも、タスクの一貫した順序付けを保証すると同時に、ユーザーが識別できる操作の遅れのリスクを低減するためです。

#### プロミスの条件付き使用に関する並べ替えの確保

マイクロタスクが実行順序が常に一貫していることを保証するために使われる 1 つの状況は、プロミスが `if...else` 文（または他の条件文）の 1 つの節で使われ、他の節では使われないときです。次のようなコードを考えてみてください。

```js
customElement.prototype.getData = (url) => {
  if (this.cache[url]) {
    this.data = this.cache[url];
    this.dispatchEvent(new Event("load"));
  } else {
    fetch(url)
      .then((result) => result.arrayBuffer())
      .then((data) => {
        this.cache[url] = data;
        this.data = data;
        this.dispatchEvent(new Event("load"));
      });
  }
};
```

ここで紹介する問題は、 `if...else` 文の 1 つのブランチでタスクを使い（画像がキャッシュにある場合）、 `else` 節でプロミスを使用することにより、例えば以下のように、処理の順序が異なる状況が発生することです。

```js
element.addEventListener("load", () => console.log("Loaded data"));
console.log("Fetching data...");
element.getData();
console.log("Data fetched");
```

このコードを 2 回連続で実行すると、以下のような結果になります。

データをキャッシュしていない場合
```

Fetching data
Data fetched
Loaded data
```

データをキャッシュしている場合
```

Fetching data
Loaded data
Data fetched
```

さらに悪いことに、このコードの実行が終了するまでに、要素の `data` プロパティが設定されることもあれば、設定されないこともあります。

この 2 つの節のバランスをとるために、 `if` 節でマイクロタスクを使用することで、これらの操作の一貫した順序を保証することができます。

```js
customElement.prototype.getData = (url) => {
  if (this.cache[url]) {
    queueMicrotask(() => {
      this.data = this.cache[url];
      this.dispatchEvent(new Event("load"));
    });
  } else {
    fetch(url)
      .then((result) => result.arrayBuffer())
      .then((data) => {
        this.cache[url] = data;
        this.data = data;
        this.dispatchEvent(new Event("load"));
      });
  }
};
```

これは、マイクロタスク内で `data` の設定と `load` イベントの発行の両方を処理させることで、節のバランスを取っています（`if` 節では `queueMicrotask()` を使い、 `else` 節では `fetch()` が使うプロミスを使用する）。

#### 操作のバッチ化

また、マイクロタスクを使用して、様々なソースからの複数のリクエストを単一のバッチに収集し、同じ種類の作業を処理するために複数の呼び出しに伴う可能性のあるオーバーヘッドを回避することができます。

以下のスニペットは、複数のメッセージを配列にバッチする関数を作成し、コンテキストが終了したときにそれらを単一のオブジェクトとして送信するためにマイクロタスクを使用します。

```js
const messageQueue = [];

let sendMessage = (message) => {
  messageQueue.push(message);

  if (messageQueue.length === 1) {
    queueMicrotask(() => {
      const json = JSON.stringify(messageQueue);
      messageQueue.length = 0;
      fetch("url-of-receiver", json);
    });
  }
};
```

`sendMessage()` が呼び出されると、まず指定されたメッセージがメッセージキューの配列にプッシュされます。それからが面白いのです。

配列に追加したメッセージが最初のものであれば、バッチを送信するマイクロタスクをキューに入れます。マイクロタスクは、いつものように、 JavaScript の実行パスが最上位に達したとき、コールバックを実行する直前に実行されます。つまり、その間に行われる `sendMessage()` のさらなる呼び出しは、メッセージをメッセージキューにプッシュしますが、マイクロタスクを追加する前に配列の長さをチェックするため、新しいマイクロタスクはキューに入れません。

マイクロタスクが実行されるとき、それは潜在的に多くのメッセージが待っている配列を持っています。それは、 `JSON.stringify()` メソッドを使用して JSON としてそれをエンコードすることから始まります。その後、配列の内容が不要になったので、 `messageQueue` 配列を空にします。最後に、`fetch()` メソッドを用いて、 JSON 文字列をサーバーに送信します。

これにより、イベントループの同じイテレーションの中で行われる `sendMessage()` のすべての呼び出しが、タイムアウトなどの他のタスクによって送信が遅れる可能性を排除して、同じ `fetch()` 操作にメッセージを追加することができます。

サーバーは JSON 文字列を受信し、おそらくそれをデコードして、結果の配列の中で見つけたメッセージを処理します。

例
-

### 単純なマイクロタスクの例

この単純な例では、マイクロタスクをキューに入れるすることで、この最上位スクリプトの本体が実行され終わった後に、マイクロタスクのコールバックが実行されることがわかります。
```

<pre id="log"></pre>
```

#### JavaScript
```

let logElem = document.getElementById("log");
let log = (s) => (logElem.innerHTML += s + "<br>");
```

次のコードでは、マイクロタスクの実行をスケジュールするために `queueMicrotask()` を呼び出しています。この呼び出しは、画面にテキストを出力するカスタム関数である `log()` への呼び出しで括られています。

```js
log("Before enqueueing the microtask");
queueMicrotask(() => {
  log("The microtask has run.");
});
log("After enqueueing the microtask");
```

#### 結果

### タイムアウトとマイクロタスクの例

この例では、タイムアウトは 0 ミリ秒後に（または「できるだけ早く」）発生するようにスケジュールされています。これは、新しいタスクをスケジューリングするとき（例えば `setTimeout()`）とマイクロタスクを使うときの「できるだけ早く」が何を意味するかの違いを示しています。
```

<pre id="log"></pre>
```

#### JavaScript
```

let logElem = document.getElementById("log");
let log = (s) => (logElem.innerHTML += s + "<br>");
```

次のコードでは、マイクロタスクの実行をスケジュールするために `queueMicrotask()` を呼び出しています。この呼び出しは、画面にテキストを出力するカスタム関数である `log()` への呼び出しで括られています。

以下のコードでは、 0 ミリ秒後にタイムアウトが発生するようにスケジュールし、マイクロタスクをキューに入れています。これは、追加のメッセージを出力するために `log()` を呼び出すことで括られています。

```js
let callback = () => log("Regular timeout callback has run");

let urgentCallback = () => log("\*\*\* Oh noes! An urgent callback has run!");

log("Main program started");
setTimeout(callback, 0);
queueMicrotask(urgentCallback);
log("Main program exiting");
```

#### 結果

メインプログラム本体から記録された出力が最初に表示され、次にマイクロタスクからの出力、そしてタイムアウトのコールバックの順に表示されることに注意してください。これは、メインプログラムの実行を処理しているタスクが終了するとき、タイムアウトのコールバックがあるタスクキューよりもマイクロタスクキューの方が先に処理されるからです。タスクとマイクロタスクは別々のキューに保存され、マイクロタスクが最初に実行されることを覚えておくと、この点を整理するのに役立ちます。

### 関数からマイクロタスク

この例では、いくつかの作業を行う関数を追加することで、前の例を少し拡張しています。この関数は `queueMicrotask()` を使ってマイクロタスクのスケジューリングを行っています。この例で重要なことは、マイクロタスクは関数が終了するときに処理されるのではなく、メインプログラムが終了するときに処理されるということです。
```

<pre id="log"></pre>
```

#### JavaScript
```

let logElem = document.getElementById("log");
let log = (s) => (logElem.innerHTML += s + "<br>");
```

メインプログラムのコードは以下の通りです。ここで `doWork()` 関数は `queueMicrotask()` を呼び出しますが、それでもマイクロタスクはプログラム全体が終了するまで起動しません。なぜなら、タスクが終了して実行スタック上に何もなくなったときがそうだからです。

```js
let callback = () => log("Regular timeout callback has run");

let urgentCallback = () => log("\*\*\* Oh noes! An urgent callback has run!");

let doWork = () => {
  let result = 1;

  queueMicrotask(urgentCallback);

  for (let i = 2; i <= 10; i++) {
    result \*= i;
  }
  return result;
};

log("Main program started");
setTimeout(callback, 0);
log(`10! equals ${doWork()}`);
log("Main program exiting");
log("Regular timeout callback has run");
```

#### 結果

関連情報
----

* 徹底解説: マイクロタスクと JavaScript ランタイム環境 (en-US)
* `queueMicrotask()`
* 非同期 JavaScript
    + 非同期プログラミングの一般的概念
    + 非同期 JavaScript 入門
    + 強調的非同期 JavaScript: タイムアウトとインターバル (en-US)
    + プロミスによる礼儀正しい非同期プログラミング
    + 正しいアプローチの選択 (en-US)


HTMLCanvasElement: captureStream() メソッド - Web API

HTMLCanvasElement: captureStream() メソッド
=======================================

`HTMLCanvasElement` の **`captureStream()`** メソッドは、 `MediaStream` を返します。これは `CanvasCaptureMediaStreamTrack` (en-US) を含んでおり、このキャンバスの内容をリアルタイムに動画キャプチャします。

構文
--

```js
captureStream(frameRate)
```

### 引数

`frameRate` 省略可

各フレームのキャプチャレートを示す倍精度浮動小数点値です。設定されていない場合、キャンバスが変化するたびに新しいフレームがキャプチャされます。`0` に設定すると、フレームは自動的にキャプチャされません。代わりに、返されたトラックの `requestFrame()` メソッドが呼び出されたときにのみ、キャプチャされます。

### 返値

`MediaStream` オブジェクトへの参照です。その中に
 `CanvasCaptureMediaStreamTrack` (en-US) が 1 つあります。

### 例外

`NotSupportedError` `DOMException`

`frameRate` が負の値であった場合に発生します。

`SecurityError` `DOMException`

 ビットマップのオリジンがクリーンではありません。
 そのコンテンツの少なくとも一部が、文書そのものが読み込まれたサイトとは別のサイトから読み込まれたものであるか、その可能性があります。

例
-

```js
// キャプチャしたい canvas 要素を取得
const canvasElt = document.querySelector("canvas");

// ストリームの取得
const stream = canvasElt.captureStream(25); // 25 FPS

// 取得したストリームに対して何らかの処理を行う
// 例：RTCPeerConnection を使って別のコンピュータに送信
// ここで pc は既に生成された RTCPeerConnection オブジェクト
stream.getTracks().forEach((track) => pc.addTrack(track, stream));
```

仕様書
---

| Specification |
| --- |
| Media Capture from DOM Elements # dom-htmlcanvaselement-capturestream |

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

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

関連情報
----

* `HTMLMediaElement.captureStream()` - メディア要素からストリームをキャプチャするメソッド
* `MediaStream`
* `Media Capture and Streams API`


HTMLCanvasElement: contextrestored イベント - Web API

HTMLCanvasElement: contextrestored イベント
=======================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

**`contextrestored`** はキャンバス API のイベtので、ユーザーエージェントが `CanvasRenderingContext2D` のバッキングストレージを復元した場合に発行されます。

このイベントを受け取った後、再描画、リソースの再取得、コンテキストの状態の再初期化などが可能です。

構文
--

このイベント名を `addEventListener()` などのメソッドで使用したり、イベントハンドラープロパティを設定したりしてください。

```js
addEventListener("contextrestored", (event) => {});

oncontextrestored = (event) => {};
```

イベント型
-----

一般的な `Event` です。

例
-

次のコードは、コンテキストが復元されたイベントを検出するものです。

```js
const canvas = document.getElementById("canvas");

canvas.addEventListener(
  "contextrestored",
  (e) => {
    console.log(e);
    // redrawCanvas() などを呼び出す
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # event-contextrestored |

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

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

関連情報
----

* `HTMLCanvasElement: contextlost` イベント
* `CanvasRenderingContext2D.isContextLost()` (en-US)


HTMLCanvasElement: toBlob() メソッド - Web API

HTMLCanvasElement: toBlob() メソッド
================================

**`HTMLCanvasElement.toBlob()`** メソッドは、 キャンバスに含まれる画像を表す `Blob` オブジェクトを生成します。
 このファイルは、ユーザーエージェントの裁量によって、ディスクにキャッシュされるか、メモリーに保存されたりすることがあります。

 希望するファイル形式や画像品質を指定することができます。
 ファイル形式を指定しない場合、または指定された形式に対応していない場合、データは `image/png` としてエクスポートされます。
 ブラウザーは `image/png` に対応している必要があります。多くのブラウザーは `image/jpeg` や `image/webp` を含む他の形式にも対応しています。

作成する画像の解像度は、解像度メタデータのエンコーダーに対応しているファイル形式では 96dpi となります。

構文
--

```js
toBlob(callback)
toBlob(callback, type)
toBlob(callback, type, quality)
```

### 引数

`callback`

単一の引数として結果の `Blob` オブジェクトを受け取るコールバック関数です。何らかの理由で画像が作成できなかった場合は `null` が渡されることがあります。

`type` 省略可

 文字列で、画像形式を表します。
 既定の形式は `image/png` です。この形式は、指定された形式に対応していない場合にも使用されます。

`quality` 省略可

`0` から `1` の間の数値であり、作成する画像が非可逆圧縮（`image/jpeg` や `image/webp` など）であった場合の画像品質を示します。
 このオプションが指定されなかったり、許可されている範囲外の数値であったりした場合は、ユーザーエージェントは既定の品質値を使用します。

### 返値

なし (`undefined`)。

### 例外

`SecurityError`

キャンバスのビットマップがオリジンクリーンではありません。そのコンテンツの少なくとも一部が、文書そのものが読み込まれたサイトとは別のサイトから読み込まれたものであるか、その可能性があります。

例
-

### キャンバスに表示されている画像を取得する

 一度キャンバスにコンテンツを描画したら、これを何らかのサポートされている画像フォーマットに変換できます。
 たとえば、下記のコードスニペットは、ID が "canvas" の `<canvas>` 要素を取得して、PNG 画像としてコピーしてから、文書に新しい `<img>` 要素を追加しています。この画像ソースはキャンバスを使用して生成されたものです。

```js
const canvas = document.getElementById("canvas");

canvas.toBlob((blob) => {
  const newImg = document.createElement("img");
  const url = URL.createObjectURL(blob);

  newImg.onload = () => {
    // もう blob を読み取る必要は無いので、無効化します。
    URL.revokeObjectURL(url);
  };

  newImg.src = url;
  document.body.appendChild(newImg);
});
```

ここでは、PNG 画像を生成していることに注意してください。`toBlob()` の呼び出しに 2 つ目の引数を追加した場合、ユーザーエージェントが対応している画像の種類を指定できます。たとえば、次のようにして JPEG 形式の画像を取得できます。

```js
canvas.toBlob(
  (blob) => {
    /\* … \*/
  },
  "image/jpeg",
  0.95,
); // JPEG at 95% quality
```

### キャンバスを ico に変換（Mozilla のみ）

この例ではキャンバスをアイコンに変換するために `-moz-parse` を使用しており、Firefox でのみ動作します。Windows XP は PNG から ico への変換に対応していませんが、代わりに bmp を使用できます。download 属性を設定することで、ダウンロードリンクを生成できます。download 属性の値は、ファイル名として使用される名前です。

```js
const canvas = document.getElementById("canvas");
const d = canvas.width;
const ctx = canvas.getContext("2d");
ctx.beginPath();
ctx.moveTo(d / 2, 0);
ctx.lineTo(d, d);
ctx.lineTo(0, d);
ctx.closePath();
ctx.fillStyle = "yellow";
ctx.fill();

function blobCallback(iconName) {
  return (b) => {
    const a = document.createElement("a");
    a.textContent = "Download";
    document.body.appendChild(a);
    a.style.display = "block";
    a.download = `${iconName}.ico`;
    a.href = window.URL.createObjectURL(b);
  };
}
canvas.toBlob(
  blobCallback("passThisString"),
  "image/vnd.microsoft.icon",
  "-moz-parse-options:format=bmp;bpp=32",
);
```

### OS.File（chrome/add-on コンテキストのみ）で toBlob をディスクに保存する

**メモ:** このテクニックは画像をデスクトップに保存しますので、Firefox の chrome コンテキストか add-on コードでのみ利用できます。OS API はウェブサイトには存在しないからです。

```js
const canvas = document.getElementById("canvas");
const d = canvas.width;
ctx = canvas.getContext("2d");
ctx.beginPath();
ctx.moveTo(d / 2, 0);
ctx.lineTo(d, d);
ctx.lineTo(0, d);
ctx.closePath();
ctx.fillStyle = "yellow";
ctx.fill();

function blobCallback(iconName) {
  return (b) => {
    const r = new FileReader();
    r.onloadend = () => {
      // r.result contains the ArrayBuffer.
      Cu.import("resource://gre/modules/osfile.jsm");
      const writePath = OS.Path.join(
        OS.Constants.Path.desktopDir,
        `${iconName}.ico`,
      );
      const promise = OS.File.writeAtomic(writePath, new Uint8Array(r.result), {
        tmpPath: `${writePath}.tmp`,
      });
      promise.then(
        () => {
          console.log("successfully wrote file");
        },
        () => {
          console.log("failure writing file");
        },
      );
    };
    r.readAsArrayBuffer(b);
  };
}

canvas.toBlob(
  blobCallback("passThisString"),
  "image/vnd.microsoft.icon",
  "-moz-parse-options:format=bmp;bpp=32",
);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-toblob-dev |

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

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

関連情報
----

* `Blob`


HTMLCanvasElement: transferControlToOffscreen() メソッド - Web API

HTMLCanvasElement: transferControlToOffscreen() メソッド
====================================================

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
**`HTMLCanvasElement.transferControlToOffscreen()`** メソッドは、メインスレッドまたはワーカーの `OffscreenCanvas` (en-US) オブジェクトへ制御を委譲します。

構文
--

```js
transferControlToOffscreen()
```

### 引数

なし。

### 返値

`OffscreenCanvas` (en-US) オブジェクト。

例
-

次の例は、メインスレッド上の `OffscreenCanvas` (en-US) オブジェクトに制御を移譲する方法です。

```js
const htmlCanvas = document.createElement("canvas");
const offscreen = htmlCanvas.transferControlToOffscreen();
const gl = offscreen.getContext("webgl");

// Some drawing using the gl context…
```

次の例は、ワーカー上の `OffscreenCanvas` (en-US) オブジェクトに制御を移す方法を示しています。

```js
const offscreen = document.querySelector("canvas").transferControlToOffscreen();
const worker = new Worker("myworkerurl.js");
worker.postMessage({ canvas: offscreen }, [offscreen]);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-transfercontroltooffscreen-dev |

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

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

関連情報
----

* このメソッドを定義しているインターフェイス、`HTMLCanvasElement`
* `OffscreenCanvas` (en-US)


HTMLCanvasElement: webglcontextcreationerror イベント - Web API

HTMLCanvasElement: webglcontextcreationerror イベント
=================================================

**`webglcontextcreationerror`** は WebGL API のイベントで、ユーザーエージェントが `WebGLRenderingContext` コンテキストを作成することができない場合に発行されます。

このイベントには `WebGLContextEvent.statusMessage` (en-US) プロパティがあり、失敗に関する詳細情報を含むプラットフォーム依存の文字列を格納されることがあります。

このイベントはバブリングしません。

構文
--

このイベント名を `addEventListener()` などのメソッドで使用したり、イベントハンドラープロパティを設定したりしてください。

```js
addEventListener("webglcontextcreationerror", (event) => {});

onwebglcontextcreationerror = (event) => {};
```

イベント型
-----

`WebGLContextEvent` (en-US) です。`Event` を継承しています。

Event

WebGLContextEvent

(en-US)イベントプロパティ
---------

*このインターフェイスには親インターフェイスである `Event` から継承したプロパティもあります。*

`WebGLContextEvent.statusMessage` (en-US)

読み取り専用のプロパティで、イベントに関する追加情報を保持します。

例
-

```js
const canvas = document.getElementById("canvas");

canvas.addEventListener(
  "webglcontextcreationerror",
  (e) => {
    console.log(e.statusMessage || "Unknown error");
  },
  false,
);

const gl = canvas.getContext("webgl");
// logs statusMessage or "Unknown error" if unable to create WebGL context
```

仕様書
---

| Specification |
| --- |
| WebGL Specification # 5.15.4 |

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

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

関連情報
----

* `WebGLContextEvent` (en-US)
* `WebGLRenderingContext.isContextLost()` (en-US)
* `WEBGL_lose_context` (en-US), `WEBGL_lose_context.loseContext()` (en-US), `WEBGL_lose_context.restoreContext()` (en-US)


HTMLCanvasElement: webglcontextrestored イベント - Web API

HTMLCanvasElement: webglcontextrestored イベント
============================================

**`webglcontextrestored`** は WebGL API インターフェイスのイベントで、ユーザーエージェントが `WebGLRenderingContext` オブジェクトの描画バッファーを復元したときに発行されます。

コンテキストが復元されると、コンテキストが失われる前に作成したテクスチャやバッファーなどの WebGL リソースは使えなくなります。WebGL アプリケーションの状態を再初期化し、リソースを再作成する必要があります。

このイベントはバブリングしません。

構文
--

このイベント名を `addEventListener()` などのメソッドで使用したり、イベントハンドラープロパティを設定したりしてください。

```js
addEventListener("webglcontextrestored", (event) => {});

onwebglcontextrestored = (event) => {};
```

イベント型
-----

`WebGLContextEvent` (en-US) です。`Event` を継承しています。

Event

WebGLContextEvent

(en-US)イベントプロパティ
---------

*このインターフェイスには親インターフェイスである `Event` から継承したプロパティもあります。*

`WebGLContextEvent.statusMessage` (en-US)

読み取り専用のプロパティで、イベントに関する追加情報を保持します。

例
-

`WEBGL_lose_context` (en-US) 拡張機能の助けにより、`webglcontextrestored` イベントをシミュレートすることができます。

```js
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextrestored",
  (e) => {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").restoreContext();

// "webglcontextrestored" event is logged.
```

仕様書
---

| Specification |
| --- |
| WebGL Specification # 5.15.3 |

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

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

関連情報
----

* `WebGLContextEvent` (en-US)
* `WebGLRenderingContext.isContextLost()` (en-US)
* `WEBGL_lose_context` (en-US), `WEBGL_lose_context.loseContext()` (en-US), `WEBGL_lose_context.restoreContext()` (en-US)


HTMLCanvasElement: getContext() メソッド - Web API

HTMLCanvasElement: getContext() メソッド
====================================

**`HTMLCanvasElement.getContext()`** メソッドは、描画コンテキストを返します。対応していないコンテキスト識別子であったり、既に別なコンテキストモードが設定されていたりした場合は `null` になります。

同じキャンバス要素において、同じ `contextType` 引数を指定して後からこのメソッドを呼び出すと、常に最初の時点で呼び出された時と同じ描画コンテキストインスタンスが返されます。そのキャンバス要素で異なる描画コンテキストオブジェクトを取得することはできません。

構文
--

```js
getContext(contextType)
getContext(contextType, contextAttributes)
```

### 引数

`contextType`

キャンバスに関連する描画コンテキストを定義するコンテキスト識別子が入っている文字列です。利用可能な値は次の通りです。

* `"2d"`: 2 次元の描画コンテキストを表す `CanvasRenderingContext2D` オブジェクトが作成されます。
* `"webgl"`（または `"experimental-webgl"`）: 3 次元レンダリングコンテキストを表す `WebGLRenderingContext` オブジェクトを作成します。このコンテキストは、WebGL version 1 (OpenGL ES 2.0) を実装しているブラウザーでのみ利用可能です。
* `"webgl2"`: 3 次元レンダリングコンテキストを表す `WebGL2RenderingContext` (en-US) オブジェクトを作成します。このコンテキストは、WebGL version 2 (OpenGL ES 3.0) を実装しているブラウザーでのみ利用できます。
Experimental
* `"webgpu"`: これは、WebGPU レンダーパイプライン用の 3 次元レンダリングコンテキストを表す `GPUCanvasContext` (en-US) オブジェクトを作成するものです。このコンテキストは、WebGPU API を実装しているブラウザーでのみ利用できます。
* `"bitmaprenderer"`: 指定された`ImageBitmapRenderingContext` (en-US)でキャンバスのコンテンツを置き換える機能のみを提供します。

**メモ:** 識別子 `"experimental-webgl"` は、WebGL の新しい実装で使用されます。これらの実装は、テストスイート適合性に達していないか、プラットフォームのグラフィックドライバーがまだ安定していないかのいずれかです。Khronos Group が、一定の適合性ルールのもと、WebGL 実装を認証しています。

`contextAttributes` 省略可

レンダリングコンテキストを作成する際に、いくつかのコンテキスト属性を使用することができます。例えば、以下のようなものです。

```js
const gl = canvas.getContext("webgl", {
  antialias: false,
  depth: false,
});
```

2 次元のコンテキスト属性:

`alpha`

キャンバスにアルファチャンネルが含まれているかどうかを示す論理値です。`false` に設定すると、ブラウザーは背景が常に不透明であることを認識するようになり、透過コンテンツや画像の描画を高速化することができます。

`colorSpace` 省略可

レンダリングコンテキストの色空間を指定します。使用可能な値は以下の通りです。

* `"srgb"`: sRGB 色空間を選択します。これが既定値です。
* `"display-p3"`: display-p3 色空間を選択します。

`desynchronized`

論理値で、ユーザーエージェントがキャンバスの描画サイクルをイベントループから非同期化することによって、遅延を縮小することを示唆します。

`willReadFrequently`

多くのリードバック操作を予定しているかどうかを示す論理値です。これにより、（ハードウェアアクセラレーションではなく）ソフトウェア2Dキャンバスを使用するようになり、`getImageData()` を頻繁に呼び出す際にメモリーを節約することができます。

WebGL コンテキスト属性:

`alpha`

論理値で、キャンバスがアルファバッファーを持っているかどうかを示します。

`depth`

論理値で、描画バッファーに 16 ビット以上のの深度バッファーがあることがリクエストされたことを示します。

`stencil`

論理値で、描画バッファーに 8 ビット以上のステンシルバッファーを持つようリクエストされたことを示します。

`desynchronized`

論理値で、ユーザーエージェントがキャンバスの描画サイクルをイベントループから非同期化することでレイテンシーを縮小することを示唆します。

`antialias`

論理値で、可能であればアンチエイリアスを行うか否かを示します。

`failIfMajorPerformanceCaveat`

論理値で、システム性能が低い場合やハードウェア GPU が利用できない場合に、コンテキストを作成するかどうかを示します。

`powerPreference`

どのような GPU 構成が WebGL コンテキストに適しているかを示すユーザーエージェントへのヒントです。使用可能な値は次のとおりです。

`"default"`

どの GPU 構成が最も適しているかをユーザーエージェントに決定させます。これが既定値です。

`"high-performance"`

消費電力よりもレンダリング性能を優先します。

`"low-power"`

描画性能よりも省電力を優先します。

`premultipliedAlpha`

論理値で、ページコンポジターが描画バッファーにアルファがあらかじめ乗算された色を格納することを想定することを示します。

`preserveDrawingBuffer`

値が true の場合、バッファーがクリアされることはなく、作者がクリアするか上書きするまでその値が保持されます。

`xrCompatible`

論理値で、没入型 XR 機器に対応したグラフィックアダプターを使用するよう、ユーザーエージェントに示唆します。コンテキスト生成時にこの同期フラグを設定することは推奨されません。XR セッションを始めるには、非同期の `WebGLRenderingContext.makeXRCompatible()` (en-US) メソッドを呼び出す必要があります。

**メモ:** WebGPU 仕様書では、`getContext()` に固有のコンテキスト属性を定義していません。その代わりに、`GPUCanvasContext.configure()` (en-US) メソッドで構成オプションを提供しています。

### 返値

次のいずれかの描画コンテキストです。

* `CanvasRenderingContext2D`（`"2d"` の場合）
* `WebGLRenderingContext`（`"webgl"` および `"experimental-webgl"` の場合）
* `WebGL2RenderingContext` (en-US)（`"webgl2"` の場合）
* `GPUCanvasContext` (en-US)（`"webgpu"` の場合）
* `ImageBitmapRenderingContext` (en-US)（`"bitmaprenderer"` の場合）

`contextType` が使用可能な描画コンテキストに一致しない場合、または最初にリクエストされた `contextType` と異なる場合は、`null` を返します。

例
-

この `<canvas>` 要素があったとします。

```html
<canvas id="canvas" width="300" height="300"></canvas>
```

以下のコードで、キャンバスの `2d` コンテキストを取得することができます。

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
console.log(ctx); // CanvasRenderingContext2D { /\* … \*/ }
```

これでキャンバスの 2D 描画コンテキストを取得し、その中に描画することができるようになりました。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-getcontext-dev |

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

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

関連情報
----

* `HTMLCanvasElement`: `HTMLCanvasElement.getContext()` メソッドを定義しているインターフェイス
* `OffscreenCanvas.getContext()` (en-US)
* `CanvasRenderingContext2D.getContextAttributes()` (en-US), `WebGLRenderingContext.getContextAttributes()` (en-US)
* `CanvasRenderingContext2D`, `ImageBitmapRenderingContext` (en-US),
 `WebGLRenderingContext`, `WebGL2RenderingContext` (en-US), `GPUCanvasContext` (en-US): 利用可能な描画コンテキスト
* DCI-P3 色空間（ウィキペディア）
* sRGB 色空間（ウィキペディア）


HTMLCanvasElement: height プロパティ - Web API

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

**`HTMLCanvasElement.height`** プロパティは CSS ピクセル数として解釈される正の整数であり、この `<canvas>` 要素の `height` 属性を反映します。この属性が指定されなかった場合、または負の数など、無効な値をが設定された場合、既定値の `150` が使用されます。

これはキャンバスのサイズを制御する 2 つのプロパティのうちの 1 つで、もう一方は `HTMLCanvasElement.width` です。

値
-

数値です。

例
-

この `<canvas>` 要素があったとします。

```html
<canvas id="canvas" width="300" height="300"></canvas>
```

次のコードでキャンバスの高さを取得することができます。

```js
const canvas = document.getElementById("canvas");
console.log(canvas.height); // 300
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-height |

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

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

関連情報
----

* `HTMLCanvasElement`: `HTMLCanvasElement.height` プロパティを定義しているインターフェイス
* `HTMLCanvasElement.width`: キャンバスのサイズを制御するために使用される他のプロパティ


HTMLCanvasElement: contextlost イベント - Web API

HTMLCanvasElement: contextlost イベント
===================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

**`contextlost`** はキャンバス API のイベントで、 `CanvasRenderingContext2D` コンテキストに関連付けられたバックストレージが失われたことをユーザーエージェントが検出すると、発行されます。
 コンテキストは、ドライバーのクラッシュやアプリケーションのメモリー不足など、いくつかの理由で失われることがあります。

 既定では、ユーザーエージェントはコンテキストの復元を試み、`contextrestored` イベントを発行します。
 ユーザーコードは、イベント処理中に `Event.preventDefault()` を呼び出すことにより、コンテキストが復元されるのを防ぐことができます。

構文
--

このイベント名を `addEventListener()` などのメソッドで使用したり、イベントハンドラープロパティを設定したりしてください。

```js
addEventListener("contextlost", (event) => {});

oncontextlost = (event) => {};
```

イベント型
-----

一般的な `Event` です。

例
-

次のコードは、`contextlost` イベントを検出するものです。

```js
const canvas = document.getElementById("canvas");

canvas.addEventListener("contextlost", (event) => {
  console.log(event);
});
```

コンテキストが復元されないようにするためのコードは次のようになります。

```js
const canvas = document.getElementById("canvas");

canvas.addEventListener("contextlost", (event) => {
  event.preventDefault();
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # event-contextlost |

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

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

関連情報
----

* `HTMLCanvasElement: contextrestored` イベント
* `CanvasRenderingContext2D.isContextLost()` (en-US)


HTMLCanvasElement: toDataURL() メソッド - Web API

HTMLCanvasElement: toDataURL() メソッド
===================================

**`HTMLCanvasElement.toDataURL()`** メソッドは、 `type` 引数で指定された形式で画像を表現したものが入ったデータ URL を返します。

 希望するファイル形式や画像品質を指定することができます。
 ファイル形式を指定しなかった場合、または指定された形式に対応していない場合は、データは `image/png` として書き出されます。
 言い換えれば、他のリクエストされた `type` に対して、返値が `data:image/png` で始まる場合、その形式は対応していないということです。

ブラウザーは `image/png` に対応している必要があります。多くのブラウザーは `image/jpeg` や `image/webp` などの他の形式にも対応しています。

作成する画像データの解像度は、解像度メタデータのエンコーダーに対応したファイル形式の場合、 96dpi となります。

構文
--

```js
toDataURL()
toDataURL(type)
toDataURL(type, encoderOptions)
```

### 引数

`type` 省略可

 文字列で、画像形式を表します。
 既定の形式は `image/png` です。この形式は、指定された形式に対応していない場合にも使用されます。

`encoderOptions` 省略可

`0` から `1` の間の数値であり、作成する画像が非可逆圧縮（`image/jpeg` や `image/webp` など）であった場合の画像品質を示します。
 このオプションが指定されなかったり、許可されている範囲外の数値であったりした場合は、ユーザーエージェントは既定の品質値を使用します。

### 返値

要求されたデータ URL の入った文字列です。

キャンバスの高さまたは幅が `0` またはキャンバスの最大サイズより大きい場合、 `"data:,"` という文字列が返されます。

### 例外

`SecurityError`

 キャンバスのビットマップがオリジンクリーンではありません。
 そのコンテンツの少なくとも一部が、文書そのものが読み込まれたサイトとは別のサイトから読み込まれたものであるか、その可能性があります。

例
-

このような `<canvas>` 要素を用意します

```html
<canvas id="canvas" width="5" height="5"></canvas>
```

以下のコードによりキャンバスの Data URL を取得できます。

```js
const canvas = document.getElementById("canvas");
const dataURL = canvas.toDataURL();
console.log(dataURL);
// "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNby
// blAAAADElEQVQImWNgoBMAAABpAAFEI8ARAAAAAElFTkSuQmCC"
```

### JPEG の画質を設定する

```js
const fullQuality = canvas.toDataURL("image/jpeg", 1.0);
// data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…9oADAMBAAIRAxEAPwD/AD/6AP/Z"
const mediumQuality = canvas.toDataURL("image/jpeg", 0.5);
const lowQuality = canvas.toDataURL("image/jpeg", 0.1);
```

### 例: 動的に画像を変更

マウスイベントと連携して使用することで、画像を動的に変化させることができます（この例では、グレースケールとカラー）。

#### HTML

```html
<img class="grayscale" src="myPicture.png" alt="Description of my picture" />
```

#### JavaScript

```js
window.addEventListener("load", removeColors);

function showColorImg() {
  this.style.display = "none";
  this.nextSibling.style.display = "inline";
}

function showGrayImg() {
  this.previousSibling.style.display = "inline";
  this.style.display = "none";
}

function removeColors() {
  const images = document.getElementsByClassName("grayscale");
  const canvas = document.createElement("canvas");
  const ctx = canvas.getContext("2d");

  for (const colorImg of images) {
    const width = colorImg.offsetWidth;
    const height = colorImg.offsetHeight;
    canvas.width = width;
    canvas.height = height;
    ctx.drawImage(colorImg, 0, 0);
    const imgData = ctx.getImageData(0, 0, width, height);
    const pix = imgData.data;
    const pixLen = pix.length;
    for (let pixel = 0; pixel < pixLen; pixel += 4) {
      pix[pixel + 2] =
        pix[pixel + 1] =
        pix[pixel] =
          (pix[pixel] + pix[pixel + 1] + pix[pixel + 2]) / 3;
    }
    ctx.putImageData(imgData, 0, 0);
    const grayImg = new Image();
    grayImg.src = canvas.toDataURL();
    grayImg.onmouseover = showColorImg;
    colorImg.onmouseout = showGrayImg;
    ctx.clearRect(0, 0, width, height);
    colorImg.style.display = "none";
    colorImg.parentNode.insertBefore(grayImg, colorImg);
  }
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-todataurl-dev |

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

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

関連情報
----

* データ URL（HTTP リファレンス）


HTMLCanvasElement: webglcontextlost イベント - Web API

HTMLCanvasElement: webglcontextlost イベント
========================================

**`webglcontextlost`** は WebGL API のイベントで、`WebGLRenderingContext` オブジェクトに関連づけられた描画バッファーが失われたことをユーザーエージェントが検出した場合に発行されます。

このイベントはバブリングしません。

構文
--

このイベント名を `addEventListener()` などのメソッドで使用したり、イベントハンドラープロパティを設定したりしてください。

```js
addEventListener("webglcontextlost", (event) => {});

onwebglcontextlost = (event) => {};
```

イベント型
-----

`WebGLContextEvent` (en-US) です。`Event` を継承しています。

Event

WebGLContextEvent

(en-US)イベントプロパティ
---------

*このインターフェイスには親インターフェイスである `Event` から継承したプロパティもあります。*

`WebGLContextEvent.statusMessage` (en-US)

読み取り専用のプロパティで、イベントに関する追加情報を保持します。

例
-

`WEBGL_lose_context` (en-US) 拡張機能の助けにより、`webglcontextlost` イベントをシミュレートすることができます。

```js
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");

canvas.addEventListener("webglcontextlost", (event) => {
  console.log(event);
});

gl.getExtension("WEBGL\_lose\_context").loseContext();

// "webglcontextlost" event is logged.
```

仕様書
---

| Specification |
| --- |
| WebGL Specification # 5.15.2 |

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

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

関連情報
----

* `WebGLContextEvent` (en-US)
* `WebGLRenderingContext.isContextLost()` (en-US)
* `WEBGL_lose_context` (en-US), `WEBGL_lose_context.loseContext()` (en-US), `WEBGL_lose_context.restoreContext()` (en-US)


HTMLCanvasElement: mozOpaque プロパティ - Web API

HTMLCanvasElement: mozOpaque プロパティ
==================================

**非推奨:** この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

**非標準:** この機能は標準ではなく、標準化の予定もありません。公開されているウェブサイトには使用しないでください。ユーザーによっては使用できないことがあります。実装ごとに大きな差があることもあり、将来は振る舞いが変わるかもしれません。

標準外の **`HTMLCanvasElement.mozOpaque`** プロパティは論理値で、この `<canvas>` 要素の `moz-opaque` 属性を反映します。これは、半透明の要素があるかどうかをキャンバスに知らせるものです。半透明がないことがキャンバスに伝われば、描画性能を最適化することができます。

**メモ:** これは、`HTMLCanvasElement.getContext()` で描画コンテキストを作成する際に、`alpha` オプションを `false` に設定することで標準化されました。`mozOpaque` を使用することは避けてください。Firefox は将来的に対応をやめる予定です。

値
-

論理値です。

例
-

この `<canvas>` 要素があったとします。

```html
<canvas id="canvas" width="300" height="300" moz-opaque></canvas>
```

`mozOpaque` プロパティは、取得したり設定したりすることができます。例えば、`mimeType === 'image/jpeg'` などの場合に条件付きで `true` に設定し、半透明が不要なアプリケーションでのパフォーマンスを得ることができます。

```js
const canvas = document.getElementById("canvas");
console.log(canvas.mozOpaque); // true
// deactivate it
canvas.mozOpaque = false;
```

仕様書
---

標準には含まれていません。

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

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

関連情報
----

* `HTMLCanvasElement`: `HTMLCanvasElement.mozOpaque` プロパティを定義するのに使用するインターフェイス
* `moz-opaque`: `<canvas>` 要素の HTML 属性
* Optimizing your JavaScript game for Firefox OS


HTMLCanvasElement: width プロパティ - Web API

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

**`HTMLCanvasElement.width`** プロパティは CSS ピクセル数として解釈される正の整数であり、この `<canvas>` 要素の `width` 属性を反映します。この属性が指定されなかった場合、または負の数など、無効な値をが設定された場合、既定値の `300` が使用されます。

これはキャンバスのサイズを制御する 2 つのプロパティのうちの 1 つで、もう一方は `HTMLCanvasElement.height` です。

値
-

数値です。

例
-

この `<canvas>` 要素があったとします。

```html
<canvas id="canvas" width="300" height="300"></canvas>
```

次のコードでキャンバスの幅を取得することができます。

```js
const canvas = document.getElementById("canvas");
console.log(canvas.width); // 300
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-canvas-height |

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

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

関連情報
----

* `HTMLCanvasElement`: `HTMLCanvasElement.width` プロパティを定義しているインターフェイス
* `HTMLCanvasElement.height`: キャンバスのサイズを制御するために使用される他のプロパティ


Accelerometer: z プロパティ - Web API

Accelerometer: z プロパティ
======================

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

`Accelerometer` インターフェイスの読み取り専用プロパティ **`z`** は、デバイスの z 軸方向の加速度を表す数値を返します。

値
-

`Number` です。

例
-

通常、加速度は `reading` イベントコールバックで取得します。以下の例では、これを 1 秒あたり 60 回行います。

```js
const accelerometer = new Accelerometer({ frequency: 60 });

accelerometer.addEventListener("reading", (e) => {
  console.log(`X 軸方向の加速度 ${accelerometer.x}`);
  console.log(`Y 軸方向の加速度 ${accelerometer.y}`);
  console.log(`Z 軸方向の加速度 ${accelerometer.z}`);
});
accelerometer.start();
```

仕様書
---

| Specification |
| --- |
| Accelerometer # accelerometer-z |

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

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


Accelerometer: x プロパティ - Web API

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

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

`Accelerometer` インターフェイスの読み取り専用プロパティ **`x`** は、デバイスの x 軸方向の加速度を表す数値を返します。

値
-

`Number` です。

例
-

通常、加速度は `reading` イベントコールバックで取得します。以下の例では、これを 1 秒あたり 60 回行います。

```js
const accelerometer = new Accelerometer({ frequency: 60 });

accelerometer.addEventListener("reading", (e) => {
  console.log(`X 軸方向の加速度 ${accelerometer.x}`);
  console.log(`Y 軸方向の加速度 ${accelerometer.y}`);
  console.log(`Z 軸方向の加速度 ${accelerometer.z}`);
});
accelerometer.start();
```

仕様書
---

| Specification |
| --- |
| Accelerometer # accelerometer-x |

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

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


Accelerometer: y プロパティ - Web API

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

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

`Accelerometer` インターフェイスの読み取り専用プロパティ **`y`** は、デバイスの y 軸方向の加速度を表す数値を返します。

値
-

`Number` です。

例
-

通常、加速度は `reading` イベントコールバックで取得します。以下の例では、これを 1 秒あたり 60 回行います。

```js
const accelerometer = new Accelerometer({ frequency: 60 });

accelerometer.addEventListener("reading", (e) => {
  console.log(`X 軸方向の加速度 ${accelerometer.x}`);
  console.log(`Y 軸方向の加速度 ${accelerometer.y}`);
  console.log(`Z 軸方向の加速度 ${accelerometer.z}`);
});
accelerometer.start();
```

仕様書
---

| Specification |
| --- |
| Accelerometer # accelerometer-y |

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

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


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

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

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

**`Accelerometer()`** コンストラクターは、取得時点でデバイスの 3 軸それぞれにかかっている加速度を返す新しい `Accelerometer` オブジェクトを生成します。

構文
--

```js
new Accelerometer()
new Accelerometer(options)
```

### 引数

`options` 省略可

以下のオプションがあります。

`frequency`

1 秒あたり行いたいサンプリングの回数で、`reading` イベントが 1 秒あたり何回呼ばれるかを表します。整数または小数が利用でき、小数は 1 秒に 1 回未満の頻度を指定する際に用います。実際に計測が行われる頻度はデバイスのハードウェアに依存し、指定より少なくなる可能性があります。

`referenceFrame`

`'device'` か `'screen'` のいずれかです。デフォルトは `'device'` です。

### 例外

`SecurityError` `DOMException`

この機能の使用が Permissions Policy によりブロックされたとき投げられます。

仕様書
---

| Specification |
| --- |
| Accelerometer # dom-accelerometer-accelerometer |

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

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

関連情報
----

* `reading` イベント


IDBObjectStore: indexNames プロパティ - Web API

IDBObjectStore: indexNames プロパティ
================================

`IDBObjectStore` インターフェイスの読み取り専用プロパティ **`indexNames`** は、オブジェクトストア内のオブジェクトに対するインデックスのリストを返します。

**注:** この機能は Web Worker 内で利用可能です

値
-

`DOMStringList` です。

例
-

以下のコード断片では、データベースの読み書きトランザクションを開き、`add()` を用いてデータをオブジェクトストアに追加します。オブジェクトストアの生成後、コンソールに `objectStore.indexNames` を記録します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する
  // これは後でよく使う
  db = this.result;

  // addData() 関数を実行し、データをデータベースに追加する
  addData();
};

function addData() {
  // IDB に挿入できる新しいオブジェクトを生成する
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // 読み書きトランザクションを開き、データを追加する準備をする
  const transaction = db.transaction(["toDoList"], "readwrite");

  // すべて完了し、トランザクションが正常終了したら報告する
  transaction.oncomplete = (event) => {
    note.innerHTML += "<li>トランザクションが完了しました。</li>";
  };

  transaction.onerror = (event) => {
    note.innerHTML +=
      "<li>トランザクションはエラーのため開けませんでした。アイテムは重複させられません。</li>";
  };

  // トランザクション上でオブジェクトストアを生成する
  const objectStore = transaction.objectStore("toDoList");
  console.log(objectStore.indexNames);

  // オブジェクトストアに newItem オブジェクトを追加する要求を行う
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // 要求の成功を報告する
    note.innerHTML += "<li>要求に成功しました。</li>";
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-indexnames① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: openKeyCursor() メソッド - Web API

IDBObjectStore: openKeyCursor() メソッド
====================================

`IDBObjectStore` インターフェイスの **`openKeyCursor()`** メソッドは、`result` がマッチした結果の走査に用いることができる `IDBCursor` に設定される `IDBRequest` オブジェクトを返します。カーソルを用いてオブジェクトストア内のキーを走査するのに用います。

追加を行う操作が正常に完了したかを判定するには、結果の `success` イベントを監視してください。

構文
--

```js
openKeyCursor()
openKeyCursor(query)
openKeyCursor(query, direction)
```

### 引数

`query` 省略可

問い合わせを行うキー範囲です。単一のキーが渡された場合は、そのキーのみを含むキー範囲になります。何も渡されなかった場合は、オブジェクトストア内の全レコードを選択するキー範囲になります。

`direction` 省略可

 カーソルが動く方向を決める `IDBCursorDirection` です。
 有効な値は `"next"`、`"nextunique"`、`"prev"`、`"prevunique"` です。デフォルトは `"next"` です。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は以下になります。

* 与えられたクエリーにマッチする最初のレコードを指す `IDBCursor` オブジェクト
* マッチするレコードが見つからなかった場合は `null`
### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`InvalidStateError` `DOMException`

この `IDBObjectStore` または `IDBIndex` が削除済のとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

指定のキーまたはキー範囲が無効であるとき投げられます。

例
-

このシンプルな断片では、トランザクションを生成し、オブジェクトストアを取得し、カーソルを用いてオブジェクトストア内の全レコードを走査します。

```js
const transaction = db.transaction("name", "readonly");
const objectStore = transaction.objectStore("name");
const request = objectStore.openKeyCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    // cursor.key に走査中の現在のレコードのキーが入っている
    // openCursor と違って cursor.value は無いことに注意
    // ここで結果を用いて何かする
    cursor.continue();
  } else {
    // もう結果は無い
  }
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-openkeycursor① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: index() メソッド - Web API

IDBObjectStore: index() メソッド
============================

`IDBObjectStore` インターフェイスの **`index()`** メソッドは、現在のオブジェクトストアの名前付きインデックスを開きます。開くと、たとえば、カーソルを用いてレコード群をそのインデックスでソートして取得できます。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
index(name)
```

### 引数

`name`

開くインデックスの名前です。

### 返値

指定のインデックスにアクセスするための `IDBIndex` オブジェクトです。

### 例外

`InvalidStateError` `DOMException`

元のオブジェクトストアが削除済か、オブジェクトストアのトランザクションが終了しているとき投げられます。

`NotFoundError` `DOMException`

指定の名前 (大文字と小文字を区別します) のインデックスがデータベースに存在しないとき投げられます。

例
-

以下の例では、トランザクションとオブジェクトストアを開き、シンプルな連絡先データベースからインデックス `lName` を取得します。そして、`IDBIndex.openCursor` を用いてこのインデックスで基本的なカーソルを開きます。これは、返されるレコードが主キーではなくインデックスに基づいてソートされる以外、`IDBObjectStore.openCursor` を用いて `ObjectStore` で直接カーソルを開くのと同じように動きます。

最後に、レコードを走査し、データを HTML テーブルに挿入します。動く例全体は、IndexedDB-examples デモリポジトリー内の IDBIndex 例 を参照してください。(動く例を見る)

```js
function displayDataByIndex() {
  tableEntry.innerHTML = "";
  const transaction = db.transaction(["contactsList"], "readonly");
  const objectStore = transaction.objectStore("contactsList");

  const myIndex = objectStore.index("lName");
  myIndex.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.innerHTML =
        `<td>${cursor.value.id}</td>` +
        `<td>${cursor.value.lName}</td>` +
        `<td>${cursor.value.fName}</td>` +
        `<td>${cursor.value.jTitle}</td>` +
        `<td>${cursor.value.company}</td>` +
        `<td>${cursor.value.eMail}</td>` +
        `<td>${cursor.value.phone}</td>` +
        `<td>${cursor.value.age}</td>`;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("全エントリーを表示しました。");
    }
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbobjectstore-index |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: getKey() メソッド - Web API

IDBObjectStore: getKey() メソッド
=============================

`IDBObjectStore` インターフェイスの **`getKey()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで指定のクエリーで選択されたキーを返します。これはオブジェクトストアから指定のレコードを取得する用です。

キーが正常に見つかった場合は、その構造化複製を作成し、要求オブジェクトの `result` に設定します。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
getKey(key)
```

### 引数

`key`

取得するレコードを特定するキーまたはキー範囲です。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は与えられたキーまたはキー範囲にマッチする最初のレコードのキーになります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`InvalidStateError` `DOMException`

この `IDBObjectStore` が削除されたか取り除かれたとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

与えられたキーまたはキー範囲が無効なキーを含むとき投げられます。

例
-

```js
let openRequest = indexedDB.open("telemetry");
openRequest.onsuccess = (event) => {
  let db = event.target.result;
  let store = db.transaction("netlogs").objectStore("netlogs");

  let today = new Date();
  let yesterday = new Date(today);
  yesterday.setDate(today.getDate() - 1);
  let request = store.getKey(IDBKeyRange(yesterday, today));
  request.onsuccess = (event) => {
    let when = event.target.result;
    alert(`直近 24 時間で最初のアクティビティは ${when} に発生しました。`);
  };
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-getkey① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: createIndex() メソッド - Web API

IDBObjectStore: createIndex() メソッド
==================================

`IDBObjectStore` インターフェイスの **`createIndex()`** メソッドは、接続中のデータベースに新しい `IDBIndex` オブジェクトを作成して返します。これは、データベースの各レコードが持つべき新しいデータポイントを定義するフィールド (列) を定義します。

IndexedDB のインデックスには *任意の* JavaScript のデータ型を入れることができることを覚えておいてください。IndexedDB は保存するオブジェクトのシリアライズに構造化複製アルゴリズムを用いるので、単純なオブジェクトも複雑なオブジェクトも保存できます。

このメソッドは `VersionChange` トランザクションモードのコールバックからのみ呼び出せることに注意してください。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
createIndex(indexName, keyPath)
createIndex(indexName, keyPath, options)
```

### 引数

`indexName`

作成するインデックスの名前です。なお、空の名前のインデックスを作成することもできます。

`keyPath`

インデックスで使用するキーパスです。なお、空の `keyPath` でインデックスを作成することも、`keyPath` としてシーケンス (配列) を渡すこともできます。

`options` 省略可

以下のプロパティを持ちうるオブジェクトです。

`unique`

`true` に設定した場合、このインデックスは単一のキーについて重複した値を許可しません。デフォルトは `false` です。

`multiEntry`

`true` に設定した場合、このインデックスは `keyPath` が配列に解決したとき、配列の各要素についてインデックスにエントリーを追加します。
 `false` に設定した場合、配列を 1 個のエントリーとして追加します。デフォルトは `false` です。

`locale`
Non-standard

 現在 Firefox (43+) でのみ対応しています。インデックスのロケールを指定できます。
 指定すると、キー範囲によるデータのソート操作はすべて、このロケールのソート規則に沿います。
 (ロケールを意識した並べ替えを参照してください)
 以下の 3 通りの方法のいずれかで指定できます。

* `string`: 特定のロケールコードの文字列、たとえば `en-US` や `pl` です。
* `auto`: プラットフォームのデフォルトのロケールを用います。(ユーザーエージェントの設定で変わる可能性があります)
* `null` もしくは `undefined`: ロケールが指定されない場合、通常の JavaScript のソートが用いられます。(ロケールを意識しません)

### 返値

新しく作成されたインデックスを表す `IDBIndex` オブジェクトを返します。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`ConstraintError` `DOMException`

同じ名前のインデックスが既にデータベースに存在するとき投げられます。インデックスの名前は大文字と小文字を区別します。

`InvalidAccessError` `DOMException`

与えられたキーパスがシーケンスで、かつ `objectParameters` オブジェクトで `multiEntry` が `true` に設定されているとき投げられます。

`InvalidStateError` `DOMException`

以下のとき投げられます。

* このメソッドが `versionchange` トランザクションモードのコールバック、すなわち `onupgradeneeded` のハンドラーから呼ばれていないとき。
* オブジェクトストアが削除済のとき。

`SyntaxError` `DOMException`

指定された `keyPath` が有効なキーパスでないとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` が属するトランザクションが実行中でないとき (たとえば、削除されたか取り除かれたとき) 投げられます。Firefox のバージョン 41 より前では、この場合も `InvalidStateError` が投げられ、誤解を招いていました。これは今では修正されています。(Webkit bug 1176165 を参照してください)

例
-

以下の例では、より高いバージョン番号のデータベースが読み込まれた際にデータベースの構造を更新する `onupgradeneeded` のハンドラーがあります。オブジェクトストアに新しいインデックスを作成するため、`createIndex()` が使われています。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
let db;

// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

// データベースを開く用の 2 個のイベントハンドラー
DBOpenRequest.onerror = (event) => {
  note.innerHTML += "<li>データベースの読み込みエラー</li>";
};

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する
  // これは後でよく使う
  db = request.result;

  // displayData() 関数を実行し、IDB に既に入っている
  // to-do リストのデータすべてをタスクリストに入れる
  displayData();
};

// このハンドラーは、データベースが新しく作られたときに発火し、
// データベースが作成されていなかったか、
// window.indexedDB.open() (前を参照) で新しいバージョン番号が指定されたことを示します。
// これは最近のブラウザーでしか実装されていません。
DBOpenRequest.onupgradeneeded = (event) => {
  const db = event.target.result;

  db.onerror = (event) => {
    note.innerHTML += "<li>データベース読み込みエラー</li>";
  };

  // このデータベース用の objectStore を作成する
  const objectStore = db.createObjectStore("toDoList", {
    keyPath: "taskTitle",
  });

  // この objectStore に格納するデータアイテムを定義する

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });
  objectStore.createIndex("notified", "notified", { unique: false });
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-createindex① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: count() メソッド - Web API

IDBObjectStore: count() メソッド
============================

`IDBObjectStore` インターフェイスの **`count()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで、指定されたキーまたは `IDBKeyRange` にマッチするレコードの総数を返します。引数が指定されない場合は、オブジェクトストア内の全レコードの数を返します。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
count()
count(query)
```

### 引数

`query` 省略可

数えたいレコードの範囲を指定するキーまたは `IDBKeyRange` オブジェクトです。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は与えられたクエリーにマッチするレコードの数になります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`InvalidStateError` `DOMException`

この `IDBObjectStore` が削除されているとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

指定されたキーまたはキー範囲が無効であるとき投げられます。

例
-

このシンプルな断片では、トランザクションを生成し、オブジェクトストアを取得し、`count()` を用いてオブジェクトストア内のレコードを数えます。`success` ハンドラーが実行された時、コンソールにカウント値 (整数) を記録します。

```js
const transaction = db.transaction(["fThings"], "readonly");
const objectStore = transaction.objectStore("fThings");

const countRequest = objectStore.count();
countRequest.onsuccess = () => {
  console.log(countRequest.result);
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-count① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: put() メソッド - Web API

IDBObjectStore: put() メソッド
==========================

`IDBObjectStore` インターフェイスの **`put()`** メソッドは、データベース内の指定のレコードを更新するか、指定のアイテムが存在しない場合は新規レコードを挿入します。

このメソッドは `IDBRequest` オブジェクトを返し、別スレッドで、値の構造化複製を作成し、この複製をオブジェクトストアに格納します。これは、トランザクションモードが `readwrite` のとき、オブジェクトストアに新規レコードを追加するか既存レコードを更新する用です。レコードが正常に格納されると、返された要求オブジェクトで、`result` が格納されたレコードのキーに設定され、`transaction` がオブジェクトストアが開かれたトランザクションに設定された `success` イベントが発火します。

`put` メソッドは *更新または挿入を行う* メソッドです。
 *挿入のみを行う* メソッドは、`IDBObjectStore.add` メソッドを参照してください。

更新したいレコードを指す `IDBCursor` があるときは、`IDBObjectStore.put()` を用いるよりも `IDBCursor.update()` で更新を行うほうがよいことを覚えておいてください。そうすることで、新規レコードを挿入するのではなく、既存のレコードを更新することが明確になります。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
put(item)
put(item, key)
```

### 引数

`item`

更新 (または挿入) を行いたいアイテムです。

`key` 省略可

更新したいレコードの主キーです。(たとえば `IDBCursor.primaryKey` から取得できます)

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は新しいレコードのキーまたは更新したレコードのキーになります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`ReadOnlyError` `DOMException`

この操作に対応するトランザクションが読み取り専用モードのとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

以下のいずれかの条件を満たすとき投げられます。

* オブジェクトストアでインラインキーを使用しているかキージェネレーターが存在し、かつ引数 `key` が指定されたとき。
* オブジェクトストアがアウトラインキーを用いかつキージェネレーターも存在せず、引数 `key` が指定されないとき。
* オブジェクトストアがインラインキーを用いているが `key` ジェネレーターは存在せず、オブジェクトストアのキーパスが有効なキーを生成しないとき。
* 引数 `key` が指定されたが、有効なキーでないとき。

`InvalidStateError` `DOMException`

`IDBObjectStore` が削除されたか取り除かれたとき投げられます。

`DataCloneError` `DOMException`

保存されるデータが内部の構造化複製アルゴリズムで複製できなかったとき投げられます。

例
-

以下の例では、レコードタイトルを指定した要求を行います。要求に成功すると、`onsuccess` 関数で (`objectStoreTitleRequest.result` から利用可能な) `IDBObjectStore` から対応するレコードを取得し、レコードのプロパティ 1 個を更新し、更新したレコードを `put()` を用いた別の要求によりオブジェクトストアに書き戻します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
const title = "Walk dog";

// いつも通りトランザクションを開く
const objectStore = db
  .transaction(["toDoList"], "readwrite")
  .objectStore("toDoList");

// タイトルがこの title である to-do リストのオブジェクトを取得する
const objectStoreTitleRequest = objectStore.get(title);

objectStoreTitleRequest.onsuccess = () => {
  // 結果として返されたデータオブジェクトを取得する
  const data = objectStoreTitleRequest.result;

  // オブジェクトの notified の値を "yes" に更新する
  data.notified = "yes";

  // アイテムをデータベースに書き戻す別の要求を生成する
  const updateTitleRequest = objectStore.put(data);

  // この要求を開始したトランザクションを記録する
  console.log(
    `この要求を開始したトランザクションは ${updateTitleRequest.transaction}`,
  );

  // 新しい要求が成功したら、再び displayData() 関数を実行し、表示を更新する
  updateTitleRequest.onsuccess = () => {
    displayData();
  };
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-put① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動くデモを見る)


IDBObjectStore: getAll() メソッド - Web API

IDBObjectStore: getAll() メソッド
=============================

`IDBObjectStore` インターフェイスの **`getAll()`** メソッドは、指定の引数にマッチするすべてのオブジェクト、または引数が与えられない場合はすべてのオブジェクトが入った `IDBRequest` オブジェクトを返します。

値が正常に見つかった場合は、その構造化複製を作成し、要求オブジェクトの `result` に設定します。

このメソッドは、以下の場合に同じ結果になります。

* レコードがデータベースに存在しない場合
* レコードの値が `undefined` の場合

これらを区別するには、以下のメソッドを使用できます。

1. `openCursor()` メソッドを同じキーで使用します。このメソッドはレコードが存在すればカーソルを返し、存在しなければカーソルを返しません。
2. `count()` メソッドを同じキーで使用します。このメソッドは行が存在すれば 1 を、存在しなければ 0 を返します。
構文
--

```js
getAll()
getAll(query)
getAll(query, count)
```

### 引数

`query` 省略可

問い合わせを行うキーまたは `IDBKeyRange` です。何も渡さない場合、デフォルトはオブジェクトストア内の全レコードを選択するキー範囲です。

`count` 省略可

複数の値が見つかった場合に返す値の数を指定します。`0` 未満の場合や `2^32 - 1` 超の場合は、`TypeError` 例外が投げられます。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は与えられた問い合わせにマッチする全レコード (`count` が指定された場合は `count` の数まで) の値の `Array` になります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

指定のキーまたはキー範囲が無効なキーを含むか `null` であるとき投げられます。

`InvalidStateError` `DOMException`

`IDBObjectStore` が削除されたか取り除かれたとき投げられます。

`TypeError`

引数 `count` が `0` から `2^32 - 1` の範囲 (両端を含む) にないとき投げられます。

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-getall① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: keyPath プロパティ - Web API

IDBObjectStore: keyPath プロパティ
=============================

`IDBObjectStore` インターフェイスの読み取り専用プロパティ **`keyPath`** は、このオブジェクトストアのキーパスを返します。

このプロパティが `null` の場合は、アプリケーションは変更操作のたびにキーを指定しなければなりません。

**注:** この機能は Web Worker 内で利用可能です

値
-

任意のデータ型です。

例
-

以下のコード断片では、データベースの読み書きトランザクションを開き、`add()` を用いてデータをオブジェクトストアに追加します。オブジェクトストアの生成後、コンソールに `objectStore.keyPath` を記録します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する
  // これは後でよく使う
  db = DBOpenRequest.result;

  // addData() 関数を実行し、データをデータベースに追加する
  addData();
};

function addData() {
  // IDB に挿入できる新しいオブジェクトを生成する
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // 読み書きトランザクションを開き、データを追加する準備をする
  const transaction = db.transaction(["toDoList"], "readwrite");

  // すべて完了し、トランザクションが正常終了したら報告する
  transaction.oncomplete = (event) => {
    note.innerHTML += "<li>トランザクションが完了しました。</li>";
  };

  transaction.onerror = (event) => {
    note.innerHTML +=
      "<li>トランザクションはエラーのため開けませんでした。アイテムは重複させられません。</li>";
  };

  // トランザクション上でオブジェクトストアを生成する
  const objectStore = transaction.objectStore("toDoList");
  console.log(objectStore.keyPath);

  // オブジェクトストアに newItem オブジェクトを追加する要求を行う
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // 要求の成功を報告する
    note.innerHTML += "<li>要求に成功しました。</li>";
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-keypath① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: deleteIndex() メソッド - Web API

IDBObjectStore: deleteIndex() メソッド
==================================

`IDBObjectStore` インターフェイスの **`deleteIndex()`** メソッドは、バージョンの更新時に用いられ、接続中のデータベース内の指定した名前のインデックスを破棄します。

なお、このメソッドは `VersionChange` トランザクションモードのコールバックからのみ呼び出せます。また、このメソッドは `IDBObjectStore.indexNames` プロパティを同期的に変更します。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
deleteIndex(indexName)
```

### 引数

`indexName`

削除する既存のインデックスの名前です。

### 返値

なし (`undefined`)

### 例外

`InvalidStateError` `DOMException`

このメソッドが `versionchange` トランザクションモードのコールバックから呼ばれていないとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` が属するトランザクションが実行中でない (たとえば、削除されたか取り除かれた) とき投げられます。

`NotFoundError` `DOMException`

指定された名前のインデックス (大文字と小文字を区別します) がデータベースに無いとき投げられます。

例
-

以下の例では、より高いバージョン番号のデータベースが読み込まれたときにデータベースの構造を更新する `onupgradeneeded` のハンドラーがあります。`IDBObjectStore.createIndex` を用いてオブジェクトストアに新しいインデックスを作成し、その後 `deleteIndex()` を用いて不要な古いインデックスを削除します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
let db;

// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

// 以下の 2 個のイベントハンドラーは、データベースを開くのに成功したか、失敗した時に動く
DBOpenRequest.onerror = (event) => {
  note.innerHTML += "<li>データベース読み込みエラー</li>";
};

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する。これは後でよく使う
  db = event.target.result;

  // displayData() 関数を実行し、IDB に格納済の to-do リストデータすべてをタスクリストに入れる
  displayData();
};

// このイベントは、新しいバージョンのデータベースの作成が必要な場合を処理します。
// これは、データベースが作成されていなかったか、
// 前の行の window.indexedDB.open で新しいバージョン番号が指定された場合です。
// これは最近のブラウザーでしか実装されていません。
DBOpenRequest.onupgradeneeded = (event) => {
  const db = event.target.result;

  db.onerror = (event) => {
    note.innerHTML += "<li>データベースの読み込みエラー</li>";
  };

  // このデータベース用の objectStore を作成する
  const objectStore = db.createObjectStore("toDoList", {
    keyPath: "taskTitle",
  });

  // objectStore に格納するデータアイテムを定義する

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });
  objectStore.createIndex("notified", "notified", { unique: false });

  objectStore.deleteIndex("seconds");
  objectStore.deleteIndex("contact");
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-deleteindex① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: delete() メソッド - Web API

IDBObjectStore: delete() メソッド
=============================

`IDBObjectStore` インターフェイスの **`delete()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで指定のレコードまたはレコード群を削除します。

キーまたは `IDBKeyRange` を渡すことができ、これによってオブジェクトストアから 1 個または複数のレコードを削除できます。オブジェクトストア内の全レコードを削除するには、`IDBObjectStore.clear` を使用してください。

`IDBCursor` を使用している場合は、`IDBCursor.delete()` メソッドを用いることで現在のレコードをより効率よく削除できることを覚えておいてください。この方法では、レコードのキーを明示的に検索せずにすみます。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
delete(key)
```

### 引数

`key`

削除するレコードのキー、もしくはキーが範囲内のレコードをすべて削除する `IDBKeyRange` です。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は `undefined` になります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`TransactionInactiveError` `DOMException`

このオブジェクトストアのトランザクションが実行中でないとき投げられます。

`ReadOnlyError` `DOMException`

このオブジェクトストアのトランザクションのモードが読み取り専用のとき投げられます。

`InvalidStateError` `DOMException`

このオブジェクトストアが削除済のとき投げられます。

`DataError` `DOMException`

`key` が有効なキーでもキー範囲でもないとき投げられます。

例
-

以下のコード断片では、To-do Notifications サンプルアプリケーションの一部である `deleteItem()` 関数を紹介しています。このアプリケーションは、to-do リストの項目を IndexedDB を用いて保存します。このアプリケーションのコード全体を GitHub で見ることも、動くアプリケーションを試すこともできます。

`deleteItem()` 関数は、ユーザーが to-do リストの項目を削除する項目をクリックすると呼び出されます。アイテムキーはボタンの `'data-task'` データ属性で設定されるので、削除するアイテムを特定できます。この関数はデータベースのトランザクションを開き、その中でキーを指定してアイテムを削除します。トランザクションの完了時、この関数はアプリケーションの UI を更新してアイテムが削除されたことを報告します。

なお、この関数内で使われる `db` はアプリケーションの読み込み時に初期化され、`IDBDatabase` オブジェクトを参照するグローバル変数です。

```js
function deleteItem(event) {
  // 削除するタスクの名前を取得する
  let dataTask = event.target.getAttribute("data-task");

  // データベースのトランザクションを開始し、タスクを上で取得した名前で検索して削除する
  let transaction = db.transaction(["toDoList"], "readwrite");
  let request = transaction.objectStore("toDoList").delete(dataTask);

  // データアイテムが削除されたことを報告する
  transaction.oncomplete = () => {
    // ボタンの親 (リストアイテム) を削除し、表示を消す
    event.target.parentNode.parentNode.removeChild(event.target.parentNode);
    note.innerHTML += `<li>タスク "${dataTask}" が削除されました。</li>`;
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-delete① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: name プロパティ - Web API

IDBObjectStore: name プロパティ
==========================

`IDBObjectStore` インターフェイスの **`name`** プロパティは、このオブジェクトストアの名前を表します。

**注:** この機能は Web Worker 内で利用可能です

値
-

このオブジェクトストアの名前を表す文字列です。

### 例外

オブジェクトストアの名前を変更しようとすると、以下の例外が発生する可能性があります。

`InvalidStateError` `DOMException`

オブジェクトストアが削除済か、現在のトランザクションがアップグレードトランザクションでないとき投げられます。インデックスの名前の変更はアップグレードトランザクション (`versionchange` モード) でのみ可能です。

`TransactionInactiveError` `DOMException`

現在のトランザクションが実行中でないとき投げられます。

`ConstraintError` `DOMException`

オブジェクトストアで既に指定された `name` が使用中のとき投げられます。

例
-

以下のコード断片では、データベースの読み書きトランザクションを開き、`add()` を用いてデータをオブジェクトストアに追加します。オブジェクトストアの生成後、コンソールに `objectStore.name` を記録します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

```js
// データベースを開く
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>データベースを初期化しました。</li>";

  // データベースを開いた結果を変数 db に格納する
  // これは後でよく使う
  db = DBOpenRequest.result;

  // addData() 関数を実行し、データをデータベースに追加する
  addData();
};

function addData() {
  // IDB に挿入できる新しいオブジェクトを生成する
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // 読み書きトランザクションを開き、データを追加する準備をする
  const transaction = db.transaction(["toDoList"], "readwrite");

  // すべて完了し、トランザクションが正常終了したら報告する
  transaction.oncomplete = (event) => {
    note.innerHTML += "<li>トランザクションが完了しました。</li>";
  };

  transaction.onerror = (event) => {
    note.innerHTML +=
      "<li>トランザクションはエラーのため開けませんでした。アイテムは重複させられません。</li>";
  };

  // トランザクション上でオブジェクトストアを生成する
  const objectStore = transaction.objectStore("toDoList");
  console.log(objectStore.name);

  // オブジェクトストアに newItem オブジェクトを追加する要求を行う
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // 要求の成功を報告する
    note.innerHTML += "<li>要求に成功しました。</li>";
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-name① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: getAllKeys() メソッド - Web API

IDBObjectStore: getAllKeys() メソッド
=================================

`IDBObjectStore` インターフェイスの `getAllKeys()` メソッドは、オブジェクトストア内の指定の引数にマッチするすべてのオブジェクトに対応するレコードキー、もしくは引数が与えられない場合はすべてのオブジェクトに対応するレコードキーを取得する `IDBRequest` を返します。

値が正常に見つかった場合は、その構造化複製を作成し、要求オブジェクトの `result` に設定します。

このメソッドは、以下の場合に同じ結果になります。

* レコードがデータベースに存在しない場合
* レコードの値が `undefined` の場合

これらを区別するには、`openCursor()` を同じキーで呼ぶ必要があります。このメソッドは、レコードが存在すればカーソルを返し、存在しなければカーソルを返しません。

構文
--

```js
getAllKeys()
getAllKeys(query)
getAllKeys(query, count)
```

### 引数

`query` 省略可

`IDBKeyRange` またはそれに解決される値です。

`count` 省略可

複数の値が見つかったときに返す値の数を指定します。`0` 未満や `2^32 - 1` 超の場合は、`TypeError` 例外が投げられます。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は与えられた問い合わせにマッチする全レコード (`count` が指定された場合は `count` の数まで) のキーの `Array` になります。

### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

与えられたキーまたはキー範囲が無効なキーを含むか `null` であるとき投げられます。

`InvalidStateError` `DOMException`

`IDBObjectStore` が削除されたか取り除かれたとき投げられます。

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-getallkeys① |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)


IDBObjectStore: openCursor() メソッド - Web API

IDBObjectStore: openCursor() メソッド
=================================

`IDBObjectStore` インターフェイスの **`openCursor()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで新しい `IDBCursorWithValue` オブジェクトを返します。カーソルを用いてオブジェクトストアを走査するのに用います。

追加を行う操作が正常に完了したかを判定するには、結果の `success` イベントを監視してください。

**注:** この機能は Web Worker 内で利用可能です

構文
--

```js
openCursor()
openCursor(query)
openCursor(query, direction)
```

### 引数

`query` 省略可

問い合わせを行うキーまたは `IDBKeyRange` です。単一の有効なキーが渡された場合は、そのキーのみを含む範囲になります。何も渡されない場合は、オブジェクトストア内の全レコードを選択するキー範囲になります。

`direction` 省略可

カーソルが動く方向を決める文字列です。デフォルトは `next` です。以下の値が有効です。

`next`

カーソルはオブジェクトストアの最初で開き、キーの昇順で重複を含むすべてのレコードを返します。

`nextunique`

カーソルはオブジェクトストアの最初で開き、キーの昇順で重複を除いたすべてのレコードを返します。

`prev`

カーソルはオブジェクトストアの最初で開き、キーの降順で重複を含むすべてのレコードを返します。

`prevunique`

カーソルはオブジェクトストアの最初で開き、キーの降順で重複を除いたすべてのレコードを返します。

### 返値

この操作に関係する今後のイベントが発火する `IDBRequest` オブジェクトです。

操作に成功した場合は、この要求の `result` プロパティの値は以下になります。

* 与えられたクエリーにマッチする最初のレコードを指す `IDBCursorWithValue` オブジェクト
* マッチするレコードが見つからなかった場合は `null`
### 例外

このメソッドは、以下の種類のいずれかの `DOMException` を投げる可能性があります。

`InvalidStateError` `DOMException`

この `IDBObjectStore` または `IDBIndex` が削除済のとき投げられます。

`TransactionInactiveError` `DOMException`

この `IDBObjectStore` のトランザクションが実行中でないとき投げられます。

`DataError` `DOMException`

指定されたキーまたはキー範囲が無効であるとき投げられます。

例
-

以下のシンプルな断片では、トランザクションを生成し、オブジェクトストアを取得し、カーソルを用いてオブジェクトストア内の全レコードを走査します。

```js
const transaction = db.transaction("name", "readonly");
const objectStore = transaction.objectStore("name");
const request = objectStore.openCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    // cursor.value に走査中の現在のレコードが入っている
    // ここで結果を用いて何かする
    cursor.continue();
  } else {
    // もう結果は無い
  }
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-opencursor② |

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

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

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キー範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)