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

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

**`isSameNode()`** は `Node` インターフェイスのメソッドで、 `===` 厳密等価演算子の古い別名です。
 すなわち、 2 つのノードが全く同じであるかどうか（言い換えれば、同じオブジェクトを指しているかどうか）を検査します。

**メモ:** `isSameNode()` を使用する必要はありません。 `===` 厳密等価演算子を使用してください。

構文
--

```js
isSameNode(otherNode)
```

### 引数

`otherNode`

検査対象となる `Node` です。

**メモ:** この引数は省略可能ではありませんが、 `null` に設定することはできます。

### 返値

論理値で、両ノードが厳密に等しい場合は `true`、そうでなければ `false` です。

例
-

この例では、 3 つの `<div>` ブロックを作成しています。 1 つ目と 3 つ目は内容と属性が同じであり、 2 つ目は異なっています。このとき、`isSameNode()` を使って JavaScript でノードを比較した結果は以下のようになります。

### HTML

```html
<div>最初の要素です。</div>
<div>2 番目の要素です。</div>
<div>最初の要素です。</div>

<p id="output"></p>
```

```
#output {
  width: 440px;
  border: 2px solid black;
  border-radius: 5px;
  padding: 10px;
  margin-top: 20px;
  display: block;
}
```

### JavaScript

```js
let output = document.getElementById("output");
let divList = document.getElementsByTagName("div");

output.innerHTML += `div 0 と div 0 は同じか: ${divList[0].isSameNode(
 divList[0],
)}<br/>`;
output.innerHTML += `div 0 と div 1 は同じか: ${divList[0].isSameNode(
 divList[1],
)}<br/>`;
output.innerHTML += `div 0 と div 2 は同じか: ${divList[0].isSameNode(
 divList[2],
)}<br/>`;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-issamenode |

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

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

関連情報
----

* `Node.isEqualNode()`


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

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

**`compareDocumentPosition()`** は `Node` インターフェイスのメソッドで、引数のノードの位置を、呼び出されたノードからの相対位置で報告します。

構文
--

```js
compareDocumentPosition(otherNode)
```

### 引数

`otherNode`

`Node` で、このノードとの相対位置を報告するノードを指定します。

### 返値

整数値で、 `otherNode` の `node` から見た相対位置を、以下の `Node` の定数プロパティを組み合わせたビットマスクで表します。

`Node.DOCUMENT_POSITION_DISCONNECTED` (`1`)

両方のノードが、異なる文書、または同じ文書の異なるツリーにあります。

`Node.DOCUMENT_POSITION_PRECEDING` (`2`)

`otherNode` はこのノードより、両者を含むツリーの前順深さ優先走査で前にある（祖先ノード、前にある兄弟ノード、前にある兄弟ノードの子孫ノード、祖先ノードの前にある兄弟ノードなど）か、（接続されていないのであれば）任意だが一貫した順序で、そのノードよりも前に位置します。

`Node.DOCUMENT_POSITION_FOLLOWING` (`4`)

`otherNode` はこのノードより、両者を含むツリーの前順深さ優先走査で後にある（子孫ノード、後にある兄弟ノード、後にある兄弟ノードの子孫ノード、祖先ノードの後にある兄弟ノードなど）か、（接続されていないのであれば）任意だが一貫した順序で、そのノードよりも後に位置します。

`Node.DOCUMENT_POSITION_CONTAINS` (`8`)

`otherNode` はこのノードの祖先ノードです。

`Node.DOCUMENT_POSITION_CONTAINED_BY` (`16`)

`otherNode` はこのノードの子孫ノードです。

`Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC` (`32`)

その結果は、任意や実装固有の動作に依存し、移植性は保証されません。

複数の条件に適合する場合、複数のビットが設定されることがあります。例えば、 `otherNode` が文書中でより先にあり、***かつ*** `compareDocumentPosition()` が呼び出されたノードを含んでいれば、 `DOCUMENT_POSITION_CONTAINS` と `DOCUMENT_POSITION_PRECEDING` の両ビットが設定され、 `10` (`0x0A`) という値になります。

例
-

```js
const head = document.head;
const body = document.body;

if (head.compareDocumentPosition(body) & Node.DOCUMENT\_POSITION\_FOLLOWING) {
  console.log("正しい形式の文書です");
} else {
  console.error("<head> が <body> の前にありません");
}
```

**メモ:** `compareDocumentPosition()` の返値はビットマスクですので、意味のある結果を得るにはビット AND 演算子を使用する必要があります。

仕様書
---

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

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

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

関連情報
----

* `Node.contains()`


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

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

**`contains()`** は `Node` インターフェイスのメソッドで、あるノードが指定されたノードの子孫であるか、すなわち、このノード自体であるか、直接の子ノード (`childNodes`) の何れかであるか、直接の子ノードの子ノードの何れかであるか（以下同様）を示す論理値を返します。

**メモ:** ノードは自分自身に**含まれます**。

構文
--

```js
contains(otherNode)
```

### 引数

`otherNode`

検査する `Node` です。

**メモ:** `otherNode` は省略できませんが、 `null` に設定することはできます。

### 返値

 論理値で、 `true` は `otherNode` がそのノードに含まれていることを表します。
 そうでなければ `false` になります。

`otherNode` 引数が `null` であれば、 `contains()` は常に `false` になります。

例
-

この関数は、ある要素がそのページの body 要素に含まれるかどうかを検査するものです。 `contains` は包括的かつ決定的であるため、 body がそれ自身を含むかどうかは `isInPage` の意図するところではないため、明示的に `false` を返します。

```js
function isInPage(node) {
  return node === document.body ? false : document.body.contains(node);
}
```

仕様書
---

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

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

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

関連情報
----

* `Node.compareDocumentPosition`
* `Node.hasChildNodes`


Node: nodeType プロパティ - Web API

Node: nodeType プロパティ
====================

**`nodeType`** は `Node` インターフェイスの読み取り専用プロパティであり、整数値でこのノードが何であるかを識別します。これは様々なノードの種類、例えば `elements`、`text`、`comments` を見分けます。

値
-

整数値で、このノードの種類を識別します。可能な値は次の通りです。

`Node.ELEMENT_NODE` (`1`)

`<p>` や `<div>` などの `Element` ノードです。

`Node.ATTRIBUTE_NODE` (`2`)

`Element` の `Attribute` ノードです。

`Node.TEXT_NODE` (`3`)

`Element` や `Attr` の中に存在する `Text` です。

`Node.CDATA_SECTION_NODE`(`4`)

`<!CDATA[[ … ]]>` のような `CDATASection` です。

`Node.PROCESSING_INSTRUCTION_NODE` (`7`)

`<?xml-stylesheet … ?>` のような XML 文書の `ProcessingInstruction` です。

`Node.COMMENT_NODE` (`8`)

`<!-- … -->` のような `Comment` ノードです。

`Node.DOCUMENT_NODE` (`9`)

`Document` ノードです。

`Node.DOCUMENT_TYPE_NODE` (`10`)

`<!DOCTYPE html>` のような `DocumentType` ノードです。

`Node.DOCUMENT_FRAGMENT_NODE` (`11`)

`DocumentFragment` ノードです。

`Node.ENTITY_REFERENCE_NODE` (`5`), `Node.ENTITY_NODE` (`6`), `Node.NOTATION_NODE` (`12`) は非推奨になっており、使用されなくなっています。

例
-

様々な種類のノード
---------

```js
document.nodeType === Node.DOCUMENT\_NODE; // true
document.doctype.nodeType === Node.DOCUMENT\_TYPE\_NODE; // true

document.createDocumentFragment().nodeType === Node.DOCUMENT\_FRAGMENT\_NODE; // true

const p = document.createElement("p");
p.textContent = "昔々…";

p.nodeType === Node.ELEMENT\_NODE; // true
p.firstChild.nodeType === Node.TEXT\_NODE; // true
```

### コメント

次の例は、ノードの最初の要素がコメントノードであるかをチェックし、そうでない場合にメッセージを表示するものです。

```js
const node = document.documentElement.firstChild;
if (node.nodeType !== Node.COMMENT\_NODE) {
  console.warn("コメントを入れてください。");
}
```

仕様書
---

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

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

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


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

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

**`removeChild()`** は `Node` インターフェイスのメソッドで、子ノードを DOM から取り除き、取り除いたノードを返します。

**メモ:** 取り除かれた子ノードへの参照が保持されている限り、子ノードはメモリー内に残りますが、 DOM の一部ではなくなります。
 これは、後のコードで再利用することができます。

`removeChild()` の返値が保持されず、他の参照もなくなった場合は、まもなくメモリーから自動的に削除されます。

`Node.cloneNode()` とは異なり、返値は関連付けられた `EventListener` オブジェクトを保持します。

構文
--

```js
removeChild(child)
```

### 引数

`child`

`Node` で、 DOM から取り除きたい子ノードを指定します。

### 例外

`NotFoundError` `DOMException`

`child` がこのノードの子ではない場合に発生します。

`TypeError`

`child` が `null` であった場合に発生します。

例
-

### 単純な例

この HTML を使います。

```html
<div id="top">
  <div id="nested"></div>
</div>
```

親ノードが分かる場合に、指定された要素を取り除きます。

```js
let d = document.getElementById("top");
let d_nested = document.getElementById("nested");
let throwawayNode = d.removeChild(d_nested);
```

親ノードが分からないときに指定された要素を取り除きます。

```js
let node = document.getElementById("nested");
if (node.parentNode) {
  node.parentNode.removeChild(node);
}
```

ある要素からすべての子を削除します。

```js
let element = document.getElementById("idOfParent");
while (element.firstChild) {
  element.removeChild(element.firstChild);
}
```

### TypeError が発生する例

```html
<!--HTML コードの例-->
<div id="top"></div>
```

```js
let top = document.getElementById("top");
let nested = document.getElementById("nested");

// TypeError が発生
let garbage = top.removeChild(nested);
```

### NotFoundError が発生する例

```html
<!--HTML コードの例-->
<div id="top">
  <div id="nested"></div>
</div>
```

```js
let top = document.getElementById("top");
let nested = document.getElementById("nested");

// 最初の呼び出しでは正しくノードを取り除く
let garbage = top.removeChild(nested);

// NotFoundError が発生
garbage = top.removeChild(nested);
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-removechild |

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

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

関連情報
----

* `Node.replaceChild()`
* `Node.parentNode`
* `Element.remove()`
* `Node.cloneNode()`


Node: lastChild プロパティ - Web API

Node: lastChild プロパティ
=====================

**`lastChild`** は `Node` インターフェイスの読み取り専用プロパティで、このノードの最後の子ノードを返します。子ノードがない場合は `null` を返します。

**メモ:** このプロパティは、このノードの最後の子ノードである任意の種類のノードを返す。
 `Text` や `Comment` ノードである可能性があります。
 他の要素の子である最後の `Element` を取得したい場合は、`Element.lastElementChild` の使用を検討してください。

値
-

このノードの最後の子である `Node`、または子ノードがなければ `null` です。

例
-

```js
const tr = document.getElementById("row1");
const corner_td = tr.lastChild;
```

仕様書
---

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

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

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

関連情報
----

* `Node.firstChild`
* `Element.lastElementChild`


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

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

**`replaceChild()`** は `Node` インターフェイスのメソッドで、この（親）ノードの中の子ノードを置き換えます。

構文
--

```js
replaceChild(newChild, oldChild)
```

### 引数

`newChild`

`oldChild` を置き換える新しいノードです。

**警告:** 新しいノードが既に DOM のどこか別なところにある場合は、まずその位置から取り除かれます。

`oldChild`

置き換えられる子ノードです。

**メモ:** 引数の順序で、*新しい*ものの前に*古い*ものが来るのは異例です。
 `Element.replaceWith()` は、要素であるノードのみに適用されるものですが、読んだり使用したりしやすいかもしれません。

### 返値

置き換えられた `Node` です。これは `oldChild` と同じノードです。

### 例外

`HierarchyRequestError` `DOMException`

DOM ツリーの制約に違反した場合に発生します。すなわち、以下のいずれかが発生する場合です。

* `oldChild` の親が `Document`, `DocumentFragment`, `Element` のいずれにもならない場合。
* `oldChild` を `newChild` で置き換えると循環参照になる場合。すなわち `newChild` がこのノードの祖先である場合。
* `newChild` が `DocumentFragment`, `DocumentType`, `Element`, `CharacterData` のいずれでもない場合。
* 現在のノードが `Text` であり、親ノードが `Document` になる場合。
* 現在のノードが `DocumentType` であり、その親が `Document` にならない場合。 *doctype* は常に *document* の直下になければならないからです。
* このノードの親が `Document` で `newChild` が `DocumentFragment` であり、複数の `Element` の子、または `Text` の子がある場合。
* `oldChild` を `newChild` で置き換えると、 `Document` の子の `Element` が複数になる場合。
* `oldChild` を `newChild` で置き換えると、 `Element` ノードが `DocumentType` の前になる場合。

`NotFoundError` `DOMException`

`oldChild` の親ノードが現在のノードではない場合に発生します。

例
-

