MediaSession.setActionHandler() - Web API

MediaSession.setActionHandler()
===============================

**`setActionHandler()`** は `MediaSession` インターフェイスのメソッドで、メディアセッションのアクションにハンドラーを設定します。
 これらのアクションは、ユーザーが端末に内蔵された物理的または画面上のメディアコントロール（再生、停止、シークボタンなど）を操作したときに、ウェブアプリケーションが通知を受け取ることができます。

構文
--

```js
setActionHandler(type, callback)
```

### 引数

`type`

待ち受けするアクションの種類を表す文字列です。これは、次のいずれかになります。

`hangup`

通話を終了します。

`nextslide`

スライドデッキを表示しているときに、次のスライドに移動します。

`nexttrack`

再生を次のトラックに進めます。

`pause`

メディアの再生を一時停止します。

`play`

メディアの再生を始めます（または再開します）。

`previousslide`

スライドデッキを表示しているときに、前回表示したスライドに移動します。

`previoustrack`

前のトラックに戻します。

`seekbackward`

 メディアの中で、現在位置から後方にシークします。
 コールバックに渡す `seekOffset` プロパティは、後方へのシーク時間を指定します。

`seekforward`

 メディアの中で、現在の位置から前方にシークします。
 コールバックに渡す `seekOffset` プロパティは、前方へのシーク時間を指定します。

`seekto`

 メディア内の指定した時刻に再生位置を移動します。
 シーク先の時刻は、コールバックに渡される `seekTime` プロパティで指定します。
 複数の `seekto` 操作を連続して行う場合は、コールバックに渡される `fastSeek` プロパティに `true` という値を指定することも可能です。
 これにより、ブラウザーは繰り返される処理を最適化するための手順を踏むことができ、パフォーマンスが向上する可能性が高くなることを知ることができます。

`skipad`

 現在再生中の広告や CM をスキップして通過します。
 この操作は、プラットフォームやユーザーエージェントによって利用できる場合とできない場合があり、また、契約レベルや他にも状況によって無効となる場合があります。

`stop`

再生を完全に停止します。

`togglecamera`

ユーザーのアクティブなカメラをオンまたはオフにします。

`togglemicrophone`

ユーザーのマイクをミュート/ミュート解除します。

`callback`

指定したアクション種別を呼び出したときに呼び出す関数です。コールバックは値を返してはいけません。コールバックは、以下のプロパティを格納した辞書を受け取ります。

`action`

アクションの種類を表す文字列です。このプロパティにより、単一のコールバックで複数のアクションの種類を処理することができます。

`fastSeek` 省略可

`seekto` アクションは、このプロパティをオプションとして含めることができます。このプロパティは、「高速」シークを実行するかどうかを示す論理値です。
 高速」シークとは、メディアを早送りしたり、反転させたりするときに、急速にスキップするように、シークが実行されることです。
 このプロパティは、メディアをシークするために使用可能な最短の方法を使用することを示すために使用することができます。
 この状況では、`fastSeek` はシークシーケンスの最終アクションに含まれません。

`seekOffset` 省略可

 アクションが `seekforward` または `seekbackward` で、このプロパティが存在する場合、再生位置を前方または後方に移動するための秒数を示す浮動小数点の値です。
 このプロパティが存在しない場合、これらのアクションは、前方または後方にスキップするための妥当な既定値（7 秒または 10 秒など）を選ぶ必要があります。

`seekTime` 省略可

アクションが `seekto` の場合、このプロパティが存在しなければなりません。このプロパティは、メディア内で再生位置を移動する絶対時刻を示す浮動小数点数で、0はメディアの開始時刻を示します。このプロパティは、他のアクション種別には存在しません。

### 返値

なし (`undefined`)。

解説
--

以前に確立したアクションハンドラーを削除するには、`setActionHandler()` を再度呼び出して、`callback` に `null` を指定します。

アクションハンドラーは単一の引数として、アクションの種類（同じ関数で複数のアクションを処理することができる）と、アクションを実行するために必要なデータを提供するオブジェクトを入力として受け取ります。

例
-

### 音楽プレイヤーのアクションハンドラーを設定

この例では、新しいメディアセッションを作成し、アクションハンドラー（何かするわけではありません）を割り当てています。

```js
if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Unforgettable",
    artist: "Nat King Cole",
    album: "The Ultimate Collection (Remastered)",
    artwork: [
      {
        src: "https://dummyimage.com/96x96",
        sizes: "96x96",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/128x128",
        sizes: "128x128",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/192x192",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/256x256",
        sizes: "256x256",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/384x384",
        sizes: "384x384",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/512x512",
        sizes: "512x512",
        type: "image/png",
      },
    ],
  });

  navigator.mediaSession.setActionHandler("play", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("pause", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("stop", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("seekbackward", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("seekforward", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("seekto", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("previoustrack", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("nexttrack", () => {
    /\* Code excerpted. \*/
  });
  navigator.mediaSession.setActionHandler("skipad", () => {
    /\* Code excerpted. \*/
  });
}
```

次の例では、再生と一時停止のための 2 つの関数を設定し、関連するアクションハンドラーのコールバックとして使用しています。

```js
const actionHandlers = [
  // play
  [
    "play",
    async () => {
      // play our audio
      await audioEl.play();
      // set playback state
      navigator.mediaSession.playbackState = "playing";
      // update our status element
      updateStatus(allMeta[index], "Action: play | Track is playing…");
    },
  ],
  [
    "pause",
    () => {
      // pause out audio
      audioEl.pause();
      // set playback state
      navigator.mediaSession.playbackState = "paused";
      // update our status element
      updateStatus(allMeta[index], "Action: pause | Track has been paused…");
    },
  ],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}
```

この例では、適切なアクションハンドラーを使用し、再生メディアを通してどちらかの方向にシークできるようにしています。

```js
let skipTime = 10; // Time to skip in seconds

navigator.mediaSession.setActionHandler("seekbackward", (evt) => {
  // User clicked "Seek Backward" media notification icon.
  audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

navigator.mediaSession.setActionHandler("seekforward", (evt) => {
  // User clicked "Seek Forward" media notification icon.
  audio.currentTime = Math.min(audio.currentTime + skipTime, audio.duration);
});
```

メディアアクションハンドラーを削除する場合は、null を割り当ててください。

```js
navigator.mediaSession.setActionHandler("nexttrack", null);
```

### 1 つのハンドラー関数で複数のアクションに対応

また、必要に応じて、`action` プロパティの値を調べることで、1 つの関数を使用して複数のアクション種類を処理することも可能です。

```js
let skipTime = 7;

navigator.mediaSession.setActionHandler("seekforward", handleSeek);
navigator.mediaSession.setActionHandler("seekbackward", handleSeek);

function handleSeek(details) {
  switch (details.action) {
    case "seekforward":
      audio.currentTime = Math.min(
        audio.currentTime + skipTime,
        audio.duration,
      );
      break;
    case "seekbackward":
      audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
      break;
  }
}
```

ここでは、`handleSeek()`関数が`seekbackward`と`seekforward`の両方のアクションを処理します。

### アクションハンドラーを使用してスライドプレゼンテーションを制御する

アクションハンドラー `"previousslide"` と `"nextslide"` を使用すると、例えば、ユーザーがプレゼンテーションを Picture-in-Picture ウィンドウに入れ、ブラウザーの提供するスライド移動用のコントロールを押すことで、スライドプレゼンテーションを前に進めたり後ろに戻したりすることを扱うことができます。

```js
try {
  navigator.mediaSession.setActionHandler("previousslide", () => {
    log('> User clicked "Previous Slide" icon.');
    if (slideNumber > 1) slideNumber--;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "previousslide" media session action is not supported.');
}

try {
  navigator.mediaSession.setActionHandler("nextslide", () => {
    log('> User clicked "Next Slide" icon.');
    slideNumber++;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "nextslide" media session action is not supported.');
}
```

動作する例としては、Presenting Slides / Media Session Sampleを参照してください。

仕様書
---

| Specification |
| --- |
| Media Session # dom-mediasession-setactionhandler |

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

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


CSSFontFaceRule.style - Web API

CSSFontFaceRule.style
=====================

**`style`** は `CSSFontFaceRule` インターフェイスの読み取り専用プロパティで、この `@font-face` アットルールからスタイル情報を返します。これは `CSSStyleDeclaration` オブジェクトの形です。

値
-

`CSSStyleDeclaration` です。

例
-

この例では、 `@font-face` ページに例として挙げられている CSS を使用しています。最初に返される `CSSRule` は `CSSFontFaceRule` となります。 `style` プロパティは `CSSStyleDeclaration` を返し、`fontFamily`, `fontWeight`, `src` プロパティにはルールの情報が現れます。

```css
@font-face {
  font-family: MyHelvetica;
  src: local("Helvetica Neue Bold"), local("HelveticaNeue-Bold"),
    url(MgOpenModernaBold.ttf);
  font-weight: bold;
}
```

```js
let myRules = document.styleSheets[0].cssRules;
console.log(myRules[0].style); //a CSSStyleDeclaration
```

仕様書
---

| Specification |
| --- |
| CSS Fonts Module Level 4 # dom-cssfontfacerule-style |

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

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


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

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

このコンストラクターは、合成した `DragEvent` オブジェクトを作成するために使用します。

このインターフェイスにはコンストラクターがありますが、有用な `DataTransfer` オブジェクトは、ドラッグ＆ドロップの際にブラウザーが調整する処理とセキュリティモデルを持っているので、スクリプトから作成することはできません。

このインターフェイスは、 `MouseEvent` および `Event` のプロパティを継承しています。

構文
--

```js
new DragEvent(type)
new DragEvent(type, dragEventInit)
```

### 引数

`type`

イベント名を表す文字列です（DragEvent のイベントの種類を参照）。

`dragEventInit` 省略可

`DragEventInit` 辞書で、以下のフィールドがあります。

* `"dataTransfer"`: オプションで既定値は `"null"` です。型は `DataTransfer` です。

`DragEventInit` 辞書は MouseEventInit 辞書から継承しています。

仕様書
---

| Specification |
| --- |
| HTML Standard # the-dragevent-interface |

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

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


DragEvent: dataTransfer プロパティ - Web API

DragEvent: dataTransfer プロパティ
=============================

**`DragEvent.dataTransfer`** プロパティは、ドラッグ操作のデータを（`DataTransfer` オブジェクトとして）保持します。

このプロパティは 読取専用  です。

値
-

`DataTransfer` オブジェクトで、ドラッグイベントのデータが入ります。

例
-

この例では、 `dragend` イベントハンドラーの中でドラッグ＆ドロップデータへアクセスする方法を説明します。

