ShadowRoot.host - Web API

ShadowRoot.host
===============

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
**`host`** は `ShadowRoot` の読み取り専用プロパティで、 `ShadowRoot` が取り付けられている DOM 要素の参照を返します。

構文
--

```js
const someElement = shadowRoot.host;
```

### 値

DOM の `Element` です。

例
-

```js
let customElem = document.querySelector('my-shadow-dom-element');
let shadow = customElem.shadowRoot;

  ...

// 後で、元のホスト要素を返す
let hostElem = shadow.host;
```

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-shadowroot-host |

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

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


ShadowRoot: activeElement プロパティ - Web API

ShadowRoot: activeElement プロパティ
===============================

**`activeElement`** は `ShadowRoot` インターフェイスの読み取り専用プロパティで、シャドウツリー内でフォーカスを持っている要素を返します。

値
-

現在フォーカスを持っている `Element`、またはフォーカスを持っている要素がなければ `null` です。

例
-

```js
let customElem = document.querySelector("my-shadow-dom-element");
let shadow = customElem.shadowRoot;
let focusedElem = shadow.activeElement;
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-documentorshadowroot-activeelement-dev |

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

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

関連情報
----

* `Document.activeElement`


ShadowRoot.fullscreenElement - Web API

ShadowRoot.fullscreenElement
============================

**`fullscreenElement`** は `ShadowRoot` インターフェイスの読み取り専用プロパティで、現在全画面モードで表示されているシャドウツリー内の要素を返します。

構文
--

```js
shadowRoot.fullscreenElement;
```

### 値

現在全画面モードで表示されている `Element`、または全画面モードの要素がなければ `null` を返します。

例
-

```js
let customElem = document.querySelector("my-shadow-dom-element");
let shadow = customElem.shadowRoot;
let fullscreenElem = shadow.fullscreenElement;
```

仕様書
---

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenelement② |

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

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

関連情報
----

* `Document.fullscreenElement`


ShadowRoot.pointerLockElement - Web API

ShadowRoot.pointerLockElement
=============================

**`pointerLockElement`** は `ShadowRoot` インターフェースの読み取り専用プロパティで、ポインターがロックされている間、マウスイベントのターゲットとして設定される要素を提供します。ロックが保留されている場合、ポインタのロックが解除されている場合、ターゲットが別のツリーにある場合は `null` になります。

構文
--

```js
shadowRoot.pointerLockElement;
```

### 値

`Element` または `null` です。

例
-

```js
let customElem = document.querySelector("my-shadow-dom-element");
let shadow = customElem.shadowRoot;
let pleElem = shadow.pointerLockElement;
```

仕様書
---

| Specification |
| --- |
| Pointer Lock 2.0 # dom-documentorshadowroot-pointerlockelement |

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

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

関連情報
----

* `Document.exitPointerLock()`
* `Element.requestPointerLock()`
* ポインターロック


ShadowRoot.pictureInPictureElement - Web API

ShadowRoot.pictureInPictureElement
==================================

**`pictureInPictureElement`** は `ShadowRoot` インターフェイスの読み取り専用プロパティで、このシャドウツリー内で現在、ピクチャインピクチャモードで表示されている要素 (`Element`) を返します。現在、ピクチャインピクチャモードが使用されていない場合は `null` を返します。

構文
--

```js
shadowRoot.pictureInPictureElement;
```

### 値

現在ピクチャインピクチャモードになっている `Element` オブジェクトへの参照、またはピクチャインピクチャモードが現在シャドウツリーで使われていない場合は `null` が返されます。

例
-

```js
let customElem = document.querySelector("my-shadow-dom-element");
let shadow = customElem.shadowRoot;
let pipElem = shadow.pictureInPictureElement;
```

仕様書
---

| Specification |
| --- |
| Picture-in-Picture # ref-for-dom-documentorshadowroot-pictureinpictureelement①⑤ |

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

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

関連情報
----

* `Document.pictureInPictureElement`


XPathResult: snapshotItem() メソッド - Web API

XPathResult: snapshotItem() メソッド
================================

**`snapshotItem()`** は `XPathResult` インターフェイスのメソッドで、アイテムのスナップショットの集合、またはインデックスがノードの範囲を外れている場合は `null` を返します。イテレーターの返値とは異なり、スナップショットは無効になることはありませんが、変更したときに現在の文書に対応しない場合があります。

構文
--

```js
snapshotItem(i)
```

### 引数

`i`

数値で、項目のインデックスです。

### 返値

`XPathResult` のノード集合内の指定されたインデックスの `Node` です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `UNORDERED_NODE_SNAPSHOT_TYPE` または `ORDERED_NODE_SNAPSHOT_TYPE` でない場合、 `XPathException` による例外が `TYPE_ERR` 型で発生します。

例
-

以下の例は `snapshotItem()` メソッドの使用例を表しています。

### HTML

```html
<div>XPath example</div>
<div>Tag names of the matched nodes: <output></output></div>
```

### JavaScript

```js
const xpath = "//div";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ORDERED\_NODE\_SNAPSHOT\_TYPE,
  null,
);
let node = null;
const tagNames = [];
for (let i = 0; i < result.snapshotLength; i++) {
  node = result.snapshotItem(i);
  tagNames.push(node.localName);
}
document.querySelector("output").textContent = tagNames.join(", ");
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-snapshotitem-index-index |

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

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


XPathResult: resultType プロパティ - Web API

XPathResult: resultType プロパティ
=============================

**`resultType`** は `XPathResult` インターフェイスの読み取り専用プロパティで、定義した結果の型を型定数で表します。

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

値
-

結果の型を表す整数で、型定数で定義されたものです。

定数
--

| 結果の定義済みの型定数 | 値 | 説明 |
| --- | --- | --- |
| `ANY_TYPE` | `0` | 式を評価した結果として自然に得られる型を格納した結果集合です。結果がノード集合の場合、 `UNORDERED_NODE_ITERATOR_TYPE` が常に結果として得られる型であることに注意してください。 |
| `NUMBER_TYPE` | `1` | 単一の数値を格納した結果です。この例は、例えば `count()` 関数を使用した XPath 式の中で有益です。 |
| `STRING_TYPE` | `2` | 単一の文字列を格納した結果です。 |
| `BOOLEAN_TYPE` | `3` | 1 つの論理値を格納した結果です。これは例えば、`not()`関数を使用した XPath 式の中で有益なものです。 |
| `UNORDERED_NODE_ITERATOR_TYPE` | `4` | 式に一致するすべてのノードを格納した結果ノード集合です。ノードは必ずしも文書内の順序とは限りません。 |
| `ORDERED_NODE_ITERATOR_TYPE` | `5` | 式に一致するすべてのノードを格納した結果ノード集合です。結果セットのノードは、文書内のノードと同じ順序で現れます。 |
| `UNORDERED_NODE_SNAPSHOT_TYPE` | `6` | 式に一致するすべてのノードのスナップショットを含む結果ノード集合です。ノードは必ずしも文書内の順序とは限りません。 |
| `ORDERED_NODE_SNAPSHOT_TYPE` | `7` | 式に一致するすべてのノードのスナップショットを含む結果ノード集合です。結果セットのノードは、文書内のノードと同じ順序で現れます。 |
| `ANY_UNORDERED_NODE_TYPE` | `8` | 式に一致する単一のノードを格納した結果ノード集合です。このノードは、必ずしも文書内の式に一致する最初のノードであるとは限りません。 |
| `FIRST_ORDERED_NODE_TYPE` | `9` | 式に一致する文書内の最初のノードを格納した結果ノード集合です。 |

例
-

次の例では `resultType` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<div>Is XPath result a node set: <output></output></div>
```

### JavaScript

```js
const xpath = "//div";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ANY\_TYPE,
  null,
);
document.querySelector("output").textContent =
  result.resultType >= XPathResult.UNORDERED\_NODE\_ITERATOR\_TYPE &&
  result.resultType <= XPathResult.FIRST\_ORDERED\_NODE\_TYPE;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-resulttype |

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

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


XPathResult: singleNodeValue プロパティ - Web API

XPathResult: singleNodeValue プロパティ
==================================

**`singleNodeValue`** は `XPathResult` インターフェイスの読み取り専用プロパティで、 `Node` 値を返すか、`XPathResult.resultType` が `ANY_UNORDERED_NODE_TYPE` または `FIRST_ORDERED_NODE_TYPE` である結果のノードが一致しなかった場合は `null` を返します。

値
-

返値は `Document.evaluate()` が返す `XPathResult` の `Node` 値です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `ANY_UNORDERED_NODE_TYPE` または `FIRST_ORDERED_NODE_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `singleNodeValue` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<div>
  Tag name of the element having the text content 'XPath example':
  <output></output>
</div>
```

### JavaScript

```js
const xpath = "//\*[text()='XPath example']";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.FIRST\_ORDERED\_NODE\_TYPE,
  null,
);
document.querySelector("output").textContent = result.singleNodeValue.localName;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-singlenodevalue |

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

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


XPathResult: stringValue プロパティ - Web API

XPathResult: stringValue プロパティ
==============================

**`stringValue`** は `XPathResult` インターフェイスの読み取り専用プロパティで、 `XPathResult.resultType` が `STRING_TYPE` である結果の文字列値を返します。

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

値
-

返値は `Document.evaluate()` が返す `XPathResult` の文字列値です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `STRING_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `stringValue` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<div>Text content of the <div> above: <output></output></div>
```

### JavaScript

```js
const xpath = "//div/text()";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.STRING\_TYPE,
  null,
);
document.querySelector("output").textContent = result.stringValue;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-stringvalue |

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

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


XPathResult: iterateNext() メソッド - Web API

XPathResult: iterateNext() メソッド
===============================

**`iterateNext()`** は `XPathResult` インターフェイスのメソッドで、ノード集合の結果を反復処理し、そこから次のノードを返すか、まだノードがない場合は `null` を返します。

構文
--

```js
iterateNext()
```

### 引数

なし。

### 返値

`XPathResult` ノード集合の中の次の `Node` です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `UNORDERED_NODE_ITERATOR_TYPE` または `ORDERED_NODE_ITERATOR_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

#### INVALID\_STATE\_ERR

結果を返してから文書が変更された場合、 `INVALID_STATE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `iterateNext()` メソッドを使用しています。

### HTML

```html
<div>XPath example</div>
<div>Tag names of the matched nodes: <output></output></div>
```

### JavaScript

```js
const xpath = "//div";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ANY\_TYPE,
  null,
);
let node = null;
const tagNames = [];
while ((node = result.iterateNext())) {
  tagNames.push(node.localName);
}
document.querySelector("output").textContent = tagNames.join(", ");
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-iteratenext |

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

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


XPathResult: snapshotLength プロパティ - Web API

XPathResult: snapshotLength プロパティ
=================================

**`snapshotLength`** は `XPathResult` インターフェイスの読み取り専用プロパティで、結果スナップショットのノード数を表します。

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

値
-

結果スナップショットのノード数を表す整数値です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `UNORDERED_NODE_SNAPSHOT_TYPE` または `ORDERED_NODE_SNAPSHOT_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `snapshotLength` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<div>Number of matched nodes: <output></output></div>
```

### JavaScript

```js
const xpath = "//div";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ORDERED\_NODE\_SNAPSHOT\_TYPE,
  null,
);
document.querySelector("output").textContent = result.snapshotLength;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-snapshotlength |

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

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


XPathResult: numberValue プロパティ - Web API

XPathResult: numberValue プロパティ
==============================

**`numberValue`** は `XPathResult` インターフェイスの読み取り専用プロパティで、 `XPathResult.resultType` が `NUMBER_TYPE` である結果の数値を返します。

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

値
-

返値は `Document.evaluate()` が返す `XPathResult` の数値です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `NUMBER_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `numberValue` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<div>Number of <div>s: <output></output></div>
```

### JavaScript

```js
const xpath = "count(//div)";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.NUMBER\_TYPE,
  null,
);
document.querySelector("output").textContent = result.numberValue;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-numbervalue |

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

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


XPathResult: booleanValue プロパティ - Web API

XPathResult: booleanValue プロパティ
===============================

**`booleanValue`** は `XPathResult` インターフェイスのプロパティで、 `XPathResult.resultType` が `BOOLEAN_TYPE` である結果の論理値を返します。

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

値
-

返値は `Document.evaluate()` が返す `XPathResult` の論理値です。

### 例外

#### TYPE\_ERR

`XPathResult.resultType` が `BOOLEAN_TYPE` でない場合、 `TYPE_ERR` 型の `XPathException` が発生します。

例
-

次の例では `booleanValue` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<p>Text is 'XPath example': <output></output></p>
```

### JavaScript

```js
const xpath = "//div/text() = 'XPath example'";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.BOOLEAN\_TYPE,
  null,
);
document.querySelector("output").textContent = result.booleanValue;
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-booleanvalue |

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

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


XPathResult: invalidIteratorState プロパティ - Web API

XPathResult: invalidIteratorState プロパティ
=======================================

**`invalidIteratorState`** は `XPathResult` インターフェイスの読み取り専用プロパティで、イテレーターが不正な状態になったことを示します。 `XPathResult.resultType` が `UNORDERED_NODE_ITERATOR_TYPE` または `ORDERED_NODE_ITERATOR_TYPE` で、この結果を返してから文書が変更された場合は `true` です。

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

値
-

イテレーターが不正になったかどうかを示す論理値。

例
-

次の例では `invalidIteratorState` プロパティを使用しています。

### HTML

```html
<div>XPath example</div>
<p>Iterator state: <output></output></p>
```

### JavaScript

```js
const xpath = "//div";
const result = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ANY\_TYPE,
  null,
);
// Invalidates the iterator state
document.querySelector("div").remove();
document.querySelector("output").textContent = result.invalidIteratorState
  ? "invalid"
  : "valid";