```js
// 前提:
// <div>
// <span id="childSpan">foo bar</span>
// </div>

// ID も属性も内容も持たない空要素を生成
const sp1 = document.createElement("span");

// 生成したノードに id 属性 'newSpan' を付与
sp1.id = "newSpan";

// 新しい要素にいくらかの内容を作成
const sp1_content = document.createTextNode("新しい置換 span 要素");

// その内容を新しい要素に適用
sp1.appendChild(sp1_content);

// 置き換えられる既存のノードの参照を作る
const sp2 = document.getElementById("childSpan");
const parentDiv = sp2.parentNode;

// 既存のノード sp2 を新しい span 要素 sp1 で置換
parentDiv.replaceChild(sp1, sp2);

// 結果:
// <div>
// <span id="newSpan">新しい置換 span 要素</span>
// </div>
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-replacechild |

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

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

関連情報
----

* `Node.removeChild`
* `Element.replaceWith`


Node: selectstart イベント - Web API

Node: selectstart イベント
======================

**`selectstart`** は選択 API のイベントで、新しい選択範囲をユーザが指定した際に発行されます。

イベントがキャンセルされた場合、選択範囲は変更されません。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

```js
// addEventListener バージョン
document.addEventListener("selectstart", () => {
  console.log("選択が開始されました");
});

// onselectstart バージョン
document.onselectstart = () => {
  console.log("選択が開始されました。");
};
```

仕様書
---

| Specification |
| --- |
| Selection API # selectstart-event |
| Selection API # dom-globaleventhandlers-onselectstart |

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

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

関連情報
----

* `selectionchange`


Node: previousSibling プロパティ - Web API

Node: previousSibling プロパティ
===========================

**`previousSibling`** は `Node` インターフェイスの読み取り専用プロパティで、指定されたノードの親ノードの `childNodes` リスト内で、直前にある ノードを返します。指定されたノードがリストの先頭にあった倍は `null` を返します。

**メモ:** ブラウザーはソースのマークアップにあるホワイトスペースを表すために、文書にテキストノードを挿入します。
 そのため、例えば `Node.firstChild` や `Node.previousSibling` を使用して得たノードが、取得しようとした実際のノードではなく、ホワイトスペースのテキストノードであることがあります。

DOM でのホワイトスペースの記事に、この動作に関する詳しい情報があります。

`previousElementSibling` を使用すると、（テキストノードやその他の要素以外のノードを飛ばして）前の要素を取得することができます。

子ノードのリストで反対方向に移動する場合は、 Node.nextSibling を使用してください。

値
-

 現在のノードの直前のノードを表す `Node` です。
 存在しない場合は `null` です。

例
-

次の例では、要素にテキストノードがある場合とない場合の `previousSibling` の動作を示しています。

### 最初の例

この例では、一連の `img` 要素が互いに隣り合っており、その間にホワイトスペースがありません。

```html
<img id="b0" /><img id="b1" /><img id="b2" />
```

```js
document.getElementById("b1").previousSibling; // <img id="b0">
document.getElementById("b2").previousSibling.id; // "b1"
```

### 2 番目の例

この例では、 `img` 要素の間にホワイトスペースのテキストノード（改行）があります。

```html
<img id="b0" />
<img id="b1" />
<img id="b2" />
```

```js
document.getElementById("b1").previousSibling; // #text
document.getElementById("b1").previousSibling.previousSibling; // <img id="b0">
document.getElementById("b2").previousSibling.previousSibling; // <img id="b1">
document.getElementById("b2").previousSibling; // #text
document.getElementById("b2").previousSibling.id; // undefined
```

仕様書
---

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

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

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

関連情報
----

* `Node.nextSibling`
* `Element.previousElementSibling`


Node: nodeName プロパティ - Web API

Node: nodeName プロパティ
====================

**`nodeName`** は `Node` の読み取り専用プロパティで、現在のノードの名前を文字列で返します。

値
-

文字列です。ノードの種類によって、次のような値になります。

`Attr`

`Attr.name` の値で、この属性の*修飾名*です。

`CDATASection`

`"#cdata-section"` という文字列です。

`Comment`

`"#comment"` という文字列です。

`Document`

`"#document"` という文字列です。

`DocumentFragment`

`"#document-fragment"` という文字列です。

`DocumentType`

`DocumentType.name` の値です。

`Element`

`Element.tagName` の値です。これは HTML 要素であればその要素のタグの*大文字の*名前であり、 XML 要素（SVG や MathML の要素）であればその要素のタグの*小文字の*名前です。

`ProcessingInstruction`

`ProcessingInstruction.target` の値です。

`Text`

`"#text"` という文字列です。

例
-

この例では、様々なノードのノード名を表示します。

```html
こちらは HTML です。
<div id="d1">Hello world</div>
<!-- コメントの例 -->
テキスト<span>テキスト</span> テキスト<br />
<svg height="20" width="20">
  <circle cx="10" cy="10" r="5" stroke="black" stroke-width="1" fill="red" />
</svg>
<hr />
<output id="result">まだ出力されていません。</output>
```

また、スクリプトは以下の通りです。

```js
let node = document.querySelector("body").firstChild;
let result = "ノード名:<br/>";
while (node) {
  result += `${node.nodeName}<br/>`;
  node = node.nextSibling;
}

const output = document.getElementById("result");
output.innerHTML = result;
```

仕様書
---

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

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

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

関連情報
----

* `Element.tagName`
* `Attr.name`
* `DocumentType.name`
* `ProcessingInstruction.target`


Node: childNodes プロパティ - Web API

Node: childNodes プロパティ
======================

**`childNodes`** は `Node` インターフェイスの読み取り専用プロパティであり、`NodeList` で指定された要素の子ノードの生きたリストを返し、最初の子ノードは位置 `0` に割り当てられます。子ノードには要素、テキスト、コメントが含まれます。

**メモ:** `NodeList` が生きたリストであるというのは、新しい子が追加されたり取り除かれたりするたびに、内容が変化するという意味です。

ノードのコレクションの項目はオブジェクトであり、文字列ではありません。ノードオブジェクトからデータを取得するには、そのプロパティを使用してください。例えば、最初の子ノードの名前を取得するには、 `elementNodeReference.childNodes[0].nodeName` を使うことで実現できます。

`document` オブジェクト自体には 2 つの子があります。文書型宣言と、ルート要素、ふつうは `documentElement` として参照されます。 HTML 文書の場合、後者は `<html>` 要素です。

 覚えておくべき重要なこととして、 `childNodes` には*すべての*子ノードが含まれ、テキストやコメントなどの要素以外のノードが含まれることです。
 要素のみが含まれるコレクションを取得するのであれば、 `Element.children` を代わりに使用してください。

値
-

このノードの子を含む生きた `NodeList` です。

**メモ:** `childNodes` を複数回呼び出しても、*同じ* `NodeList` が返されます。

例
-

### 単純な使用方法

```js
// parg は <p> 要素へのオブジェクト参照であることに注意

// まず、要素に子ノードがあるかどうかをチェックします
if (parg.hasChildNodes()) {
  let children = parg.childNodes;

  for (const node of children) {
    // それぞれの子を children[i] として処理します
    // 注: リストは生きています。子を追加したり取り除いたりすると、リストの `length` が変わります
  }
}
```

### ノードからすべての子を削除

```js
// これはあるノードからすべての子を取り除くための一つの方法です
// box はある要素へのオブジェクト参照です
while (box.firstChild) {
  // リストは生きているので、呼び出されるたびにインデックスが変わります
  box.removeChild(box.firstChild);
}
```

仕様書
---

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

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

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

関連情報
----

* `Node.firstChild`
* `Node.lastChild`
* `Node.nextSibling`
* `Node.previousSibling`
* `Element.children`


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

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

**`isEqualNode()`** は `Node` インターフェイスのメソッドで、 2 つのノードが等しいかどうかを検査します。
 2 つのノードは、同じ型、定義特性（要素の場合、 ID や子ノードの数など）、その属性が一致している場合、等しいといえます。データで一致が求められる具体的な点は、ノードの型によって異なります。

構文
--

```js
isEqualNode(otherNode)
```

### 引数

`otherNode`

比較対象となる `Node` です。

**メモ:** この引数は省略可能ではありませんが、 `null` に設定することはできます。

### 返値

 論理値で、 2 つのノードが等しければ `true`、そうでなければ `false` です。
 `otherNode` が `null` であった場合、 `isEqualNode()` は常に false を返します。

例
-

この例では、 3 つの `<div>` ブロックを作成しています。 1 つ目と 3 つ目は内容と属性が同じであり、 2 つ目は異なっています。このとき、`isEqualNode()` を使って JavaScript でノードを比較した結果は以下のようになります。

### HTML

```html
<div>最初の要素です。</div>
<div>2 番目の要素です。</div>
<div>最初の要素です。</div>

<p id="output"></p>
```

```
#output {
  width: 440px;
  border: 2px solid black;
  border-radius: 5px;
  padding: 10px;
  margin-top: 20px;
  display: block;
}
```

### JavaScript

```js
let output = document.getElementById("output");
let divList = document.getElementsByTagName("div");

output.innerHTML += `div 0 と div 0 は同じか: ${divList[0].isEqualNode(
 divList[0],
)}<br/>`;
output.innerHTML += `div 0 と div 1 は同じか: ${divList[0].isEqualNode(
 divList[1],
)}<br/>`;
output.innerHTML += `div 0 と div 2 は同じか: ${divList[0].isEqualNode(
 divList[2],
)}<br/>`;
```

### 結果

仕様書
---

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

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

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

関連情報
----

* `Node.isSameNode()`


Node: parentNode プロパティ - Web API

Node: parentNode プロパティ
======================

**`parentNode`** は `Node` インターフェイスの読み取り専用プロパティで、 DOM ツリー内の特定のノードの親ノードを返します。

`Document` および `DocumentFragment` ノードには親が付くことはないので、 `parentNode` は常に `null` になります。
 ノードが生成されてからツリーに割り当てられていない場合も `null` を返します。

値
-

現在のノードの親に当たる `Node` です。要素の親になるのは `Element` ノード、 `Document` ノード、 `DocumentFragment` ノードの何れかです。

例
-

```js
if (node.parentNode) {
  // ノードがツリーの中にある場合は、ツリーから取り除く
  node.parentNode.removeChild(node);
}
```

仕様書
---

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

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

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

関連情報
----

* `Node.firstChild`
* `Node.lastChild`
* `Node.childNodes`
* `Node.nextSibling`
* `Node.parentElement`
* `Node.previousSibling`
* `Node.removeChild`


Node: firstChild プロパティ - Web API

Node: firstChild プロパティ
======================

**`firstChild`** は `Node` インターフェイスの読み取り専用プロパティで、ツリー内におけるこのノードの最初の子、またはこのノードに子がない場合は `null` を返します。

このノードが `Document` であった場合は、このプロパティは直接のこのリスト内で最初のノードを返します。

**メモ:** このプロパティはこのノードの最初の子であれば、あらゆる種類のノードを返します。
 `Text` または `Comment` ノードになることがあります。
 他の要素の子である最初の `Element` を取得したい場合は、 `Element.firstElementChild` を使用することを検討してください。

値
-

`Node`、または存在しなければ `null`。

例
-

次の例では `firstChild` の使用方法と、このプロパティを使用すると空白ノードがどのように影響するかを示しています。

```html
<p id="para-01">
  <span>最初の span</span>
</p>

<script>
 const p01 = document.getElementById("para-01");
 console.log(p01.firstChild.nodeName);
</script>
```

上記の例ではコンソールに '#text' と表示されます。開始タグ `<p>` の末尾と `<span>` タグとの間にある空白を調整するためにテキストノードが挿入されているためです。**あらゆる**ホワイトスペースは、単一の空白から複数のスペース、改行、タブに至るまで、 1 つの `#text` ノードを生成します。

`#text` ノードはもう 1 つ、閉じタグ `</span>` と `</p>` の間に挿入されます。

ホワイトスペースをソースから取り除くと、 #text ノードは挿入されず、 span 要素がその段落の最初の子になります。

```html
<p id="para-01"><span>最初の span</span></p>

<script>
 const p01 = document.getElementById("para-01");
 console.log(p01.firstChild.nodeName);
</script>
```

コンソールには 'SPAN' と表示されるようになります。

`node.firstChild` が `#text` や `#comment` ノードを返す問題を回避するには、 `Element.firstElementChild` を使用すると最初の要素ノードのみを返すことができます。

仕様書
---

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

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

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

関連情報
----

* `Element.firstElementChild`
* `Node.lastChild`


Node: isConnected プロパティ - Web API

Node: isConnected プロパティ
=======================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
**`isConnected`** は `Node` インターフェイスの読み出し専用のプロパティで、ノードが `Document` オブジェクトに（直接的または間接的に）接続されているかどうかを示す論理値を返します。

値
-

論理値で、 `true` はこのノードが関連するコンテキストオブジェクトに接続されていることを表し、 `false` は接続していないことを表します。

例
-

### 標準 DOM

標準 DOM の例です。

```js
let test = document.createElement("p");
console.log(test.isConnected); // Returns false
document.body.appendChild(test);
console.log(test.isConnected); // Returns true
```

### シャドウ DOM

シャドウ DOM の例です。

```js
// シャドウルートを生成
const shadow = this.attachShadow({ mode: "open" });

// いくらかの CSS を作成してシャドウ DOM に適用
const style = document.createElement("style");
console.log(style.isConnected); // returns false

style.textContent = `
.wrapper {
 position: relative;
}