```js
function processData(d) {
  // データを処理...
}

dragTarget.addEventListener(
  "dragend",
  (ev) => {
    // ドラッグ＆ドロップのデータ処理を呼び出す
    if (ev.dataTransfer !== null) processData(ev.dataTransfer);
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-dragevent-datatransfer-dev |

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

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


HTMLLabelElement: form プロパティ - Web API

HTMLLabelElement: form プロパティ
============================

**`HTMLLabelElement.form`** は読み取り専用のプロパティで、このラベルに関連付けられたコントロールが所属するフォームを表す `HTMLFormElement` オブジェクトを返します。関連付けられたコントロールがないか、そのコントロールがフォーム内にない場合は null を返します。

このプロパティは `HTMLLabelElement.control.form` のショートカットです。

値
-

`HTMLFormElement` で、このラベルの `control` が関連付けられたフォームを表します。もし `control` が `null` （すなわちラベルがコントロールと関連付けられていない）であるか、コントロールがフォームの一部でない場合、このプロパティは `null` を返します。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-label-form-dev |

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

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

関連情報
----

* `HTMLLabelElement`
* `HTMLElement`
* `<label>`
* HTML フォームガイド


HTMLLabelElement: control プロパティ - Web API

HTMLLabelElement: control プロパティ
===============================

**`HTMLLabelElement.control`** は読み取り専用プロパティで、この `<label>` 要素に関連付けられているコントロールへの参照（`HTMLElement` 型のオブジェクトまたはその派生物のうちの 1 つ）を返します。ラベルがコントロールと関連付けられていない場合は `null` を返します。

値
-

`HTMLElement` の派生オブジェクトで、この `<label>` が関連付けられているコントロールを表します。ラベルが孤立している場合は `null` になります。

**メモ:** このプロパティに値があり、 `HTMLLabelElement.htmlFor` に値がある場合、 `HTMLLabelElement.htmlFor` プロパティは必ず同じコントロールを参照します。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-label-control-dev |

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

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

関連情報
----

* `HTMLLabelElement`
* `HTMLElement`
* `<label>`
* HTML フォームガイド


HTMLLabelElement: htmlFor プロパティ - Web API

HTMLLabelElement: htmlFor プロパティ
===============================

**`HTMLLabelElement.htmlFor`** プロパティは `for` コンテンツプロパティの値を反映します。つまり、このスクリプトでアクセス可能なプロパティは、ラベルに関連付けられたコントロール要素の ID である `for` コンテンツプロパティの値を設定したり読み取ったりするために使用されます。

値
-

文字列で、このコントロールに関連する要素の ID 文字列が入ります。

**メモ:** このプロパティに値がある場合 `HTMLLabelElement.control` プロパティも同じコントロールになります。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-label-htmlfor |

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

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

関連情報
----

* `HTMLLabelElement`
* `HTMLLabelElement.control`
* `HTMLElement`
* `<label>`
* HTML フォームガイド


AbstractRange: collapsed プロパティ - Web API

AbstractRange: collapsed プロパティ
==============================

**`collapsed`** は `AbstractRange` インターフェイスの読み取り専用プロパティで、範囲の開始位置と終了位置が同じであれば `true` を返します。

値
-

論理値で、範囲が折りたたまれている場合に `true` となります。折りたたまれた範囲とは、開始位置と終了位置が同じで、 0 文字の長さの範囲です。

例
-

```js
let isCollapsed = range.collapsed;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-collapsed① |

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

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


AbstractRange: startContainer プロパティ - Web API

AbstractRange: startContainer プロパティ
===================================

**`startContainer`** は `AbstractRange` インターフェイスの読み取り専用プロパティで、範囲の先頭の `Node` を返します。

値
-

範囲の開始位置が内部にある `Node` です。

例
-

```js
let startNode = range.startContainer;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startcontainer① |

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

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


AbstractRange: startOffset プロパティ - Web API

AbstractRange: startOffset プロパティ
================================

**`startOffset`** は `AbstractRange` インターフェイスの読み取り専用プロパティで、開始ノードにおける範囲の開始位置のオフセットを返します。

値
-

範囲の最初の文字が位置を `startContainer` が示す `Node` 内の文字数で示す整数値です。

例
-

```js
let startOffset = range.startOffset;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startoffset① |

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

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


AbstractRange: endOffset プロパティ - Web API

AbstractRange: endOffset プロパティ
==============================

**`endOffset`** は `AbstractRange` インターフェイスの読み取り専用プロパティで、範囲の終了位置の最後のノードの中のオフセットを返します。

値
-

範囲の最後の文字が位置する `endContainer` が示す `Node` 内の文字数を示す整数値です。

例
-

```js
let endOffset = range.endOffset;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endoffset① |

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

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


AbstractRange: endContainer プロパティ - Web API

AbstractRange: endContainer プロパティ
=================================

**`endContainer`** は `AbstractRange` インターフェイスの読み取り専用プロパティで、範囲の末尾がある `Node` を返します。

値
-

範囲の最後の文字を含む `Node` です。

例
-

```js
let endNode = range.endContainer;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endcontainer① |

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

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


PerformanceElementTiming: renderTime プロパティ - Web API

PerformanceElementTiming: renderTime プロパティ
==========================================

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

**`renderTime`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、関連付けられた要素の描画時刻を返します。

値
-

その要素の描画時間を表す `DOMHighResTimeStamp` です。

画像の場合、これは**画像の描画タイムスタンプ**になります。これは画像が完全に読み込まれた後に発生する次のペイントとして定義されます。Timing-allow-origin ヘッダーによって定義されています。タイミング許可チェックが失敗した場合、これは `0` を返します。

テキストノードの場合、これは **テキスト描画タイムスタンプ** になります。これは、要素にテキストが描画されるようになったタイミングを定義します。

例
-

### `renderTime` のログ出力

この例では、`elementtiming` 属性を追加して `<image>` 要素を監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを用います。 `entry.renderTime` を呼び出すと、画像要素のレンダリング時刻を返します。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.renderTime);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

### オリジンを跨いだ画像の描画時刻

セキュリティ上の理由から、リソースがオリジン間リクエストである場合、 `renderTime` プロパティの値は `0` です。オリジン間のレンダリング時刻情報を公開するには、`Timing-Allow-Origin` HTTP レスポンスヘッダーを設定する必要があります。HTTP レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` で `renderTime` が見られるようにするには、オリジン間リソースは次のように送信します。

```http
Timing-Allow-Origin: https://developer.mozilla.org
```

別の方法として、 `startTime` を使用することもできます。この場合、項目の `renderTime` の値が `0` でなければその値を返し、そうでなければこの項目の `loadTime` の値を返します。ただし、指標をより正確なものにするために、 `Timing-Allow-Origin` ヘッダーを設定することをお勧めします。

`startTime` を使用した場合、`renderTime` が使用されたかどうかを調べることで、不正確さにフラグを立てることができます。

```js
const isRenderTime = entry.renderTime ? true : false;
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-rendertime① |

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

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


PerformanceElementTiming: loadTime プロパティ - Web API

PerformanceElementTiming: loadTime プロパティ
========================================

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

**`loadTime`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、テキストに対しては常に `0` を返します。画像については画像リソースが読み込まれてから要素に装着されるまでの時間を返します。

値
-

`DOMHighResTimeStamp` で、この要素の `loadTime` です。テキストに対しては `0` です。

例
-

### `loadTime` をログ出力

この例では `<img>` 要素に `elementtiming` 属性を追加して監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録されます。オブザーバーが作成される前のデータにアクセスするには `buffered` フラグを使用します。 `entry.loadTime` を呼び出すと、画像要素の読み込み時間を返します。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.loadTime);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-loadtime① |

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

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


PerformanceElementTiming: toJSON() メソッド - Web API

PerformanceElementTiming: toJSON() メソッド
=======================================

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

**`toJSON()`** は `PerformanceElementTiming` インターフェイスのメソッドで、シリアライザーです。 `PerformanceElementTiming` オブジェクトの JSON 表現を返します。

構文
--

```js
toJSON()
```

### 引数

なし。

### 返値

`JSON` オブジェクトです。これは、 `PerformanceElementTiming` オブジェクトをシリアライズしたものです。

JSON には `element` プロパティが格納されませんが、これが `Element` 型の一種であり、`toJSON()` 操作を提供していないからです。しかし、要素の `id` は提供されます。

例
-

### toJSON メソッドの使用

この例では、`entry.toJSON()` を呼び出すと、画像要素の情報を含む `PerformanceElementTiming` オブジェクトの JSON 表現が返されます。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.toJSON());
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

This would log a JSON object like so:

```json
{
  "name": "image-paint",
  "entryType": "element",
  "startTime": 670894.1000000238,
  "duration": 0,
  "renderTime": 0,
  "loadTime": 670894.1000000238,
  "intersectionRect": {
    "x": 299,
    "y": 76,
    "width": 135,
    "height": 155,
    "top": 76,
    "right": 434,
    "bottom": 231,
    "left": 299
  },
  "identifier": "big-image",
  "naturalWidth": 135,
  "naturalHeight": 155,
  "id": "myImage",
  "url": "https://en.wikipedia.org/static/images/project-logos/enwiki.png"
}
```

JSON 文字列を取得するには、 `JSON.stringify(entry)` を直接使用することができます。これが `toJSON()` を自動的に呼び出します。

仕様書
---

| Specification |
| --- |
| Element Timing API # dom-performanceelementtiming-tojson |

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

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

関連情報
----

* `JSON`


PerformanceElementTiming: intersectionRect プロパティ - Web API

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

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

**`intersectionRect`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、ビューポート内の要素の矩形を返します。

値
-

`DOMRectReadOnly` で、ビューポートにおけるこの要素の矩形を表します。

表示画像の場合、これはビューポート内の画像の表示矩形です。テキストの場合、これはビューポート内のノードの表示矩形です。これは、要素に属するすべてのテキストノードを結合したものを格納する最小の長方形です。

例
-

### `intersectionRect` の出力

この例では、 `elementtiming` 属性を追加して `<img>` 要素を監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを用います。 `entry.intersectionRect` を呼び出すと、画像の表示矩形を持つ `DOMRectReadOnly` オブジェクトが返されます。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.intersectionRect);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-intersectionrect |

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

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


PerformanceElementTiming: identifier プロパティ - Web API

PerformanceElementTiming: identifier プロパティ
==========================================

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

**`identifier`** は `PerformanceElementTiming` インターフェイスの読み取り専用のプロパティで、その要素の `elementtiming` 属性の値を返します。

値
-

文字列です。

例
-

### `identifier` の使用

この例では、`elementtiming` 属性を追加して `<img>` 要素を監視しています。 `PerformanceObserver` は `"要素"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを用います。`elementtiming` の値は `big-image` です。したがって `entry.identifier` を呼び出すと文字列 `big-image` を返します。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.naturalWidth);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-identifier |

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

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


PerformanceElementTiming: naturalHeight プロパティ - Web API

PerformanceElementTiming: naturalHeight プロパティ
=============================================

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

**`naturalHeight`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、画像要素の内在的な高さを返します。

値
-

符号なし 32 ビット整数 (unsigned long) です。 これが画像に適用されている場合は画像の内在的な高さを表し、テキストの場合は `0` となります。

例
-

### `naturalHeight` のログ出力

この例では、`elementtiming` 属性を追加して `<image>` 要素を監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを使用しています。画像ファイルの幅は 1000px、高さは 750px あります。 `entry.naturalHeight` を呼び出すと、ピクセル単位の内在的な高さである `750` を返します。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.naturalHeight);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-naturalheight |

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

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


PerformanceElementTiming: naturalWidth プロパティ - Web API

PerformanceElementTiming: naturalWidth プロパティ
============================================

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

**`naturalWidth`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、画像要素の内在的な幅を返します。

値
-

符号なし 32 ビット整数 (unsigned long) です。 これが画像に適用されている場合は画像の内在的な幅を表し、テキストの場合は `0` となります。

例
-

### `naturalWidth` のログ出力

この例では、`elementtiming` 属性を追加して `<image>` 要素を監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを使用しています。画像ファイルの幅は 1000px、高さは 750px あります。 `entry.naturalWidth` を呼び出すと、ピクセル単位の内在的な幅である `1000` を返します。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.naturalWidth);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-naturalwidth |

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

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


PerformanceElementTiming: url プロパティ - Web API

PerformanceElementTiming: url プロパティ
===================================

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

**`url`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、要素が画像の場合、リソースのリクエストの初期 URL を返します。

値
-

画像の場合はリソースリクエストの初期 URL となる文字列、テキストの場合は `0` となります。

例
-

### `url` をログ出力

この例では、 `elementtiming` 属性を追加して `<img>` 要素を監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグを用います。 `entry.url` を呼び出すと `https://example.com/image.jpg` が返されます。

```html
<img
 src="https://example.com/image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.url);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-url |

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

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


PerformanceElementTiming: id プロパティ - Web API

PerformanceElementTiming: id プロパティ
==================================

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

**`id`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、関連付けられた要素の `id` を返します。

値
-

文字列です。

例
-

### `id` の使用

この例では`<img>`要素に`elementtiming`属性を追加して監視しています。 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグが使用されます。これはコンソールに `myImage` とログ出力します。これは画像要素の `id` です。

```html
<img
 src="image.jpg"
 alt="a nice image"
 elementtiming="big-image"
 id="myImage" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.id);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-id |

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

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