```

### 結果

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-xpathresult-invaliditeratorstate |

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

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


HTMLInputElement: webkitdirectory プロパティ - Web API

HTMLInputElement: webkitdirectory プロパティ
=======================================

**`HTMLInputElement.webkitdirectory`** はプロパティで、 `webkitdirectory` という HTML 属性の値を反映し、 `<input>` 要素によってユーザーがファイルの代わりにディレクトリーを選択できることを示します。ディレクトリーが選択された場合、ディレクトリーとその内容の階層構造が選択されたアイテムのセットに含まれます。選択されているファイルシステムのファイルアイテムは、 `webkitEntries` を使用して受け取ることができます。

**メモ:** このプロパティは、Google Chrome 固有の API として元々存在していたため、仕様書では `webkitEntries` と呼ばれています。いつか改名される可能性があります。

値
-

論理型で、 `true` は `<input>` 要素がディレクトリーのみを選択することができることを、 `false` はファイルのみが選択できることを示します。

結果を理解する
-------

ユーザーが選択を行った後、 `files` の中のそれぞれの `File` オブジェクトは各自が `File.webkitRelativePath` プロパティセットを持ち、ファイルが所在する位置が選択されたディレクトリーの中の相対パスで設定されます。例えば、次のようなファイルシステムを考えてみてください。

* PhotoAlbums
    + Birthdays
        - Jamie's 1st birthday
            * PIC1000.jpg
            * PIC1004.jpg
            * PIC1044.jpg
        - Don's 40th birthday
            * PIC2343.jpg
            * PIC2344.jpg
            * PIC2355.jpg
            * PIC2356.jpg
    + Vacations
        - Mars
            * PIC5533.jpg
            * PIC5534.jpg
            * PIC5556.jpg
            * PIC5684.jpg
            * PIC5712.jpg

ユーザーが `PhotoAlbums` を選択すると、 files によって報告されるリストは上記のすべてのファイルに対する `File` オブジェクトを含みます。 — しかし、ディレクトリーは含みません。 `PIC2343.jpg` の項目では `webkitRelativePath` が `PhotoAlbums/Birthdays/Don's 40th birthday/PIC2343.jpg` となります。これによって `FileList` が平坦でも階層構造を知ることができます。

**メモ:** `webkitRelativePath` の挙動は *Chromium 72 より前*では異なります。詳しくはこのバグを参照してください。

例
-

この例では、ユーザーが 1 つまたは複数のディレクトリーを選択することができるディレクトリーピッカーが表示されます。 `change` イベントが発生すると、選択されたディレクトリー階層ないのすべてのファイルを含むリストが生成され、表示されます。

### HTML content

```html
<input type="file" id="filepicker" name="fileList" webkitdirectory multiple />
<ul id="listing"></ul>
```

### JavaScript content

```js
document.getElementById("filepicker").addEventListener(
  "change",
  (event) => {
    let output = document.getElementById("listing");
    for (const file of event.target.files) {
      let item = document.createElement("li");
      item.textContent = file.webkitRelativePath;
      output.appendChild(item);
    }
  },
  false,
);
```

### 結果

仕様書
---

| Specification |
| --- |
| File and Directory Entries API # dom-htmlinputelement-webkitdirectory |

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

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

関連情報
----

* ファイルとディレクトリー項目 API
* `HTMLInputElement.webkitEntries`
* `File.webkitRelativePath`


HTMLInputElement: files プロパティ - Web API

HTMLInputElement: files プロパティ
=============================

**`HTMLInputElement.files`** プロパティを通じて、`<input type="file">` 要素で選択された `FileList` にアクセスできます。

値
-

選択されているファイルがあれば、それをリストする `FileList` オブジェクトです。**`HTMLInputElement`** が `type="file"` でない場合は、`null` が返ります。

例
-

以下の例は、**`HTMLInputElement.files`** プロパティにアクセスして、ユーザーが選択したそれぞれのファイルの名前、更新日時、サイズ、種類を出力する方法を示します。

### HTML

```html
<input id="files" type="file" multiple />
```

### JavaScript

**`HTMLInputElement.files`** は、ファイルが選択されていなくても `FileList` を返すことに注意してください。
 この性質があるため、ファイルが選択されているかをチェックせずに `for...of` で走査しても安全です。

```js
const fileInput = document.getElementById("files");

console.log(fileInput.files instanceof FileList); // 空でも true となる

for (const file of fileInput.files) {
  console.log(file.name); // ファイル名を表示
  let fileDate = new Date(file.lastModified);
  console.log(fileDate.toLocaleDateString()); // 日付を表示
  console.log(
    file.size < 1000 ? file.size : Math.round(file.size / 1000) + "KB",
  );
  console.log(file.type); // MIME タイプを表示
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-input-files-dev |

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

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

関連情報
----

* `DataTransfer.files`


HTMLInputElement: stepUp() メソッド - Web API

HTMLInputElement: stepUp() メソッド
===============================

**`HTMLInputElement.stepUp()`** メソッドは、数値型の `<input>` 要素の値を
 `step` 属性の値、または step 属性が明示的に設定されていない場合は既定の `step` の値だけ増加させるものです。このメソッドを呼び出すと、 `value` は (`step` \* n) だけ減少します。ここで、n は指定されなかった場合、既定で `1` となり、`step` が指定されなかった場合、 `step` の既定値となります。

| 入力型 | 既定の step の値 | step の宣言の例 |
| --- | --- | --- |
| date | `1` （日） | 7 日（1 週間）単位の増加:`<input type="date" min="2019-12-25" step="7">` |
| month | `1` （ヶ月） | 12 ヶ月（1 年）単位の増加:`<input type="month" min="2019-12" step="12">` |
| week | `1` （週間） | 2 週間単位の増加:`<input type="week" min="2019-W23" step="2">` |
| time | `60` （秒） | 900 秒（15 分）単位の増加:`<input type="time" min="09:00" step="900">` |
| datetime-local | `1` （日） | 同じ曜日:`<input type="datetime-local" min="019-12-25T19:30"
step="7">` |
| number | `1` | 0.1 刻み`<input type="number" min="0" step="0.1" max="10">` |
| range | `1` | 2 ずつ増加:`<input type="range" min="0" step="2" max="10">` |

このメソッドを呼び出すと、フォームコントロール内で設定された制約の範囲内で、 `step` 属性で指定された値に引数を掛けた値だけ、フォームコントロールの値を変更します。引数が渡されなかった場合の既定値は `1` です。このメソッドは、値が `max` を上回ったり、 `step` 属性が設定する制約に違反させるようなことはしません。

`stepUp()` メソッドを呼び出す前の値が無効であった場合、例えば `step` 属性で設定した制約に適合しない場合、 `stepUp()` メソッドを呼び出すと、フォームコントロールの制約に適合する値が返されます。

フォームコントロールが時刻、日付、数値以外のもので、 `step` 属性に対応していない場合（前述の表に対応する入力型のリストを参照）、または `step` 値が `any` に設定されている場合、 `InvalidStateError` 例外が発生します。

構文
--

```js
stepUp()
stepUp(stepIncrement)
```

### 引数

`stepIncrement` 省略可

数値です。引数が渡されなかった場合、 `stepIncrement` は既定で `1` になります。

### 返値

なし (`undefined`)。

例
-

この例のボタンをクリックすると、 number 入力型の値が増加します。

### HTML

```html
<p>
  <label for="theNumber">
    0 から 400 までの 5 で割り切れる数を入力してください。
  </label>
  <input type="number" step="5" id="theNumber" min="0" max="400" />
</p>
<p>
  <label>増加させたい段階の数を入力するか、空欄のままにしてください。</label>
  <input type="number" step="1" id="incrementInput" min="0" max="25" />
</p>
<input type="button" value="Increment" id="theButton" />
```

### Java10Script

```js
/\* 関数を呼び出すボタンを生成 \*/
const button = document.getElementById("theButton");
button.addEventListener("click", () => {
  stepOnUp();
});

function stepOnUp() {
  let input = document.getElementById("theNumber");
  let val = document.getElementById("incrementInput").value;

  if (val) {
    /\* 引数付きで加算 \*/
    input.stepUp(val);
  } else {
    /\* 引数なしで加算。 0 を試してください。 \*/
    input.stepUp();
  }
}
```

### CSS

```css
input:invalid {
  border: red solid 3px;
}
```

### 結果

`stepUp` メソッドに引数を渡さなかった場合、既定値は `1` になります。他の値は `step` 属性の値に乗算されるので、この場合は `5` となります。 *`stepIncrement`* に 4 を渡した場合、 `stepUp` は `4 * 5` すなわち `20` だけ行われます。この引数が `0` であった場合、数値は加算されません。 `stepUp` メソッドは入力が範囲外にならないように、この場合は `400` になった時点で停止し、引数として渡された値の小数点以下を切り捨てます。

段階の加算係数を `1.2` に設定してみてください。メソッドを呼び出すとどうなるでしょうか？

値を不正な数値である `4` に設定してみてください。メソッドを呼び出すとどうなるでしょうか？

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-input-stepup-dev |

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

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

関連情報
----

* `<input>`
* `HTMLInputElement`
* `HTMLInputElement.stepDown`
* `step`,
 `min`, `max` 属性


HTMLInputElement: setSelectionRange() メソッド - Web API

HTMLInputElement: setSelectionRange() メソッド
==========================================

**`HTMLInputElement.setSelectionRange()`** メソッドは、 `<input>` または `<textarea>` 要素の中で現在のテキストの選択範囲の開始位置と終了位置を設定します。

オプションとして、新しいバージョンのブラウザーでは、選択が行われたとみなす方向を指定することができます。これにより、例えば、ユーザーが選択範囲を設定するのに、選択されたテキストの末尾から先頭に向けてクリックとドラッグが行われたことを示すことができます。

この関数は 1 回の呼び出しで、 `HTMLInputElement.selectionStart`, `selectionEnd`, `selectionDirection` の各プロパティを更新します。

WHATWG フォーム仕様書によると、 `selectionStart`, `selectionEnd` プロパティと `setSelectionRange` メソッドは、 text, search, URL, tel, password 型の入力欄にのみ適用されることに注意してください。 Chrome のバージョン 33 以降では、それ以外の入力型でこれらのプロパティとメソッドにアクセスすると例外が発生します。例えば、 `number` 型の入力欄では、 "Failed to read the 'selectionStart' property from 'HTMLInputElement': The input element's type ('number') does not support selection" （'HTMLInputElement' の 'selectionStart' プロパティを読み取りに失敗しました。この input 要素の入力型 ('number') は選択に対応していません）となります。

input 要素の**すべて**のテキストを選択したい場合は、代わりに HTMLInputElement.select() メソッドを使用してください。

構文
--

```js
setSelectionRange(selectionStart, selectionEnd)
setSelectionRange(selectionStart, selectionEnd, selectionDirection)
```

### 引数

`selectionEnd` が `selectionStart` より小さい場合、両方の値は `selectionEnd` として扱われます。

`selectionStart`

選択する最初の文字の 0 から始まる位置です。位置が要素の値の長さよりも大きい場合は、要素の値の末尾の位置と見なされます。

`selectionEnd`

選択する最後の文字の*次の* 0 から始まる位置です。位置が要素の長さよりも大きい場合は、要素の値の末尾の位置と見なされます。

`selectionDirection` 省略可

選択が行われたと見なされる方向を示す文字列です。取りうる値は次の通りです。

* `"forward"`
* `"backward"`
* `"none"` 選択方向が不明または無関係な場合です。既定値です。

### 返値

なし (`undefined`)。

例
-

この例の中のボタンをクリックすると、テキストボックスの 3、4、5 番目の文字（"Mozilla" の "zil"）が選択状態になります。

### HTML

```html
<input type="text" id="text-box" size="20" value="Mozilla" />
<button onclick="selectText()">テキストを選択</button>
```

### JavaScript

```js
function selectText() {
  const input = document.getElementById("text-box");
  input.focus();
  input.setSelectionRange(2, 5);
}
```

### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-textarea/input-setselectionrange-dev |

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

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

関連情報
----

* `<input>`
* `<textarea>`
* `HTMLInputElement`
* `Selection`


HTMLInputElement: selectionchange イベント - Web API

HTMLInputElement: selectionchange イベント
======================================

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

**`selectionchange`** は選択 API のイベントで、 `<input>` 要素の中でテキストの選択状態が変化したときに発行されます。
 これは、文字単位の選択範囲位が変化した場合も、キャレットが移動したときも含みます。

このイベントはキャンセル不可です。

このイベントは通常 `<input>` 上にイベントリスナーを追加し、ハンドラー関数内で `HTMLInputElement` の `selectionStart`、`selectionEnd`、`selectionDirection` の各プロパティを読み取ることで処理します。

また、`onselectionchange` イベントハンドラーにリスナーを追加し、ハンドラー関数内で `Document.getSelection()` を使って選択状態を得ることもできます。しかし、これはテキストの選択範囲の変更を取得するのにはあまり便利ではありません。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

以下の例は、 `<input>` 要素の中にあるテキストの選択状態を取得する方法を示しています。

### HTML

```html
<div>
  こちらにテキストを入力して選択してください:<br /><input
 id="mytext"
 rows="2"
 cols="20" />
</div>
<div>selectionStart: <span id="start"></span></div>
<div>selectionEnd: <span id="end"></span></div>
<div>selectionDirection: <span id="direction"></span></div>
```

### JavaScript

```js
const myinput = document.getElementById("mytext");