.info {
 font-size: 0.8rem;
 width: 200px;
 display: inline-block;
 border: 1px solid black;
 padding: 10px;
 background: white;
 border-radius: 10px;
 opacity: 0;
 transition: 0.6s all;
 positions: absolute;
 bottom: 20px;
 left: 10px;
 z-index: 3
}
`;

// 生成された style 要素をシャドウ DOM に取り付ける

shadow.appendChild(style);
console.log(style.isConnected); // Returns true
```

仕様書
---

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

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

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

関連情報
----

* Node.prototype.isConnected polyfill


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

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

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
**`getRootNode()`** は `Node` インターフェイスのメソッドで、そのコンテキストのオブジェクトのルート、利用できる場合はオプションでシャドウルートを含んだものを返します。

構文
--

```js
getRootNode()
getRootNode(options)
```

### 引数

`options` 省略可

ルートノードを取得するためのオプションを設定するオブジェクトです。利用可能なオプションは次の通りです。

* `composed`: 論理値で、シャドウルートを返すか (`false`、既定値)、またはシャドウルートを越えたルートノードを返すか (`true`) を示します。

### 返値

`Node` を継承したオブジェクトです。これはどこで `getRootNode()` を呼び出したかによって異なる形になります。例えば、

* 標準のウェブページ内の要素に対して呼び出した場合は、ページ全体を表す `HTMLDocument` オブジェクトを返します。
* シャドウ DOM の中の要素に対して呼び出した場合は、関連する `ShadowRoot` オブジェクトを返します。
例
-

### 例 1

最初に、 HTML/document ノードの参照を返す単純な例です。

```js
const rootNode = node.getRootNode();
```

### 例 2

この例はもっと複雑で、通常のルートを返す場合と、シャドウルートを含むルートの違いを示します。

```html
<div class="parent">
  <div class="child"></div>
</div>
<div class="shadowHost">shadowHost</div>
<pre id="output">Output: </pre>
```

```js
const parent = document.querySelector(".parent");
const child = document.querySelector(".child");
const shadowHost = document.querySelector(".shadowHost");
const output = document.getElementById("output");

output.textContent += `\nparent's root: ${parent.getRootNode().nodeName} \n`; // #document
output.textContent += `child's root: ${child.getRootNode().nodeName} \n\n`; // #document

// ShadowRoot の生成
const shadowRoot = shadowHost.attachShadow({ mode: "open" });
shadowRoot.innerHTML =
  '<style>div{background:#2bb8aa;}</style><div class="shadowChild">shadowChild</div>';
const shadowChild = shadowRoot.querySelector(".shadowChild");

// 合成の既定値は false
output.textContent += `shadowChild.getRootNode() === shadowRoot : ${
 shadowChild.getRootNode() === shadowRoot
} \n`; // true
output.textContent += `shadowChild.getRootNode({composed:false}) === shadowRoot : ${
 shadowChild.getRootNode({ composed: false }) === shadowRoot
} \n`; // true
output.textContent += `shadowChild.getRootNode({composed:true}).nodeName : ${
 shadowChild.getRootNode({ composed: true }).nodeName
} \n`; // #document
```

仕様書
---

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

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

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


Node: nextSibling プロパティ - Web API

Node: nextSibling プロパティ
=======================

**`nextSibling`** は `Node` インターフェイスの読み取り専用プロパティで、指定されたノードの親の `childNodes` の中で、そのすぐ次のノードを返します。または、指定されたノードが親要素の最後の子要素である場合は `null` を返します。

**メモ:** ブラウザーはソースのマークアップにあるホワイトスペースを表すために、文書に `Text` ノードを挿入します。
 そのため、例えば `Node.firstChild` や `Node.previousSibling` を使用して得たノードが、取得しようとした実際のノードではなく、ホワイトスペースのテキストノードであることがあります。

DOM でのホワイトスペースの記事に、この動作に関する詳しい情報があります。

`Element.nextElementSibling` を使用すると、ホワイトスペースのノードや要素間のテキスト、コメントなどを飛ばして次の要素を取得することができます。

子ノードのリストで反対方向に移動する場合は、 Node.previousSibling を使用してください。

値
-

現在のノードの次の兄弟ノードを表す `Node`、または存在しない場合は `null` です。

例
-

```html
<div id="div-1">こちらは div-1 です。</div>
<div id="div-2">こちらは div-2 です。</div>
<br />
<output><em>計算結果がありません。</em></output>
```

```js
let el = document.getElementById("div-1").nextSibling;
let i = 1;

let result = "div-1 の兄弟要素:<br/>";

while (el) {
  result += `${i}. ${el.nodeName}<br/>`;
  el = el.nextSibling;
  i++;
}

const output = document.querySelector("output");
output.innerHTML = result;
```

仕様書
---

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

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

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

関連情報
----

* `Element.nextElementSibling`
* `Node.previousSibling`


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

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

**`appendChild()`** は `Node` インターフェイスのメソッドで、指定された親ノードの子ノードリストの末尾にノードを追加します。追加しようとしたノードが既に存在していた場合は、 `appendChild()` はその子ノードを現在の位置から新しい位置へ移動します。

 指定された子ノードが `DocumentFragment` であった場合、その
 `DocumentFragment` の内容全体が指定された親ノードの子ノードリストに移動します。

`appendChild()` は、新しく追加されたノードを返します。また、子が `DocumentFragment` であれば、空になったフラグメントを返します。

**メモ:** このメソッドとは異なり、 `Element.append()` メソッドは複数の引数や文字列の追加に対応しています。ノードが要素であった場合は、こちらを使用することができます。

構文
--

```js
appendChild(aChild)
```

### 引数

`aChild`

指定された親ノードに追加するノード（ふつうは要素）。

### 返値

`Node` で追加された子ノード (`aChild`) を返します。
 ただし、 `aChild` が `DocumentFragment` であった場合は、空の `DocumentFragment` を返します。

### 例外

`HierarchyRequestError` `DOMException`

DOM ツリーの制約に違反した場合に発生します。すなわち、以下のいずれかが発生する場合です。

* `aChild` の親が `Document`, `DocumentFragment`, `Element` のいずれにもならない場合。
* `aChild` を挿入すると循環参照になる場合。すなわち `aChild` がこのノードの祖先である場合。
* `aChild` が `DocumentFragment`, `DocumentType`, `Element`, `CharacterData` のいずれでもない場合。
* 現在のノードが `Text` であり、親ノードが `Document` になる場合。
* 現在のノードが `DocumentType` であり、その親が `Document` にならない場合。 *doctype* は常に *document* の直下になければならないからです。
* このノードの親が `Document` で `aChild` が `DocumentFragment` であり、複数の `Element` の子、または `Text` の子がある場合。
* `aChild` を挿入すると `Document` の子の `Element` が複数になる場合。

解説
--

指定された子ノードが文書内の既存のノードへの参照である場合、 `appendChild()` はそのノードを現在の位置から新しい位置に移動させます。つまり、あるノードが文書内の2点に同時に存在することはできません。新しい親の下にノードを追加する前に、ノードのコピーを作成するには `Node.cloneNode()` メソッドを使用することができます。`cloneNode` で作成されたコピーは、自動的に同期されるわけではありません。

`appendChild()`は親ノードではなく、新しく追加されたノードを返します。つまり、新しいノードが作成されたらすぐに、そのノードへの参照を失うことなく、追加することができます。

```js
const paragraph = document.body.appendChild(document.createElement("p"));
// 段落に後から要素を追加することも可能です
```

一方で、`appendChild()` は fluent API 流に（JQuery のように）使用することはできません。

```js
// 3 つの段落を追加することはできません。
// 代わりに、3 つの段落は入れ子になります。
document.body
  .appendChild(document.createElement("p"))
  .appendChild(document.createElement("p"))
  .appendChild(document.createElement("p"));
```

例
-

### 本文に段落を追加

```js
// 新しい段落要素を作成し、文書の body の末尾に追加します。
const p = document.createElement("p");
document.body.appendChild(p);
```

### 入れ子構造の DOM の作成

この例では、いくつかある一時変数をできるだけ使用して、入れ子の DOM 構造を作成することを試みています。

```js
const fragment = document.createDocumentFragment();
const li = fragment
  .appendChild(document.createElement("section"))
  .appendChild(document.createElement("ul"))
  .appendChild(document.createElement("li"));
li.textContent = "hello world";

document.body.appendChild(fragment);
```

以下のような DOM ツリーが生成されます。

```html
<section>
  <ul>
    <li>hello world</li>
  </ul>
</section>
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-appendchild |

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

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

関連情報
----

* `Node.removeChild()`
* `Node.replaceChild()`
* `Node.insertBefore()`
* `Node.hasChildNodes()`
* `Element.insertAdjacentElement()`
* `Element.append()`


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

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

**`lookupNamespaceURI()`** は `Node` インターフェイスのメソッドで、引数として接頭辞を受け取り、このノードに関連付けられた名前空間が見つかれば、その URI を返します（見つからなければ `null` を返します）。

構文
--

```js
lookupNamespaceURI(prefix)
```

### 引数

`prefix`

検索する接頭辞です。

**メモ:** この引数は省略可能ではありませんが、 `null` に設定することはできます。

### 返値

 指定された接頭辞に対応する名前空間 URI の入った文字列です。
 接頭辞が見つからない場合、 `null` を返します。
 要求された `prefix` が `null` である場合は、既定の名前空間 URI を返します。

例
-

```html
Namespace URL for <code>xlink</code> on <output>:
<output>未検査</output>.<br />
Namespace URL for <code>xml</code> on <output>:
<output>未検査</output>.<br />
Namespace URL for <code>html</code> on <output>:
<output>未検査</output>.<br />
Namespace URL for <code>``</code> on <output>:
<output>未検査</output>.<br />
Namespace URL for <code>svg</code> on <svg>:
<output>未検査</output>.<br />
Namespace URL for <code>xlink</code> on <svg>:
<output>未検査</output>.<br />
Namespace URL for <code>xml</code> on <svg>:
<output>未検査</output>.<br />
<svg xmlns:svg="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.lookupNamespaceURI("xlink");
  result[1].value = aHtmlElt.lookupNamespaceURI("xml");
  result[2].value = aHtmlElt.lookupNamespaceURI("html");
  result[3].value = aHtmlElt.lookupNamespaceURI("");
  result[4].value = aSvgElt.lookupNamespaceURI("svg");
  result[5].value = aSvgElt.lookupNamespaceURI("xlink");
  result[6].value = aSvgElt.lookupNamespaceURI("xml");
});
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-node-lookupnamespaceuri |

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

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

関連情報
----

* `Node.lookupPrefix`
* `Node.isDefaultNameSpace`


location: assign() メソッド - Web API

location: assign() メソッド
=======================

**`Location.assign()`** メソッドは、指定された URL の文書をウィンドウに読み込んで表示します。移動した後、ユーザーは「戻る」ボタンを押すことによって `Location.assign()` を呼び出したページに戻ることができます。

セキュリティ違反のために代入ができない場合は、 `DOMException` が `SECURITY_ERROR` 型で発生します。これは、メソッドを呼び出すスクリプトのオリジンが、 `Location` オブジェクトによって元々記述されていたページのオリジンと異なる場合に起こります。主に、スクリプトが異なるドメインでホストされている場合に起こります。

指定された URL が有効でない場合、 `DOMException` が `SYNTAX_ERROR` 型で発生します。

構文
--

```js
assign(url)
```

### 引数

`url`

文字列で、移動先のページの URL です。

### 返値

なし (`undefined`)。

例
-

```js
// Location.reload の記事へ移動
window.location.assign(
  "https://developer.mozilla.org/ja/docs/Web/API/Location/reload",
);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-assign-dev |

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

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

関連情報
----

* 所属先の `Location` インターフェイス
* 同様のメソッド: `Location.replace()` および `Location.reload()`


location: hostname プロパティ - Web API

location: hostname プロパティ
========================

**`hostname`** は `Location` インターフェイスのプロパティで、URL のドメインが入った文字列です。

値
-

文字列です。

例
-

```js
const anchor = document.createElement("a");
anchor.href = "https://developer.mozilla.org:4097/ja/docs/Location.hostname";

console.log(anchor.hostname); // developer.mozilla.org
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-hostname-dev |

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

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


location: host プロパティ - Web API

location: host プロパティ
====================

**`host`** は `Location` インターフェイスのプロパティで、ホスト、すなわち*ホスト名*と、 URL の*ポート番号*が空でなければ、 `':'` およびその*ポート番号*の入った文字列です。

値
-

文字列です。

例
-

```js
const anchor = document.createElement("a");

anchor.href = "https://developer.mozilla.org/en-US/Location.host";
console.log(anchor.host === "developer.mozilla.org");

anchor.href = "https://developer.mozilla.org:443/en-US/Location.host";
console.log(anchor.host === "developer.mozilla.org");
// 443 はこのスキームの既定のポートなので含まれない

anchor.href = "https://developer.mozilla.org:4097/en-US/Location.host";
console.log(anchor.host === "developer.mozilla.org:4097");
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-host-dev |

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

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


location: port プロパティ - Web API

location: port プロパティ
====================

**`port`** は `Location` インターフェイスのプロパティで、URL のポート番号が入った文字列です。URL に明示的にポート番号が指定されていない場合は、`''` に設定されます。

値
-

文字列です。

例
-