PerformanceElementTiming: element プロパティ - Web API

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

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

**`element`** は `PerformanceElementTiming` インターフェイスの読み取り専用プロパティで、監視されている要素へのポインターである `Element` を返します。

値
-

`Element` です。または、要素がシャドウ DOM の要素である場合は `null` です。

例
-

### 監視対象の要素のログ出力

この例では、 `elementtiming` 属性を追加して `<img>` 要素を監視しています。また、 `PerformanceObserver` は `"element"` 型のパフォーマンス項目をすべて取得するために登録され、オブザーバー作成前のデータにアクセスするために `buffered` フラグが使用されます。監視された DOM 要素はコンソールにログ出力されます。

```html
<img src="image.jpg" alt="a nice image" elementtiming="big-image" />
```

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.identifier === "big-image") {
      console.log(entry.element);
    }
  });
});
observer.observe({ type: "element", buffered: true });
```

仕様書
---

| Specification |
| --- |
| Element Timing API # ref-for-dom-performanceelementtiming-element |

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

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


DOMMatrixReadOnly: flipX() メソッド - Web API

DOMMatrixReadOnly: flipX() メソッド
===============================

`flipX()` は `DOMMatrixReadOnly` インターフェイスのメソッドで、元の行列を X 軸で反転させた新しい行列を作成します。

構文
--

```js
  DOMMatrixReadOnly.flipX()
```

### 返値

元の行列を X 軸で反転した結果である新しい行列を含む `DOMMatrix` を返します。これは、行列に `DOMMatrix(-1, 0, 0, 1, 0, 0)` を乗算することと等価です。元の行列は変更されません。

例
-

### 三角形の反転

この例では、 SVG に三角形の図形を持つ2つのパスが格納されており、どちらも同じ位置に描画されています。なお、 viewBox 属性の x 座標が負であり、 x 軸の両辺からのコンテンツを表示されます。

JavaScript は最初に単位行列を作成し、次に `flipX()` メソッドを使って新しい行列を作成し、それを青い三角形に用いて X 軸を反転させています。赤い三角形はその場に残ります。

#### HTML

```html
<svg width="100" height="100" viewBox="-50 0 100 100">
  <path fill="red" d="M 0 50 L 50 0 L 50 100 Z" />
  <path id="flipped" fill="blue" d="M 0 50 L 50 0 L 50 100 Z" />
</svg>
```

#### JavaScript

```js
const flipped = document.getElementById("flipped");
const matrix = new DOMMatrixReadOnly();
const flippedMatrix = matrix.flipX();
flipped.setAttribute("transform", flippedMatrix.toString());
```

#### 結果

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dommatrixreadonly-flipx |

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

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


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

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

**`DOMMatrixReadOnly`** コンストラクターは新しい `DOMMatrixReadOnly` オブジェクトを作成します。このオブジェクトは 4x4 行列を表し、 2D および 3D の演算に適しています。

構文
--

```js
DOMMatrixReadOnly()
DOMMatrixReadOnly(init)
```

### 引数

`init` 省略可

作成したい行列を指定する、数値の並びを格納した文字列、または数値の配列です。

数値の配列が渡された場合の動作は、配列の長さに依存します。

* `[a, b, c, d, e, f]` という形で構成される 6 要素の配列を指定すると，指定された成分で初期化された 2D の読み取り専用の行列が作成されます．
* `[m11, m12, m13, …, m42, m43, m44]` という形で構成される 16 要素の配列（列優先順）に対して、指定された要素で初期化された 3D の読み取り専用の行列が作成されます。

仕様書
---

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

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

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


DOMMatrixReadOnly: scale() メソッド - Web API

DOMMatrixReadOnly: scale() メソッド
===============================

**`scale()`** は `DOMMatrixReadOnly` インターフェイスのメソッドで、 元の行列に拡大縮小変換を施した新しい行列を作成します。

構文
--

`scale()` メソッドには 1 つから 6 つの値を指定します。

```js
DOMMatrixReadOnly.scale(scaleX);
DOMMatrixReadOnly.scale(scaleX, scaleY);
DOMMatrixReadOnly.scale(scaleX, scaleY, scaleZ);
DOMMatrixReadOnly.scale(scaleX, scaleY, scaleZ, originX);
DOMMatrixReadOnly.scale(scaleX, scaleY, scaleZ, originX, originY);
DOMMatrixReadOnly.scale(scaleX, scaleY, scaleZ, originX, originY, originZ);
```

### 引数

`scaleX`

X 軸の拡大縮小する値の倍率。

`scaleY` 省略可

Y 軸の拡大縮小する値の倍率。省略した場合は `scaleX` の値が既定値となります。

`scaleZ` 省略可

z 軸の拡大縮小する値の倍率。この値が 1 以外の場合、結果の行列は 3D になります。

`originX` 省略可

変換の原点の x 座標。原点が与えられなかった場合、既定値は 0 です。

`originY` 省略可

変換の原点の y 座標。原点が与えられなかった場合、既定値は 0 です。

`originZ` 省略可

変換の原点の z 座標。原点が与えられなかった場合、既定値は 0 です。この値が 0 以外の場合、結果の行列は 3D になります。

### 返値

行列の x と y を指定された係数で拡大縮小し、指定された原点を中心とした新しい行列を格納した `DOMMatrix` を返します。元の行列は変更されません。

z 軸を中心に拡大縮小すると、 4✕4 の 3D 行列になります。

例
-

この SVG には赤、青、緑の 3 つの正方形があり、それぞれ文書の原点に配置されています。

```html
<svg width="250" height="250" viewBox="0 0 25 25">
  <rect width="25" height="25" fill="red" />
  <rect id="transformed" width="25" height="25" fill="blue" />
  <rect id="transformedOrigin" width="25" height="25" fill="green" />
</svg>
```

この JavaScript では最初に単位行列を作成し、次に `scale()` メソッドを使用して単一の引数を持つ新しい行列を作成します。

3 つの引数を使用して新しい行列を作成し、その `is2D` プロパティを監視することで、そのブラウザーが 6 つの引数の `scale()` メソッドに対応しているかどうかをテストします。これが `false` ならば、 3 つ目の引数は `scaleZ` 引数としてブラウザーに受け入れられ、これは 3D 行列となります。

次に、ブラウザーの対応に応じて、 3 つまたは 6 つの引数を使用して、指定された原点に対して拡大縮小された新しい行列を作成します。

これらの新しい行列は `transform` として青と緑の正方形に適用され、寸法と位置が変更されます。赤い正方形はそのままの位置に配置されます。

```js
const matrix = new DOMMatrixReadOnly();
const scaledMatrix = matrix.scale(0.5);

let scaledMatrixWithOrigin = matrix.scale(0.5, 25, 25);

// ブラウザーがこれらの引数を scaleX, scaleY, scaleZ と解釈した場合、結果の行列は 3D になります。
const browserExpectsSixParamScale = !scaledMatrixWithOrigin.is2D;
if (browserExpectsSixParamScale) {
  scaledMatrixWithOrigin = matrix.scale(0.5, 0.5, 1, 25, 25, 0);
}

document
  .querySelector("#transformed")
  .setAttribute("transform", scaledMatrix.toString());
document
  .querySelector("#transformedOrigin")
  .setAttribute("transform", scaledMatrixWithOrigin.toString());
```

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dommatrixreadonly-scale |

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

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


DOMMatrixReadOnly: translate() メソッド - Web API

DOMMatrixReadOnly: translate() メソッド
===================================

`translate()` は `DOMMatrixReadOnly` インターフェイスのメソッドで、元の行列を平行移動させた結果の新しい行列を作成します。

構文
--

```js
DOMMatrix.translate(translateX, translateY)
DOMMatrix.translate(translateX, translateY, translateZ)
```

### 引数

`translateX`

平行移動させるベクトルの横軸（x 座標）を表す数値です。

`translateY`

平行移動させるベクトルの縦軸（y 座標）を表す数値です。

`translateZ` 省略可

平行移動させるベクトルの z 成分を表す数値です。指定されなかった場合の既定値は 0 になります。 0 以外の数値であった場合、結果の行列は 3D になります。

### 返値

行列を指定されたベクトルで平行移動させた結果の新しい行列を格納した `DOMMatrix` を返します．元の行列は変更されません．

平行移動が Z 軸について適用された場合、結果の行列は 4x4 の 3D 行列になります。

例
-

この SVG には赤と青の 2 つの正方形が格納されており、それぞれが文書の原点に配置されています。

```html
<svg width="250" height="250" viewBox="0 0 50 50">
  <rect width="25" height="25" fill="red" />
  <rect id="transformed" width="25" height="25" fill="blue" />
</svg>
```

以下の JavaScript では、まず単位行列を作成し、次に `translate()` メソッドを使用して新しい変換行列を作成し、それを `transform` として青い正方形に適用しています。赤い正方形はそのままの位置に配置されます。

```js
const matrix = new DOMMatrixReadOnly().translate(25, 25);

document
  .querySelector("#transformed")
  .setAttribute("transform", matrix.toString());