myinput.addEventListener("selectionchange", () => {
  document.getElementById("start").textContent = myinput.selectionStart;
  document.getElementById("end").textContent = myinput.selectionEnd;
  document.getElementById("direction").textContent = myinput.selectionDirection;
});
```

### 結果

仕様書
---

| Specification |
| --- |
| Selection API # selectionchange-event |
| Selection API # dom-globaleventhandlers-onselectionchange |

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

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


HTMLInputElement: invalid イベント - Web API

HTMLInputElement: invalid イベント
==============================

**`invalid`** イベントは、送信可能な要素が制約検証を受け、制約を満たしていない場合に発行されます。

このイベントは、送信時にフォームの問題の概要を表示するのに便利です。フォームが送信されると、 `invalid` イベントがそれぞれの妥当ではない状態にあるフォームコントロールで発生します。送信可能な要素が妥当であるかどうかは、その所有者である `<form>` を送信する前、または `checkValidity()` メソッドがその要素またはその所有者である `<form>` に呼び出された後にチェックされます。

`blur` ではチェックが行われません。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

フォームが無効な値で送信された場合、送信可能な要素がチェックされ、エラーが見つかった場合、無効な要素で `invalid` イベントが発生します。この例では、入力に無効な値があったために `invalid` イベントが発生した場合、無効な値がログに記録されます。

### HTML

```html
<form action="#">
  <div>
    <label>
      1 から 10 までの整数を入力してください:
      <input type="number" min="1" max="10" required />
    </label>
  </div>
  <div><input type="submit" value="送信" /></div>
</form>
<hr />
Invalid values:
<ul id="log"></ul>
```

### JavaScript

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

input.addEventListener("invalid", (e) => {
  log.appendChild(
    Object.assign(document.createElement("li"), {
      textContent: JSON.stringify(e.target.value),
    }),
  );
});
```

### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # event-invalid |

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

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

関連情報
----

* HTML の `<form>` element
* 関連イベント: `submit`
* CSS の `:invalid` 擬似クラス


HTMLInputElement: setRangeText() メソッド - Web API

HTMLInputElement: setRangeText() メソッド
=====================================

**`HTMLInputElement.setRangeText()`** メソッドは、 `<input>` や `<textarea>` 要素の中のテキストの範囲を新しい文字列に置き換えます。

構文
--

```js
setRangeText(replacement)
setRangeText(replacement, start)
setRangeText(replacement, start, end)
setRangeText(replacement, start, end, selectMode)
```

### 引数

`replacement`

挿入する文字列。

`start` 省略可

置換する最初の文字を 0 から始まる位置で指定します。既定値は現在の `selectionStart` の値（ユーザーが現在選択している先頭）です。

`end` 省略可

置換する最後の文字の*次の*文字を 0 から始まる位置で指定します。既定値は現在の `selectionEnd` の値（ユーザーが現在選択している末尾）です。

`selectMode` 省略可

 テキストが置換された後で、選択範囲がどのように設定されるかを定義する文字列です。
 次の値が利用できます。

* `"select"`: 新規挿入したテキストを選択します。
* `"start"`: 挿入したテキストの直前に選択範囲を移動します。
* `"end"`: 挿入したテキストの直後に選択範囲を移動します。
* `"preserve"`: 選択範囲を保全しようとします。これが既定値です。

### 返値

なし (`undefined`)。

例
-

この例にあるボタンをクリックすると、テキストボックス内のテキストの一部を置き換えます。新しく挿入されたテキストは、その後で強調（選択）されます。

### HTML

```html
<input
 type="text"
 id="text-box"
 size="30"
 value="このテキストは更新されていません。" />
<button onclick="selectText()">テキストを更新</button>
```

### JavaScript

```js
function selectText() {
  const input = document.getElementById("text-box");
  input.focus();
  input.setRangeText("ました", 11, 16, "select");
}
```

### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-textarea/input-setrangetext-dev |

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

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

関連情報
----

* `<input>`
* `<textarea>`
* `HTMLInputElement`
* `Selection`


HTMLInputElement: disabled プロパティ - Web API

HTMLInputElement: disabled プロパティ
================================

**`HTMLInputElement.disabled`** は `disabled` という HTML の属性を反映した論理値で、このコントロールが無効であるかどうかを表します。無効である場合、クリックを受け付けません。無効化された要素は使用できず、クリックもできません。

値
-

論理値です。

例
-

### HTML

```html
<p>
  <label>
    <input id="check-box" name="b" value="1" type="checkbox" disabled />
    このボックスをチェックしてください。
  </label>
</p>
<p>
  <label>
    <input id="toggle-box" name="b" value="2" type="checkbox" />
    他のボックスを有効にします。
  </label>
</p>
```

### JavaScript

```js
const checkBox = document.getElementById("check-box");
const toggleBox = document.getElementById("toggle-box");

toggleBox.addEventListener(
  "change",
  (event) => {
    checkBox.disabled = !event.target.checked;
  },
  false,
);
```

### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-fe-disabled |

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

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


HTMLInputElement: labels プロパティ - Web API

HTMLInputElement: labels プロパティ
==============================

**`HTMLInputElement.labels`** は読み取り専用プロパティで、 `hidden` 以外の `<input>` 要素に関連付けられた `<label>` 要素の `NodeList` を返します。この要素が `hidden` 型であった場合は、このプロパティは `null` を返します。

値
-

`NodeList` で、その `<input>` 要素に関連付けられた `<label>` 要素が入ります。

例
-

### HTML

```html
<label id="label1" for="test">Label 1</label>
<input id="test" />
<label id="label2" for="test">Label 2</label>
```

### JavaScript

```js
window.addEventListener("DOMContentLoaded", () => {
  const input = document.getElementById("test");
  for (const label of input.labels) {
    console.log(label.textContent); // "Label 1" and "Label 2"
  }
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-lfe-labels-dev |

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

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


HTMLInputElement: stepDown() メソッド - Web API

HTMLInputElement: stepDown() メソッド
=================================

**`HTMLInputElement.stepDown([n])`** メソッドは、数値型の `<input>` 要素の値を
 `step` 属性の値、または引数として数値が渡された場合は step 属性の最大 `n` 倍の値だけ減少させるものです。

このメソッドを呼び出すと、 `value` は (`step` \* n) だけ減少します。ここで、n は指定されなかった場合、既定で 1 となり、`step` が指定されなかった場合、 `step` の既定値となります。

 step 属性に対応しているすべての数値、日付、時刻の入力タイプ（date, month,
 week, time,datetime-local, number, range）で有効です。

`<input id="myTime" type="time" max="17:00" step="900" value="17:00">` と指定された場合、 `myTime.stepDown(3)` を呼び出すと値は 16:15 になります。これは `3 * 900` または 45 分を引くからです。 `myTime.stepDown()` を引数無しで呼び出すと、 `n` が既定で `1` となるので `16:45` になります。

```html
<!-- 900 秒 (15 分) の間隔で減算 -->
<input type="time" max="17:00" step="900" />

<!-- 7 日 (1 週間) の間隔で減算 -->
<input type="date" max="2019-12-25" step="7" />

<!-- 12 ヶ月 (1 年) の間隔で減算 -->
<input type="month" max="2019-12" step="12" />
```

しかし、 `stepDown` を `<input type="time" max="17:00" step="900">` で呼び出すと、期待するような `17:00` にはなりません。 — `stepUp` を `<input type="time" min="17:00" step="900">` で呼び出した場合も同様です。初めて `stepDown` を呼び出すと、 `max` 属性が設定されているにもかかわらず `23:45` になります。次に呼び出すと、値は `17:00` となり、もう一度呼び出すと、値は `16:45` になります。

```js
let input1 = document.createElement("input");
input1.setAttribute("type", "time");
input1.setAttribute("min", "17:00");
input1.setAttribute("step", 900);
console.log(input1.value); // ""
input1.stepUp();
console.log(input1.value); // "17:00"
// しかし
let input2 = document.createElement("input");
input2.setAttribute("type", "time");
input2.setAttribute("max", "17:00");
input2.setAttribute("step", 900);
console.log(input2.value); // ""
input2.stepDown();
console.log(input2.value); // "23:45"
input2.stepDown();
console.log(input2.value); // "17:00"
input2.stepDown();
console.log(input2.value); // "16:45"
```

このメソッドを呼び出すと、フォームコントロール内で設定された制約の範囲内で、 `step` 属性で指定された値に引数を掛けた値だけ、フォームコントロールの値を変更します。引数が渡されなかった場合の既定値は `1` です。このメソッドは、値が `min` を下回ったり、 `step` 属性が設定する制約に違反させるようなことはしません。 `n` に負の値を指定すると、値が増加しますが、`max` の値を超えて増加することはありません。

`stepDown()` メソッドを呼び出す前の値が無効であった場合、例えば `step` 属性で設定した制約に適合しない場合、 `stepDown()` メソッドを呼び出すと、フォームコントロールの制約に適合する値が返されます。

フォームコントロールが時刻、日付、数値以外のもので、 `step` 属性に対応していない場合（前述の対応している入力型のリストを参照）、または `step` 値が `any` に設定されている場合、 `InvalidStateError` 例外が発生します。

`HTMLInputElement.stepDown()`

`value` を（`step` \* n だけ）減少させます。ここで n が指定されなかった場合は、既定で 1 になります。次の場合は例外 `InvalidStateError` が発生します。

* このメソッドが現在の `type` の値に適切ではない場合
* この要素に `step` の値がなかった場合
* `value` が数値に変換できなかった場合
* 結果の値が `max` を超えたり、 `min` を下回ったりした場合

構文
--

```js
stepDown()
stepDown(stepDecrement)
```

### 引数

`stepDecrement` 省略可

数値です。引数が渡されなかった場合、 *stepDecrement* は既定で 1 になります。

この値が浮動小数点数であった場合、値は `Math.floor(stepDecrement)` が渡されたときと同様に減少します。この値が負の数であった場合は、値は減少するのではなく増加します。

### 返値

なし (`undefined`)。

例
-

この例のボタンをクリックすると、 number 入力型の値が減少します。

### HTML

```html
<p>
  <label for="theNumber">
    0 から 400 までの 5 で割り切れる数を入力してください。
  </label>
  <input type="number" step="5" id="theNumber" min="0" max="400" />
</p>
<p>
  <label for="decrementButton">
    減少させたい段階の数を入力するか、空欄のままにしてください。
  </label>
  <input type="number" step="1" id="decrementInput" min="-2" max="15" />
</p>
<input type="button" value="Decrement" id="theButton" />
```

### JavaScript

```js
/\* 関数を呼び出すボタンを生成 \*/
let button = document.getElementById("theButton");
button.addEventListener("click", () => {
  stepOnDown();
});

function stepOnDown() {
  let input = document.getElementById("theNumber");
  let val = document.getElementById("decrementInput").value;

  if (val) {
    // 引数付きで減算
    input.stepDown(val);
  } else {
    // 引数なしで減算。 0, 5, -2 などを試してください。
    input.stepDown();
  }
}
```

### CSS

```css
input:invalid {
  border: red solid 3px;
}
```

### 結果

`stepDown()` メソッドに引数を渡さなかった場合、既定値は 1 になります。他の値は `step` 属性の値に乗算されるので、この場合は 5 となります。 *`stepDecrement`* に `4` を渡した場合、 `stepDown` は `4 * 5` すなわち `20` だけ行われます。この引数が `0` であった場合、数値は減算されません。 `stepDown()` メソッドは入力が範囲外にならないように、この場合は 0 になった時点で停止し、引数として渡された値の小数点以下を切り捨てます。

入力の言さんちをを `1.2` に設定してみてください。メソッドを呼び出すとどうなるでしょうか？

値を不正な数値である `44` に設定してみてください。メソッドを呼び出すとどうなるでしょうか？

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-input-stepdown-dev |

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

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

関連情報
----

* `<input>`
* `HTMLInputElement`
* `HTMLInputElement.stepUp()`
* `step`,
 `min`, `max` 属性


HTMLInputElement: popoverTargetAction プロパティ - Web API

HTMLInputElement: popoverTargetAction プロパティ
===========================================

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

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

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

**`popoverTargetAction`** は `HTMLButtonElement` インターフェイスのプロパティで、`<input>` 要素の `type="button"` 型でで制御されるポップオーバー要素で実行されるアクション（`"hide"`、`"show"`、`"toggle"` の何れか）を取得および設定します。

これは HTML の `popovertargetaction` 属性の値を反映します。

値
-

列挙値です。取りうる値は次の通りです。

`"hide"`

このボタンは表示中のポップオーバーを非表示にします。すでに非表示のポップオーバーを非表示にしようとした場合は、何も行われません。

`"show"`

このボタンは非表示のポップオーバーを表示します。すでに表示中のポップオーバーを表示させようとした場合は、何も行われません。

`"toggle"`

このボタンはポップオーバーを表示と非表示の間でトグル切り替えします。ポップオーバーが非表示の場合は、表示されます。ポップオーバーが表示中の場合は、非表示になります。`popoverTargetAction` が設定されていない場合、`"toggle"` がこの制御ボタンで行われる既定のアクションになります。

例
-

```js
function supportsPopover() {
  return HTMLElement.prototype.hasOwnProperty("popover");
}

const popover = document.getElementById("mypopover");
const toggleBtn = document.getElementById("toggleBtn");

const popoverSupported = supportsPopover();