```js
// 文書内に <a id="myAnchor" href="/ja/docs/Location.search?q=123"> 要素があるとする
const anchor = document.getElementByID("myAnchor");
const result = anchor.port; // Returns:'443'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-port-dev |

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

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


location: reload() メソッド - Web API

location: reload() メソッド
=======================

**`location.reload()`** メソッドは、再読み込みボタンのように現在の URL を再読み込みします。

再読み込みはブロックされ、 `SECURITY_ERROR` の `DOMException` が発生する可能性があります。これは、 `location.reload()` を呼び出すスクリプトのオリジンが、 `Location` オブジェクトを保持するページのオリジンと異なる場合に発生します。詳細については、同一オリジンポリシーを参照してください。

構文
--

```js
reload()
```

### 引数

なし。

**メモ:** Firefox は標準外の論理値の `forceGet` 引数 を `location.reload()` で対応しており、 Firefox にキャッシュをバイパスして現在の文書を強制的に再読み込みするように指示することができます。しかし、他のすべてのブラウザーでは、`location.reload()` の呼び出しで指定した引数は無視され、いかなる効果も持ちません。

しかし、すべてのブラウザーで強制再読み込みの効果が発生することを前提に書かれた既存のコードで `location.reload(true)` のインスタンスに出会うことがあるかもしれません。 GitHub で "`location.reload(true)`" を検索すると、数十万件の結果が得られます。ということは、既存のコードの中にもそれがあるものがたくさんあるのです。

その歴史は、 Netscape Navigator のある版で対応が追加され、それが最終的に Firefox で取り上げられたようです。そして、あるとき W3C Web APIs Working Group が `location.reload()` の仕様に追加することを検討するための課題を取り上げました。しかし、実際に追加されることはありませんでした。

つまり、論理値の引数は現在の `location.reload()` の仕様には含まれていませんし、実際、これまでに発表された `location.reload()` の仕様には含まれていません。

### 返値

なし (`undefined`)。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-reload-dev |

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

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

関連情報
----

* 所属先の `Location` インターフェイス
* 同様のメソッド: `Location.assign()` および `Location.replace()`


location: origin プロパティ - Web API

location: origin プロパティ
======================

**`origin`** は `Location` インターフェイスの読み取り専用プロパティで、指定された URL のオリジンの Unicode シリアライズが入った文字列です。

すなわち、下記のようになります。

* `http` または `https` を使用する URL の場合、スキームの後に `'://'` を、その後にドメインを、その後に `':'` を、その後にポート（明示的に指定されなかった場合は、それぞれ既定の `80` および `443` のポート）を指定することができます。
* `file:` スキームを使用した URL では、値はブラウザー依存になります。
* `blob:` スキームを使用した URL では、その URL のオリジンが `blob:` に続きます。例えば、 `"blob:https://mozilla.org"` は `"https://mozilla.org"` がついています。

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

値
-

文字列です。

例
-

```js
// このページ上の、オリジンを返します。
const result = window.location.origin; // 返値:'https://developer.mozilla.org'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-origin-dev |

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

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


location: href プロパティ - Web API

location: href プロパティ
====================

**`href`** は `Location` インターフェイスのプロパティで、文字列化です。文字列で URL 全体を表し、href を更新することができます。

`href` の値を設定すると、指定された URL に*移動*します。もし、*redirection* が欲しい場合は、`location.replace()`を使用してください。`href` プロパティ値の設定との違いは、 `location.replace()` メソッドを使用した場合、指定した URL に移動した後、現在のページはセッションの履歴に保存されないことです - つまりユーザーは戻るボタンで移動することはできません。

文字列
---

文字列です。

例
-

```js
// 文書内に <a id="myAnchor" href="/ja/docs/Location/href"> 要素があるとする
const anchor = document.getElementById("myAnchor");
const result = anchor.href; // Returns: 'https://developer.mozilla.org/ja/Location/href'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-href-dev |

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

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


location: ancestorOrigins プロパティ - Web API

location: ancestorOrigins プロパティ
===============================

**`ancestorOrigins`** は `Location` インターフェイスの読み取り専用プロパティで、静的な `DOMStringList` であり、指定された `Location` オブジェクトに関連付けられたこの文書の閲覧コンテキストのすべての祖先のオリジンを、逆順で保持します。

文書のスクリプトで `location.ancestorOrigins` を使用すると、例えば、文書がフレーム化されることを予期していないサイトによってフレーム化されている場合、いつでもそれを判断することができます。また、どのサイトやサイトのリストでフレーム化されているかによって、文書の動作を変えるために使用することもできます。

値
-

`DOMStringList` です。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-ancestororigins-dev |

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

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


location: hash プロパティ - Web API

location: hash プロパティ
====================

**`hash`** は `Location` インターフェイスのプロパティで、`'#'` に URL のフラグメント識別子が続く文字列です。これはページ上の ID で、 URL がターゲットにしようとしているものです。

フラグメントは URL デコードされません。 URL にフラグメント識別子がない場合、このプロパティは空文字列、 `""` になります。

値
-

文字列です。

例
-

```html
<a id="myAnchor" href="/ja/docs/Location.href#Examples">Examples</a>
<script>
 const anchor = document.getElementById("myAnchor");
 console.log(anchor.hash); // '#Examples' を返す
</script>
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-hash-dev |

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

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


location: pathname プロパティ - Web API

location: pathname プロパティ
========================

**`pathname`** は `Location` インターフェイスのプロパティで、その位置を表す URL のパスが入った文字列です。パスがない場合は空文字列になります。そうでない場合、`pathname` には最初の '/' に続いて URL のパス部分が入り、クエリー文字列やフラグメントは含みません。

値
-

文字列です。

例
-

```js
// 文書内に <a id="myAnchor" href="/ja/docs/Location.pathname"> 要素があるとする
const anchor = document.getElementById("myAnchor");
const result = anchor.pathname; // 返値:'/ja/docs/Location.pathname'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-pathname-dev |

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

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


location: toString() メソッド - Web API

location: toString() メソッド
=========================

**`toString()`** は `Location` インターフェイスの文字列化メソッドであり、URL 全体を文字列で返します。これは `Location.href` の読み取り専用版です。

構文
--

```js
toString()
```

### 引数

なし。

### 返値

このオブジェクトの URL を表す文字列です。

例
-

```js
// このコードが https://example.com/path?search#hash で実行されていると想像してください
const result = window.location.toString(); // 返値: 'https://example.com/path?search#hash'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-href-dev |

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

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


location: replace() メソッド - Web API

location: replace() メソッド
========================

**`replace()`** は `Location` インターフェイスのメソッドで、現在のリソースを指定された URL のもので置き換えます。 `assign()` メソッドとの違いは、 `replace()` を使用すると現在のページがセッションの `History` に保存されないことです。すなわち、ユーザーが［戻る］ボタンを使用して戻ることができなくなります。

セキュリティ違反のために代入ができない場合、 `DOMException` が `SECURITY_ERROR` 型で発生します。これは、メソッドを呼び出すスクリプトのオリジンが、 `Location` オブジェクトによって元々記述されていたページのオリジンと異なる場合に起こります。主に、スクリプトが異なるドメインでホストされている場合に起こります。

指定された URL が有効でない場合、 `DOMException` が `SYNTAX_ERROR` 型で発生します。

構文
--

```js
replace(url)
```

### 引数

`url`

文字列で、移動先のページの URL です。

### 返値

なし (`undefined`)。

例
-

```js
// このページを置き換えて、 Location.reload の記事に移動します。
window.location.replace(
  "https://developer.mozilla.org/ja/docs/Web/API/Location.reload",
);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-replace-dev |

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

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

関連情報
----

* 所属先の `Location` インターフェイス
* 同様のメソッド: `Location.assign()` および `Location.reload()`


location: search プロパティ - Web API

location: search プロパティ
======================

**`search`** は `Location` インターフェイスのプロパティで、*クエリー文字列*とも呼ばれる検索文字列です。つまり、 `'?'` の後の URL 引数を含む文字列を指定します。

最近のブラウザーでは、クエリー文字列から引数を簡単に解析するために、 `URLSearchParams` と `URL.searchParams` が提供されています。

値
-

文字列です。

例
-

```js
// 文書内に <a id="myAnchor" href="/ja/docs/Location.search?q=123"> 要素があるとする
const anchor = document.getElementById("myAnchor");
const queryString = anchor.search; // Returns:'?q=123'

// さらに解釈する
const params = new URLSearchParams(queryString);
const q = parseInt(params.get("q")); // 数値 123
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-search-dev |

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

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


location: protocol プロパティ - Web API

location: protocol プロパティ
========================

**`protocol`** は `Location` インターフェイスのプロパティで、 URL のプロトコルスキームを、最後の `':'` を含めて表す文字列です。

値
-

文字列です。

例
-

```js
// 文書内に <a id="myAnchor" href="/ja/docs/Location.search?q=123"> 要素があるとする
const anchor = document.getElementById("myAnchor");
const result = anchor.protocol; // Returns:'https:'
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-location-protocol-dev |

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

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


CSSStyleSheet: removeRule() メソッド - Web API

CSSStyleSheet: removeRule() メソッド
================================

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

旧式の `CSSStyleSheet` の **`removeRule()`** メソッドは、スタイルシートオブジェクトからルールを削除します。これは、標準で推奨されるメソッド `deleteRule()` と機能的に同じです。

**メモ:** これは古いメソッドであり、標準のメソッド `deleteRule()` によって置き換えられました。代わりにこちらを使用してください。

構文
--

```js
removeRule(index)
```

### 引数

`index`

このスタイルシートの `CSSRuleList` の中の位置で、削除するルールを示します。

### 返値

なし (`undefined`)。

例
-

この例では、スタイルシート `myStyles` から最初のルールを削除します。

```js
myStyles.removeRule(0);
```

これを標準の `deleteRule()` メソッドを使用するように書き換えるのは、とても簡単です。

```js
myStyles.deleteRule(0);
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-removerule |

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

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

関連情報
----

* CSS オブジェクトモデル
* 動的スタイル情報の利用
* `insertRule()`


CSSStyleSheet: cssRules プロパティ - Web API

CSSStyleSheet: cssRules プロパティ
=============================

**`cssRules`** は `CSSStyleSheet` の読み取り専用プロパティで、スタイルシートを構成するすべての CSS ルールについて、リアルタイムで最新のリストを提供する生きた `CSSRuleList` を返します。リストの各項目は、単一のルールを定義する `CSSRule` です。

値
-

ライブで更新される `CSSRuleList` で、スタイルシートを構成するすべての CSS ルールを含みます。ルールリストのそれぞれの項目は、スタイルシートを構成する単一のルールを記述する `CSSRule` オブジェクトです。

例
-

スタイルシートの中のそれぞれのルールは、添字でアクセスすることができます。

```js
const ruleList = document.styleSheets[0].cssRules;

for (let i = 0; i < ruleList.length; i++) {
  processRule(ruleList[i]);
}
```

ルールは `for...of` を使用してアクセスすることもできます。

```js
const ruleList = document.styleSheets[0].cssRules;

for (const rule of ruleList) {
  processRule(rule);
}
```

しかし、 `CSSRule` は厳密には配列ではないので、 `forEach()` を使用することはできません。

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-cssrules |

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

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

関連情報
----

* CSS オブジェクトモデル
* 動的なスタイル情報の使用


CSSStyleSheet: deleteRule() メソッド - Web API

CSSStyleSheet: deleteRule() メソッド
================================

**`CSSStyleSheet.deleteRule()`** メソッドは、スタイルルールを現在のスタイルシートオブジェクトから削除します。

構文
--

```js
deleteRule(index)
```

### 引数

`index`

このスタイルシートの `CSSRuleList` で、削除するルールの位置を示します。

### 返値

なし (`undefined`)。

例
-

この例では、スタイルシート `myStyles` から最初のルールを削除します。

```js
myStyles.deleteRule(0);
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-deleterule |

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

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

関連情報
----

* CSS オブジェクトモデル
* Constructable Stylesheets (web.dev)
* 動的スタイル情報の利用
* `insertRule()`


CSSStyleSheet: rules プロパティ - Web API

CSSStyleSheet: rules プロパティ
==========================

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

**`rules`** は `CSSStyleSheet` インターフェイスの非推奨の古いプロパティです。機能的には推奨される `cssRules` プロパティと同じで、
 スタイルシートを構成する CSS ルールのライブ更新されるリストにアクセスすることができます。

**メモ:** 古いプロパティなので、`rules`は使用せず、代わりに推奨される `cssRules` を使用しましょう。
 `rules` がすぐに削除される可能性は低いですが、利用できる範囲はそれほど広くなく、これを使用するとサイトやアプリの互換性に問題が発生します。

値
-

スタイルシートを構成する各 CSS ルールを格納するライブ更新される `CSSRuleList` です。ルールリストの各項目は `CSSRule` オブジェクトであり、スタイルシートを構成する 1 つのルールを記述しています。

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-rules |

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

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

関連情報
----

* CSS オブジェクトモデル
* 動的スタイル情報の利用


CSSStyleSheet: addRule() メソッド - Web API

CSSStyleSheet: addRule() メソッド
=============================

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

旧式の `CSSStyleSheet` インターフェイスの **`addRule()`** は古いメソッドで、新しいルールをスタイルシートに追加します。このメソッドの使用を避け、より標準的な `insertRule()` メソッドを使用しましょう。

構文
--

```js
addRule(selector, styleBlock, index)
```

### 引数

`selector`

CSS ルールのセレクター部分を指定する文字列です。既定値は文字列 `undefined` です。

`styleBlock`

`selector` に一致する要素に適用されるスタイルブロックを示す文字列です。既定値は文字列 `undefined` です。

`index` 省略可

オプションで、このスタイルシートの `CSSRuleList` の中に新しいルールを挿入するための位置を指定します。`index` が指定されなかった場合、現在リストにある最後の項目の次の位置（つまり、 `cssStyleSheet.cssRules.length` の値）が使用されます。

### 返値

常に -1 を返します。

ルールを合法的に挿入できる場所に関するルールがやや難解なため、例外が発生する可能性があることに注意してください。詳細は `insertRule()` を参照してください。

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

このメソッドはブラウザーでは、テンプレートリテラル ``${selector}{${styleBlock}}`` を使用して文字列を構築し、それから標準の `insertRule()` メソッドを呼び出すように実装されています。

従って、以下のような既存のコードがあった場合、

```js
cssStyleSheet.addRule(selector, styles, 0);
```

次のようにして、もっと標準の `insertRule()` を使用して書き直すことができます。

```js
cssStyleSheet.insertRule(`${selector} {${styles}}`, 0);
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-addrule |

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

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