```

仕様書
---

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dommatrixreadonly-translate |

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

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


RTCPeerConnection() - Web API

RTCPeerConnection()
===================

**`RTCPeerConnection()`** コンストラクターは、ローカル端末とリモート端末間の接続を表す新しく作成された `RTCPeerConnection` を返します。

構文
--

```js
new RTCPeerConnection();
new RTCPeerConnection(configuration);
```

### 引数

`configuration` 省略可

新しい接続を構成するためのオプションを提供するオブジェクトです。

`bundlePolicy` 省略可

 リモートの相手が SDP BUNDLE 規格に対応していない場合に、候補の交渉を処理する方法を指定します。
 リモートのエンドポイントが BUNDLE に対応している場合、使用したポリシーに関わら ず、交渉の完了時にすべてのメディアトラックとデータチャネルが 1 つのトランスポートにバンドルされ、最初に作成された余分なトランスポートはその時点で閉じられます。

 技術的には、 BUNDLE は 2 つのピア間のすべてのメディアフローを単一の **5 タプル**に流すことができます。
 つまり、一方のピアの単一の IP とポートから、もう一方のピアの単一の IP とポートへ、同じトランスポートプロトコルを使用して流れます。

これは以下の文字列値のいずれかでなければならず、そうでない場合は `balanced` とみなされます。

`balanced`

 ICE エージェントは、最初に追加されたコンテンツの種類（音声、映像、データチャネル）ごとに 1 つの `RTCDtlsTransport` (en-US) を作成します。
 リモートエンドポイントがBUNDLEに対応していない場合、これらの DTLS トランスポートのそれぞれは、 1 つの種類のデータに対するすべての通信を処理します。

`max-compat`

 ICE エージェントは、最初にメディアトラックごとに 1 つの `RTCDtlsTransport` (en-US) を作成し、データチャンネル用に別のものを作成します。
 リモートエンドポイントが BUNDLE に対応していない場合、すべてはこれらの別々の DTLS トランスポート上で交渉されます。

`max-bundle`

 ICE エージェントは最初、 `RTCDtlsTransport` (en-US) のすべてのデータを運ぶために、単一の `RTCPeerConnection` のみを作成します。
 リモートエンドポイントが BUNDLE に対応していない場合、 1 つのトラックのみが交渉され、残りは無視されます。

`certificates` 省略可

 接続が認証に使用する `RTCCertificate` (en-US) 型のオブジェクトの `Array` です。
 このプロパティが指定されていない場合、資格情報のセットは各 `RTCPeerConnection` インスタンスに対して自動的に生成されます。
 1 つの接続で使用される資格情報は 1 つだけですが、複数のアルゴリズムに資格情報を提供することで、状況によっては接続に成功する確率が向上する場合があります。
 詳しくは、資格情報の使用を参照してください。

**メモ:** この構成オプションは、最初に指定した後は変更できません。いったん資格情報が設定されると、今後 `RTCPeerConnection.setConfiguration()` (en-US) を呼び出す際には、このプロパティは無視されます。

`iceCandidatePoolSize` 省略可

 先読みされる ICE 候補プールのサイズを指定する、符号なし 16 ビット整数値です。
 既定値は 0 （候補の先読みをしない）です。
 接続を試みる前に ICE エージェントに ICE 候補のフェッチを開始させ、 `RTCPeerConnection.setLocalDescription()` (en-US) が呼ばれたときにすでに検査できるようにすると、よりすばやく接続できるようになる場合があります。

**メモ:** ICE 候補者プールのサイズを変更すると、ICE の収集が開始されるきっかけとなる場合があります。

`iceServers` 省略可

 ICE エージェントが使用するサーバーを記述した `RTCIceServer` (en-US) オブジェクトの配列です。
 これらは通常、 STUN サーバーや TURN サーバーです。
 これが指定されていない場合、 STUN や TURN サーバーがない状態で接続が試みられ、ローカルピアーに接続が制限されます。

`iceTransportPolicy` 省略可

 現在の ICE トランスポートポリシー。
 ポリシーが指定されていない場合、既定で `all` とみなされ、すべての候補が考慮されるようになります。
 指定できる値は次のとおりです。

`"all"`

ICE の候補はすべて考慮されます。

`"public"`
非推奨

公開 IP アドレスを持つ ICE の候補のみが考慮されます。*仕様書の 2016 年 5 月 13 日の草稿から削除されました。*

`"relay"`

STUN や TURN サーバーを経由しているなど、 IP アドレスが中継されている ICE の候補のみが考慮されます。

`peerIdentity` 省略可

 文字列で、 `RTCPeerConnection` のターゲットピア ID を指定します。
 この値が設定されている場合（既定値は `null`）、 `RTCPeerConnection` は与えられた名前での認証に成功しない限り、リモートピアに接続しないようにします。

`rtcpMuxPolicy` 省略可

非多重 RTCP に対応するために、 ICE の候補を収集する際に使用する RTCP mux ポリシー。指定可能な値は以下のとおりです。

`negotiate`

 ICE エージェントに RTP (en-US) と RTCP (en-US) 候補の両方を収集するように指示します。
 リモートピアが RTCP を多重化できる場合、 RTCP 候補は、対応する RTP 候補の上に多重化されます。
 そうでない場合、 RTP と RTCP の両方の候補が別々に返されます。

`require`

 ICE エージェントに、 RTP のみの ICE 候補を収集し、その上に RTCP を多重化するように指示します。
 リモートピアーが RTCP の多重化に対応していない場合、セッション交渉は失敗します。
 これは既定値です。

### 返値

新しく作成された `RTCPeerConnection` オブジェクトで、 `configuration` が指定されていればその通りに設定され、そうでなければ適切な基本の既定値に設定されます。

### 資格情報の使用

`RTCPeerConnection` が自動的に資格情報を生成するのではなく、 `RTCPeerConnection` が使用するために独自に提供したい場合は、静的な `RTCPeerConnection.generateCertificate()` (en-US) 関数を呼び出すことによって行うことができます。

`certificates` プロパティの値は、一度指定すると変更することができません。もし、接続の `setConfiguration()` (en-US) の呼び出しに渡された設定に含まれていたとしても、無視されます。

この属性は複数の資格情報の提供に対応しています。それは、与えられた DTLS 接続が 1 つの資格情報のみを使用したとしても、複数の資格情報を提供することで複数の暗号化アルゴリズムに対応することができるからです。 `RTCPeerConnection` の実装は、DTLS ハンドシェイク中に決定された、自身とリモートピアーが対応するアルゴリズムに基づいて、使用する資格情報を選択することになります。

資格情報を提供しない場合、新しい資格情報が自動的に生成されます。自分で資格情報を用意することの明らかな利点は、 ID キーの継続性です。次回以降の呼び出しに同じ資格情報を使用すると、リモートピアーは同じ呼び出し元であることを指示することができます。また、新しい鍵を生成するコストもかかりません。

仕様書
---

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection |

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

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

関連情報
----

* シグナリングとビデオ通話
* WebRTC の構造の概要
* WebRTC セッションの寿命 (en-US)
* `RTCPeerConnection`


RTCPeerConnection.canTrickleIceCandidates - Web API

RTCPeerConnection.canTrickleIceCandidates
=========================================

**`RTCPeerConnection`** は読み取り専用のプロパティで、リモートピアーがトリクル ICE 候補を受け入れることができるかどうかを示す論理値を返します。

**ICE トリクリング**とは、最初の提案や回答がすでに相手に送られた後も、候補を送り続けるプロセスのことです。

このプロパティは `RTCPeerConnection.setRemoteDescription()` (en-US) を呼び出した後にのみ設定されます。理想的には、シグナルプロトコルがトリクルサポートを検出する方法を提供し、このプロパティに依存する必要がないようにすることです。　WebRTC ブラウザーは、常にトリクル ICE に対応しています。トリクリングに対応していない場合、または指示することができない場合は、このプロパティの偽値をチェックし、 `iceGatheringState` (en-US) の値が `"completed"` に変わるまで待ってから最初の提案を作成し送信することができます。そうすることで、提案にすべての候補が含まれるようになります。

値
-

論理値で、リモートピアーがトリクル ICE 候補を受け入れることができる場合は `true`、受け入れることができない場合は `false` となります。リモートピアーが確立されていない場合、この値は `null` となります。

**メモ:** このプロパティの値は、ローカルピアーが `RTCPeerConnection.setRemoteDescription()` (en-US)を呼び出した時点で決定されます。
 ICE　エージェントがリモートピアーがトリクル ICE 候補に対応しているかどうかを判断するために、指定された説明が使用されます。

例
-

```js
const pc = new RTCPeerConnection();

function waitToCompleteIceGathering(pc) {
  return new Promise((resolve) => {
    pc.addEventListener(
      "icegatheringstatechange",
      (e) =>
        e.target.iceGatheringState === "complete" &&
        resolve(pc.localDescription),
    );
  });
}

// The following code might be used to handle an offer from a peer when
// it isn't known whether it supports trickle ICE.
async function newPeer(remoteOffer) {
  await pc.setRemoteDescription(remoteOffer);
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  if (pc.canTrickleIceCandidates) return pc.localDescription;
  const answer = await waitToCompleteIceGathering(pc);
  sendAnswerToPeer(answer); //To peer via signaling channel
}
// Handle error with try/catch

pc.addEventListener(
  "icecandidate",
  (e) => pc.canTrickleIceCandidates && sendCandidateToPeer(e.candidate),
);
```

仕様書
---

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-cantrickleicecandidates |

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

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

関連情報
----

* WebRTC
* `RTCPeerConnection.addIceCandidate()` (en-US)
* WebRTC セッションの寿命 (en-US)


RTCPeerConnection.close() - Web API

RTCPeerConnection.close()
=========================

**`RTCPeerConnection.close()`** メソッドは、現在のピア接続を閉じます。

構文
--

```js
close()
```

*このメソッドには引数がなく、何も返しません。*

このメソッドを呼び出すと、RTCPeerConnection の ICE エージェントが終了し、進行中の ICE 処理とアクティブなストリームがすべて終了します。また、TURN 権限を含め、ICE エージェントが使用するすべてのリソースを解放します。このメソッドを返すと、すべての `RTCRtpSender` (en-US) オブジェクトが停止したとみなされます（まだ停止中かもしれませんが、どう考えても停止しています）。

このメソッドが返されると、`RTCPeerConnection.signalingState` (en-US) が返す信号状態は `closed` となります。

同じリモートピアーに接続する新しい接続を作成する前に、前回の `RTCPeerConnection` への参照をすべて `delete` するようにしてください（ブラウザーによってはエラーが発生する場合があります）。

例
-

```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");

dc.onmessage = (event) => {
  console.log(`received: ${event.data}`);
  pc.close(); // 最初の受信メッセージで閉じることを決定した
};

dc.onopen = () => {
  console.log("datachannel open");
};

dc.onclose = () => {
  console.log("datachannel close");
};
```

仕様書
---

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-close |

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

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

関連情報
----

* WebRTC
* `RTCPeerConnection`
* `RTCPeerConnection.signalingState` (en-US)


RTCPeerConnection: localDescription プロパティ - Web API

RTCPeerConnection: localDescription プロパティ
=========================================

**`RTCPeerConnection.localDescription`** は読み取り専用プロパティで、接続のローカル側のセッションを説明する `RTCSessionDescription` を返します。
 まだ設定されていない場合は `null` となります。

構文
--

```js
const sessionDescription = peerConnection.localDescription
```

 より基本的なレベルでは、 `RTCPeerConnection.pendingLocalDescription` (en-US) のプロパティが `null` でない場合、その値が返されます。
 それ以外の場合は、 `RTCPeerConnection.currentLocalDescription` (en-US) の値が返されます。
 このアルゴリズムの詳細と使用理由については、 WebRTC Connectivity ページの Pending and current descriptions を参照してください。

例
-

この例では `localDescription` を見て、`RTCSessionDescription` オブジェクトの `type` と `sdp` フィールドを含むアラートを表示します。

```js
const pc = new RTCPeerConnection();
// ...
const sd = pc.localDescription;
if (sd) {
  alert(`Local session: type='${sd.type}'; sdp description='${sd.sdp}'`);
} else {
  alert("No local session yet.");
}
```

仕様書
---

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-localdescription |

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

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

関連情報
----

* `RTCPeerConnection.setLocalDescription()` (en-US),
 `RTCPeerConnection.pendingLocalDescription` (en-US),
 `RTCPeerConnection.currentLocalDescription` (en-US)
* `RTCPeerConnection.setRemoteDescription()` (en-US),
 `RTCPeerConnection.remoteDescription` (en-US),
 `RTCPeerConnection.pendingRemoteDescription` (en-US),
 `RTCPeerConnection.currentRemoteDescription` (en-US)
* WebRTC


FileReader.readAsText() - Web API

FileReader.readAsText()
=======================

**`readAsText()`** メソッドは、指定された `Blob` または `File` の内容を読み取るために使用します。読み取り操作が完了すると、 `readyState` が `DONE` に変わり、 `loadend` イベントが発生し、 `result` プロパティにはファイルの内容が文字列として格納されます。

**メモ:** `Blob.text()` メソッドは、ファイルをテキストとして読み取るための新しいプロミスベースの API です。

**メモ:** このメソッドは、ファイルの内容全体をメモリーに読み込みますので、巨大なファイルには適していません。巨大なファイルには `readAsArrayBuffer()` の方が適しています。

構文
--

```js
readAsText(blob)
readAsText(blob, encoding)
```

### 引数

`blob`

メソッドで読み込む `Blob` または `File` オブジェクトです。

`encoding` 省略可

読み込みの際に使用する文字エンコーディングを指定する文字列です。この引数が指定されなかった場合は UTF-8 で解釈されます。

### 返値

なし (`undefined`)。

例
-

### HTML

```html
<input type="file" onchange="previewFile()" /><br />
<p class="content"></p>
```

### JavaScript

```js
function previewFile() {
  const content = document.querySelector(".content");
  const [file] = document.querySelector("input[type=file]").files;
  const reader = new FileReader();

  reader.addEventListener(
    "load",
    () => {
      // this will then display a text file
      content.innerText = reader.result;
    },
    false,
  );

  if (file) {
    reader.readAsText(file);
  }
}
```

### 結果

仕様書
---

| Specification |
| --- |
| File API # readAsDataText |

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

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

関連情報
----

* `FileReader`


FileReader: abort イベント - Web API

FileReader: abort イベント
======================

`abort` イベントは、読み込みが中断されたときに発生します。例えば、プログラムが `FileReader.abort()` を呼び出した場合などです。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

### ライブデモ

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">プロフィール画像を選択してください:</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview" />

  <div class="event-log">
    <label for="eventLog">イベントログ:</label>
    <textarea readonly class="event-log-contents" id="eventLog"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
  resize: none;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

#### JavaScript

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent += `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
  reader.abort();
}