if (popoverSupported) {
  popover.popover = "auto";
  toggleBtn.popoverTargetElement = popover;
  toggleBtn.popoverTargetAction = "toggle";
} else {
  console.log("Popover API not supported.");
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-popovertargetaction |

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

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

関連情報
----

* ポップオーバー API


HTMLInputElement: select() メソッド - Web API

HTMLInputElement: select() メソッド
===============================

**`HTMLInputElement.select()`** メソッドは、`<textarea>` 要素またはテキストフィールドを含む `<input>` 要素内のすべてのテキストを選択します。

構文
--

```js
select()
```

### 引数

なし。

### 返値

なし (`undefined`)。

例
-

この例のボタンをクリックすると、 `<input>` 要素内のすべてのテキストが選択されます。

### HTML

```html
<input type="text" id="text-box" size="20" value="Hello world!" />
<button onclick="selectText()">テキストを選択</button>
```

### JavaScript

```js
function selectText() {
  const input = document.getElementById("text-box");
  input.focus();
  input.select();
}
```

### 結果

メモ
--

`element.select()` を呼び出しても、入力欄がフォーカスを得るとは限りませんので、よく `HTMLElement.focus` と一緒に使われます。

これに対応していないブラウザーでは、 HTMLInputElement.setSelectionRange() の引数に 0 と入力値の長さを指定して呼び出すことで置き換えることができます。

```html
<input onClick="this.select();" value="Sample Text" />
<!-- equivalent to -->
<input
 onClick="this.setSelectionRange(0, this.value.length);"
 value="Sample Text" />
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-textarea/input-select |

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

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

関連情報
----

* `<input>`
* `<textarea>`
* `HTMLInputElement`
* `HTMLInputElement.setSelectionRange`


HTMLInputElement: setCustomValidity() メソッド - Web API

HTMLInputElement: setCustomValidity() メソッド
==========================================

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

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

* Learn more
* See full compatibility
* Report feedback
**`HTMLInputElement.setCustomValidity()`** メソッドは、その要素にカスタム検証メッセージを設定します。

構文
--

```js
setCustomValidity(message)
```

### 引数

`message`

検証エラーに使用するメッセージです。

### 返値

なし (`undefined`)。

### 例外

なし。

例
-

この例では、 input 要素の ID を渡し、値が不足しているか、低すぎるか、高すぎるかによって、異なるエラーメッセージを設定します。さらに、同じ要素で `reportValidity()` メソッドを呼び出す必要があります。そうしないと何も起こりません。

```js
function validate(inputID) {
  const input = document.getElementById(inputID);
  const validityState = input.validity;

  if (validityState.valueMissing) {
    input.setCustomValidity("You gotta fill this out, yo!");
  } else if (validityState.rangeUnderflow) {
    input.setCustomValidity("We need a higher number!");
  } else if (validityState.rangeOverflow) {
    input.setCustomValidity("That's too high!");
  } else {
    input.setCustomValidity("");
  }

  input.reportValidity();
}
```

エラーがない場合は、メッセージを空文字列に設定することが重要です。エラーメッセージが空でない限り、フォームは検証を通過せず、送信されません。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-cva-setcustomvalidity-dev |

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

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

関連情報
----

* 学習: クライアント側フォーム検証
* ガイド: 制約検証
* `ValidityState`


HTMLInputElement: showPicker() メソッド - Web API

HTMLInputElement: showPicker() メソッド
===================================

**`HTMLInputElement.showPicker()`** メソッドは、`input` 要素のブラウザーのピッカーを表示します。

これは、通常、要素が選択されたときに表示されるピッカーと同じものですが、ボタンを押すなど、ユーザーの操作で起動させることができます。

ブラウザーがよく実装しているのは、`"date"`, `"month"`, `"week"`, `"time"`, `"datetime-local"`, `"color"`, `"file"` の型の入力欄です。これは `<datalist>` 要素や `autocomplete` 属性からの項目を表示することもできます。

もっと一般的に言えば、このメソッドは、ピッカーを持つプラットフォーム上のあらゆる入力要素にピッカーを表示するのが理想的です。

構文
--

```js
showPicker()
```

### 引数

なし。

### 返値

`undefined` です。

### 例外

`InvalidStateError` の `DOMException`

要素が変更可能でない場合、つまりユーザーが変更することができない、または自動的に事前入力することができない場合に発生します。

`NotAllowedError` の `DOMException`

タッチジェスチャーやマウスクリックなどのユーザー操作によって明示的に起動されなかった場合に発生します（ピッカーには一時的な有効化が必要です）。

`SecurityError` の `DOMException`

別オリジンの iframe で呼び出された場合に発生します。ただし、ファイルピッカーとカラーピッカーは例外（歴史的な理由で除外されます）。

セキュリティ
------

一時的な活性化が必要です。この機能を作業するためには、ユーザーがページや UI 要素を操作する必要があります。

例
-

### 機能検出

以下のコードは、`showPicker()` に対応しているかどうかをチェックする方法を示します。

```js
if ("showPicker" in HTMLInputElement.prototype) {
  // showPicker() is supported.
}
```

### 通常の入力欄のピッカー

この例は、この機能を `color` と `file` の入力ピッカーに使用する方法を示しています。

**メモ:** `date`、`datetime-local`、`month`、`time`、`week` のピッカーも同じように起動します。
 ライブ例がオリジン間フレームで実行され、`SecurityError`を発生させてしまうため、ここでは示せません。

#### HTML

```html
<p>
  <input type="color" />
  <button id="color">カラーピッカーを表示</button>
</p>

<p>
  <input type="file" />
  <button id="file">ファイルピッカーを表示</button>
</p>
```

#### JavaScript

このコードは、選択されたボタンの直前の要素を取得し、それに対して `showPicker()` を呼び出すだけです。

```js
document.querySelectorAll("button").forEach((button) => {
  button.addEventListener("click", (event) => {
    const input = event.srcElement.previousElementSibling;
    try {
      input.showPicker();
    } catch (error) {
      window.alert(error);
    }
  });
});
```

#### 結果

それぞれの入力型の横にあるボタンをクリックすると、その入力型のピッカーが表示されます。

### データリスト入力における showPicker()

`showPicker()`は、`<datalist>` で定義されている選択肢のリストに対してピッカーを起動することができます。

まず `<datalist>` を HTML で定義します。いくつものインターネットブラウザー、それを使用する `text` 型の入力、そしてボタンから構成されています。

```html
<datalist id="browsers">
  <option value="Chrome"></option>
  <option value="Firefox"></option>
  <option value="Opera"></option>
  <option value="Safari"></option>
  <option value="Microsoft Edge"></option>
</datalist>

<input type="text" list="browsers" />
<button>ブラウザーを選択</button>
```

下記コードでは、ボタンがクリックされたときに `showPicker()` を呼び出すイベントリスナーを追加しています。

```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");

button.addEventListener("click", () => {
  try {
    browserInput.showPicker();
  } catch (error) {
    // 他のピッカーの仕組みで代替
  }
});
```

### 自動補完における showPicker()

`showPicker()` は `autocomplete` のある入力欄に対するピッカーを起動することができます。

ここでは、自動補完の選択肢の "name" を取る入力を定義しています。

```html
<input autocomplete="name" /> <button>自動補完の選択肢を表示</button>
```

下記コードは、ボタンがクリックされたときの入力のピッカーを示すものです。

```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");

button.addEventListener("click", () => {
  try {
    browserInput.showPicker();
  } catch (error) {
    // 他のピッカーの仕組みで代替
  }
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-input-showpicker |

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

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

関連情報
----

* `<input>`
* `HTMLInputElement`
* `<datalist>`
* `autocomplete`


HTMLInputElement: select イベント - Web API

HTMLInputElement: select イベント
=============================

**`select`** イベントは、いくらかのテキストが選択されたときに発生します。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

### 選択範囲をログ出力

```html
<input value="この要素のテキストの一部を選択してみてください。" />
<p id="log"></p>
```

```js
function logSelection(event) {
  const log = document.getElementById("log");
  const selection = event.target.value.substring(
    event.target.selectionStart,
    event.target.selectionEnd,
  );
  log.textContent = `You selected: ${selection}`;
}

const input = document.querySelector("input");
input.addEventListener("select", logSelection);
```

### onselect による同等の処理

イベントハンドラーを `onselect` プロパティで設定することもできます。

```js
input.onselect = logSelection;
```

仕様書
---

| Specification |
| --- |
| HTML Standard # event-select |
| HTML Standard # handler-onselect |

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

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


HTMLInputElement: webkitEntries プロパティ - Web API

HTMLInputElement: webkitEntries プロパティ
=====================================

**`webkitEntries`** は `HTMLInputElement` インターフェイスの読み取り専用プロパティで、ユーザーが `<input>` 要素の `file` 型を用いて選択したファイルやディレクトリーを表す、ファイルシステムの項目（`FileSystemEntry` (en-US) に基づくオブジェクト）の配列を含みます。その選択がドラッグ & ドロップで行われた場合にのみ、ダイアログ内でファイルを選択しても、プロパティは空になります。

`webkitdirectory` プロパティが `true` である場合のみ、配列が入ることがあります。これは、 `<input>` 要素でユーザーがディレクトリーを選択することができることを意味します。

**メモ:** このプロパティは仕様書で `webkitEntries` と呼ばれていますが、これはもともと Google Chrome 独自の API であったためです。いつか改名される可能性があります。

値
-

`FileSystemEntry` (en-US) に基づいたオブジェクト配列で、それぞれの要素が `<input>` 要素で選択されたファイルを表します。具体的には、ファイルは `FileSystemFileEntry` オブジェクトで表現され、許可されていれば、ディレクトリーは `FileSystemDirectoryEntry` オブジェクトで表されます。

例
-

この例では、ファイル選択 `<input>` 要素を作成し、選択されたファイルを処理する方法を示しています。

### HTML

```html
<input id="files" type="file" multiple />
```

### JavaScript

```js
document.getElementById("files").addEventListener("change", (event) => {
  event.target.webkitEntries.forEach((entry) => {
    /\* do stuff with the entry \*/
  });
});
```

`change` イベントが発生するたびに、このコードは選択されたファイルリストを走査して、 `FileSystemEntry` (en-US) ベースのオブジェクトを取得し操作をします。

仕様書
---

| Specification |
| --- |
| File and Directory Entries API # dom-htmlinputelement-webkitentries |

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

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

関連情報
----

* ファイルとディレクトリー項目 API
* ファイルとディレクトリー項目 API 入門
* `HTMLInputElement`
* `FileSystemEntry` (en-US)
* `FileSystem`


HTMLInputElement: checkValidity() メソッド - Web API

HTMLInputElement: checkValidity() メソッド
======================================

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

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

* Learn more
* See full compatibility
* Report feedback
**`HTMLInputElement.checkValidity()`** メソッドは、その要素の値の妥当性を示す論理値を返します。値が無効である場合、このメソッドは要素に `invalid` イベントを発行します。

構文
--

```js
checkValidity()
```

### 引数

なし。

### 返値

要素の値を検証して問題ない場合は `true` を、そうでなければ `false` を返します。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-cva-checkvalidity-dev |

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

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

関連情報
----

* reportValidity
* 学習: クライアント側フォーム検証
* ガイド: 制約検証


HTMLInputElement: reportValidity() メソッド - Web API

HTMLInputElement: reportValidity() メソッド
=======================================

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

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

* Learn more
* See full compatibility
* Report feedback
**`reportValidity()`** は `HTMLInputElement` インターフェイスのメソッドで、 `checkValidity()` メソッドと同じ検証のチェック手順を実行します。値が無効であった場合、このメソッドはその要素に `invalid` イベントを発行し、（そのイベントがキャンセルされなければ）ユーザーに問題を報告します。

構文
--

```js
reportValidity()
```

### 引数

なし。

### 返値

要素を検証して問題がなければ `true` を返し、それ以外の場合は `false` を返します。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-cva-reportvalidity-dev |

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

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

関連情報
----

* checkValidity
* 学習: クライアント側フォーム検証
* ガイド: 制約検証


HTMLInputElement: popoverTargetElement プロパティ - Web API

HTMLInputElement: popoverTargetElement プロパティ
============================================

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

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

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

**`popoverTargetElement`** は `HTMLInputElement` インターフェイスのプロパティで、`<input>` 要素の `type="button"` 型で制御されるポップオーバー要素を取得および設定します。

これは JavaScript において HTML の `popovertarget` 属性に相当するものです。

値
-

DOM 内でのポップオーバー要素への参照です。

例
-

```js
function supportsPopover() {
  return HTMLElement.prototype.hasOwnProperty("popover");
}

const popover = document.getElementById("mypopover");
const toggleBtn = document.getElementById("toggleBtn");

const popoverSupported = supportsPopover();

if (popoverSupported) {
  popover.popover = "auto";
  toggleBtn.popoverTargetElement = popover;
  toggleBtn.popoverTargetAction = "toggle";
} else {
  console.log("Popover API not supported.");
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-popovertargetelement |

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

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

関連情報
----

* ポップオーバー API


HTMLInputElement: search イベント - Web API

HTMLInputElement: search イベント
=============================

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

**`search`** イベントは、 `<input>` 要素の `type="search"` にて検索が開始されたときに発生します。

検索を開始する方法はいくつかあり、例えば、 `<input>` にフォーカスがある時に `Enter` を押したり、`incremental` 属性が存在すれば、最も新しいキー入力から UA 定義のタイムアウト時間が経過してから検索が開始されます（新しくキー入力をするとタイムアウトがリセットされるので、イベントが繰り返して発生します）。

現在 UA が `<input type="search">` を実装している方法では、フィールド内をクリアするために追加のコントロールを置きます。このコントロールを使用しても `search` イベントが発生します。この場合、 `<input>` 要素の `value` は空文字列になります。

このイベントはキャンセル不可です。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

```js
// addEventListener 版
const input = document.querySelector('input[type="search"]');

input.addEventListener("search", () => {
  console.log(`The term searched for was ${input.value}`);
});
```

```js
// onsearch 版
const input = document.querySelector('input[type="search"]');

input.onsearch = () => {
  console.log(`The term searched for was ${input.value}`);
};
```

仕様書
---

このイベントは仕様書に含まれていません。

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

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


HTMLInputElement: multiple プロパティ - Web API

HTMLInputElement: multiple プロパティ
================================

**`HTMLInputElement.multiple`** プロパティは、入力フィールドが複数の値を持つことができるかどうかを示します。 Firefox では、 `multiple` は `<input type="file">` でのみ対応しています。

値
-

論理値です。

例
-

```js
// fileInput は <input type=file multiple> です
let fileInput = document.getElementById("myfileinput");

if (fileInput.multiple) {
  // fileInput.files を反復処理
  for (const file of fileInput.files) {
    // ファイルの一つに対してアクションを実行
  }
  // 一つのファイルのみが有効な場合
} else {
  let [file] = fileInput.files;
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-input-multiple |

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

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

関連情報
----

* FileList
* Bug 523771 - <input type=file multiple> への対応


GamepadHapticActuator.pulse() - Web API

GamepadHapticActuator.pulse()
=============================

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

`GamepadHapticActuator` インターフェイスの **`pulse()`** メソッドは、指定された期間、特定の強度でハードウェアパルスを作成します。

構文
--

```js
gamepadHapticActuatorInstance.pulse(value, duration).then(function(result) { ... });
```

### 引数

*value*

パルスの強度を表す double 。これはハードウェアの型によって異なりますが、通常は 0.0 (強度なし) から 1.0 (完全な強度) の値を取ります。

*duration*

パルスの持続時間をミリ秒で表す double 。

**メモ:** `pulse()` への繰り返しの呼び出しは、それらがまた進行中である場合、以前の呼び出しをオーバーライドします。

### 返り値

パルスが正常に完了したときに `true` の値で解決される promise 。

例
-

TBC

仕様書
---

| Specification |
| --- |
| Gamepad Extensions # dom-gamepadhapticactuator-pulse |

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

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

関連情報
----

* Gamepad API


GamepadHapticActuator.type - Web API

GamepadHapticActuator.type
==========================

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

`GamepadHapticActuator` インターフェイスの **`type`** 読み取り専用プロパティは、触覚ハードウェアの型を表す列挙型を返します。

構文
--

```js
var myActuatorType = gamepadHapticActuatorInstance.type;
```

### 値

列挙型 `GamepadHapticActuatorType`; 現在利用な型は次の通りです:

* `vibration` — 振動のハードウェアで、ゴロゴロとした効果を生み出します。
例
-

TBC

仕様書
---

| Specification |
| --- |
| Gamepad Extensions # dom-gamepadhapticactuatortype |

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

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

関連情報
----

* Gamepad API


ScriptProcessorNode: audioprocess イベント - Web API

ScriptProcessorNode: audioprocess イベント
======================================

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

`ScriptProcessorNode` インターフェイスの `audioprocess` イベントは、スクリプトプロセッサーの入力バッファーが処理される準備ができた時発火します。

**メモ:** この機能は AudioWorklets および `AudioWorkletNode` インターフェイスに置き換えられました。

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

イベント型
-----

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

Event

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

*親の `Event` から継承したプロパティも実装しています。*

`playbackTime` 読取専用

音声が再生される時間を表す `double` の値です。`AudioContext.currentTime` の時間として定義されます。

`inputBuffer` 読取専用

 処理対象の入力音声データが格納されたバッファーの `AudioBuffer` です。
 チャンネル数はファクトリーメソッド `AudioContext.createScriptProcessor()` の引数 `numberOfInputChannels` で指定した数です。
 返される `AudioBuffer` はイベントハンドラーのスコープでのみ有効であることに注意してください。

`outputBuffer` 読取専用

 出力音声データを格納する先であるバッファーの `AudioBuffer` です。
 チャンネル数はファクトリーメソッド `AudioContext.createScriptProcessor()` の引数 `numberOfOutputChannels` で指定した数です。
 返される `AudioBuffer` はイベントハンドラーのスコープでのみ有効であることに注意してください。

例
-

```js
scriptNode.addEventListener("audioprocess", (audioProcessingEvent) => {
  // 入力バッファーは、前に読み込んだ歌です
  const inputBuffer = audioProcessingEvent.inputBuffer;

  // 出力バッファーには、変更されて再生されるサンプルが入ります
  const outputBuffer = audioProcessingEvent.outputBuffer;

  // 出力の各チャンネルについてループします (今回は 1 個のみ)
  for (let channel = 0; channel < outputBuffer.numberOfChannels; channel++) {
    const inputData = inputBuffer.getChannelData(channel);
    const outputData = outputBuffer.getChannelData(channel);

    // 4096 個のサンプルについてループします
    for (let sample = 0; sample < inputBuffer.length; sample++) {
      // 出力を入力と同じにします
      outputData[sample] = inputData[sample];

      // 出力の各サンプルにノイズを加えます
      outputData[sample] += (Math.random() \* 2 - 1) \* 0.2;
    }
  }
});
```

イベントハンドラーを `onaudioprocess` プロパティを用いて設定することもできます。

```js
scriptNode.onaudioprocess = (audioProcessingEvent) => {
  // ...
};
```

仕様書
---

2014 年 8 月 29 日の Web Audio API specification の発行以降、この機能は非推奨になりました。この機能は標準化を検討されていません。

この機能は AudioWorklets および `AudioWorkletNode` インターフェイスに置き換えられました。

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

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

関連情報
----

* Web Audio API


ScriptProcessorNode.bufferSize - Web API

ScriptProcessorNode.bufferSize
==============================

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

`ScriptProcessorNode` インターフェイスの `bufferSize` プロパティは、入力と出力両方のバッファーサイズを表す整数をサンプルフレーム数単位で返します。この値は `256` 〜 `16384` の範囲の 2 のべき乗を取りえます。

**メモ:** この機能は AudioWorklets および `AudioWorkletNode` インターフェイスに置き換えられました。

値
-

整数です。

例
-

サンプルコードは `BaseAudioContext.createScriptProcessor()` を参照してください。

仕様書
---

2014 年 8 月 29 日の Web Audio API specification の発行以降、この機能は非推奨になりました。この機能は標準化を検討されていません。

この機能は AudioWorklets および `AudioWorkletNode` インターフェイスに置き換えられました。

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

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

関連情報
----

* Web Audio API の使用


USBConfiguration: configurationValue プロパティ - Web API

USBConfiguration: configurationValue プロパティ
==========================================

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

`USBConfiguration` インターフェイスの読み取り専用プロパティ **`configurationValue`** は、このコンフィギュレーションのコンフィギュレーション番号を返します。これはデバイスによって提供されたこのコンフィギュレーションを定義しているコンフィギュレーションディスクリプターの `bConfigurationValue` フィールドと一致します。

値
-

現在の `USBConfiguration` インスタンスで指定された `USBDevice` の コンフィギュレーションディスクリプターです。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbconfiguration-configurationvalue |

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

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


USBConfiguration: configurationName プロパティ - Web API

USBConfiguration: configurationName プロパティ
=========================================

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

`USBConfiguration` インターフェイスの読み取り専用プロパティ **`configurationName`** は、デバイスによって提供されたこのコンフィギュレーションを説明する名前を返します。これはこのコンフィギュレーションを定義しているコンフィギュレーションディスクリプターの `iConfiguration` フィールドで提供されるインデックスのストリングディスクリプターの値と一致します。

値
-

デバイスによって提供されたこのコンフィギュレーションを説明する名前です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbconfiguration-configurationname |

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

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


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

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

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

**`USBConfiguration()`** コンストラクターは、渡された `USBDevice` の指定のコンフィギュレーション番号のコンフィギュレーションの情報が格納された新しい `USBConfiguration` オブジェクトを生成します。

構文
--

```js
new USBConfiguration(device, configurationValue)
```

### 引数

`device`

設定を行う `USBDevice` を指定します。

`configurationValue`

読み取りを行うコンフィギュレーションディスクリプターを指定します。これは 0 から 255 の符号なし整数です。

仕様書
---

| Specification |
| --- |
| WebUSB API # dom-usbconfiguration-usbconfiguration |

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

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


USBConfiguration: interfaces プロパティ - Web API

USBConfiguration: interfaces プロパティ
==================================

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

`USBConfiguration` インターフェイスの読み取り専用プロパティ **`interfaces`** は、このコンフィギュレーションが対応しているそれぞれのインターフェイスを表す `USBInterface` のインスタンスが格納された配列を返します。

値
-

`USBInterface` のインスタンスが格納された配列です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbconfiguration-interfaces |

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

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


CSSNumericValue.toSum() - Web API

CSSNumericValue.toSum()
=======================

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

**`toSum()`** は `CSSNumericValue` インターフェイスのメソッドで、 `CSSMathSum` (en-US) オブジェクトの値を、指定した単位の値に変換するものです。

構文
--

```js
toSum(units);
```

### 引数

`units`

変換先の単位です。

### 返値

`CSSNumericValue` です。

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

```js
let v = CSS.px("23").add(CSS.percent("4")).add(CSS.cm("3")).add(CSS.in("9"));
v.toString(); // => "calc(23px + 4% + 3cm + 9in)"
v.toSum("px", "percent").toString(); // => "calc(1000.39px + 4%)"
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-tosum |

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

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


CSSNumericValue.div() - Web API

CSSNumericValue.div()
=====================

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

**`div()`** は `CSSNumericValue` インターフェイスのメソッドで、 `CSSNumericValue` を指定された値で除算します。

構文
--

```js
div(number);
```

### 引数

`number`

数値または `CSSNumericValue` です。

### 返値

`CSSMathProduct` (en-US) です。

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

```js
let mathProduct = CSS.px("24").div(CSS.percent("4"));
// Prints "calc(24px / 4%)"
mathProduct.toString();
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-div |

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

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


CSSNumericValue.add() - Web API

CSSNumericValue.add()
=====================

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

**`add()`** は `CSSNumericValue` インターフェイスのメソッドで、指定された値を `CSSNumericValue` に加算します。

構文
--

```js
add(number);
```

### 引数

`number`

数値または `CSSNumericValue` です。

### 返値

`CSSMathSum` (en-US) です。

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

```js
let mathSum = CSS.px("23")
  .add(CSS.percent("4"))
  .add(CSS.cm("3"))
  .add(CSS.in("9"));
// Prints "calc(23px + 4% + 3cm + 9in)"
console.log(mathSum.toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-add |

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

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


CSSNumericValue.max() - Web API

CSSNumericValue.max()
=====================

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

**`max()`** は `CSSNumericValue` インターフェイスのメソッドで、渡された値の中から最も大きい値を返します。渡された値は同じ型でなければなりません。

構文
--

```js
max(number1, /\* ..., \*/ numberN);
```

### 引数

`number1`, …, `numberN`

数値または `CSSNumericValue` です。

### 返値

A `CSSUnitValue` (en-US).

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

先に述べたように、渡される値はすべて同じ型と値でなければなりません。以下のいくつかの例では、それらが異なる場合に何が起こるかを説明しています。

```js
// Prints "2cm"
console.log(CSS.cm("1").max(CSS.cm("2")).toString());

// Prints "max(1cm, 0.393701in)"
console.log(CSS.cm("1").max(CSS.in("0.393701")).toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-max |

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

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


CSSNumericValue.min() - Web API

CSSNumericValue.min()
=====================

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

**`min()`** は `CSSNumericValue` インターフェイスのメソッドで、渡された値のうちで最も小さい値を返します。渡された値は同じ型でなければなりません。

構文
--

```js
min(number1, /\* ..., \*/ numberN);
```

### 引数

`number1`, …, `numberN`

数値または `CSSNumericValue` です。

### 返値

A `CSSUnitValue` (en-US).

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

先に述べたように、渡される値はすべて同じ型と値でなければなりません。以下のいくつかの例では、それらが異なる場合に何が起こるかを説明しています。

```js
// Prints "1cm"
console.log(CSS.cm("1").min(CSS.cm("2")).toString());

// Prints "max(1cm, 0.393701in)"
console.log(CSS.cm("1").max(CSS.in("0.393701")).toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-min |

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

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


CSSNumericValue.parse() - Web API

CSSNumericValue.parse()
=======================

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

**`parse()`** は `CSSNumericValue` インターフェイスのメソッドで、値の文字列をメンバーが値と単位となっているオブジェクトに変換します。

構文
--

```js
parse(cssText);
```

### 引数

`cssText`

数値と単位の部分を持つ文字列です。

### 返値

`CSSNumericValue` です。

### 例外

`SyntaxError` `DOMException`

TBD

例
-

以下は、`unit` プロパティが `"px"` で、`value` プロパティが `42` である `CSSUnitValue` (en-US) オブジェクトを返すものです。

```js
let numValue = CSSNumericValue.parse("42.0px");
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-parse |

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

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


CSSNumericValue.to() - Web API

CSSNumericValue.to()
====================

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

**`to()`** は `CSSNumericValue` インターフェイスのメソッドで、数値をある単位から他の単位へ変換します。

構文
--

```js
to(unit);
```

### 引数

`unit`

変換先の単位です。

### 返値

`CSSMathSum` (en-US) です。

### 例外

`SyntaxError` `DOMException`

無効な型がメソッドに渡された場合に発生します。

`TypeError`

渡された値が加算できない場合に発生します。

例
-

```js
// Prints "0.608542cm"
console.log(CSS.px("23").to("cm").toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-to |

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

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


CSSNumericValue.equals() - Web API

CSSNumericValue.equals()
========================

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

**`equals()`** は `CSSNumericValue` インターフェイスのメソッドで、渡された値が厳密に等しいかどうかを示す論理値を返します。 `true` の値を返すのは、渡されたすべての値が同じ型と値であり、かつ同じ順序である場合です。これにより、構造的な等価性を素早く検査することができます。

構文
--

```js
equals(number);
```

### 引数

`number`

数値または `CSSNumericValue` です。

### 返値

論理値です。

### 例外

なし。

例
-

先に述べたように、渡される値はすべて同じ型、同じ値でなければならず、また同じ順序でなければなりません。以下のいくつかの例では、それらが異なる場合に何が起こるかを説明しています。

```js
let cssMathSum = new CSSMathSum(CSS.px(1), CSS.px(2));
let matchingCssMathSum = new CSSMathSum(CSS.px(1), CSS.px(2));
// Prints true
console.log(cssMathSum.equals(matchingCssMathSum));

let otherCssMathSum = CSSMathSum(CSS.px(2), CSS.px(1));
// Prints false
console.log(cssMathSum.equals(otherCssMathSum));

// Also prints false
console.log(CSS.cm("1").equal(CSS.in("0.393701")));
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-equals |

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

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


CSSNumericValue.mul() - Web API

CSSNumericValue.mul()
=====================

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

**`mul()`** は `CSSNumericValue` インターフェイスのメソッドで、この `CSSNumericValue` に指定された値を乗算します。

構文
--

```js
mul(number);
```

### 引数

`number`

数値または `CSSNumericValue` です。

### 返値

`CSSMathProduct` (en-US) です。

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

```js
let mathSum = CSS.px("23")
  .mul(CSS.percent("4"))
  .mul(CSS.cm("3"))
  .mul(CSS.in("9"));
// Prints "calc(23px \* 4% \* 3cm \* 9in)"
console.log(mathSum.toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-mul |

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

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


CSSNumericValue.type() - Web API

CSSNumericValue.type()
======================

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

**`type()`** は `CSSNumericValue` インターフェイスのメソッドで、 `CSSNumericValue` の型をf `angle`, `flex`,
 `frequency`, `length`, `resolution`,
 `percent`, `percentHint`, `time` の何れかで返します。

構文
--

```js
type();
```

### 引数

なし。

### 返値

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

### 例外

なし。

例
-

```js
let mathSum = CSS.px("23")
  .sub(CSS.percent("4"))
  .sub(CSS.cm("3"))
  .sub(CSS.in("9"));
// Returns an object with the structure: {length: 1, percentHint: "length"}
let cssNumericType = mathSum.type();
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-type |

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

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


CSSNumericValue.sub() - Web API

CSSNumericValue.sub()
=====================

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

**`sub()`** は `CSSNumericValue` インターフェイスのメソッドで、この `CSSNumericValue` から指定された値を減算します。

構文
--

```js
sub(number);
```

### 引数

`number`

数値または `CSSMathSum` (en-US) です。

### 返値

`CSSMathSum` (en-US) です。

### 例外

`TypeError`

無効な型がメソッドに渡された場合に発生します。

例
-

```js
let mathSum = CSS.px("23")
  .sum(CSS.percent("4"))
  .sum(CSS.cm("3"))
  .sum(CSS.in("9"));
// Prints "calc(23px - 4% - 3cm - 9in)"
console.log(mathSum.toString());
```

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericvalue-sub |

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

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


グローバル間フェッチの使用 - Web API

グローバル間フェッチの使用
=============

この記事では、フェッチ（および潜在的に同種のリソース取得の振る舞いを示す他の API）で発生するエッジケースについて説明します。 相対 URL を含む オリジン間フェッチ（cross-origin fetch）が `<iframe>` から開始される場合、相対 URL は iframe の位置ではなく現在のグローバルな位置に対して解決していました。

エッジケース
------

多くのサイトは、このエッジケースに出くわすことはないでしょう。条件は以下の通りです。

* 同一オリジン (same-origin) の iframe が必要です。
* その同一オリジンの iframe には、異なるベース URL を持つ位置が必要です。
* フェッチ関数をグローバル間 (cross-global) で使用する必要があります。 例えば、 `frame.contentWindow.fetch()` のようにします。
* フェッチするために渡す URL は相対である必要があります。
問題
--

以前は、例えば次のように、現在のグローバルに対して相対 URL を解決していました。

```js
let absolute = new URL(relative, window.location.href);
```

これ自体は問題ではありません。 この種の振る舞いを示すさまざまな API が仕様で定義されている振る舞いと矛盾してそれを実行しているだけであり、それがさらに問題を引き起こす可能性があります。

解決策
---

Firefox 60 以降では、 Mozilla は、使用している `fetch()` 関数を所有するグローバルに対して相対 URL を解決するようになりました（Firefox バグ 1432272 を参照）。 したがって、上記の場合、次のように、 iframe の位置に対して解決します。

```js
let absolute = new URL(relative, frame.contentWindow.location.href);
```

今後の潜在的な問題を軽減するために、この振る舞いの変更に合わせた新しい仕様を取得することについて、多くの議論が進行中です。


フェッチ API の使用 - Web API

フェッチ API の使用
============

フェッチ API は、リクエストやレスポンスといったプロトコルを操作する要素にアクセスするための JavaScript インターフェイスです。グローバルの `fetch()` メソッドも提供しており、簡単で論理的な方法で、非同期にネットワーク越しでリソースを取得することができます。

コールバックベースの API である `XMLHttpRequest` とは異なり、Fetch は Promise ベースであり、サービスワーカー で簡単に使用できる優れた代替手段を提供します。Fetch は、CORS やその他の HTTP 拡張機能などの高度な HTTP 概念も統合します。

基本的なフェッチリクエストは、以下のコードを見てください。

```js
async function logMovies() {
  const response = await fetch("http://example.com/movies.json");
  const movies = await response.json();
  console.log(movies);
}
```

これはネットワーク越しに JSON ファイルを取得してパースし、コンソールにデータを出力するスクリプトです。 `fetch()` の最も簡単な使い方は 1 つの引数 — fetch で取得したいリソースへのパス — のみをとり、 `Response` オブジェクトで解決するプロミスを返します。

`Response` は、実際の JSON レスポンス本体を直接持っているのではなく、 HTTP レスポンス全体を表現するものです。 `Response` オブジェクトから JSON の本体の内容を抽出するには、 `json()` メソッドを使用します。これはレスポンス本体のテキストを JSON として解釈した結果で解決する第 2 のプロミスを返します。

**メモ:** 本体の内容が他の形式である場合に展開する同様の方法は、本体の節を参照してください。

フェッチリクエストは、受け取るリソースからの指示ではなく、コンテンツセキュリティポリシーの `connect-src` ディレクティブによって制御されます。

リクエストオプションの適用
-------------

`fetch()` メソッドには 2 つ目の引数を適用することができ、 `init` オブジェクトで様々な種類の設定を制御することができます。

すべての設定可能なオプションや詳しい説明については、 `fetch()` を参照してください。

```js
// POST メソッドの実装の例
async function postData(url = "", data = {}) {
  // 既定のオプションには \* が付いています
  const response = await fetch(url, {
    method: "POST", // \*GET, POST, PUT, DELETE, etc.
    mode: "cors", // no-cors, \*cors, same-origin
    cache: "no-cache", // \*default, no-cache, reload, force-cache, only-if-cached
    credentials: "same-origin", // include, \*same-origin, omit
    headers: {
      "Content-Type": "application/json",
      // 'Content-Type': 'application/x-www-form-urlencoded',
    },
    redirect: "follow", // manual, \*follow, error
    referrerPolicy: "no-referrer", // no-referrer, \*no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
    body: JSON.stringify(data), // 本体のデータ型は "Content-Type" ヘッダーと一致させる必要があります
  });
  return response.json(); // JSON のレスポンスをネイティブの JavaScript オブジェクトに解釈
}

postData("https://example.com/answer", { answer: 42 }).then((data) => {
  console.log(data); // `data.json()` の呼び出しで解釈された JSON データ
});
```

なお、 `mode: "no-cors"` はリクエスト中の限られたヘッダーにしか許可されていません。

* `Accept`
* `Accept-Language`
* `Content-Language`
* `Content-Type` のうち、値が `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain` のいずれかのもの
fetch の中止
---------

未完了の `fetch()` 操作を中止するには、`AbortController` および `AbortSignal` インターフェイスを使用します。

```js
const controller = new AbortController();
const signal = controller.signal;
const url = "video.mp4";

const downloadBtn = document.querySelector("#download");
const abortBtn = document.querySelector("#abort");

downloadBtn.addEventListener("click", async () => {
  try {
    const response = await fetch(url, { signal });
    console.log("Download complete", response);
  } catch (error) {
    console.error(`Download error: ${error.message}`);
  }
});

abortBtn.addEventListener("click", () => {
  controller.abort();
  console.log("Download aborted");
});
```

資格情報つきのリクエストの送信
---------------

ブラウザーに資格情報のついたリクエストを送るようにするには、同一オリジンの場合もオリジン間の呼び出しの場合も、 `credentials: 'include'` を `init` オブジェクトに追加して `fetch()` メソッドに渡してください。

```js
fetch("https://example.com", {
  credentials: "include",
});
```

**メモ:** `Access-Control-Allow-Origin` は `credentials: 'include'` を含むリクエストでは、ワイルドカードを使用することを禁止しています。このような場合、正確なオリジンを提供する必要があります。 CORS unblocker 拡張機能を使用している場合でも、リクエストは失敗します。

**メモ:** この設定に関係なく、ブラウザーはプリフライトリクエストで資格情報を送信しないようにしてください。詳細については、 CORS 資格情報を含むリクエストを参照してください。

リクエスト URL が呼び出しスクリプトと同一オリジンの場合だけ資格情報を送りたい場合、 `credentials: 'same-origin'` を追加します。

```js
// オリジン 'https://example.com' で呼び出すスクリプトです。

fetch("https://example.com", {
  credentials: "same-origin",
});
```

ブラウザーがリクエストに資格情報を含めないことを保証するには、代わりに `credentials: 'omit'` を使用してください。

```js
fetch("https://example.com", {
  credentials: "omit",
});
```

JSON データのアップロード
---------------

`fetch()` を使って JSON エンコードしたデータを POST します。

```js
async function postJSON(data) {
  try {
    const response = await fetch("https://example.com/profile", {
      method: "POST", // or 'PUT'
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(data),
    });

    const result = await response.json();
    console.log("Success:", result);
  } catch (error) {
    console.error("Error:", error);
  }
}

const data = { username: "example" };
postJSON(data);
```

ファイルのアップロード
-----------

ファイルは HTML の `<input type="file" />` input 要素と、`FormData()` と `fetch()` を使ってアップロードできます。

```js
async function upload(formData) {
  try {
    const response = await fetch("https://example.com/profile/avatar", {
      method: "PUT",
      body: formData,
    });
    const result = await response.json();
    console.log("Success:", result);
  } catch (error) {
    console.error("Error:", error);
  }
}

const formData = new FormData();
const fileField = document.querySelector('input[type="file"]');

formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);

upload(formData);
```

複数のファイルのアップロード
--------------

ファイルのアップロードは、 HTML の `<input type="file" multiple />` 入力要素と `FormData()` と `fetch()` を使用して行うことができます。

```js
async function uploadMultiple(formData) {
  try {
    const response = await fetch("https://example.com/posts", {
      method: "POST",
      body: formData,
    });
    const result = await response.json();
    console.log("Success:", result);
  } catch (error) {
    console.error("Error:", error);
  }
}

const photos = document.querySelector('input[type="file"][multiple]');
const formData = new FormData();

formData.append("title", "My Vegas Vacation");

for (const [i, photo] of Array.from(photos.files).entries()) {
  formData.append(`photos\_${i}`, photo);
}

uploadMultiple(formData);
```

### テキストファイルの 1 行ずつの処理

レスポンスから読み込まれる塊は、行の境界できれいに分割されておらず、文字列ではなく Uint8Array になっています。テキストファイルを読み取って一行ずつ処理したい場合、これらの複雑な処理を行うのはあなた次第です。次の例は、行イテレーターを作成することでこれを行う方法の一つを示しています（簡単にするため、テキストは UTF-8 であると仮定しており、読み取りエラーは処理していません）。

```js
async function\* makeTextFileLineIterator(fileURL) {
  const utf8Decoder = new TextDecoder("utf-8");
  const response = await fetch(fileURL);
  const reader = response.body.getReader();
  let { value: chunk, done: readerDone } = await reader.read();
  chunk = chunk ? utf8Decoder.decode(chunk) : "";

  const newline = /\r?\n/gm;
  let startIndex = 0;
  let result;

  while (true) {
    const result = newline.exec(chunk);
    if (!result) {
      if (readerDone) break;
      const remainder = chunk.substr(startIndex);
      ({ value: chunk, done: readerDone } = await reader.read());
      chunk = remainder + (chunk ? utf8Decoder.decode(chunk) : "");
      startIndex = newline.lastIndex = 0;
      continue;
    }
    yield chunk.substring(startIndex, result.index);
    startIndex = newline.lastIndex;
  }

  if (startIndex < chunk.length) {
    // Last line didn't end in a newline char
    yield chunk.substr(startIndex);
  }
}

async function run() {
  for await (const line of makeTextFileLineIterator(urlOfFile)) {
    processLine(line);
  }
}

run();
```

フェッチが成功したかの確認
-------------

`fetch()` のプロミスは、ネットワークエラーに遭遇したりサーバー側の CORS の設定（通常はアクセス権の問題など）が間違っていたりすると、 `TypeError` で拒否されます。例えば、 404 はネットワークエラーにはなりません。 `fetch()` が成功したかどうかを正確に判定するには、プロミスが解決された後で、 `Response.ok` プロパティが true になっているかを確認してください。次のようなコードになるでしょう。

```js
async function fetchImage() {
  try {
    const response = await fetch("flowers.jpg");
    if (!response.ok) {
      throw new Error("Network response was not OK");
    }
    const myBlob = await response.blob();
    myImage.src = URL.createObjectURL(myBlob);
  } catch (error) {
    console.error("There has been a problem with your fetch operation:", error);
  }
}
```

独自のリクエストオブジェクトの提供
-----------------

`fetch()` の呼び出しに、リクエストしたいリソースへのパスを渡す代わりに、`Request()` コンストラクターを使用して Request オブジェクトを作成し、 `fetch()` メソッドの引数として渡すこともできます。

```js
async function fetchImage(request) {
  try {
    const response = await fetch(request);
    if (!response.ok) {
      throw new Error("Network response was not OK");
    }
    const myBlob = await response.blob();
    myImage.src = URL.createObjectURL(myBlob);
  } catch (error) {
    console.error("Error:", error);
  }
}

const myHeaders = new Headers();

const myRequest = new Request("flowers.jpg", {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
});

fetchImage(myRequest);
```

`Request()` は、 `fetch()` メソッドとまったく同じ引数を受け入れます。既存のリクエストオブジェクトを渡して、コピーを作成することもできます。

```js
const anotherRequest = new Request(myRequest, myInit);
```

 リクエストとレスポンスの本体は一度しか使用できないので、これはかなり有益なことです。
 このようにコピーを作成することで、リクエストやレスポンスを効果的に使用することができ、使用した場合には `init` オプションを変更することができます。
 コピーは本体が読み込まれる前に作成されなければなりません。

**メモ:** `clone()` メソッドを利用してコピーを生成することもできます。コピーを作成するどちらの方法でも、元のリクエストまたはレスポンスの 本体がすでに読まれている場合は失敗しますが、複製されたレスポンスまたは リクエストの本体を読んでも、元で読み取り済みとマークされることはありません。

Headers
-------

`Headers` インターフェイスでは、 `Headers()` コンストラクターを使用して、ヘッダーオブジェクトを作成することができます。ヘッダーオブジェクトは、シンプルな複数の名前と値のマップです。

```js
const content = "Hello World";
const myHeaders = new Headers();
myHeaders.append("Content-Type", "text/plain");
myHeaders.append("Content-Length", content.length.toString());
myHeaders.append("X-Custom-Header", "ProcessThisImmediately");
```

コンストラクターに配列の配列またはオブジェクトリテラルを渡すことで、同じことが実現できます。

```js
const myHeaders = new Headers({
  "Content-Type": "text/plain",
  "Content-Length": content.length.toString(),
  "X-Custom-Header": "ProcessThisImmediately",
});
```

ヘッダーの中身を見たり、検索することができます。

```js
console.log(myHeaders.has("Content-Type")); // true
console.log(myHeaders.has("Set-Cookie")); // false
myHeaders.set("Content-Type", "text/html");
myHeaders.append("X-Custom-Header", "AnotherValue");

console.log(myHeaders.get("Content-Length")); // 11
console.log(myHeaders.get("X-Custom-Header")); // ['ProcessThisImmediately', 'AnotherValue']

myHeaders.delete("X-Custom-Header");
console.log(myHeaders.get("X-Custom-Header")); // null
```

いくつかの操作はサービスワーカーでしか役立ちませんが、ヘッダーを操作するためのより良い API を提供しています。

Headers のメソッドはすべて、有効な HTTP ヘッダーではない名前が渡されたときは `TypeError` が発生します。 immutable ガード（下記参照）がかかっている場合に変更操作を行った場合も `TypeError` が発生します。それ以外の場合は、暗黙に失敗します。例を示します。

```js
const myResponse = Response.error();
try {
  myResponse.headers.set("Origin", "http://mybank.com");
} catch (e) {
  console.log("銀行のふりをしないで下さい！");
}
```

ヘッダーの良い使用方法としては、以下のように、処理を行う前に、コンテンツタイプが正しいかどうか判定する等の使い方があります。

```js
async function fetchJSON(request) {
  try {
    const response = await fetch(request);
    const contentType = response.headers.get("content-type");
    if (!contentType || !contentType.includes("application/json")) {
      throw new TypeError("Oops, we haven't got JSON!");
    }
    const jsonData = await response.json();
    // process your data further
  } catch (error) {
    console.error("Error:", error);
  }
}
```

### ガード

ヘッダーは、リクエストで送信でき、レスポンスで受信できます。また、どの情報が変更できる（または、すべき）かといったさまざまな制限があります。そのため、ヘッダーには *guard* プロパティがあります。これはリクエストやレスポンスに含まれませんが、ヘッダーオブジェクトでできる変更操作に影響を与えます。

設定できるガード値には以下のものがあります。

* `none`: 既定値です。
* `request`: リクエストから得たヘッダーオブジェクト (`Request.headers`) を保護します。
* `request-no-cors`: `Request.mode` が `no-cors` で生成されたリクエストから得たヘッダーオブジェクトを保護します。
* `response`: レスポンスから得たヘッダーオブジェクト (`Response.headers`) を保護します。
* `immutable`: ヘッダーを読み取り専用にします。主にサービスワーカーで使用されます。

**メモ:** `response` のガードされたヘッダーオブジェクトに `Content-Length` ヘッダーを追加したり設定したりすることはできません。同様に、レスポンスヘッダーに `Set-Cookie` を挿入することもできません。サービスワーカーは合成されたレスポンスでクッキーを設定することはできません。

Response オブジェクト
---------------

すでに見てきたように、 `Response` インスタンスは、 `fetch()` プロミスが解決 (resolve) されたときに返値として渡されます。

使用できる主なレスポンスプロパティには、以下のものがあります。

* `Response.status` — 整数値 (既定値は 200) で、 HTTP ステータスコードが入ります。
* `Response.statusText` — HTTP ステータスコードに対応するメッセージの文字列 (既定値は "")。なお、 HTTP/2 ではステータスメッセージに対応していません。
* `Response.ok` — 上述の例で使用したように、これは HTTP ステータスコードが 200-299 の範囲にあるかどうかをチェックする略記法です。これは論理値を返します。

Response オブジェクトは JavaScript で動的に作ることもできます。これはサービスワーカーで非常に役立ちます。例えばリクエストを受け取ったときに `respondWith()` メソッドによってカスタマイズされたレスポンスを返すようなときに役立ちます。

```js
const myBody = new Blob();

addEventListener("fetch", (event) => {
  // ServiceWorker intercepting a fetch
  event.respondWith(
    new Response(myBody, {
      headers: { "Content-Type": "text/plain" },
    }),
  );
});
```

`Response()` コンストラクターは、オプションとして 2 つの引数をとることができます。レスポンス本体と初期化オブジェクトです。 (`Request()` が受け取れるものと似ています。)

**メモ:** 静的メソッド `error()` は単純にエラーレスポンスを返します。同様に `redirect()` メソッドも 指定した URL にリダイレクトするレスポンスを返します。これらはサービスワーカーにのみ関連しています。

本体
--

リクエストにもレスポンスにも本体データが含まれています。本体は以下のタイプのいずれかのインスタンスです。

* `ArrayBuffer`
* `TypedArray` （Uint8Array など）
* `DataView`
* `Blob`
* `File`
* `String`、または文字列リテラル
* `URLSearchParams`
* `FormData`

`Request` および `Response` インターフェイスは本体を展開するために以下のメソッドを持っています。これらはすべて最終的に実際の内容で解決されるプロミスを返します。

* `Request.arrayBuffer()` / `Response.arrayBuffer()`
* `Request.blob()` / `Response.blob()`
* `Request.formData()` / `Response.formData()`
* `Request.json()` / `Response.json()`
* `Request.text()` / `Response.text()`

これらはテキストでないデータを XHR よりはるかに楽に扱うことができます。

リクエスト本体は、 body 引数を渡すことによって設定することができます。

```js
const form = new FormData(document.getElementById("login-form"));
fetch("/login", {
  method: "POST",
  body: form,
});
```

リクエストとレスポンス（および `fetch()` 関数の拡張）は、自動的にコンテンツ種別を決定しようとします。リクエストもまた、指定されていなければ自動で `Content-Type` ヘッダーを設定しようとします。

使用可能かどうかの判別
-----------

Fetch API が利用できるかどうかは、`Headers`、`Request`、`Response`、`fetch()` のいずれかが `Window` もしくは `Worker` のスコープで参照できるかどうかによって判断できます。例を挙げます。

```js
if (window.fetch) {
  // ここで fetch リクエストを実行
} else {
  // XMLHttpRequest で何か実行する？
}
```

`jQuery.ajax()` との差異
--------------------

`fetch` の仕様は、 `jQuery.ajax()` とは特に以下の点で異なっています。

* `fetch()` から返されるプロミスは、レスポンスが HTTP 404 や 500 を返す HTTP エラーステータスの場合でも拒否されません。サーバーがヘッダーで応答すると、プロミスは直ちに正常に解決します（レスポンスが 200-299 の範囲にない場合は、レスポンスの `ok` プロパティが `false` に設定されます）。拒否されるのは、ネットワーク障害があった場合や、何かがリクエストの完了を妨げた場合のみです。
* `credentials` オプションを `include` に設定しない限り、`fetch()` は次のように動作します。
    + オリジン間リクエストではクッキーを送信しません。
    + オリジン間のレスポンスでは、送り返されたクッキーを設定しません。
    + 2018 年 8 月現在、既定の資格情報ポリシーは same-origin に変更されています。
関連情報
----

* サービスワーカー API
* HTTP アクセス制御 (CORS)
* HTTP
* フェッチのポリフィル
* Fetch の例 (GitHub)


フェッチの基本概念 - Web API

フェッチの基本概念
=========

フェッチ API は、（ネットワーク越しの場合も含めて）リソースを取得するインターフェイスを提供します。 `XMLHttpRequest` を使っていた人にはなじみ深いでしょうが、より強力で柔軟な機能を提供します。この記事では、フェッチ API の基本概念のいくつかを説明します。

**メモ:** この記事は随時加筆されます。もっと説明が必要と感じるフェッチの概念を見つけた場合、MDN ディスカッションフォーラムまたは Matrix の MDN Web Docs ルームで誰かに知らせてください。

概要
--

フェッチの核心はインターフェイスの抽象化であり、HTTP のリクエスト (`Request`)、レスポンス (`Response`)、ヘッダー (`Headers`) を抽象化するインターフェイスであり、非同期のリソースのリクエストを行うための `fetch()` メソッドで行います。 HTTP の主要部分が JavaScript オブジェクトとして抽象化されているため、他の API からそれらの機能を利用しやすくなっています。

サービスワーカーは、フェッチを多用する API の一例です。

フェッチはそれらのリクエストの非同期な性質をもう一歩先へ進めるものです。 API は完全に `Promise` ベースです。

ガード
---

ガードは `Headers` オブジェクトの機能で、ヘッダーが使用されている場所に応じて `immutable`, `request`, `request-no-cors`, `response`, `none` のいずれかの値を取ります。

新しい `Headers` オブジェクトが `Headers()` コンストラクターを使用してが生成されるとき、ガードは `none` （既定値）に設定されます。 `Request` または `Response` オブジェクトが生成された場合、関連づけられた `Headers` オブジェクトのガードは下記のとおり設定されます。

| 新しいオブジェクト型 | コンストラクター | 関連する `Headers` オブジェクトのガード設定 |
| --- | --- | --- |
| `Request` | `Request()` | `request` |
| `Request()` で `mode` に `no-cors` を設定したもの | `request-no-cors` |
| `Response` | `Response()` | `response` |
| `error()` または `redirect()` メソッド | `immutable` |

ヘッダーのガードは、ヘッダーの内容を変更する `set()`、 `delete()`、`append()` の各メソッドに影響します。 `Headers` のガードが `immutable` の場合、変更しようとすると `TypeError` が発生します。しかし、次の場合は動作します。

* ガードが `request` で、ヘッダーの *name* が禁止ヘッダー名 ではない場合。
* ガードが `request-no-cors` で、ヘッダーの *name*/*value* が単純ヘッダーである場合。
* ガードが `response` で、ヘッダーの *name* が禁止レスポンスヘッダー名ではない場合。


ReadableStreamDefaultController: close() メソッド - Web API

ReadableStreamDefaultController: close() メソッド
=============================================

**`close()`** は `ReadableStreamDefaultController` インターフェイスのメソッドで、関連するストリームを閉じます。

リーダーは、以前にキューに入れられたチャンクをストリームから読み取ることができますが、それらを読み取とってしまうとストリームは閉じられます。 ストリームを完全に取り除き、キューに入れられたチャンクを破棄する場合は、`ReadableStream.cancel()` または `ReadableStreamDefaultReader.cancel()` を使用してください。

構文
--

```js
close()
```

### 引数

なし。

### 返値

なし (`undefined`)。

### 例外

`TypeError`

ソースオブジェクトは `ReadableStreamDefaultController` ではありません。

例
-

次の単純な例では、コンストラクターを使用してカスタムの `ReadableStream` を作成します（完全なコードについては、単純なランダムストリームの例を参照）。 `start()` 関数は、1 秒ごとにテキストのランダムな文字列を生成し、それをストリームのキューに入れます。 `ReadableStream.cancel()` が何らかの理由で呼び出された場合、生成を停止するための `cancel()` 関数も提供します。

ボタンが押されると、生成を停止し、`ReadableStreamDefaultController.close()` を使用してストリームを閉じ、ストリームからデータを読み取る別の関数を実行します。

```js
let interval;
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // ストリームに文字列を追加
      controller.enqueue(string);

      // それを画面に表示
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // この例では実際には pull は必要ありません
  },
  cancel() {
    // リーダーがキャンセルされた場合に呼び出されるため、
    // 文字列の生成を停止する必要があります
    clearInterval(interval);
  },
});
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-close① |

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

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

関連情報
----

* 読み取り可能なストリームの使用
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: enqueue() メソッド - Web API

ReadableStreamDefaultController: enqueue() メソッド
===============================================

**`enqueue()`** は `ReadableStreamDefaultController` インターフェイスのメソッドで、受け取ったのチャンクを関連するストリームのキューに入れます。

構文
--

```js
enqueue(chunk)
```

### 引数

`chunk`

キューに入れるチャンク。

### 返値

なし (`undefined`)。

### 例外

`TypeError`

ソースオブジェクトが `ReadableStreamDefaultController` ではありません。

例
-

次の単純な例では、コンストラクターを使用してカスタムの `ReadableStream` を作成します（完全なコードについては、単純なランダムストリームの例を参照）。 `start()` 関数は、1 秒ごとにテキストのランダムな文字列を生成し、それをストリームのキューに入れます — `controller.enqueue(string)` を参照。 `ReadableStream.cancel()` が何らかの理由で呼び出された場合、生成を停止するための `cancel()` 関数も提供します。

ボタンが押されると、生成を停止し、`ReadableStreamDefaultController.close()` を使用してストリームを閉じ、ストリームからデータを読み取る別の関数を実行します。

```js
let interval;
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // ストリームに文字列を追加
      controller.enqueue(string);

      // それを画面に表示
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // この例では実際には pull は必要ありません
  },
  cancel() {
    // リーダーがキャンセルされた場合に呼び出されるため、
    // 文字列の生成を停止する必要があります
    clearInterval(interval);
  },
});
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-enqueue① |

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

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

関連情報
----

* 読み取り可能なストリームの使用
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: desiredSize プロパティ - Web API

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

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

### 値

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

例
-

仕様にある基になるプッシュソースと背圧サポートのある読み取り可能なストリームの例は、`desiredSize` を使用してストリームがいっぱいになったことを手動で検出し、背圧を適用する良い例を示しています。 また、`ReadablestreamDefaultController.error()` を使用して、依存しているシステムの別の部分に障害が発生した場合に手動でストリームのエラーをトリガーします。

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-desired-size② |

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

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

関連情報
----

* 読み取り可能なストリームの使用
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: error() メソッド - Web API

ReadableStreamDefaultController: error() メソッド
=============================================

**`error()`** は `ReadableStreamDefaultController` インターフェイスのメソッドで、関連づけられたストリームとの今後のやり取りをエラーにします。

**メモ:** `error()` メソッドは複数回呼び出すことができ、ストリームが読み取り可能でないときに呼び出すことができます。

構文
--

```js
error(e)
```

### 引数

`e`

今後のやり取りを失敗させるエラー。

### 返値

なし (`undefined`)。

### 例外

`TypeError`

ソースオブジェクトが `ReadableStreamDefaultController` ではないか、何らかの理由でストリームが読み取り可能ではありません。

例
-

仕様にある基になるプッシュソースと背圧サポートのある読み取り可能なストリームの例は、`ReadablestreamDefaultController.desiredSize` を使用してストリームがいっぱいになったことを手動で検出し、背圧を適用しています。 また、`error()` を使用して、依存しているシステムの別の部分に障害が発生した場合に手動でストリームのエラーをトリガーする良い例を示しています。

仕様書
---

| Specification |
| --- |
| Streams Standard # rs-default-controller-error |

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

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

関連情報
----

* 読み取り可能なストリームの使用
* `ReadableStreamDefaultController`


FormDataEvent: formData プロパティ - Web API

FormDataEvent: formData プロパティ
=============================

`formData` は `FormDataEvent` インターフェイスの読み取り専用プロパティで、このイベントが発行された時点のフォームに含まれていたデータを表す `FormData` オブジェクトが入っています。

### 返値

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

例
-

```js
// フォームの参照を取得

const formElem = document.querySelector("form");

// submit ハンドラー

formElem.addEventListener("submit", (e) => {
  // フォームの送信時、既定の動作を抑止
  e.preventDefault();

  // FormData オブジェクトを構築、これにより formdata イベントが発行
  new FormData(formElem);
});

// データを取得するための formdata ハンドラー

formElem.addEventListener("formdata", (e) => {
  console.log("formdata fired");

  // イベントオブジェクトからのフォームデータの取得
  let data = e.formData;
  for (const value of data.values()) {
    console.log(value);
  }

  // XHR を介してデータを送信
  const request = new XMLHttpRequest();
  request.open("POST", "/formHandler");
  request.send(data);
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # the-formdataevent-interface:dom-formdataevent-formdata-2 |

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

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

関連情報
----

* `XMLHTTPRequest`
* XMLHttpRequest の使用
* FormData オブジェクトの使用
* `<form>`


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

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

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

構文
--

```js
new FormDataEvent(type, formEventInit)
```

### 引数

`type`

 文字列で、このイベントの名前を表します。
 大文字小文字を区別し、ブラウザーは常に `formdata` に設定します。

`options`

オブジェクトで、*`Event()` で定義されているプロパティに加え*、以下のプロパティを持つことができます。

`formData`

`FormDataEvent` に事前に入力する `FormData` オブジェクトです。
 これには、 `FormDataEvent.formData` プロパティを介してアクセスします。

### 返値

新しい `FormDataEvent` オブジェクトです。

例
-

```js
const fd = new FormData();
fd.append("test", "test");

const fdEv = new FormDataEvent("formdata", { formData: fd });

for (const value of fdEv.formData.values()) {
  console.log(value);
}
```

仕様書
---

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

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

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

関連情報
----

* `FormDataEvent`


FontFaceSetLoadEvent: fontfaces プロパティ - Web API

FontFaceSetLoadEvent: fontfaces プロパティ
=====================================

**`fontfaces`** は `FontFaceSetLoadEvent` インターフェイスの読み取り専用プロパティで、 `FontFace` インスタンスの配列を返します。

値
-

`FontFace` インスタンスの配列です。

仕様書
---

| Specification |
| --- |
| CSS Font Loading Module Level 3 # dom-fontfacesetloadevent-fontfaces |

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

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


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

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

**`FontFaceSetLoadEvent()`** コンストラクターは、 `FontFaceSetLoadEvent` オブジェクトを返します。これは `FontFaceSet` の読み込みのたびに発生します。

構文
--

```js
new FontFaceSetLoadEvent(type)
new FontFaceSetLoadEvent(type, options)
```

### 引数

`type`

 イベント名の文字列です。
 大文字と小文字が区別され、ブラウザーは常に `loading`、`loadingdone`、`loadingerror` のいずれかに設定します。

`options` 省略可

オブジェクトで、*`Event()` で定義されているプロパティに加え*、以下のプロパティを持つことができます。

`fontfaces` 省略可

`FontFace` の配列です。既定値は空配列です。

### 返値

新しい `FontFaceSetLoadEvent` オブジェクトです。

仕様書
---

| Specification |
| --- |
| CSS Font Loading Module Level 3 # dom-fontfacesetloadevent-fontfacesetloadevent |

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

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


XRRigidTransform.matrix - Web API

XRRigidTransform.matrix
=======================

`XRRigidTransform` の **`matrix`** 読み取り専用プロパティは、オブジェクトによって表される変換行列を返します。 そして、返された行列に列ベクトルを前乗算して、`orientation` で指定された 3D 回転でベクトルを回転させ、`position` で平行移動させることができます。

構文
--
```

let matrix = xrRigidTransform.matrix;
```

### 値

`position` プロパティと `orientation` プロパティで記述される 4x4 変換行列を表す 16 個のエントリーを含む `Float32Array` (en-US)。

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

### 行列のフォーマット

WebGL で使用されるすべての 4x4 変換行列は、16 要素の `Float32Array` (en-US) に格納されます。 値は、列優先の順序で配列に格納されます。 つまり、各列は上から下に向かって配列に書き込まれ、その後、1 つ右側の列に移動して、次の列が配列に書き込まれます。 したがって、配列 [a0, a1, a2, ..., a13, a14, a15] の場合、行列は次のようになります。

[

a
[
0
]

a
[
4
]

a
[
8
]

a
[
12
]

a
[
1
]

a
[
5
]

a
[
9
]

a
[
13
]

a
[
2
]

a
[
6
]

a
[
10
]

a
[
14
]

a
[
3
]

a
[
7
]

a
[
11
]

a
[
15
]

]

\begin{bmatrix} a[0] & a[4] & a[8] & a[12]\ a[1] & a[5] & a[9] & a[13]\ a[2] & a[6] & a[10] & a[14]\ a[3] & a[7] & a[11] & a[15]\ \end{bmatrix}

`matrix` は最初に要求されたときに計算します。 その後は、必要になるたびに計算して速度が低下しないように、キャッシュされます。

### 行列の作成

このセクションでは、より高度な読者を対象として、API が指定された変換の行列を計算する方法について説明します。 それは、新しい行列を割り当て、それに 4x4 の単位行列を書き込むことから始まります。

[

1

0

0

0

0

1

0

0

0

0

1

0

0

0

0

1

]

\begin{bmatrix} 1 & 0 & 0 & 0\ 0 & 1 & 0 & 0\ 0 & 0 & 1 & 0\ 0 & 0 & 0 & 1 \end{bmatrix}

これは、適用した点、ベクトル、またはオブジェクトの向きや位置を変更しない変換です。

次に、このように `position` を右側の列に配置して、回転を変更せずに、各次元で指定した距離だけ座標系を変換する平行移動行列を作成します。 ここで、`px`、`py`、`pz` は、`DOMPointReadOnly` の `position` の `x`、`y`、`z` メンバーの値です。

[

1

0

0

px

0

1

0

py

0

0

1

pz

0

0

0

1

]

\begin{bmatrix} 1 & 0 & 0 & x\ 0 & 1 & 0 & y\ 0 & 0 & 1 & z\ 0 & 0 & 0 & 1 \end{bmatrix}

次に、`orientation` で指定された単位クォータニオンから列ベクトル回転行列を計算することにより、回転行列を作成します。

[

1
-
2
(

q
y
2

+

q
z
2

)

2
(

q
x

q
y

-

q
z

q
w

)

2
(

q
x

q
z

+

q
y

q
w

)

0

2
(

q
x

q
y

+

q
z

q
w

)

1
-
2
(

q
x
2

+

q
z
2

)

2
(

q
y

q
z

-

q
x

q
w

)

0

2
(

q
x

q
z

-

q
y

q
w

)

2
(

q
y

q
z

+

q
x

q
w

)

1
-
2
(

q
x
2

+

q
y
2

)

0

0

0

0

1

]

\begin{bmatrix} 1 - 2(q\_y^2 + q\_z^2) & 2(q\_xq\_y - q\_zq\_w) & 2(q\_xq\_z + q\_yq\_w) & p\_x\ 2(q\_xq\_y + q\_zq\_w) & 1 - 2(q\_x^2 + q\_z^2) & 2(q\_yq\_z - q\_xq\_w) & p\_y\ 2(q\_xq\_z - q\_yq\_w) & 2(q\_yq\_z + q\_xq\_w) & 1 - 2(q\_x^2 + q\_y^2) & p\_z\ 0 & 0 & 0 & 1 \end{bmatrix}

最終的な変換 `matrix` は、平行移動行列に回転行列を `(translation * rotation)` の順序で乗算することで計算します。 これにより、`matrix` が返す最終的な変換行列を生成します。

[

1
-
2
(

q
y
2

+

q
z
2

)

2
(

q
x

q
y

-

q
z

q
w

)

2
(

q
x

q
z

+

q
y

q
w

)

px

2
(

q
x

q
y

+

q
z

q
w

)

1
-
2
(

q
x
2

+

q
z
2

)

2
(

q
y

q
z

-

q
x

q
w

)

py

2
(

q
x

q
z

-

q
y

q
w

)

2
(

q
y

q
z

+

q
x

q
w

)

1
-
2
(

q
x
2

+

q
y
2

)

pz

0

0

0

1

]

\begin{bmatrix} 1 - 2(q\_y^2 + q\_z^2) & 2(q\_xq\_y - q\_zq\_w) & 2(q\_xq\_z + q\_yq\_w) & p\_x\ 2(q\_xq\_y + q\_zq\_w) & 1 - 2(q\_x^2 + q\_z^2) & 2(q\_yq\_z - q\_xq\_w) & p\_y\ 2(q\_xq\_z - q\_yq\_w) & 2(q\_yq\_z + q\_xq\_w) & 1 - 2(q\_x^2 + q\_y^2) & p\_z\ 0 & 0 & 0 & 1 \end{bmatrix}

例
-

この例では、特定のオフセットと向きに一致するようにオブジェクトを配置するために、WebGL オブジェクトのレンダリング中に変換として使用できる行列を作成するための変換が作成されます。 次に、`matrix` を、WebGL を使用して、指定された名前に一致するオブジェクトを指定された位置と向きに配置するために指定された変換行列を使用してレンダリングするライブラリー関数に渡します。

```js
let transform = new XRRigidTransform(
  { x: 0, y: 0.5, z: 0.5 },
  { x: 0, y: -0.5, z: -0.5, w: 1 },
);
drawGLObject("magic-lamp", transform.matrix);
```

仕様
--

| Specification |
| --- |
| WebXR Device API # dom-xrrigidtransform-matrix |

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

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


XRRigidTransform.inverse - Web API

XRRigidTransform.inverse
========================

`XRRigidTransform` インターフェイスの **`inverse`** 読み取り専用プロパティは、それ自体の変換の逆である別の `XRRigidTransform` オブジェクトを返します。 つまり、逆を明示的に生成する代わりに、`inverse` プロパティを使用して、`XRRigidTransform` の逆をいつでも取得できます。

構文
--
```

let transformInverse = xrRigidTransform.inverse;
```

### 値

アクセスした `XRRigidTransform` の逆を含む `XRRigidTransform`。

親 `XRRigidTransform` によって以前に変換されたオブジェクトに変換の逆を適用すると、常に変換が元に戻され、結果としてオブジェクトは前のポーズに戻ります。 つまり、その位置と向きの両方が以前の構成に戻ります。

例
-

この例では、オブジェクトのモデルビュー行列は、ビュー行列を取得し、それをオブジェクトのポーズ行列で乗算することによって計算されます。

```js
let modelViewMatrix = mat4.create();

for (let view of pose.view) {
  let viewport = glLayer.getViewport(view);
  gl.viewport(viewport.x, viewport.y, viewport.width, viewport.height);

  /\* ... \*/

  mat4.multiply(modelViewMatrix, view.transform.inverse.matrix, objectMatrix);
  gl.uniformMatrix4fv(
    programInfo.uniformLocations.modelViewMatrix,
    false,
    modelViewMatrix,
  );

  /\* ... \*/
}
```

このレンダラーのコアコードのあらましは、ビューアーの位置と向きに基づいてオブジェクトを変換するために使用するモデルビュー行列として、その変換の逆の行列をを取ることによって、ポーズのビューがどのように表されるかを示しています。 逆の行列にオブジェクトの行列を掛けてモデルビュー行列を取得し、その情報を含むようにユニフォームを設定することで、シェーダープログラムに渡します。

仕様
--

| Specification |
| --- |
| WebXR Device API # dom-xrrigidtransform-inverse |

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

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