関連情報
----

* CSS オブジェクトモデル
* 動的スタイル情報の利用


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

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

**`CSSStyleSheet()`** コンストラクターは、新しい `CSSStyleSheet` オブジェクトを生成します。これは、単一のスタイルシートを表します。

スタイルシートを構築した後は、`CSSStyleSheet.replace()`、`CSSStyleSheet.replaceSync()`、`CSSStyleSheet.insertRule()`、`CSSStyleSheet.deleteRule()` の各メソッドを使用して、新しいスタイルシートのルールを変更することができます。

 このメソッドを使用して生成されたスタイルシートは「構築スタイルシート」(constructed stylesheet) と呼ばれます。
 構築スタイルシートは、 `ShadowRoot.adoptedStyleSheets` (en-US) および `Document.adoptedStyleSheets` (en-US) を使用して文書やそのシャドウ DOM サブツリー間で共有することができます。

構文
--

```js
new CSSStyleSheet()
new CSSStyleSheet(options)
```

### 引数

`options` 省略可

以下のものを持つオブジェクトです。

`baseURL` 省略可

スタイルシートの相対 URL の解決に用いる `baseURL` を格納した文字列。

`media` 省略可

メディアルールのリストを含む `MediaList`、または単一のルールを含む文字列。

`disabled` 省略可

論理値で、スタイルシートが無効かどうかを示します。既定で false になります。

例
-

 次の例では、新しい `CSSStyleSheet` が `"print"` というメディアルールで構築されています。
 コンソールで `StyleSheet.media` を表示すると、このプリントルールの単一の項目を持つ `MediaList` が返されます。

```js
let stylesheet = new CSSStyleSheet({ media: "print" });
console.log(stylesheet.media);
```

### スタイルシートのシャドウ DOM との共有

次のコードは、シートを構築し、`CSSStyleSheet.replaceSync()` を呼び出して、シートにルールを追加する様子を表します。

```js
// 空の「構築」スタイルシートを生成
const sheet = new CSSStyleSheet();
// シートにルールを適用
sheet.replaceSync("a { color: red; }");
```

そして、`ShadowRoot` を作成し、このシートオブジェクトを配列内の `ShadowRoot.adoptedStyleSheets` (en-US) プロパティに渡しています。

```js
// 文書内に要素を作成し、シャドウルートを作成する
const node = document.createElement("div");
const shadow = node.attachShadow({ mode: "open" });

//シートをシャドウ DOM に導入
shadow.adoptedStyleSheets = [sheet];
```

 配列に追加した後のスタイルシートは変更することができます。
 次の例では、`CSSStyleSheet.insertRule()` を使用して、同じシートに新しいルールを追加しています。

```js
sheet.insertRule("\* { background-color: blue; }");
// これで、文書の背景が青色になる
```

 同じ文書内の複数のシャドウサブツリーで同じシートを共有することができます。
 それ以外の例は、`ShadowRoot.adoptedStyleSheets` (en-US) を参照してください。

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-cssstylesheet |

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

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

関連情報
----

* Constructable Stylesheets (web.dev)
* シャドウ DOM の使用
* construct-style-sheets-polyfill


CSSStyleSheet: ownerRule プロパティ - Web API

CSSStyleSheet: ownerRule プロパティ
==============================

`CSSStyleSheet` の **`ownerRule`** は読み取り専用プロパティで、`CSSImportRule` を返します。これは、スタイルシートを文書にインポートする `@import` アットルールに対応します。スタイルシートが `@import` を使用して文書にインポートされていない場合、返される値は `null` です。

値
-

`CSSImportRule` です。これは、スタイルシートを文書にインポートする `@import` アットルールに対応します。スタイルシートが `@import` を使用して文書にインポートされていない場合、返される値は `null` です。

例
-

このスニペットは、`@import` アットルールを使用して文書にインポートされていないルールを探すものです。

```js
const ruleList = document.styleSheets[0].cssRules;

for (const rule of ruleList) {
  if (!rule.ownerRule) {
    /\* ルールはインポートされていない \*/
  }
}
```

このスニペットは、`@import` に関連するスタイルシートへの参照を取得し、それを何らかの方法で処理します。

```js
const ruleList = document.styleSheets[0].cssRules;

for (const rule of ruleList) {
  if (rule.ownerRule) {
    checkStylesheet(rule.ownerRule.styleSheet);
  }
}
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-ownerrule |

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

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

関連情報
----

* CSS オブジェクトモデル
* 動的スタイル情報の利用


CSSStyleSheet: replace() メソッド - Web API

CSSStyleSheet: replace() メソッド
=============================

**`replace()`** は `CSSStyleSheet` インターフェイスのメソッドで、スタイルシートの内容を渡された内容で非同期に置き換えます。このメソッドは `CSSStyleSheet` オブジェクトで解決されるプロミスを返します。

`replace()` と `CSSStyleSheet.replaceSync()` の両メソッドは、 `CSSStyleSheet()` コンストラクターで作成されたスタイルシートでのみ使用できます。

構文
--

```js
replace(text)
```

### 引数

`text`

スタイルシートのコンテンツを置き換えるためのスタイルルールを格納した文字列。文字列に解釈可能なルールのリストが入っていない場合、値は空文字列に設定されます。

**メモ:** もし `text` に渡されたルールの中に `@import` ルールでインポートされた外部スタイルシートがあった場合は、それらのルールは除去され、コンソールに警告が出力されます。

### 返値

`Promise` で、 `CSSStyleSheet` に解決します。

### 例外

`NotAllowedError` `DOMException`

次の 2 つの条件のうち一方が成立した場合に発生します。

* このスタイルシートが `CSSStyleSheet()` コンストラクターを使用して作成されていない。
* このスタイルシートが変更不可に設定されている。

例
-

次の例では、新しいスタイルシートを作成し、`replace()` を使って 2 つの CSS ルールを追加しています。最初のルールはコンソールに `body { font-size: 1.4em; }` と表示されます。

```js
const stylesheet = new CSSStyleSheet();

stylesheet
  .replace("body { font-size: 1.4em; } p { color: red; }")
  .then(() => {
    console.log(stylesheet.cssRules[0].cssText);
  })
  .catch((err) => {
    console.error("Failed to replace styles:", err);
  });
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-replace |

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

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

関連情報
----

* Constructable Stylesheets (web.dev)
* シャドウ DOM の使用


CSSStyleSheet: insertRule() メソッド - Web API

CSSStyleSheet: insertRule() メソッド
================================

**CSSStyleSheet.insertRule()** メソッドは、新しい CSS ルールを現在のスタイルシートに挿入します。

**メモ:** `insertRule()` は `CSSStyleSheet` 専用のメソッドですが、実際にはルールを `CSSStyleSheet.cssRules` に、内部的には `CSSRuleList` に挿入します。

構文
--

```js
insertRule(rule)
insertRule(rule, index)
```

### 引数

`rule`

挿入されるルールが入った文字列です。どのようなルールを挿入するかは、種類によります。

* **ルールセット** の場合、セレクターとスタイル定義です。
* **アットルール** の場合、アットマーク付き識別子とルールの内容です。

`index` 省略可

`stylesheet.cssRules.length` 以下の正の数で、 `CSSStyleSheet.cssRules` の中で新しく挿入されるルールの位置を示します。既定値は `0` です。（古い実装では、これは必須でした。詳しくはブラウザーの互換性を参照してください。）

### 返値

スタイルシートのルールリスト内の、新たに挿入されたルールの位置です。

### 例外

`IndexSizeError` `DOMException`

`index` > `CSSRuleList.length` の場合に発生します。

`HierarchyRequestError` `DOMException`

CSS の制約上、`rule` が `index` `0` に挿入できない場合に発生します。

`SyntaxError` `DOMException`

`rule` 引数に 2 つ以上のルールが与えられた場合に発生します。

`HierarchyRequestError` `DOMException`

スタイルルールの後に `@import` アットルールを挿入しようとした場合に発生します。

`InvalidStateError` `DOMException`

`rule` が `@namespace` であり、ルールリストに `@import` アットルールや `@namespace` アットルール以外のものがあった場合に発生します。

例
-

### 新しいルールの挿入

このスニペットは、新しいルールをスタイルシートの先頭に追加します。

```js
myStyle.insertRule("#blanc { color: white }", 0);
```

### スタイルシートルールを追加する関数

```js
/\*\*
 \* Add a stylesheet rule to the document (it may be better practice
 \* to dynamically change classes, so style information can be kept in
 \* genuine stylesheets and avoid adding extra elements to the DOM).
 \* Note that an array is needed for declarations and rules since ECMAScript does
 \* not guarantee a predictable object iteration order, and since CSS is
 \* order-dependent.
 \* @param {Array} rules Accepts an array of JSON-encoded declarations
 \* @example
addStylesheetRules([
 ['h2', // Also accepts a second argument as an array of arrays instead
 ['color', 'red'],
 ['background-color', 'green', true] // 'true' for !important rules
 ],
 ['.myClass',
 ['background-color', 'yellow']
 ]
]);
\*/
function addStylesheetRules(rules) {
  const styleEl = document.createElement("style");

  // Append <style> element to <head>
  document.head.appendChild(styleEl);

  // Grab style element's sheet
  const styleSheet = styleEl.sheet;

  for (let i = 0; i < rules.length; i++) {
    let j = 1,
      rule = rules[i],
      selector = rule[0],
      propStr = "";
    // If the second argument of a rule is an array of arrays, correct our variables.
    if (Array.isArray(rule[1][0])) {
      rule = rule[1];
      j = 0;
    }

    for (let pl = rule.length; j < pl; j++) {
      const prop = rule[j];
      propStr += `${prop[0]}: ${prop[1]}${prop[2] ? " !important" : ""};\n`;
    }

    // Insert CSS Rule
    styleSheet.insertRule(
      `${selector}{${propStr}}`,
      styleSheet.cssRules.length,
    );
  }
}
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-insertrule |

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

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

関連情報
----

* `CSSStyleSheet.deleteRule`
* Constructable Stylesheets (web.dev)


CSSStyleSheet: replaceSync() メソッド - Web API

CSSStyleSheet: replaceSync() メソッド
=================================

**`replaceSync()`** は `CSSStyleSheet` インターフェイスのメソッドで、スタイルシートの内容を渡された内容で同期的に置き換えます。.

`replaceSync()` と `CSSStyleSheet.replace()` の両メソッドは、 `CSSStyleSheet()` コンストラクターで作成されたスタイルシートでのみ使用できます。

構文
--

```js
replaceSync(text)
```

### 引数

`text`

スタイルシートのコンテンツを置き換えるためのスタイルルールを格納した文字列。文字列に解釈可能なルールのリストが入っていない場合、値は空文字列に設定されます。

**メモ:** もし `text` に渡されたルールの中に `@import` ルールでインポートされた外部スタイルシートがあった場合は、それらのルールは除去され、コンソールに警告が出力されます。

### 返値

なし (`undefined`)。

### 例外

`NotAllowedError` `DOMException`

このスタイルシートが `CSSStyleSheet()` コンストラクターを使用して作成されていない場合、または変更不可に設定されている場合に発生します。

例
-

次の例では、新しいスタイルシートを作成し、`replaceSync()` を使って 2 つの CSS ルールを追加しています。

```js
const stylesheet = new CSSStyleSheet();