fileInput.addEventListener("change", handleSelected);
```

#### 結果

仕様書
---

| Specification |
| --- |
| File API # dfn-abort-event |
| File API # dfn-onabort |

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

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

関連情報
----

* 関連イベント: `loadstart`, `loadend`, `progress`, `error`, `load`


FileReader() - Web API

FileReader()
============

**`FileReader()`** コンストラクターは、新しい FileReader を作成します。

`FileReader` の使用方法の詳細については、ウェブアプリケーションからのファイルの使用を参照してください。

構文
--

```js
new FileReader()
```

### 引数

なし。

例
-

次のコードスニペットは、`FileReader()` コンストラクタを使用した `FileReader` オブジェクトの作成と、その後のオブジェクトの使用法を示しています。

```js
function printFile(file) {
  const reader = new FileReader();
  reader.onload = (evt) => {
    console.log(evt.target.result);
  };
  reader.readAsText(file);
}
```

仕様書
---

| Specification |
| --- |
| File API # filereaderConstrctr |

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

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

関連情報
----

* ウェブアプリケーションからのファイルの使用


FileReader: load イベント - Web API

FileReader: load イベント
=====================

`load` イベントは、ファイルが正常に読み込めたときに発生します。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

### ライブデモ

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">プロフィール画像を選択してください:</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview" />

  <div class="event-log">
    <label for="eventLog">イベントログ:</label>
    <textarea readonly class="event-log-contents" id="eventLog"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
  resize: none;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

#### JavaScript

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent += `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

#### 結果

仕様書
---

| Specification |
| --- |
| File API # dfn-load-event |
| File API # dfn-onload |

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

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

関連情報
----

* 関連イベント: `FileReader.loadstart_event`, `FileReader.loadend_event`, `FileReader.progress_event`, `FileReader.error_event`, `FileReader.abort_event`


FileReader.readAsBinaryString() - Web API

FileReader.readAsBinaryString()
===============================

`readAsBinaryString` メソッドは、 指定された `Blob` または `File` オブジェクトを読み込むために使用します。 読込処理が終了すると `readyState` は `DONE` に変わり、`loadend` イベントが生じます。それと同時に `result` プロパティには生のバイナリーデータを文字列で解釈したものが格納されます。

 このメソッドは、ファイル API の仕様から一度削除されましたが、後方互換のために再導入されました。
 `FileReader.readAsArrayBuffer()` の使用が推奨されています。

構文
--

```js
readAsBinaryString(blob)
```

### 引数

`blob`

メソッドで読み込む `Blob` または `File` オブジェクトです。

### 返値

なし (`undefined`)。

例
-

```js
const canvas = document.createElement("canvas");
const height = 200;
const width = 200;

canvas.width = width;
canvas.height = height;

const ctx = canvas.getContext("2d");

ctx.strokeStyle = "#090";
ctx.beginPath();
ctx.arc(width / 2, height / 2, width / 2 - width / 10, 0, Math.PI \* 2);
ctx.stroke();

canvas.toBlob((blob) => {
  const reader = new FileReader();

  reader.onload = () => {
    console.log(reader.result);
  };

  reader.readAsBinaryString(blob);
});
```

仕様書
---

| Specification |
| --- |
| File API # readAsBinaryString |

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

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

関連情報
----

* `FileReader`


FileReader: loadstart イベント - Web API

FileReader: loadstart イベント
==========================

`loadstart` イベントは、ファイル読み込み操作が始まったときに発生します。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

### ライブデモ

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">プロフィール画像を選択してください:</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview" />

  <div class="event-log">
    <label for="eventLog">イベントログ:</label>
    <textarea readonly class="event-log-contents" id="eventLog"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
  resize: none;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

#### JavaScript

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent += `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

#### 結果

仕様書
---

| Specification |
| --- |
| File API # dfn-loadstart-event |
| File API # dfn-onloadstart |

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

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

関連情報
----

* 関連イベント: `FileReader.load_event`, `FileReader.loadend_event`, `FileReader.progress_event`, `FileReader.error_event`, `FileReader.abort_event`


FileReader.error - Web API

FileReader.error
================

`FileReader` の **`error`** プロパティは、ファイルの読み取り中に発生したエラーを返します。

値
-

`DOMError` に関連するエラーが含まれています。 Chrome 48 以降/Firefox 58 以降では、 `DOMError` が DOM 標準から削除されているため、このプロパティは `DOMException` を返します。

仕様書
---

| Specification |
| --- |
| File API # dom-filereader-error |

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

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

関連情報
----

* `FileReader`


FileReader.abort() - Web API

FileReader.abort()
==================

**`abort`** メソッドは、読み取り操作を中止します。戻る時に、 `readyState` が `DONE` になります。

構文
--

```js
abort()
```

### 引数

なし。

### 返値

なし (`undefined`)。

仕様書
---

| Specification |
| --- |
| File API # abort |

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

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

関連情報
----

* `FileReader`


FileReader: error イベント - Web API

FileReader: error イベント
======================

`error` イベントは、エラーによって読み取りが失敗したとき (例えば、ファイルが見つからなかった場合や読み取り可能ではなかった場合) に発生します。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

```js
const fileInput = document.querySelector('input[type="file"]');
const reader = new FileReader();