stylesheet.replaceSync("body { font-size: 1.4em; } p { color: red; }");
```

仕様書
---

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-replacesync |

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

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

関連情報
----

* Constructable Stylesheets (web.dev)
* シャドウ DOM の使用


NDEFReader: scan() メソッド - Web API

NDEFReader: scan() メソッド
=======================

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

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

`scan()` は `NDEFReader` インターフェイスのメソッドで、読み取り機器を起動し、 `Promise` を返します。このプロミスは NFC タグの読み取り操作がスケジュールされたときに解決し、ハードウェアや権限のエラーが発生したときは拒否されます。このメソッドは、 "nfc" の権限が事前に許可されていない場合は、許可を問い合わせるプロンプトを起動します。

構文
--

```js
scan(options)
```

### 引数

`options` 省略可

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

`signal`

`AbortSignal` で、これによってこの `scan()` 操作をキャンセルすることができます。

### 返値

`Promise` で、 NFC アダプターで読み取り操作のスケジューリングが終わると直ちに解決します。

例外
--

このメソッドからは例外は発生しません。代わりに返されるプロミスが拒否され、 `DOMException` が `name` を何れかの一つとして渡されます。

`AbortError`

`options` 引数で渡された `AbortSignal` によってスキャン操作が中止された場合に返されます。

`InvalidStateError` `DOMException`

既に進行中のスキャンがある場合に返されます。

`NotAllowedError`

この操作の権限が拒否された場合に返されます。

`NotSupportedError`

ウェブ NFC と互換性のある NFC アダプターがない、または接続が確立できなかった場合に返されます。

例
-

### スキャン中のエラーの取り扱い

この例では、スキャンのプロミスが拒否され、 `readingerror` が発生したときの様子を示しています。

```js
const ndef = new NDEFReader();
ndef
  .scan()
  .then(() => {
    console.log("Scan started successfully.");
    ndef.onreadingerror = (event) => {
      console.log(
        "Error! Cannot read data from the NFC tag. Try a different one?",
      );
    };
    ndef.onreading = (event) => {
      console.log("NDEF message read.");
    };
  })
  .catch((error) => {
    console.log(`Error! Scan failed to start: ${error}.`);
  });
```

仕様書
---

| Specification |
| --- |
| Web NFC API # dom-ndefreader-scan |

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

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


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

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

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

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

**`NDEFReader()`** は `NDEFReader` インターフェイスのコンストラクターで、新しい `NDEFReader` オブジェクトを返します。これはリーダーの磁気誘導範囲にある互換性のある NFC 機器、例えば NDEF タグからの NDEF メッセージを読み取るのに使用されます。
 field.

構文
--

```js
new NDEFReader()
```

### 引数

なし。

### 返値

新しい `NDEFReader` オブジェクト。

仕様書
---

| Specification |
| --- |
| Web NFC API # dom-ndefreader-constructor |

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

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


NDEFReader: readingerror イベント - Web API

NDEFReader: readingerror イベント
=============================

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

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

`readingerror` は `NDEFReader` インターフェイスのイベントで、 NFC タグの読み取りの際にエラーが発生するたびに発行されます。例えば、タグがリーダーの磁気誘導範囲から離れたときです。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

次の例は、 `onreading` と `onreadingerror` の両方のイベントハンドラーを使用してイベントを処理する方法を示しています。

```js
const ndef = new NDEFReader();
ndef
  .scan()
  .then(() => {
    console.log("Scan started successfully.");
    ndef.onreadingerror = (event) => {
      console.log(
        "Error! Cannot read data from the NFC tag. Try a different one?",
      );
    };
    ndef.onreading = (event) => {
      console.log("NDEF message read.");
    };
  })
  .catch((error) => {
    console.log(`Error! Scan failed to start: ${error}.`);
  });
```

仕様書
---

| Specification |
| --- |
| Web NFC API # dom-ndefreader-onreadingerror |

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

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


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

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

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

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

`write()` は `NDEFReader` インターフェイスのプロパティで、タグに NDEF メッセージを書き込むことを試みます。 `Promise` を返し、これはタグにメッセージが書き込まれると解決し、ハードウェアや権限のエラーが発生すると拒否されます。このメソッドは、 "nfc" の権限が事前に許可されていない場合は、許可を問い合わせるプロンプトを起動します。

構文
--

```js
write(message)
write(message, options)
```

### 引数

`message`

書き込まれるメッセージで、文字列のオブジェクトまたはリテラル、`ArrayBuffer`、`TypedArray`、`DataView`、レコードの配列のいずれかです。レコードには以下のメンバーがあります。

`data` 省略可

通信されるデータで、文字列のオブジェクトまたはリテラル、`ArrayBuffer`、`TypedArray`、`DataView`、ネストされたレコードの配列のいずれかです。

`encoding` 省略可

文字列で、このレコードのエンコーディングを指定します。

`id` 省略可

このレコードの開発者が定義した識別子です。

`lang` 省略可

RFC 5646: Tags for Identifying Languages （または BCP 47）による有効な言語タグです。

`mediaType` 省略可

有効な MIME タイプです。

`recordType`

文字列で、 `data` に格納されたデータの型を示します。以下の値の何れかになります。

`"absolute-url"`

データへの絶対 URL です。

`"empty"`

空の `NDEFRecord` です。

`"mime"`

有効な MIME タイプです。

`"smart-poster"`

NDEF-SMARTPOSTER 仕様書で定義されているスマートポスターです。

`"text"`

NDEF-TEXT 仕様書で定義されているテキストです。

`"unknown"`

レコード型が不明です。

`"URL"`

NDEF-URI 仕様書で定義されている URL です。

`options` 省略可

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

`overwrite`

既存のレコードが存在した場合、上書きするかどうかを指定する論理値です。

`signal` 省略可

オプションの `AbortSignal` で、現在の書き込み操作をキャンセルすることができます。

### 返値

`Promise` で、メッセージがタグに書き込まれたら解決し、ハードウェアまたは権限のエラーが発生した場合は拒否されます。

例外
--

このメソッドからは例外は発生しません。代わりに返されるプロミスが拒否され、 `DOMException` が `name` を何れかの一つとして渡されます。

`AbortError`

`options` 引数で渡された `AbortSignal` によってスキャン操作が中止された。

`NotAllowedError`

この操作の権限が拒否されたか、 `overwrite` が `false` であり、既にタグにそのレコードがあった。

`NotSupportedError`

ウェブ NFC と互換性のある NFC アダプターがない、または利用可能な NFC アダプターがプッシュメッセージに対応していない、または接続が確立できなかった。

`NotReadableError`

UA が接続されている NFC アラプターにアクセスできなかった（例えば、ユーザー設定のため）。

`NetworkError`

開始された後で転送に失敗した（例えば、タグがリーダーから取り外された）。

例
-

### テキスト文字列の書き込み

以下の例では、文字列を NFC タグへ書き込み、発生するエラーを処理する方法を示します。

```js
const ndef = new NDEFReader();
ndef
  .write("Hello World")
  .then(() => {
    console.log("Message written.");
  })
  .catch((error) => {
    console.log(`Write failed :-( try again: ${error}.`);
  });
```

### URL の書き込み

次の例は、 NFC タグにレコードオブジェクト（上記）を書き込み、発生したエラーを処理する方法を示しています。

```js
const ndef = new NDEFReader();
try {
  await ndef.write({
    records: [{ recordType: "url", data: "http://example.com/" }],
  });
} catch {
  console.log("Write failed :-( try again.");
}
```

### タイムアウトで書き込みをスケジューリング

書き込み操作に時間制限を設けると便利な場合があります。例えば、ユーザーにタグをタッチするように要求し、一定時間内にタグが見つからなかったら、タイムアウトするようにします。

```js
const ndef = new NDEFReader();
ndef.onreading = (event) => console.log("We read a tag!");

function write(data, { timeout } = {}) {
  return new Promise((resolve, reject) => {
    const ctlr = new AbortController();
    ctlr.signal.onabort = () => reject("Time is up, bailing out!");
    setTimeout(() => ctlr.abort(), timeout);

    ndef.addEventListener(
      "reading",
      (event) => {
        ndef.write(data, { signal: ctlr.signal }).then(resolve, reject);
      },
      { once: true },
    );
  });
}

await ndef.scan();
try {
  // Let's wait for 5 seconds only.
  await write("Hello World", { timeout: 5\_000 });
} catch (err) {
  console.error("Something went wrong", err);
} finally {
  console.log("We wrote to a tag!");
}
```

仕様書
---

| Specification |
| --- |
| Web NFC API # dom-ndefreader-write |

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

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


NDEFReader: reading イベント - Web API

NDEFReader: reading イベント
========================

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

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

`reading` は `NDEFReader` インターフェイスのイベントで、タグがリーダーの磁気誘導範囲に入り、互換性のある NFC 機器（例えば NDEF に対応している NFC タグ）からの読み取りが可能になるたびに発行されます。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

次の例は、 `onreading` と `onreadingerror` の両方のイベントハンドラーを使用してイベントを処理する方法を示しています。

```js
const ndef = new NDEFReader();
ndef
  .scan()
  .then(() => {
    console.log("Scan started successfully.");
    ndef.onreadingerror = (event) => {
      console.log(
        "Error! Cannot read data from the NFC tag. Try a different one?",
      );
    };
    ndef.onreading = (event) => {
      console.log("NDEF message read.");
    };
  })
  .catch((error) => {
    console.log(`Error! Scan failed to start: ${error}.`);
  });
```

仕様書
---

| Specification |
| --- |
| Web NFC API # dom-ndefreader-onreading |

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

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

関連情報
----

* `NDEFReader.readingerror_event`


HIDDevice.forget() - Web API

HIDDevice.forget()
==================

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

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

`HIDDevice` インターフェイスの **`forget()`** メソッドは、HID デバイスとの接続を閉じ、デバイスを忘れます。

構文
--

```js
forget()
```

### 引数

なし。

### 返値

接続が閉じられ、デバイスが忘れられ、許可がリセットされた後 `undefined` で解決する `Promise` を返します。

例
-

この例では、Nintendo Switch Joy-Con Right HID デバイスに接続し、1 回点滅させ、切断します。

```js
async function blink() {
  const devices = await navigator.hid.requestDevice({
    filters: [
      {
        vendorId: 0x057e, // Nintendo Co., Ltd
        productId: 0x2007, // Joy-Con Right
      },
    ],
  });
  const device = devices[0];
  await device.open();
  // 消灯させます
  await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
  await waitFor(100);
  // 点灯させます
  await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
  await new Promise((resolve) => setTimeout(resolve, 100));
  // 最後に、切断します
  await device.forget();
}
blink();
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-forget |

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

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


HIDDevice.open() - Web API

HIDDevice.open()
================

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

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

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

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

`HIDDevice` の **`open()`** メソッドは、オペレーティングシステムに HID デバイスを開くことを要求します。

**メモ:** HID デバイスは自動では開かれません。そのため、`HID.requestDevice()` から返された `HIDDevice` でデータの転送を可能にするには、このメソッドを用いて開く必要があります。

構文
--

```js
open()
```

### 引数

なし。

### 返値

接続が開かれたら `undefined` で解決する `Promise` を返します。

### 例外

`InvalidStateError` `DOMException`

接続が既に開かれているとき投げられます。

`NotAllowedError` `DOMException`

何らかの理由により接続を開くのに失敗したとき投げられます。

例
-

この例では、データの送受信を試みる前に HID 接続を開くのを待ちます。

```js
await device.open();
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-open |

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

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


HIDDevice.productName - Web API

HIDDevice.productName
=====================

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

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

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

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

`HIDDevice` インターフェイスの読み取り専用プロパティ **`productName`** は、接続された HID デバイスの製品名を返します。

値
-

文字列です。

例
-

この例では、`HID.getDevices()` でデバイスを取得し、`productName` の値をコンソールに出力します。

```js
document.addEventListener("DOMContentLoaded", async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach((device) => {
    console.log(`HID: ${device.productName}`);
  });
});
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-productname |

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

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


HIDDevice.sendFeatureReport() - Web API

HIDDevice.sendFeatureReport()
=============================

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

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

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

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

`HIDDevice` インターフェイスの **`sendFeatureReport()`** メソッドは、HID デバイスに Feature レポートを送信します。Feature レポートは、HID デバイスとアプリケーションが標準化されていない HID データを交換するための方法です。

各レポート形式用にデバイスがサポートしている `reportId` は、`HIDDevice.collections` から取得できます。

構文
--

```js
sendFeatureReport(reportId, data)
```

### 引数

`reportId`

8 ビットのレポート ID です。HID デバイスがレポート ID を使わない場合、`0` を送信します。

`data`

`ArrayBuffer`, `TypedArray`, `DataView` のいずれかで表されるバイト列です。

### 返値

レポートの送信完了後 `undefined` で解決する `Promise` を返します。

### 例外

`NotAllowedError` `DOMException`

何らかの理由でレポートの送信に失敗したとき投げられます。

例
-

この例では、`sendFeatureReport()` によりデバイスを点滅させます。記事 Connecting to uncommon HID devices で他の例や動くデモを見ることができます。

```js
const reportId = 1;
for (let i = 0; i < 10; i++) {
  // 消灯させます
  await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
  await waitFor(100);
  // 点灯させます
  await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
  await waitFor(100);
}
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-sendfeaturereport |

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

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


HIDDevice.sendReport() - Web API

HIDDevice.sendReport()
======================

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

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

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

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

`HIDDevice` インターフェイスの **`sendReport()`** メソッドは、Output レポートを HID デバイスに送信します。

各レポート形式用にデバイスがサポートしている `reportId` は、`HIDDevice.collections` から取得できます。

構文
--

```js
sendReport(reportId, data)
```

### 引数

`reportId`

8 ビットのレポート ID です。HID デバイスがレポート ID を使わない場合、`0` を送信します。

`data`

`ArrayBuffer`, `TypedArray`, `DataView` のいずれかで表されるバイト列です。

### 返値

レポートの送信完了後 `undefined` で解決する `Promise` を返します。

### 例外

`NotAllowedError` `DOMException`

何らかの理由でレポートの送信に失敗したとき投げられます。

例
-

この例は、Output レポートを用いて Joy-Con デバイスを鳴らす方法を示します。記事 Connecting to uncommon HID devices で他の例や動くデモを見ることができます。

```js
// まず、振動を有効化するコマンドを送信します。
// 魔法のバイト列の出典は https://github.com/mzyy94/joycon-toolweb です。
const enableVibrationData = [1, 0, 1, 64, 64, 0, 1, 64, 64, 0x48, 0x01];
await device.sendReport(0x01, new Uint8Array(enableVibrationData));

// 次に、Joy-Con デバイスを鳴らすコマンドを送信します。
// 実際のバイト列はサンプル中にあります。
const rumbleData = [
  /\* … \*/
];
await device.sendReport(0x10, new Uint8Array(rumbleData));
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-sendreport |

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

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


HIDDevice: inputreport イベント - Web API

HIDDevice: inputreport イベント
===========================

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

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

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

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

`HIDDevice` インターフェイスの **`inputreport`** イベントは、HID デバイスから新しいレポートを受信した時に発火します。

構文
--

`addEventListener()` のようなメソッドでイベント名を使うか、イベントハンドラープロパティを設定します。

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

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

イベント型
-----

`HIDInputReportEvent` です。`Event` を継承しています。

Event

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

*このインターフェイスは、`Event` から継承したプロパティも持ちます。*

`HIDInputReportEvent.data` 読取専用

Input レポートから読み取ったデータが入った `DataView` です。HID インターフェイスがレポート ID を用いている場合、`reportId` は含まれません。

`HIDInputReportEvent.device` 読取専用

この Input レポートを送信した HID インターフェイスを表す `HIDDevice` のインスタンスです。

`HIDInputReportEvent.reportId` 読取専用

レポートを識別する 1 バイトの接頭辞、もしくは HID インターフェイスがレポート ID を用いていない場合 0 です。

例
-

この例では、アプリケーションが Joy-Con Right デバイスでどのボタンが押されたかを検出するために `inputReport` イベントを監視する方法を示します。記事 Connecting to uncommon HID devices で他の例や動くデモを見ることができます。

```js
device.addEventListener("inputreport", (event) => {
  const { data, device, reportId } = event;

  // Joy-Con Right デバイスで、かつ特定のレポート ID のイベントのみを扱います。
  if (device.productId !== 0x2007 && reportId !== 0x3f) return;

  const value = data.getUint8(0);
  if (value === 0) return;

  const someButtons = { 1: "A", 2: "X", 4: "B", 8: "Y" };
  console.log(`ユーザーがボタン ${someButtons[value]} を押しました。`);
});
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-oninputreport |

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

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


HIDDevice.close() - Web API

HIDDevice.close()
=================

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

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

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

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

`HIDDevice` インターフェイスの **`close()`** メソッドは、HID デバイスとの接続を閉じます。

構文
--

```js
close()
```

### 引数

なし。

### 返値

接続が閉じられたら `undefined` で解決する `Promise` を返します。

例
-

この例では、全てのデータの送受信が完了した後、HID デバイスを閉じます。

```js
await device.close();
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-close |

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

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


HIDDevice.receiveFeatureReport() - Web API

HIDDevice.receiveFeatureReport()
================================

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

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

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

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

`HIDDevice` インターフェイスの **`receiveFeatureReport()`** メソッドは、HID レポートから Feature レポートを受信します。Feature レポートは、HID デバイスとアプリケーションが標準化されていない HID データを交換するための方法です。

各レポート形式用にデバイスがサポートしている `reportId` は、`HIDDevice.collections` から取得できます。

構文
--

```js
receiveFeatureReport(reportId)
```

### 引数

`reportId`

8 ビットのレポート ID です。HID デバイスがレポート ID を使わない場合、`0` を送信します。

### 返値

Feature レポートが入った `DataView` オブジェクトで解決する `Promise` を返します。

### 例外

`NotAllowedError` `DOMException`

何らかの理由でレポートの受信に失敗したとき投げられます。

例
-

この例では、`reportId` の値 `1` を用いてデバイスからレポートを受信します。

```js
const dataView = await device.receiveFeatureReport(1);
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-receivefeaturereport |

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

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


HIDDevice.opened - Web API

HIDDevice.opened
================

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

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

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

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

`HIDDevice` インターフェイスの読み取り専用プロパティ **`opened`** は、`HIDDevice` への接続が開かれていてデータを転送する準備ができているとき `true` を返します。

値
-

`boolean` 値です。接続が開かれているとき `true` です。

例
-

この例では、`HID.getDevices()` でデバイスを取得し、`opened` の値をコンソールに出力します。

```js
document.addEventListener("DOMContentLoaded", async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach((device) => {
    console.log(`HID: ${device.opened}`);
  });
});
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-opened |

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

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


HIDDevice.collections - Web API

HIDDevice.collections
=====================

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

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

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

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

`HIDDevice` インターフェイスの読み取り専用プロパティ **`collections`** は、レポート形式の配列を返します。

値
-

レポート形式の配列です。各エントリーは以下を含みます。

`usagePage`

このコレクションに紐づいた HID 使用法の Usage Page 部分を表す整数です。トップレベルのコレクションの使用法は、デバイスの種類を特定するために使用されます。

標準の HID 使用法の値は、HID Usage Tables に載っています。

`usage`

このコレクションに紐づいた HID 使用法の Usage ID 部分を表す整数です。

`type`

コレクションの種類を表す 8 ビットの値です。グループ化されたアイテムの関係を表します。以下のいずれかです。

`0x00`

Physical (軸のグループ)

`0x01`

Application (マウス、キーボード)

`0x02`

Logical (関連するデータ)

`0x03`

Report

`0x04`

Named array

`0x05`

Usage switch

`0x06`

Usage modified

`0x07 to 0x7F`

将来のために予約

`0x80 to 0xFF`

ベンダー定義

これらの種類についての追加情報は、Device Class Definition に載っています。

`children`

トップレベルコレクションと同じ形式の、サブコレクションの配列です。

`inputReports`

このコレクションで記述されているそれぞれの Input レポートを表す `inputReport` の配列です。

`outputReports`

このコレクションで記述されているそれぞれの Output レポートを表す `outputReport` の配列です。

`featureReports`

このコレクションで記述されているそれぞれの Feature レポートを表す `featureReport` の配列です。

例
-

この例は、`collections` プロパティが返された後、様々な要素にアクセスする方法を示しています。他の例や動くデモを記事 Connecting to uncommon HID devices で見ることができます。

```js
for (const collection of device.collections) {
  // HID コレクションには、使用法、Usage Page、レポート、サブコレクションが含まれます。
  console.log(`Usage: ${collection.usage}`);
  console.log(`Usage page: ${collection.usagePage}`);

  for (const inputReport of collection.inputReports) {
    console.log(`Input report: ${inputReport.reportId}`);
    // inputReport.items をループで走査します
  }

  for (const outputReport of collection.outputReports) {
    console.log(`Output report: ${outputReport.reportId}`);
    // outputReport.items をループで走査します
  }

  for (const featureReport of collection.featureReports) {
    console.log(`Feature report: ${featureReport.reportId}`);
    // featureReport.items をループで走査します
  }

  // collection.children を用いてサブコレクションをループで走査します
}
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-collections |

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

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


HIDDevice.vendorId - Web API

HIDDevice.vendorId
==================

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

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

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

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

`HIDDevice` インターフェイスの読み取り専用プロパティ **`vendorId`** は、接続された HID デバイスのベンダー ID を返します。これにより、デバイスの製造元を識別します。

値
-

整数です。デバイスにベンダー ID が無いか、ベンダー ID にアクセスできないときは、`0` を返します。

例
-

この例では、`HID.getDevices()` でデバイスを取得し、`vendorId` の値をコンソールに出力します。

```js
document.addEventListener("DOMContentLoaded", async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach((device) => {
    console.log(`HID: ${device.vendorId}`);
  });
});
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-vendorid |

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

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


HIDDevice.productId - Web API

HIDDevice.productId
===================

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

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

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

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

`HIDDevice` インターフェイスの読み取り専用プロパティ **`productId`** は、接続された HID デバイスのプロダクト ID を返します。

値
-

整数です。デバイスにプロダクト ID が無いか、プロダクト ID にアクセスできないときは、`0` を返します。

例
-

この例では、`HID.getDevices()` でデバイスを取得し、`productId` の値をコンソールに出力します。

```js
document.addEventListener("DOMContentLoaded", async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach((device) => {
    console.log(`HID: ${device.productId}`);
  });
});
```

仕様書
---

| Specification |
| --- |
| WebHID API # dom-hiddevice-productid |

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

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


RTCPeerConnectionIceEvent() - Web API

RTCPeerConnectionIceEvent()
===========================

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

構文
--

```js
new RTCPeerConnectionIceEvent(type, options)
```

### 引数

`type`

 文字列で、このイベントの名前です。
 大文字小文字を区別し、ブラウザーは常に `icecandidate` に設定します。

`options` 省略可

オブジェクトで、*`Event()` で定義されているプロパティに加えて*、以下のプロパティがあります。

`candidate`

`RTCIceCandidate` (en-US) で、そのイベントが関係する ICE の候補を表します。
 もし `null` ならば、そのイベントは候補の収集の終わりを示します。

`url`

 文字列で、候補を収集するために使用された STUN または TURN サーバーの URL を保持します。
 もし候補が STUN または TURN サーバーによって収集されていない場合、この値は `null` でなければならず、またこれは既定値です。

### 返値

提供されたオプションを指定して構成された、新しい `RTCPeerConnectionIceEvent` オブジェクト。

仕様書
---

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

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

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

関連情報
----

* WebRTC
* このイベントの通常ターゲット: `RTCPeerConnection`


RTCPeerConnectionIceEvent.candidate - Web API

RTCPeerConnectionIceEvent.candidate
===================================

**`candidate`** は `RTCPeerConnectionIceEvent` インターフェイスの読み取り専用のプロパティで、そのイベントに関連付けられた `RTCIceCandidate` (en-US) を返します。

値
-

受信した ICE の候補を表す `RTCIceCandidate` (en-US) オブジェクト、 またはこのネゴシエーションセッションの候補がないことを表す `null` です。

例
-

```js
pc.onicecandidate = (ev) => {
  alert(
    `The ICE candidate (transport address: '${ev.candidate.candidate}') has been added to this connection.`,
  );
};
```

仕様書
---

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

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

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

関連情報
----

* `icecandidate` (en-US)
* `RTCPeerConnection`


書き込み可能なストリームの使用 - Web API

書き込み可能なストリームの使用
===============

JavaScript 開発者として、プログラムでストリームにデータを書き込むことはとても便利です。この記事では、ストリーム API の書き込み可能なストリームの機能について説明します。

**メモ:** この記事は、書き込み可能なストリームの用途を理解し、高レベルの概念を理解していることを前提としています。 そうでない場合は、まずストリームの概念と使用方法の概要とストリーム API の概念の記事を読んでから、戻ってくることをお勧めします。

**メモ:** 読み取り可能なストリームに関する情報を探している場合は、代わりに読み取り可能なストリームの使用や読み取り可能なバイトストリームの使用をご覧ください。

例の紹介
----

dom-examples/streams リポジトリーには、単純なライターの例（Simple writer example）があります（ライブも参照）。 これは、指定されたメッセージを取得して書き込み可能なストリームに書き込み、ストリームに書き込まれるときに UI に各チャンクを表示し、書き込みが終了すると UI にメッセージ全体を表示します。

書き込み可能なストリームの仕組み
----------------

書き込み可能なストリーム機能のデモの仕組みを見てみましょう。

### 書き込み可能なストリームの構築

書き込み可能なストリームを作成するには、`WritableStream()` コンストラクターを使用します。 構文は最初は複雑に見えますが、実際にはそれほど悪くはありません。

構文の骨組みは次のようになります。

```js
const stream = new WritableStream(
  {
    start(controller) {},
    write(chunk, controller) {},
    close(controller) {},
    abort(reason) {},
  },
  {
    highWaterMark: 3,
    size: () => 1,
  },
);
```

コンストラクターは引数として 2 つのオブジェクトを取ります。 最初のオブジェクトは必須であり、データの書き込み先の基になるシンクのモデルを JavaScript で作成します。 2 番目のオブジェクトはオプションであり、ストリームに使用するカスタムのキューイング戦略を指定できる `ByteLengthQueuingStrategy` または `CountQueuingStrategy` のインスタンスの形式をとります。

次のように最初のオブジェクトには最大 4 つのメンバーを含めることができますが、それらはすべてオプションです。

1. `start(controller)` — `WritableStream` が構築された直後に 1 回だけ呼び出されるメソッド。 このメソッド内には、ストリーム機能を設定するコードを含める必要があります。 例えば、基になるシンクへのアクセスを取得します。
2. `write(chunk,controller)` — 新しいチャンク（`chunk` 引数で指定）を基になるシンクに書き込む準備ができるたびに繰り返し呼び出されるメソッド。
3. `close(controller)` — ストリームへのチャンクの書き込みが完了したことをアプリが通知した場合に呼び出されるメソッド。 基になるシンクへの書き込みを完了し、アクセスを解放するために必要なことは何でも行う必要があります。
4. `abort(reason)` — ストリームを突然閉じてエラー状態にしたいとアプリが通知した場合に呼び出されるメソッド。

この例のコンストラクター呼び出しは次のようになります。

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