function handleSelected(e) {
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    reader.addEventListener("error", () => {
      console.error(`Error occurred reading file: ${selectedFile.name}`);
    });

    reader.addEventListener("load", () => {
      console.error(`File: ${selectedFile.name} read successfully`);
    });

    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

仕様書
---

| Specification |
| --- |
| File API # dfn-error-event |
| File API # dfn-onerror |

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

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

関連情報
----

* 関連イベント: `loadstart`, `loadend`, `progress`, `load`, `abort`


FileReader.readyState - Web API

FileReader.readyState
=====================

`FileReader` の **`readyState`** プロパティは、 `FileReader` がいる読み取り操作の現在の状態を提供します。 `FileReader` は以下のいずれかの状態にあります。

| 値 | 状態 | 説明 |
| --- | --- | --- |
| `0` | `EMPTY` | Reader が作成されました。まだ読み込まれているメソッドはありません。 |
| `1` | `LOADING` | read メソッドが呼び出されました。 |
| `2` | `DONE` | 操作が完了しています。 |

`EMPTY`

`FileReader` は作成されましたが、 readAs メソッドはまだ呼び出されていません。

`LOADING`

readAs メソッドが呼び出されました。 `File` または `Blob` が読み取り中であり、まだエラーは発生していません。

`DONE`

読み取り操作が完了しています。これは、 `File` または `Blob` の全体がメモリに読み込まれたか、ファイル読み取りエラーが発生したか、 `abort()` が呼び出され、読み取りがキャンセルされたか、いずれかを意味します。

例
-

```js
const reader = new FileReader();
console.log("EMPTY", reader.readyState); // readyState は 0 になります。

reader.readAsText(blob);
console.log("LOADING", reader.readyState); // readyState は 1 になります。

reader.onloadend = () => {
  console.log("DONE", reader.readyState); // readyState は 2 になります。
};
```

値
-

`FileReader` API のために定義されている、状態を表す 3 つの定数のうちの 1 つです。

仕様書
---

| Specification |
| --- |
| File API # dom-filereader-readystate |

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

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

関連情報
----

* `Blob`


FileReader: progress イベント - Web API

FileReader: progress イベント
=========================

`progress` イベントは、 `FileReader` がデータを読むときに定期的に発生します。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

### ライブデモ

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">プロフィール画像を選択してください:</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview" />

  <div class="event-log">
    <label for="eventLog">イベントログ:</label>
    <textarea readonly class="event-log-contents" id="eventLog"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
  resize: none;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

#### JavaScript

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent += `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

#### 結果

仕様書
---

| Specification |
| --- |
| File API # dfn-progress-event |
| File API # dfn-onprogress |

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

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

関連情報
----

* 関連イベント: `loadstart`, `loadend`, `load`, `error`, `abort`


FileReader.readAsDataURL() - Web API

FileReader.readAsDataURL()
==========================

`readAsDataURL` メソッドは、指定された`Blob` または `File` の内容を読み込むために使用されます。読み込み操作が終了すると、`readyState` が `DONE` となり、`loadend` が発生します。このとき、`result` 属性には、ファイルのデータを表す、base64 エンコーディングされた data: URL の文字列が格納されます。

**メモ:** blob の `result` は、先に Base64 でエンコードされたデータの前にある Data-URL の宣言を削除しておかないと、直接 Base64 としてデコードすることができません。 Base64 でエンコードされた文字列のみを受け取る場合は、先に結果から `data:*/*;base64,` を削除しておく必要があります。

構文
--

```js
readAsDataURL(blob)
```

### 引数

`blob`

メソッドで読み込む `Blob` または `File` オブジェクトです。

### 返値

なし (`undefined`)。

例
-

### HTML

```html
<input type="file" onchange="previewFile()" /><br />
<img src="" height="200" alt="画像のプレビュー" />
```

### JavaScript

```js
function previewFile() {
  const preview = document.querySelector("img");
  const file = document.querySelector("input[type=file]").files[0];
  const reader = new FileReader();

  reader.addEventListener(
    "load",
    () => {
      // 画像ファイルを base64 文字列に変換します
      preview.src = reader.result;
    },
    false,
  );

  if (file) {
    reader.readAsDataURL(file);
  }
}
```

### ライブ結果

複数ファイルを読み取る例
------------

### HTML

```html
<input id="browse" type="file" onchange="previewFiles()" multiple />
<div id="preview"></div>
```

### JavaScript

```js
function previewFiles() {
  const preview = document.querySelector("#preview");
  const files = document.querySelector("input[type=file]").files;

  function readAndPreview(file) {
    // `file.name` が拡張子の基準と一致していることを確認します。
    if (/\.(jpe?g|png|gif)$/i.test(file.name)) {
      const reader = new FileReader();

      reader.addEventListener(
        "load",
        () => {
          const image = new Image();
          image.height = 100;
          image.title = file.name;
          image.src = this.result;
          preview.appendChild(image);
        },
        false,
      );

      reader.readAsDataURL(file);
    }
  }

  if (files) {
    Array.prototype.forEach.call(files, readAndPreview);
  }
}
```

**メモ:** Internet Explorer 10 以前では `FileReader()` コンストラクターに対応していません。十分な互換性が必要とされるときは、画像プレビューのクロスブラウザー対応ソリューションまたはもっと強力な例を参照してください。

仕様書
---

| Specification |
| --- |
| File API # readAsDataURL |

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

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

関連情報
----

* `FileReader`
* `URL.createObjectURL()`


FileReader.result - Web API

FileReader.result
=================

`FileReader` の **`result`** プロパティは、ファイルの内容を返します。このプロパティは、読み取り操作が完了した後でのみ有効で、データの形式は、読み取り操作を開始するために使用されたメソッドによって異なります。

### 値

読み取り操作を開始するためにどの読み取りメソッドが使用されたかに基づく、適切な文字列または `ArrayBuffer` です。読み取りがまだ完了していないか、失敗した場合は、値は `null` になります。

結果の型は以下の通りです。

| メソッド | 説明 |
| --- | --- |
| `readAsArrayBuffer()` | `result` はバイナリーデータを含む JavaScript の `ArrayBuffer` になります。 |
| `readAsBinaryString()` | `result` にはファイルから生のバイナリーデータが文字列で格納されます。 |
| `readAsDataURL()` | `result` はファイルのデータを表す `data:` URL の文字列になります。 |
| `readAsText()` | `result` は文字列のテキストです。 |

例
-

この例は、ファイル入力欄からファイルを読み込む関数 `read()` を示しています。これは `FileReader` オブジェクトを作成し、 `load` イベントのリスナーを作成し、ファイルが読み込まれるとその `result` を取得し、提供されたコールバック関数を `read()` に渡すことによって機能します。

内容は生のテキストデータとして扱われます。

```js
const fileInput = document.querySelector('input[type="file"]');

function read(callback) {
  const file = fileInput.files.item(0);
  const reader = new FileReader();

  reader.onload = () => {
    callback(reader.result);
  };

  reader.readAsText(file);
}
```

仕様書
---

| Specification |
| --- |
| File API # dom-filereader-result |

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

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

関連情報
----

* `FileReader`


FileReader: loadend イベント - Web API

FileReader: loadend イベント
========================

`loadend` イベントは、ファイル読み込みが、成功したかどうかにかかわらず完了したときに発生します。

このイベントはキャンセル不可で、バブリングしません。

構文
--

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

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

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

イベント型
-----

`ProgressEvent` です。 `Event` から継承しています。

Event

ProgressEventイベントプロパティ
---------

*親である `Event` からプロパティを継承しています。*

`ProgressEvent.lengthComputable` 読取専用

論理値で、このプロセスで行われる作業の合計と、すでに行われた作業の量が計算可能かどうかを示す。言い換えれば、進捗が計測可能かどうかを示します。

`ProgressEvent.loaded` 読取専用

64 ビット符号なし整数値で、このプロセスで既に作業を行った量を示します。作業した比率は、`total` をこのプロパティの値で割ることで算出できます。 HTTP を使用してリソースをダウンロードする場合、これは HTTP メッセージの本文のみをカウントし、ヘッダーやその他のオーバーヘッドは含まれません。

`ProgressEvent.total` 読取専用

64 ビット符号なし整数で、基礎となるプロセスが実行中の作業の総量を表します。 HTTP を使用してリソースをダウンロードする場合、これは `Content-Length` （メッセージの本文のサイズ）であり、ヘッダーやその他のオーバーヘッドは含まれません。

例
-

### ライブデモ

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">プロフィール画像を選択してください::</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview" />

  <div class="event-log">
    <label for="eventLog">イベントログ:</label>
    <textarea readonly class="event-log-contents" id="eventLog"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
  resize: none;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

#### JavaScript

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent += `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

#### 結果

仕様書
---

| Specification |
| --- |
| File API # dfn-loadend-event |
| File API # dfn-onloadend |

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

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

関連情報
----

* 関連イベント: `loadstart`, `load`, `progress`, `error`, `abort`


FileReader.readAsArrayBuffer() - Web API

FileReader.readAsArrayBuffer()
==============================

`FileReader` インターフェイスの **`readAsArrayBuffer()`** メソッドは、指定された `Blob` ないし `File` オブジェクトの内容を読み込むために使用します。読み込み処理が終了すると `readyState` が `DONE` に変わり、 `loadend` イベントが発行されます。それと同時に、 `result` プロパティにはファイルのデータを表す `ArrayBuffer` が格納されます。

**メモ:** `Blob.arrayBuffer()` メソッドは、ファイルを ArrayBuffer として読み取るためのプロミスベースのより新しい API です。

構文
--

```js
readAsArrayBuffer(blob)
```

### 引数

`blob`

メソッドで読み込む `Blob` または `File` オブジェクトです。

### 返値

なし (`undefined`)。

仕様書
---

| Specification |
| --- |
| File API # readAsArrayBuffer |

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

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

関連情報
----

* `FileReader`


BluetoothRemoteGATTCharacteristic: service プロパティ - Web API

BluetoothRemoteGATTCharacteristic: service プロパティ
================================================

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

読み取り専用プロパティ **`BluetoothRemoteGATTCharacteristic.service`** は、このキャラクタリスティックが属する `BluetoothRemoteGATTService` を返します。

値
-

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

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-service |

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

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


BluetoothRemoteGATTCharacteristic: writeValueWithoutResponse() メソッド - Web API

BluetoothRemoteGATTCharacteristic: writeValueWithoutResponse() メソッド
===================================================================

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

**`BluetoothRemoteGATTCharacteristic.writeValueWithoutResponse()`** メソッドは、`BluetoothRemoteGATTCharacteristic` オブジェクトの `value` プロパティを渡された `ArrayBuffer` に格納されたバイト列に設定し、`WriteCharacteristicValue`(*this*=`this`, *value=value*, *response*=`"never"`) を呼び出し、結果の `Promise` を返します。

構文
--

```js
writeValueWithoutResponse(value)
```

### 引数

`value`

`ArrayBuffer` です。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-writevaluewithoutresponse |

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

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


BluetoothRemoteGATTCharacteristic: writeValueWithResponse() メソッド - Web API

BluetoothRemoteGATTCharacteristic: writeValueWithResponse() メソッド
================================================================

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

**`BluetoothRemoteGATTCharacteristic.writeValueWithResponse()`** メソッドは、`BluetoothRemoteGATTCharacteristic` オブジェクトの `value` プロパティを渡された `ArrayBuffer` に格納されたバイト列に設定し、`WriteCharacteristicValue`(*this*=`this`, *value=value*, *response*=`"required"`) を呼び出し、結果の `Promise` を返します。

構文
--

```js
writeValueWithResponse(value)
```

### 引数

`value`

`ArrayBuffer` です。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-writevaluewithresponse |

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

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


BluetoothRemoteGATTCharacteristic: uuid プロパティ - Web API

BluetoothRemoteGATTCharacteristic: uuid プロパティ
=============================================

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

読み取り専用プロパティ **`BluetoothRemoteGATTCharacteristic.uuid`** は、このキャラクタリスティックの UUID を表す文字列を返します。たとえば、Heart Rate Measurement characteristic は `'00002a37-0000-1000-8000-00805f9b34fb'` です。

値
-

文字列です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-uuid |

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

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


BluetoothRemoteGATTCharacteristic: getDescriptors() メソッド - Web API

BluetoothRemoteGATTCharacteristic: getDescriptors() メソッド
========================================================

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

**`BluetoothRemoteGATTCharacteristic.getDescriptors()`** メソッドは、指定のディスクリプター UUID に対応するすべての `BluetoothRemoteGATTDescriptor` オブジェクトの `Array` で解決する `Promise` を返します。

構文
--

```js
getDescriptors(bluetoothDescriptorUUID)
```

### 引数

なし

### 返値

`BluetoothRemoteGATTDescriptor` オブジェクトの `Array` で解決する `Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-getdescriptors |

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

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


BluetoothRemoteGATTCharacteristic: startNotifications() メソッド - Web API

BluetoothRemoteGATTCharacteristic: startNotifications() メソッド
============================================================

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

**`BluetoothRemoteGATTCharacteristic.startNotifications()`** メソッドは、それに関する活動中のノーティフィケーションが存在するようになったら `BluetoothRemoteGATTCharacteristic` のインスタンスで解決する `Promise` を返します。

構文
--

```js
startNotifications()
```

### 引数

なし

### 返値

`BluetoothRemoteGATTCharacteristic` のインスタンスで解決する `Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-startnotifications |

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

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


BluetoothRemoteGATTCharacteristic: readValue() メソッド - Web API

BluetoothRemoteGATTCharacteristic: readValue() メソッド
===================================================

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

**`BluetoothRemoteGATTCharacteristic.readValue()`** メソッドは、利用可能で対応していれば、`value` プロパティの複製が格納された `DataView` で解決する `Promise` を返します。そうでない場合は、エラーを投げます。

構文
--

```js
readValue()
```

### 引数

なし

### 返値

`DataView` で解決する `Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-readvalue |

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

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


BluetoothRemoteGATTCharacteristic: writeValue() メソッド - Web API

BluetoothRemoteGATTCharacteristic: writeValue() メソッド
====================================================

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

かわりに `BluetoothRemoteGATTCharacteristic.writeValueWithResponse()` や `BluetoothRemoteGATTCharacteristic.writeValueWithoutResponse()` を使用してください。

**`BluetoothRemoteGATTCharacteristic.writeValue()`** メソッドは、`BluetoothRemoteGATTCharacteristic` オブジェクトの `value` プロパティを渡された `ArrayBuffer` に格納されたバイト列に設定し、`WriteCharacteristicValue`(*this*=`this`, *value=value*, *response*=`"optional"`) を呼び出し、結果の `Promise` を返します。

構文
--

```js
writeValue(value)
```

### 引数

`value`

`ArrayBuffer` です。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-writevalue |

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

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


BluetoothRemoteGATTCharacteristic: value プロパティ - Web API

BluetoothRemoteGATTCharacteristic: value プロパティ
==============================================

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

読み取り専用プロパティ **`BluetoothRemoteGATTCharacteristic.value`** は、現在キャッシュされているキャラクタリスティックの値を返します。この値は、キャラクタリスティックの値が読まれるか、ノーティフィケーションやインディケーションによって更新されると更新されます。

値
-

現在キャッシュされているキャラクタリスティックの値です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-value |

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

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


BluetoothRemoteGATTCharacteristic: properties プロパティ - Web API

BluetoothRemoteGATTCharacteristic: properties プロパティ
===================================================

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

読み取り専用プロパティ **`BluetoothRemoteGATTCharacteristic.properties`** は、このキャラクタリスティックのプロパティが格納された `BluetoothCharacteristicProperties` のインスタンスを返します。

値
-

このキャラクタリスティックのプロパティです。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-properties |

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

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


BluetoothRemoteGATTCharacteristic: stopNotifications() メソッド - Web API

BluetoothRemoteGATTCharacteristic: stopNotifications() メソッド
===========================================================

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

**`BluetoothRemoteGATTCharacteristic.stopNotifications()`** メソッドは、それに関する活動中のノーティフィケーションが存在しなくなったら `BluetoothRemoteGATTCharacteristic` のインスタンスで解決する `Promise` を返します。

構文
--

```js
stopNotifications()
```

### 引数

なし

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-stopnotifications |

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

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


BluetoothRemoteGATTCharacteristic: getDescriptor() メソッド - Web API

BluetoothRemoteGATTCharacteristic: getDescriptor() メソッド
=======================================================

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

**`BluetoothRemoteGATTCharacteristic.getDescriptor()`** メソッドは、指定のディスクリプター UUID に対応する最初の `BluetoothRemoteGATTDescriptor` で解決する `Promise` を返します。

構文
--

```js
getDescriptor(bluetoothDescriptorUUID)
```

### 引数

なし

### 返値

最初の `BluetoothRemoteGATTDescriptor` で解決する `Promise` です。

仕様書
---

| Specification |
| --- |
| Web Bluetooth # dom-bluetoothremotegattcharacteristic-getdescriptor |

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

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


HTMLScriptElement: referrerPolicy プロパティ - Web API

HTMLScriptElement: referrerPolicy プロパティ
=======================================

**`referrerPolicy`** は `HTMLScriptElement` インターフェイスのプロパティで、 `<script>` 要素の `referrerpolicy` とそのスクリプトによって行われるフェッチを反映し、リソースをフェッチする際にどのリファラーを送信するか定義しています。

値
-

文字列です。以下のいずれかです。

`no-referrer`

`Referer` ヘッダーは完全に省略されます。リクエストと共に送信されるリファラー情報はありません。

`no-referrer-when-downgrade`

プロトコルのセキュリティレベルが変わらない場合（例: HTTP→HTTP、HTTPS→HTTPS）にはリファラーとして URL を送信し、セキュリティレベルの低い宛先（例: HTTPS→HTTP）には送信しません。

`origin`

 どのような場合でも、この文書のオリジンだけをリファラーとして送信します。
 文書 `https://example.com/page.html` はリファラーとして `https://example.com/` を送ります。

`origin-when-cross-origin`

同一オリジンリクエストを行う場合は完全な URL を送信し、それ以外の場合は文書のオリジンのみを送信します。

`same-origin`

リファラーは同一サイトオリジンには送信されますが、オリジン間リクエストではリファラー情報が送信されません。

`strict-origin`

プロトコルのセキュリティレベルが変わらない場合（例: HTTPS→HTTPS）だけ、文書のオリジンをリファラーとして送信し、セキュリティレベルの低い宛先（例: HTTPS→HTTP）には送信しないようにします。

`strict-origin-when-cross-origin` (default)

これは、ポリシーが指定されていない場合のユーザーエージェントの既定の動作です。同一オリジンリクエストを行う場合は完全な URL を送信し、プロトコルのセキュリティレベルが変わらない場合はオリジンのみを送信し（例: HTTPS→HTTPS）、セキュリティレベルの低い宛先にはヘッダーを送信しません（例: HTTPS→HTTP）。

`unsafe-url`

 同一オリジンまたはオリジン間リクエストを実行するときに、完全な URL を送信します。このポリシーは、 TLS で保護されたリソースから安全でないオリジンへのオリジンとパスを漏洩します。
 この設定の影響を慎重に検討してください。

**メモ:** 空文字列の値 (`""`) は既定値であると同時に、 `referrerpolicy` が対応していない場合の代替値でもあります。もし `<script>` 要素に `referrerpolicy` が明示的に指定されていない場合には、より高いレベルのリファラーポリシー、つまり文書やドメイン全体に設定されているものを採用することになります。上位のポリシーが利用できない場合、空文字列は `no-referrer-when-downgrade` と同等に扱われます。

例
-

```js
const scriptElem = document.createElement("script");
scriptElem.src = "/";
scriptElem.referrerPolicy = "unsafe-url";
document.body.appendChild(scriptElem);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-script-referrerpolicy |

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

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

関連情報
----

* `HTMLIFrameElement.referrerPolicy`


HTMLScriptElement: supports() 静的メソッド - Web API

HTMLScriptElement: supports() 静的メソッド
====================================

**`supports()`** は `HTMLScriptElement` インターフェイスの静的メソッドで、ユーザーエージェントが対応しているスクリプトの種類を機能的に検出するための、単純で一貫したメソッドを提供します。

このメソッドは、ほとんどの現代のブラウザーが対応しているクラシックスクリプトとモジュールスクリプトに対して `true` を返すことが期待されています。

構文
--

```js
HTMLScriptElement.supports(type)
```

### 引数

`type`

 対応しているかどうかを調べるスクリプトの種類を示す文字列リテラルです。
 対応している値は以下の通りで、大文字と小文字が区別されます。

`"classic"`

 クラシックスクリプトが対応しているかどうかをテストします。
 「クラシック」スクリプトとは、モジュールスクリプトより前の通常の、伝統的な JavaScript ファイルのことです。

`"module"`

モジュールスクリプトに対応しているかどうかをテストします。

`"importmap"`

インポートマップに対応しているかどうかをテストします。

`"speculationrules"`

投機ルールが対応し、有効になっているかどうかをテストします。

他の値であれば、このメソッドは `false` を返します。

### 返値

指定されたスクリプトに対応している場合は `true` を、そうでない場合は `false` を返す。

例
-

下記のコードは `HTMLScriptElement.supports()` が定義されているかどうかを調べ、定義されている場合はそれを使用して特定の種類のスクリプトに対応しているかどうかをテストする方法を示しています。

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

function checkSupport(type) {
  const result = HTMLScriptElement.supports(type) ? "true" : "false";
  log.textContent += `HTMLScriptElement.supports('${type}') は ${result}\n`;
}

if (typeof HTMLScriptElement.supports === "undefined") {
  log.textContent = "HTMLScriptElement.supports() メソッドに対応していません";
} else {
  // 様々な種類のスクリプトに対応しているかどうかをチェック
  checkSupport("module");
  checkSupport("classic");
  checkSupport("importmap");
  checkSupport("speculationrules");
  // 他の値ならば、このメソッドは false を返す
  checkSupport("anything else");
}
```

```
<textarea id="log" rows="6" cols="80"></textarea>
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-script-supports |

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

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

関連情報
----

* `HTMLScriptElement`
* `<script>`
* JavaScript モジュール
* `Worker` コンストラクター


Node: hasChildNodes() メソッド - Web API

Node: hasChildNodes() メソッド
==========================

**`hasChildNodes()`** は `Node` インターフェイスのメソッドで、この `Node` に子ノードがあるかどうかを示す論理値を返します。

構文
--

```js
hasChildNodes()
```

### 引数

なし。

### 返値

論理値で、このノードに子ノードがあれば `true` を、そうでなければ `false` を返します。

例
-

```js
let foo = document.getElementById("foo");

if (foo.hasChildNodes()) {
  // 'foo.childNodes' で何かを行う
}
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-haschildnodes① |

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

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

関連情報
----

* `Node.childNodes`


Node: lookupPrefix() メソッド - Web API

Node: lookupPrefix() メソッド
=========================

**`lookupPrefix()`** は `Node` インターフェイスのメソッドで、指定された名前空間 URI に対応する接頭辞があれば、それを含む文字列を返します。ない場合は `null` を返します。
 複数の接頭辞の可能性があれば、最初の接頭辞を返します。

構文
--

```js
lookupPrefix(namespace)
```

### 引数

`namespace`

接頭辞を検索するための名前空間の入った文字列です。

**メモ:** この引数は省略可能ではありませんが、 `null` に設定することはできます。

### 返値

 対応する接頭辞の入った文字列です。見つからなかった場合は `null` になります。
 `namespace` が null または空文字列であった場合、 `lookupPrefix()` は `null` を返します。

このノードが `DocumentType` または `DocumentFragment` であった場合は、　`lookupPrefix()` は常に `null` を返します。

例
-

```html
Prefix for <code>http://www.w3.org/2000/svg</code> on <output>:
<output>未検査</output><br />
Prefix for <code>http://www.w3.org/XML/1998/namespace</code> on <output>:
<output>未検査</output><br />
Prefix for <code>http://www.w3.org/TR/html4/</code> on <output>:
<output>未検査</output><br />
Prefix for <code>https://www.w3.org/1999/xlink</code> on <output>:
<output>未検査</output><br />
Prefix for <code>http://www.w3.org/2000/svg</code> on <svg>:
<output>未検査</output><br />
Prefix for <code>https://www.w3.org/1999/xlink</code> on <svg>:
<output>未検査</output><br />
Prefix for <code>http://www.w3.org/XML/1998/namespace</code> on <svg>:
<output>未検査</output><br />
<svg xmlns:t="http://www.w3.org/2000/svg" height="1"></svg>
<button>結果を確認するにはクリック</button>
```

```js
const button = document.querySelector("button");
button.addEventListener("click", () => {
  const aHtmlElt = document.querySelector("output");
  const aSvgElt = document.querySelector("svg");

  const result = document.getElementsByTagName("output");
  result[0].value = aHtmlElt.lookupPrefix("http://www.w3.org/2000/svg"); // true
  result[1].value = aHtmlElt.lookupPrefix(
    "http://www.w3.org/XML/1998/namespace",
  ); // false
  result[2].value = aHtmlElt.lookupPrefix("http://www.w3.org/TR/html4/"); // true
  result[3].value = aHtmlElt.lookupPrefix("https://www.w3.org/1999/xlink"); // false
  result[4].value = aSvgElt.lookupPrefix("http://www.w3.org/2000/svg"); // true
  result[5].value = aSvgElt.lookupPrefix("https://www.w3.org/1999/xlink"); // true
  result[6].value = aSvgElt.lookupPrefix(
    "http://www.w3.org/XML/1998/namespace",
  ); // false
});
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-lookupprefix |

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

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

関連情報
----

* http://www.w3.org/TR/DOM-Level-3-Cor...amespacePrefix


Node: baseURI プロパティ - Web API

Node: baseURI プロパティ
===================

**`baseURI`** は `Node` インターフェイスの読み取り専用プロパティで、このノードを含む文書の絶対的なベース URL を返します。

ベース URL はブラウザーが絶対 URL を必要とするときに、相対 URL を解決するために使用されます。例えば、 HTML の `<img>` 要素の `src` 属性や、 SVG の `xlink:href` や `href` 属性を処理する場合などです。

このプロパティは読み取り専用ですが、値はプロパティがアクセスされるたびにアルゴリズムで決まりますので、状況が変化すると変化することがあります。

ベース URL は次のように決まります。

1. 既定で、ベース URL は文書の位置（`window.location` で指定された通り）となります。
2. これが HTML 文書であり、文書に `<base>` 要素があった場合、*最初の* `Base` 要素の `href` の値があれば、代わりに使用されます。
値
-

`Node` のベース URL を表す文字列です。

例
-

### <base> なし

```html
<output>Not calculated</output>
```

```js
const output = document.querySelector("output");
output.value = output.baseURI;
```

### <base> あり

```html
<base href="https://developer.mozilla.org/modified\_base\_uri/" />
<output>Not calculated</output>
```

```js
const output = document.querySelector("output");
output.value = output.baseURI;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-baseuri① |

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

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

関連情報
----

* `<base>` 要素


Node: parentElement プロパティ - Web API

Node: parentElement プロパティ
=========================

**`parentElement`** は `Node` インターフェイスの読み取り専用プロパティで、この DOM ノードの親である要素 (`Element`) を返します。このノードに親ノードがないか、親が DOM の `Element` でない場合は `null` を返します。

値
-

現在のノードの親ノードである `Element` を返します。そのようなものがない場合は `null` を返します。

例
-

```js
if (node.parentElement) {
  node.parentElement.style.color = "red";
}
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-parentelement① |

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

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

関連情報
----

* `Node.parentNode`


Node: isDefaultNamespace() メソッド - Web API

Node: isDefaultNamespace() メソッド
===============================

**`isDefaultNamespace()`** は `Node` インターフェイスのメソッドで、名前空間 URI を引数として受け取ります。
 その名前空間がこのノードの既定の名前空間である場合は `true` を返し、そうでない場合は `false` を返します。

**メモ:** 既定の名前空間は、 HTML 要素では常に `""` です。 SVG 要素では、 `xmlns` 属性で設定されます。

構文
--

```js
isDefaultNamespace(namespaceURI)
```

### 引数

`namespaceURI`

要素の検査対象となる名前空間を表す文字列です。

**メモ:** `namespaceURI` は省略可能ではありませんが、 `null` に設定することはできます。

### 返値

`true` または `false` の値を持つ論理値で、引数が既定の名前空間であるかどうかを示します。

例
-

```html
"" が <output> の既定の名前空間であるか: <output>未検査</output><br />
"http://www.w3.org/2000/svg" が <output> の既定の名前空間であるか:
<output>未検査</output><br />
"" が <svg> の既定の名前空間であるか: <output>未検査</output><br />
"http://www.w3.org/2000/svg" が <svg> の既定の名前空間であるか:
<output>未検査</output><br />
<svg xmlns="http://www.w3.org/2000/svg" height="1"></svg>
<button>結果を見るにはクリック</button>
```

```js
const button = document.querySelector("button");
button.addEventListener("click", () => {
  const aHtmlElt = document.querySelector("output");
  const aSvgElt = document.querySelector("svg");

  const result = document.getElementsByTagName("output");
  result[0].value = aHtmlElt.isDefaultNamespace(""); // true
  result[1].value = aHtmlElt.isDefaultNamespace("http://www.w3.org/2000/svg"); // false
  result[2].value = aSvgElt.isDefaultNamespace(""); // true
  result[3].value = aSvgElt.isDefaultNamespace("http://www.w3.org/2000/svg"); // false
});
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-isdefaultnamespace |

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

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

関連情報
----

* `Node.lookupNamespaceURI`
* `Node.lookupPrefix`


Node: normalize() メソッド - Web API

Node: normalize() メソッド
======================

**`normalize()`** は `Node` インターフェイスのメソッドで、指定されたノードとその下のツリーを*正規化された*形にします。
 正規化されたサブツリーでは、サブツリー内に空のテキストノードがなくなり、隣り合うテキストノードがなくなります。

構文
--

```js
normalize()
```

### 引数

なし。

### 返値

なし。

例
-

```html
<output id="result"></output>
```

```js
const wrapper = document.createElement("div");

wrapper.appendChild(document.createTextNode("Part 1 "));
wrapper.appendChild(document.createTextNode("Part 2 "));

let node = wrapper.firstChild;
let result = "正規化前:<br/>";
while (node) {
  result += ` ${node.nodeName}: ${node.nodeValue}<br/>`;
  node = node.nextSibling;
}

wrapper.normalize();

node = wrapper.firstChild;
result += "<br/><br/>正規化後:<br/>";
while (node) {
  result += ` ${node.nodeName}: ${node.nodeValue}<br/>`;
  node = node.nextSibling;
}

const output = document.getElementById("result");
output.innerHTML = result;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-normalize① |

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

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

関連情報
----

* 逆の操作である `Text.splitText()`


Node: textContent プロパティ - Web API

Node: textContent プロパティ
=======================

**`textContent`** は `Node` のプロパティで、ノードおよびその子孫のテキストの内容を表します。

**メモ:** `textContent` と `HTMLElement.innerText` は混同しやすいものですが、2 つのプロパティは重要な点が異なります。

値
-

文字列または `null` です。値は場面によります。

* ノードが `document` または doctype である場合、`textContent` は `null` を返します。

**メモ:** 文書全体の*すべての*テキストと CDATA データを取得するには、`document.documentElement.textContent` を使用する方法があります。
* ノードが CDATA セクション、コメント、処理命令ノード、テキストノードの場合、`textContent` はそのノードの内側のテキスト、すなわち `Node.nodeValue` を返します。
* 他のノード型の場合、`textContent` は、コメントと処理命令ノードを除く、すべての子ノードの `textContent` 属性値を連結したものを返します。（ノードが子を持たない場合、これは空文字列になります。）

**警告:** ノードの `textContent` を設定すると、そのノードの*すべて*の子が取り除かれて、指定された値を持つ単一のテキストノードに置き換わります。

### innerText との違い

`Node.textContent` と `HTMLElement.innerText` の間の違いに混乱しないでください。名前は似ているようですが、重要な違いがあります。

* `textContent` は、`<script>` と `<style>` 要素を含む、*すべて*の要素の中身を取得します。一方、`innerText` は「人間が読める」要素のみを示します。
* `textContent` はノード内のすべての要素を返します。一方、`innerText` はスタイルを反映し、「非表示」の要素のテキストは返しません。
    + もっと言えば、`innerText` は CSS のスタイルを考慮するので、`innerText` の値を読み取ると最新の計算されたスタイルを保証するために再フローを起動します。（再フローは計算が重いので、可能であれば避けるべきです。）
### innerHTML との違い

`Element.innerHTML` は、その名が示すとおり HTML を返します。時に、`innerHTML` を使用して要素内のテキストを受け取ったり書き込んだりすることがありますが、`textContent` は値が HTML として解析されないので性能が良くなります。

さらに、`textContent` を使用することで XSS 攻撃を防ぐことができます。

例
-

最初は HTML の断片です。

```html
<div id="divA">This is <span>some</span> text!</div>
```

`textContent` を使用して、要素のテキストの内容を取得することができます。

```js
let text = document.getElementById("divA").textContent;
// 変数 text の値は 'This is some text!' となります。
```

また、要素のテキストを設定するには、次のようにします。

```js
document.getElementById("divA").textContent = "This text is different!";
// divA の HTML は次のようになります。
// <div id="divA">This text is different!</div>
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-textcontent |

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

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

関連情報
----

* `HTMLElement.innerText`
* `Element.innerHTML`
* More on differences between `innerText` and `textContent`（ブログ投稿）


Node: insertBefore() メソッド - Web API

Node: insertBefore() メソッド
=========================

**`insertBefore()`** は `Node` インターフェイスのメソッドで、*参照先ノード*の前にこの*親ノード*の子としてノードを挿入します。

指定されたノードが既に文書中に存在した場合、 `insertBefore()` はこれを現在の位置から新しい位置に移動します。（つまり、既存の親ノードから自動的に削除され、指定された新しい親に追加されます。）

これは、 1 つのノードが文書中に同時に 2 か所に存在できないことを意味します。

**メモ:** `Node.cloneNode()` を使用すると、ノードを新しい親の下に追加する前に複製を作成することができます。なお、 `cloneNode()` で作成された複製は自動的には同期されません。

指定された子が `DocumentFragment` である場合、 `DocumentFragment` の内容全体が指定された親ノードの子リストに移動されます。

構文
--

```js
insertBefore(newNode, referenceNode)
```

### 引数

`newNode`

挿入するノードです。

`referenceNode`

`newNode` が挿入される位置の前にあるノードです。このノードが `null` である場合は、 `newNode` はこのノードの子ノードの末尾に挿入されます。

**メモ:** `referenceNode` は省略可能な引数では**ありません**。
 明示的に `Node` または `null` を渡す必要があります。
 渡さなかった場合や無効な値を渡した場合の動作は、ブラウザーのバージョンによって異なる可能性があります。

返値
--

追加された子ノードを返します（ただし `newNode` が `DocumentFragment` の場合は、空の `DocumentFragment` を返します）。

### 例外

挿入前の検証

例
-

### 例 1

```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // 挿入する新しいノードを作成する
 const newNode = document.createElement("span");

 // 親ノードの参照を取得する
 const parentDiv = document.getElementById("childElement").parentNode;

 // テストケース [ 1 ] 開始: 既存の childElement (すべて正しく動作)
 let sp2 = document.getElementById("childElement");
 parentDiv.insertBefore(newNode, sp2);
 // テストケース [ 1 ] 終了

 // テストケース [ 2 ] 開始: childElement が undefined 型の場合
 sp2 = undefined; // "childElement" の ID を持つノードが存在しない
 parentDiv.insertBefore(newNode, sp2); // Node 型に暗黙に動的型変換
 // テストケース [ 2 ] 終了

 // テストケース [ 3 ] 開始: childElement が "undefined" (文字列) の場合
 sp2 = "undefined"; // "childElement" の ID を持つノードが存在しない
 parentDiv.insertBefore(newNode, sp2); // "Type Error: Invalid Argument" が発生
 // テストケース [ 3 ] 終了
</script>
```

### 例 2

```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // 新しいただの <span> 要素を作成
 let sp1 = document.createElement("span");

 // 参照要素を取得
 let sp2 = document.getElementById("childElement");
 // 親要素を取得
 let parentDiv = sp2.parentNode;

 // 新しい要素を sp2 の手前に挿入
 parentDiv.insertBefore(sp1, sp2);
</script>
```

**メモ:** `insertAfter()` メソッドはありません。
 これは `insertBefore` メソッドと `Node.nextSibling` の組み合わせでエミュレートできます。

前の例では、 `sp1` は以下のようにして `sp2` の後に挿入することができます。

```js
parentDiv.insertBefore(sp1, sp2.nextSibling);
```

`sp2` に次の兄弟ノードがない場合、これが最後の子ノードです。 — `sp2.nextSibling` は `null` を返し、 `sp1` は子ノードリストの末尾（`sp2` の直後）に挿入されます。

### 例 3

要素を最初の子要素の前に挿入するために、 `firstChild` プロパティを使用します。

```js
// 親ノードを取得
let parentElement = document.getElementById("parentElement");
// 親ノードの最初の子ノードを取得
let theFirstChild = parentElement.firstChild;

// 新しい要素を取得
let newElement = document.createElement("div");

// 最初の子ノードの前に新しい要素を挿入
parentElement.insertBefore(newElement, theFirstChild);
```

要素に最初の子ノードがない場合、 `firstChild` は `null` になります。その場合も、要素は親ノードの最後の子ノードの後に追加されます。

親要素に最初の子ノードがない場合は、最後の子ノードもありません。結果的に、新しく挿入された要素は**唯一の**要素になります。

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-insertbefore |

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

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

関連情報
----

* `Node.removeChild()`
* `Node.replaceChild()`
* `Node.appendChild()`
* `Node.hasChildNodes()`
* `Element.insertAdjacentElement()`
* `Element.prepend()`
* `Element.before()`
* `Element.after()`


Node: ownerDocument プロパティ - Web API

Node: ownerDocument プロパティ
=========================

**`ownerDocument`** は `Node` インターフェイスの読み取り専用プロパティで、このノードの最上位の文書オブジェクトを返します。

値
-

すべての子ノードが作成された最上位の `Document` オブジェクトです。

このプロパティが文書自身のノードで使用された場合、値は `null` になります。

例
-

```js
// 指定された "p" から、文書オブジェクトの子である最上位の HTML を取得します。

const d = p.ownerDocument;
const html = d.documentElement;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-ownerdocument① |

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

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


Node: nodeValue プロパティ - Web API

Node: nodeValue プロパティ
=====================

**`nodeValue`** は `Node` インターフェイスのプロパティで、現在のノードの値を返したり設定したりします。

値
-

 もしあれば、現在のノードの値を含む文字列です。
 文書自身においては、 `nodeValue` は `null` を返します。
 テキスト、コメント、 CDATA ノードでは、 `nodeValue` はノードの内容を返します。
 属性ノードにおいては、属性の値が返します。

以下の表はノードの種類別の返値を表しています。

| ノード | nodeValue の値 |
| --- | --- |
| `CDATASection` | CDATA セクションの中身 |
| `Comment` | コメントの中身 |
| `Document` | `null` |
| `DocumentFragment` | `null` |
| `DocumentType` | `null` |
| `Element` | `null` |
| `NamedNodeMap` | `null` |
| `ProcessingInstruction` | 対象を除く内容物全体 |
| `Text` | テキストノードの中身 |

**メモ:** `nodeValue` が `null` になると定義されている場合は、設定しても効果がありません。

例
-

```html
<div id="d1">Hello world</div>
<!-- コメントの例 -->
<output id="result">結果が出ていません。</output>
```

また、以下のスクリプトを参照してください。

```js
let node = document.querySelector("body").firstChild;
let result = "<br/>ノード名:<br/>";
while (node) {
  result += `${node.nodeName} の値: ${node.nodeValue}<br/>`;
  node = node.nextSibling;
}

const output = document.getElementById("result");
output.innerHTML = result;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-nodevalue |

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

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


Node: cloneNode() メソッド - Web API

Node: cloneNode() メソッド
======================

**`cloneNode()`** は `Node` インターフェイスのメソッドで、このメソッドが呼び出されたノードの複製を返します。
 引数でノードに含まれるサブツリーを一緒に複製するかどうかを制御できます。

ノードを複製すると、固有（インライン）のリスナーを含む、ノードのすべての属性とその値が複製されます。 `addEventListener()` を使って追加されたイベントリスナーや、要素のプロパティに代入されたイベントリスナー（例: `node.onclick = someFunction`）は複製されません。さらに、 `<canvas>` 要素では、描画された画像は複製されません。

**警告:** `cloneNode()` を使用すると、文書内で要素の ID が重複する可能性があります。

元のノードに `id` 属性があり、複製を同じ文書に配置する場合は、複製の ID が重複しないように変更してください。

また、 `name` 属性も重複した名前を使わない場面では、変更する必要があるかもしれません。

**異なる**文書にノードを複製する場合は、代わりに `Document.importNode()` を使用してください。

構文
--

```js
cloneNode()
cloneNode(deep)
```

### 引数

`deep` 省略可

`true` の場合、ノードとそのサブツリーは、子ノードの `Text` にあるテキストも含め複製されます。

`false` の場合、このノードのみが複製されます。
 サブツリーは、そのノードに含まれているテキストも含め、複製されません。

なお、 `deep` は `<img>` や `<input>` のような空要素には効果がありません。

### 返値

 複製された `Node` を返します。
 複製されたノードには、文書に所属する他のノードに `Node.appendChild()` などを使用して追加されるまで、親ノードがなく、文書にも所属していません。

例
-

```js
let p = document.getElementById("para1");
let p_prime = p.cloneNode(true);
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-clonenode① |

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

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