* `write()` メソッドには、書き込まれた各チャンクを UI に書き込める形式にデコードするコードを含むプロミスが含まれています。 これは、各チャンクが実際に書き込まれるときに呼び出されます（次のセクションを参照）。
* `close()` メソッドは、書き込みが終了すると自動的に呼び出されます — デコードされた結果全体を 1 つの文字列で UI に出力します。
* `abort()` メソッドは、ストリームが中断された場合にコンソールにエラーを出力するだけです。
### 書き込み

実際にストリームにコンテンツを書き込むには、次のように `sendMessage()` 関数を呼び出して、書き込むメッセージと書き込み先のストリームを渡します。

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

`sendMessage()` の定義は次のようになります。

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

したがって、ここでは、`WritableStream.getWriter()` を使用してストリームにチャンクを書き込むライターを作成します。 これにより、`WritableStreamDefaultWriter` インスタンスが作成されます。

また、関連するコンストラクターを使用して新しい `TextEncoder` インスタンスを作成し、メッセージをチャンクにエンコードしてストリームに入れます。

エンコードされたチャンクを使用して、結果の配列で `forEach()` を呼び出します。 このブロック内で、`WritableStreamDefaultWriter.ready` を使用して、ライターに別のチャンクを書き込む準備ができているかどうかを確認します。 `ready` は、この場合に満たされるプロミスを返します。 その中で、 `WritableStreamDefaultWriter.write()` を呼び出して、実際にストリームにチャンクを書き込みます。 これにより、前述のように、`WritableStream()` コンストラクター内で指定された `write()` メソッドも起動されます。

チャンクがすべて書き込まれた後、最後のチャンクの書き込みが完了し、すべての作業が完了したことを確認するために、もう一度 `ready` のチェックを実行します。この `ready` のチェックが完了すると、 `WritableStreamDefaultWriter.close()` を呼び出してストリームを閉じます。 これにより、前述のように、 `WritableStream()` コンストラクター内で指定された `close()` メソッドも起動されます。

### コントローラー

`WritableStream()` 構文の骨組みを学習するときに気づくでしょうが、`start()`、`write()`、`close()` の各メソッドには、オプションで `controller` 引数を渡すことができます。 これには、 `WritableStreamDefaultController` インターフェイスのインスタンスが含まれます。 これは、開発者が必要に応じてストリームをさらに制御するために使用できます。

現在、このインターフェイスで使用できるメソッドは `WritableStreamDefaultController.error()` のみです。 このメソッドを呼び出すと、ストリームとの今後の相互作用でエラーが発生します。これは、アプリの別の部分に問題が発生したときに、エラーをストリームに伝搬させて、システム全体がきれいに失敗するようにしたい場合に便利です。これは、ゴミがストリームに黙って書き込まれる（または同様の悪しき事態になる）危険を冒すのではなく、そのような事態を避けるためです。

### 終了と中止

上記のように、書き込みが終了すると `close()` メソッドを呼び出し、`WritableStream()` コンストラクター内で指定された `close()` メソッドを起動します。

`WritableStreamDefaultWriter.abort()` を呼び出してストリームを中止することもできます。

違いは、 close を呼び出すと、ストリームが閉じられる前に、以前にキューに入れられたチャンクが書き込まれ、終了することです。

`abort()` を呼び出すと、以前にキューに入れられたチャンクはすぐに破棄され、ストリームはエラー状態に移行します。 また、これにより、`WritableStream()` コンストラクターで指定された `abort()` メソッドが呼び出されます。


ストリーム API の概念 - Web API

ストリーム API の概念
=============

ストリーム API は、とても便利なツールセットをウェブプラットフォームに追加し、 JavaScript がネットワーク経由で受信したデータのストリームにプログラムからアクセスし、開発者の希望どおりに処理できるようにするオブジェクトを提供します。ストリームに関連する概念や用語の中には、初めて耳にするものもあるかもしれません。この記事では、知るべきことをすべて説明しています。

読み取り可能なストリーム
------------

読み取り可能なストリームは、**基になるソース** (underlying source) から流れる `ReadableStream` オブジェクトによって JavaScript で表されるデータソースです。 基になるソースは、ネットワーク上のどこか、またはデータを取得するドメインのどこかにあるリソースです。

基になるソースには、次の 2 種類があります。

* **プッシュソース** (Push sources) は、アクセスしたときに常にデータをプッシュします。 ストリームへのアクセスを開始、一時停止、またはキャンセルするのはユーザー次第です。 例には、動画ストリームや TCP/ウェブソケットが含まれます。
* **プルソース** (Pull sources) では、接続後、明示的にデータを要求する必要があります。 例には、Fetch や XHR の呼び出しを介したファイルアクセス操作が含まれます。

データは、**チャンク** (chunks) と呼ばれる小さな断片で順番に読み取られます。 チャンクは 1 バイトにすることも、特定のサイズの型付き配列など、より大きなものにすることもできます。 単一のストリームには、さまざまなサイズとタイプのチャンクを含めることができます。

![読み取り可能なストリームのデータフロー](/ja/docs/Web/API/Streams_API/Concepts/readable_streams.png)

ストリームに置かれたチャンクは、**キューに入った** (enqueued) と言われます。 これは、読み取りの準備ができているキューで待機していることを意味します。 **内部キュー**（internal queue）は、まだ読み取られていないチャンクを追跡します（下の内部キューとキューイング戦略のセクションを参照）。

ストリーム内のチャンクは**リーダー** (reader) によって読み取られます。 これにより、一度に 1 つのチャンクでデータが処理されるため、ユーザーは任意の種類の操作を実行できます。 リーダーとそれに付随する他の処理コードは、**コンシューマー** (consumer) と呼ばれます。

また、**コントローラー** (controller) と呼ばれる構造も使用します。 各リーダーには、ストリームを制御する（例えば、必要に応じてキャンセルする）ことができるコントローラーが関連付けられています 。

一度にストリームを読み取ることができるのは 1 つのリーダーのみです。 リーダーが作成され、ストリームの読み取りを開始すると、ストリームは**アクティブなリーダー** (active reader) に**ロックされている** (locked) と言います。 別のリーダーにストリームの読み取りを開始させる場合は、通常、最初のリーダーをキャンセルしてから他の操作を行う必要があります（ですが、ストリームを**分岐** (tee) することができます。下の分岐の節を参照）。

読み取り可能なストリームには 2 つの異なる種類があることに注意してください。 従来の読み取り可能なストリームに加えて、バイトストリームと呼ばれる種類があります。 これは、基になるバイトソース（BYOB または bring your own buffer（独自のバッファーを持ち込む）とも呼ばれる）のソースを読み取るための従来のストリームの拡張バージョンです。 これにより、開発者が提供するバッファーにストリームを直接読み込むことができ、必要なコピーが最小限に抑えられます。 コードが使用する基になるストリーム（そして拡張により、リーダーとコントローラー）は、最初にストリームがどのように作成されたかによって異なります（`ReadableStream()` コンストラクターのページを参照）。

フェッチリクエストからの `Response.body` などのメカニズムを介して既製の読み取り可能なストリームを使用するか、`ReadableStream()` コンストラクターを使用して独自のストリームを使用できます。

分岐
--

一度にストリームを読み取ることができるのは 1 つのリーダーだけですが、ストリームを 2 つの同一のコピーに分割し、2 つの別々のリーダーで読み取ることができます。 これを**分岐** (teeing) と呼びます。

JavaScript では、これを `ReadableStream.tee()` メソッドを介して実現します。元の読み取り可能なストリームの 2 つの同一コピーを含む配列を出力し、2 つの別々のリーダーで個別に読み取ることができます。

例えば、サーバーからレスポンスを取得してブラウザーにストリーミングしたいが、サービスワーカーのキャッシュにもストリームしたい場合に、サービスワーカーでこれを行うことができます。 レスポンスの本体を複数回使用することはできず、ストリームを一度に複数のリーダーで読み取ることはできないため、これを行うには 2 つのコピーが必要です。

![データフローの分岐](/ja/docs/Web/API/Streams_API/Concepts/tee.png)

書き込み可能なストリーム
------------

**書き込み可能なストリーム** (writable stream) は、`WritableStream` オブジェクトによって JavaScript で表されるデータの書き込み先です。 これは、**基になるシンク**（underlying sink、生データが書き込まれる下位レベルの I/O シンク）の上部の抽象化として機能します。

データは、**ライター** (writer) を介して一度に 1 つのチャンクでストリームに書き込まれます。 チャンクは、リーダーのチャンクと同様に、多数の形式をとることができます。 任意のコードを使用して、書き込み可能なチャンクを生成できます。 ライターとそれに関連するコードを**プロデューサー** (producer) と呼びます。

ライターが作成され、ストリームへの書き込みを開始すると、ストリームは**アクティブなライター** (active writer) に**ロックされている** (locked) と言われます。 一度に書き込み可能なストリームに書き込むことができるのは、1 つのライターのみです。 別のライターにストリームへの書き込みを開始させたい場合は、通常、別のライターを取りつける前にそれを中止する必要があります。

**内部キュー** (internal queue) は、ストリームに書き込まれたが、基になるシンクによってまだ処理されていないチャンクを追跡します。

また、コントローラーと呼ばれる構造も使用します。 各ライターには、ストリームを制御する（例えば、必要に応じてストリームを中止する）ことができるコントローラーが関連付けられています 。

![書き込み可能なストリームのデータフロー](/ja/docs/Web/API/Streams_API/Concepts/writable_streams.png)

`WritableStream()` コンストラクターを使用して、書き込み可能なストリームを利用できます。 現在、これらのブラウザーでの可用性は非常に限られています。

パイプチェーン
-------

ストリーム API では、**パイプチェーン** (pipe chain) と呼ばれる構造を使用して、ストリームを互いにパイプ接続することが可能です。

* `ReadableStream.pipeThrough()` - ストリームを**変換ストリーム** (transform stream) に通してパイプ接続し、途中でデータ形式を変換することができます。
 これは、例えば、動画フレームのエンコードやデコード、データの圧縮や解凍、ある形式から別の形式へのデータ変換に使用することができます。
 変換ストリームは、データが読み込まれる読み取り可能なストリームと、データが書き込まれる書き込み可能なストリームのペアと、データが書き込まれると同時に新しいデータが読み込めるようになることを保証する適切なメカニズムで構成されています。
 `TransformStream` は変換ストリームの具体的な実装ですが、 `pipeThrough()` には、同じ読み取り可能なストリームと書き込み可能なストリームのプロパティを持つ任意のオブジェクトを通すことができます。
* `ReadableStream.pipeTo()` — パイプチェーンの終点として機能する書き込み可能なストリームにパイプ接続します。

パイプチェーンの始まりは**元のソース** (original source) と呼ばれ、終わりは**最終的なシンク** (ultimate sink) と呼ばれます。

![パイプチェーンの図](/ja/docs/Web/API/Streams_API/Concepts/pipechain.png)

背圧
--

ストリームの重要な概念の一つが**背圧** (backpressure) です。 これは、単一のストリームまたはパイプチェーンが読み取り/書き込みの速度を調整するプロセスです。 チェーンの後半のストリームがまだビジーで、さらに多くのチャンクを受け入れる準備ができていない場合、チェーンを介して信号を逆方向に送信して、より前の変換ストリーム（または元のソース）に必要に応じて配信速度を落とすよう指示し、どこもボトルネックにならないようにします。

`ReadableStream` で背圧を使用するには、コントローラーの `ReadableStreamDefaultController.desiredSize` プロパティを照会することで、コンシューマーが希望するチャンクサイズをコントローラーに問い合わせます。 それが低すぎる場合、`ReadableStream` は、基になるソースにデータの送信を停止するように指示でき、ストリームチェーンに沿って背圧をかけます。

後でコンシューマーが再びデータを受信したい場合は、ストリームの作成で `pull` メソッドを使用して、データをストリームに与えるよう基になるソースに指示できます。

内部キューとキューイング戦略
--------------

前に述べたように、まだ処理されて終了していないストリーム内のチャンクは、内部キューによって追跡されます。

* 読み取り可能なストリームの場合、これらはキューに入れられたがまだ読み取られていないチャンクです。
* 書き込み可能なストリームの場合、これらは書き込まれたが、基になるシンクによってまだ処理されていないチャンクです。

内部キューは、**内部キューの状態**(internal queue state) に基づいて背圧を通知する方法を決定する**キューイング戦略** (queuing strategy) を採用しています。

一般に、この戦略はキュー内のチャンクのサイズを、キューが管理しやすい最大のチャンクの合計サイズである**最高水準点** (high water mark) と呼ばれる値と比較します。

実行される計算は次です。

`最高水準点 - キュー内のチャンクの合計サイズ = 希望サイズ`

**希望サイズ** (desired size) は、ストリームが流れ続けるために受け入れることができるチャンクの数ですが、サイズは最高水準未満となります。
 チャンクの生成は適宜減速/加速され、希望サイズをゼロ以上に保ちつつ、ストリームを使用可能な限り速く流すことができます。
 この値がゼロ（または未満）になった場合、ストリームが対処できる速度よりも速くチャンクが生成されていることを意味しており、問題が発生する可能性があります。

例として、1 のチャンクサイズと 3 の最高水準点を考えてみましょう。 これは、最高水準点に到達して背圧が適用される前に、最大 3 つのチャンクをキューに入れることができることを意味します。