HTMLElement: dir プロパティ - Web API

HTMLElement: dir プロパティ
======================

**`HTMLElement.dir`** プロパティは、現在の要素のコンテンツのテキストを書く書字方向を取得または設定します。

要素のテキストを書く書字方向 (text writing directionality) は、テキストが向かう方向です（様々な言語体系に対応するため）。アラビア語とヘブライ語は、 RTL 書字方向を使用する典型的な言語です。

画像の `dir` プロパティを "`rtl`" に設定できます。 この場合、 HTML 属性の `title` と `alt` は、 "`rtl`" としてフォーマットされ、定義されます。

表の `dir` が "`rtl`" に設定されている場合、列の順序は右から左に配置されます。

要素の `dir` が "`auto`" に設定されている場合、要素の方向は、最初の強い書字方向文字 (strong directionality character)、または既定では親要素の書字方向に基づいて決定されます。

**メモ:** ブラウザーは、コンテンツの作成を支援するために、ユーザーが `<input>` と `<textarea>` の書字方向を変更することを許可する場合があります。 Chrome と Safari は入力フィールドのコンテキストメニューで書字方向のオプションを提供しており、 Chromium になる前の Edge は `Ctrl` + `左 Shift` と `Ctrl` + `右 Shift` のキーバインドを使用しています。 Firefox は `Ctrl`/`Cmd` + `Shift` + `X` を使用しますが、 **`dir`** 属性の値は更新しません。

値
-

以下のうちの何れかです。

* `ltr`: 左書き（左から右へ）
* `rtl`: 右書き（右から左へ）
* `auto`: 要素の内容に基づいて方向を決定しなければならないことを指定するためのものです。
例
-

```js
const parg = document.getElementById("para1");
parg.dir = "rtl";
// "para1" として識別される段落のテキストの方向を変更します
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-dir |

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

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

関連情報
----

* `document.dir`
* HTML の `dir` グローバル属性
* CSS の `direction` プロパティ
* CSS の `:dir` 擬似クラス


HTMLElement: inert プロパティ - Web API

HTMLElement: inert プロパティ
========================

`HTMLElement` の **`inert`** プロパティは、この要素の `inert` 属性の値を反映します。論理値で、存在する場合は、フォーカスイベントや支援技術からのイベントを含む、要素に対するユーザーの入力イベントをブラウザーが「無視」するようにします。ブラウザーは、要素でのページ検索やテキスト選択も無視することができます。これは、モーダルのような UI を構築する際に、モーダルが表示されているときにフォーカスをモーダル内に「閉じ込める」場合に便利です。

**メモ:** 不活性コンテンツとその子孫は、すべてのユーザーにとってフォーカスも知覚もできないので、対話要素や重要なコンテンツを `inert` 属性を持つ要素内に入れ子にしてはいけません。

値
-

論理値で、その要素が不活性である場合は `true`、それ以外の場合はこの値は `false` になります。

例
-

### HTML

```html
<div>
  <label for="button1">ボタン 1</label>
  <button id="button1">不活性ではありません</button>
</div>
<div inert>
  <label for="button2">ボタン 2</label>
  <button id="button2">不活性です</button>
</div>
```

### CSS

```css
[inert] > \* {
  opacity: 0.5;
}
```

### 結果

**メモ:** この属性は、それ自体では、ブラウザーに表示されるコンテンツは視覚的変化を与えません。上の例では、inert 属性を持つ要素の直系の子孫が半透明になるように CSS が適用されています。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-inert |

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

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

関連情報
----

* グローバル属性: `inert`
* `<dialog>`
* inert のポリフィル
* `disabled`


HTMLElement: blur() メソッド - Web API

HTMLElement: blur() メソッド
========================

**`HTMLElement.blur()`** メソッドは、現在の要素からキーボードフォーカスを取り除きます。

構文
--

```js
blur()
```

### 引数

なし。

### 返値

なし (`undefined`)。

例
-

### テキスト入力からフォーカスを取り除く

#### HTML

```html
<input type="text" id="sampleText" value="サンプルテキスト" /><br /><br />
<button type="button" onclick="focusInput()">
  クリックするとフォーカスを得ます
</button>
```

#### JavaScript

```js
function focusInput() {
  const textField = document.getElementById("sampleText");

  textField.focus();

  // 入力欄から 3 秒後にフォーカスが外れる
  setTimeout(() => {
    textField.blur();
  }, 3000);
}
```

#### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-blur-dev |

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

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

関連情報
----

* `HTMLElement.focus`


HTMLElement: hidePopover() メソッド - Web API

HTMLElement: hidePopover() メソッド
===============================

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

**`hidePopover()`** は `HTMLElement` インターフェイスのメソッドで、ポップオーバー要素（すなわち有効な `popover` 属性がある要素）を最上位レイヤー (en-US)から外し、`display: none` のスタイルを付けます。

`hidePopover()` が `popover` 属性のついた表示中の要素に対して呼び出された場合、`beforetoggle` イベントが発行され、続いてポップオーバーが非表示になり、それから `toggle` イベントが発行されます。要素が既に非表示であれば、エラーが発生します。

構文
--

```js
hidePopover()
```

### 引数

なし。

### 返値

なし (`undefined`)。

### 例外

`InvalidStateError` `DOMException`

このポップオーバーが既に表示である場合に発生します。

例
-

次の例では、キーボードの特定のキーを押すことで、ポップオーバーを非表示にする機能を提供します。

最初に HTML です。

```html
<div id="mypopover">
  <h2>Help!</h2>

  <p>You can use the following commands to control the app</p>

  <ul>
    <li>Press <ins>C</ins> to order cheese</li>
    <li>Press <ins>T</ins> to order tofu</li>
    <li>Press <ins>B</ins> to order bacon</li>
    <hr />
    <li>Say "Service" to summon the robot waiter to take your order</li>
    <li>Say "Escape" to engage the ejector seat</li>
  </ul>
</div>
```

そして機能をつなげる JavaScript です。

```js
const popover = document.getElementById("mypopover");

document.addEventListener("keydown", (event) => {
  if (event.key === "h") {
    popover.hidePopover();
  }
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-hidepopover |

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

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

関連情報
----

* ポップオーバー API


HTMLElement: offsetTop プロパティ - Web API

HTMLElement: offsetTop プロパティ
============================

**`HTMLElement.offsetTop`** は読み取り専用プロパティで、現在の要素の外枠から、*最も近い位置にある*祖先要素である `offsetParent` の上枠の内側までの距離を相対的に返します。

値
-

数値です。

例
-

```js
const d = document.getElementById("div1");
const topPos = d.offsetTop;

if (topPos > 10) {
  // 要素が offsetParent から 11px 以上離れている場合の処理をここに記述
}
```

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsettop |

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

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


HTMLElement: offsetHeight プロパティ - Web API

HTMLElement: offsetHeight プロパティ
===============================

**`HTMLElement.offsetHeight`** は読み取り専用プロパティで、垂直パディングや境界線を含む要素の高さを整数として返します。

通常、`offsetHeight` は、境界線、パディング、水平スクロールバー（レンダリングされている場合）を含む、要素の CSS における高さのピクセル単位の計測値です。 `::before` や `::after` などの擬似要素の高さは含まれません。 文書の body オブジェクトの場合、計測値には、要素の CSS における高さではなく、線形コンテンツの高さの合計が含まれます。 他の線形コンテンツの下に広がる浮動要素は無視されます。

（例えば、要素またはその祖先のいずれかで `style.display` を `"none"` に設定することにより）要素が非表示の場合は、`0` が返されます。

**メモ:** このプロパティは、値を整数に丸めます。 小数値が必要な場合は、`element.getBoundingClientRect()` を使用してください。

値
-

数値です。

例
-

![大きなパディング、境界、マージンを持つ要素の例です。offsetHeightは、パディングと境界を記載し、マージンを除いた要素のレイアウト高さです。](/ja/docs/Web/API/HTMLElement/offsetHeight/dimensions-offset.png)

上のサンプル画像は、スクロールバーにより、ウィンドウに収まる場合の `offsetHeight` を示しています。 ただし、スクロールできない要素には、目に見えるコンテンツよりもはるかに大きな `offsetHeight` 値が含まれる場合があります。 これらの要素は通常、スクロール可能な要素内に含まれています。 その結果、これらの非スクロール要素は、スクロール可能なコンテナの `scrollTop` の設定に応じて、完全にまたは部分的に非表示になる場合があります。

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetheight |

### メモ

`offsetHeight` は、MSIE によって最初に導入された DHTML オブジェクトモデルのプロパティです。 要素の物理的/グラフィカルな寸法、または要素の境界ボックスの高さ (border-box height) と呼ばれることもあります。

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

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

関連情報
----

* `Element.clientHeight`
* `Element.scrollHeight`
* `HTMLElement.offsetWidth`
* 要素の寸法の決定
* MSDN 要素の寸法と位置の測定（英語）


HTMLElement: showPopover() メソッド - Web API

HTMLElement: showPopover() メソッド
===============================

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

**`showPopover()`** は `HTMLElement` インターフェイスのメソッドで、ポップオーバー要素（すなわち有効な `popover` 属性がある要素）を最上位レイヤー (en-US)に追加することで表示します。

`showPopover()` が `popover` 属性のついた現在非表示の要素に対して呼び出された場合、`beforetoggle` イベントが発行され、続いてポップオーバーが表示され、それから `toggle` イベントが発行されます。要素が既に表示中であれば、エラーが発生します。

構文
--

```js
showPopover()
```

### 引数

なし。

### 返値

なし (`undefined`)。

### 例外

`InvalidStateError` `DOMException`

このポップオーバーが既に表示中の場合に発生します。

例
-

次の例では、キーボードの特定のキーを押すことで、ポップオーバーを表示する機能を提供します。

最初に HTML です。

```html
<div id="mypopover">
  <h2>Help!</h2>

  <p>You can use the following commands to control the app</p>

  <ul>
    <li>Press <ins>C</ins> to order cheese</li>
    <li>Press <ins>T</ins> to order tofu</li>
    <li>Press <ins>B</ins> to order bacon</li>
    <hr />
    <li>Say "Service" to summon the robot waiter to take your order</li>
    <li>Say "Escape" to engage the ejector seat</li>
  </ul>
</div>
```

そして機能をつなげる JavaScript です。

```js
const popover = document.getElementById("mypopover");

document.addEventListener("keydown", (event) => {
  if (event.key === "h") {
    popover.showPopover();
  }
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-showpopover |

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

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

関連情報
----

* ポップオーバー API


HTMLElement: inputMode プロパティ - Web API

HTMLElement: inputMode プロパティ
============================

`HTMLElement` の **`inputMode`** プロパティは、この要素の `inputmode` 属性の値を反映します。

要素やコンテンツの編集中にユーザーが入力する可能性のあるデータの種類を示すヒントを提供するものです。これにより、ブラウザーは適切な仮想キーボードを表示することができます。

これは主に `<input>` 要素で使用されますが、どの要素でも `contenteditable` モードであれば使用できます。

値
-

この属性は、以下の値の何れかを取ります。

`decimal`

実数の入力キーボードで、数字とユーザーのロケールの小数点（普通は `.` または `,`）を含みます。

`email`

 メールアドレスの入力に最適化された仮想キーボードです。
 通常、`@` 文字やその他の最適化が行われいます。

`none`

仮想キーボードはありません。ページが自分自身でキーボード入力制御を実装している場合に使用します。

`numeric`

 0 ～ 9 の数字だけが必要な数値入力キーボードです。
 端末によって、マイナスキーがある場合とない場合があります。

`search`

 検索入力に最適化された仮想キーボードです。
 例えば、リターン/送信キーは「検索」と表示されているかもしれません。

`tel`

電話機のキーパッド入力で、0 ～ 9 の数字、アスタリスク (`\*`)、ナンバー (`#`) キーを含めるために使用します。

`text`

ユーザーの現在のロケールに対応した標準入力キーボードです。

`url`

 URL の入力に最適化されたキーパッドです。
 これは例えば、`/` キーがより目立つように持つことができるかもしれません。

この属性の使い方は、このプロパティを反映した HTML の `inputmode` 属性のページを参照してください。

例
-

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-inputmode |

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

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

関連情報
----

* inputmode 属性


HTMLElement: dragleave イベント - Web API

HTMLElement: dragleave イベント
===========================

`dragleave` イベントは、ドラッグしている要素や選択中のテキストが妥当なドロップターゲットを離れたときに発生します。

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

構文
--

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

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

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

イベント型
-----

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

Event

UIEvent

MouseEvent

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

*以下に挙げたプロパティに加えて、親である `Event` から継承したプロパティもあります。*

`DragEvent.dataTransfer` 読取専用

ドラッグ＆ドロップ操作の間に転送されるデータです。

例
-

### dragleave 時にドロップゾーンのスタイルをリセット

この例では、コンテナーの中にドラッグ可能な要素を入れています。要素を掴んで、他のコンテナーの上にドラッグし、そして放してみましょう。

ドラッグ可能な要素がコンテナーの上にある間は、もう一方のコンテナーの背景を紫色にし、ドラッグ可能な要素がコンテナーの上にドロップされる可能性があることを知らせます。 `dragleave` イベントを待ち受けて、ドラッグ可能な要素がコンテナーからドラッグされたときにコンテナーの背景をリセットするようにします。

ドラッグ＆ドロップの完全な例については、`drag` イベントのページを参照してください。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">この div はドラッグ可</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* 例でユーザーがテキストを選択するのを防ぐ \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}

.dropzone.dragover {
  background-color: purple;
}
```

#### JavaScript

```js
const target = document.getElementById("droptarget");
target.addEventListener("dragenter", (event) => {
  // ドラッグ可能な要素がドロップ先に入ったときに、ドロップ先の候補を強調表示する。
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.add("dragover");
  }
});

target.addEventListener("dragleave", (event) => {
  // ドラッグ可能な要素がドロップ先から離れたときに、ドロップ先の候補の背景をリセットする
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.remove("dragover");
  }
});
```

#### 例

仕様書
---

| Specification |
| --- |
| HTML Standard # ix-handler-ondragleave |
| HTML Standard # event-dnd-dragleave |

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

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

関連情報
----

* その他のドラッグ＆ドロップイベント:
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragover`
    + `dragenter`
    + `drop`
* 他を対象としたこのイベント:
    + `Window`: `dragleave` イベント
    + `Document`: `dragleave` イベント
    + `SVGElement`: `dragleave` イベント


HTMLElement: beforetoggle イベント - Web API

HTMLElement: beforetoggle イベント
==============================

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

**`beforetoggle`** は `HTMLElement` インターフェイスのイベントで、ポップオーバー要素（すなわち有効な `popover` 属性がある要素）において、表示または非表示になる直前に発行されます。

* ポップオーバーが非表示状態から表示状態に遷移した場合、`event.oldState` プロパティには `closed` が、`event.newState` プロパティには `open` が設定されます。
* ポップオーバーが表示状態から非表示状態に遷移した場合、 `event.oldState` は `open` に、 `event.newState` は `closed` になります。
構文
--

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

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

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

イベント型
-----

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

Event

ToggleEvent例
-

### 基本的な例

```js
const popover = document.getElementById("mypopover");

// ...

popover.addEventListener("beforetoggle", (event) => {
  if (event.newState === "open") {
    console.log("Popover is being shown");
  } else {
    console.log("Popover is being hidden");
  }
});
```

### トグルイベントの合体に関するメモ

`beforetoggle` イベントが合体していることを特筆に値するでしょう。イベントループが循環する前に複数の `beforetoggle` イベントが発行された場合、単一のイベントしか発行されないということです。

例えば次のようになります。

```js
popover.addEventListener("beforetoggle", () => {
  //...
});

popover.showPopover();
popover.hidePopover();
// `beforetoggle` は 1 回しか発行されない
```

仕様書
---

| Specification |
| --- |
| HTML Standard # event-beforetoggle |

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

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

関連情報
----

* ポップオーバー API
* 関連イベント: `toggle`


HTMLElement: togglePopover() メソッド - Web API

HTMLElement: togglePopover() メソッド
=================================

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

**`togglePopover()`** は `HTMLElement` インターフェイスのメソッドで、ポップオーバー要素（すなわち有効な `popover` 属性がある要素）の非表示状態と表示状態をトグル切り替えします。

`togglePopover()` が `popover` 属性の付いた要素に対して呼び出されると、次のようになります。

1. `beforetoggle` イベントが発行されます。
2. ポップオーバーが非表示状態と表示状態の間で切り替わります。
    1. もともと表示状態であった場合は、非表示状態に切り替わります。
    2. もともと非表示状態であった場合は、表示状態に切り替わります。
3. `toggle` イベントが発行されます。
構文
--

```js
togglePopover(force)
```

### 引数

`force`

論理値で、`togglePopover()` を `showPopover()` または `hidePopover()` のように動作させます。ただし、そのポップオーバーが既にその状態にあっても、例外が発生しない点が異なります。

* `true` に設定された場合、ポップオーバーは非表示だった場合に表示されます。表示されていた場合は、何も起こりません。
* `false` に設定された場合、ポップオーバーは表示されていた場合に非表示になります。非表示になっていた場合は、何も起こりません。

### 返値

なし (`undefined`)。

例
-

次の例では、キーボードの特定のキーを押すことで、ポップオーバーのオン・オフを切り替える機能を提供します。

最初に HTML です。

```html
<div id="mypopover">
  <h2>Help!</h2>

  <p>You can use the following commands to control the app</p>

  <ul>
    <li>Press <ins>C</ins> to order cheese</li>
    <li>Press <ins>T</ins> to order tofu</li>
    <li>Press <ins>B</ins> to order bacon</li>
    <hr />
    <li>Say "Service" to summon the robot waiter to take your order</li>
    <li>Say "Escape" to engage the ejector seat</li>
  </ul>
</div>
```

そして機能をつなげる JavaScript です。

```js
const popover = document.getElementById("mypopover");

document.addEventListener("keydown", (event) => {
  if (event.key === "h") {
    popover.togglePopover();
  }
});
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-togglepopover |

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

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

関連情報
----

* ポップオーバー API


HTMLElement: enterKeyHint プロパティ - Web API

HTMLElement: enterKeyHint プロパティ
===============================

**`enterKeyHint`** プロパティは、仮想キーボードの Enter キーに表示するアクションラベル（またはアイコン）を定義する列挙型のプロパティです。これは HTML の `enterkeyhint` グローバル属性を反映し、以下の値のみを文字列として受け入れることができる、列挙型のプロパティです。

* `'enter'`: 通常は改行を挿入することを示します。
* `'done'`: 通常はこれ以上入力するものがなく、インプットメソッドエディター (IME) が閉じることを示します。
* `'go'`: 通常、ユーザーが入力したテキストのターゲットに移動することを意味します。
* `'next'`: 通常、ユーザーを次のテキストを受け付けるフィールドに移動させる。
* `'previous'`: 通常、テキストを受け入れる前のフィールドにユーザーを移動させます。
* `'search'`: 通常、ユーザーが入力したテキストを検索した結果に移動します。
* `'send'`: 通常、テキストをターゲットに送ります。

`enterKeyHint` の値が指定されていない場合、あるいは許可されている値とは異なる値が設定されている場合は、空の文字列を返します。

例
-

仮想キーボードに、 Enter キーのラベルをどうするかのヒントを与えます（OS やユーザーの言語に応じて、`送信`または`検索`と表示されます）。

```js
const send = document.getElementById("sendInput");
const search = document.getElementById("searchInput");

send.enterKeyHint = "send";
search.enterKeyHint = "search";
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-enterkeyhint |

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

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

関連情報
----

* HTML の `enterkeyhint` グローバル属性


HTMLElement: innerText プロパティ - Web API

HTMLElement: innerText プロパティ
============================

**`innerText`** は `HTMLElement` のプロパティで、ノードとその子孫の「レンダリングされている」テキスト内容を示します。

 ゲッターとしては、カーソルで要素の内容を選択しクリップボードにコピーした際のテキストに近いものを取得することができます。
 セッターとしては、この要素の子要素を指定された値で置き換え、すべての改行を `<br>` 要素に変換します。

**メモ:** `innerText` は `Node.textContent` と混同しやすいのですが、両者には重要な違いがあります。基本的に `innerText` はテキストがレンダリングされる表示を意識しますが、 `textContent` はそうではありません。

値
-

文字列で、要素の表示されたテキストの内容を表します。

要素自身が表示されないとき（例えば、文書から切り離されたり、表示から隠されたりしている場合）、返値は `Node.textContent` プロパティと同じ値になります。

**警告:** `innerText` をノードに設定すると、そのノードの *すべての* 子ノードが取り除かれ、指定した文字列値のテキストノード 1 つに置き換えられます。

例
-

この例では `innerText` と `Node.textContent` を比較しています。 `innerText` が `<br>` 要素のようなものをどのように意識するかや、非表示の要素を無視することに注意してください。

### HTML

```html
<h3>元の要素:</h3>
<p id="source">
  <style>
 #source {
 color: red;
 }
 #text {
 text-transform: uppercase;
 }
 </style>
  <span id="text">
    このテキストが<br />
    どう扱われるか<br />
    下で見てみてください。
  </span>
  <span style="display:none">隠しテキスト</span>
</p>
<h3>textContent の結果:</h3>
<textarea id="textContentOutput" rows="6" cols="30" readonly>…</textarea>
<h3>innerText の結果:</h3>
<textarea id="innerTextOutput" rows="6" cols="30" readonly>…</textarea>
```

### JavaScript

```js
const source = document.getElementById("source");
const textContentOutput = document.getElementById("textContentOutput");
const innerTextOutput = document.getElementById("innerTextOutput");

textContentOutput.value = source.textContent;
innerTextOutput.value = source.innerText;
```

### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # the-innertext-idl-attribute |

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

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

関連情報
----

* `HTMLElement.outerText`
* `Element.innerHTML`


HTMLElement: contentEditable プロパティ - Web API

HTMLElement: contentEditable プロパティ
==================================

**`contentEditable`** は `HTMLElement` インターフェイスのプロパティで、要素が編集可能かどうかを指定します。

これは列挙属性で、次の値を設定できます。

* '`true`' は、要素の内容が編集可能 (`contenteditable`) であることを示します。
* '`false`' は、要素が編集できないことを示します。
* '`inherit`' は、要素がその親の編集可能状態を継承することを示します。

`HTMLElement.isContentEditable` プロパティを使用すると、このプロパティの計算済みの論理値をテストできます。

値
-

文字列。

仕様書
---

| Specification |
| --- |
| HTML Standard # contenteditable |

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

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

関連情報
----

* `HTMLElement.isContentEditable`
* `contenteditable` グローバル属性


HTMLElement: dragover イベント - Web API

HTMLElement: dragover イベント
==========================

`dragover` イベントは、要素または選択されたテキストが、妥当なドロップターゲットの上にあるときに（数百ミリ秒間隔で）発生します。

このイベントはドロップターゲットで発生します。

構文
--

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

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

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

イベント型
-----

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

Event

UIEvent

MouseEvent

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

*以下に挙げたプロパティに加えて、親である `Event` から継承したプロパティもあります。*

`DragEvent.dataTransfer` 読取専用

ドラッグ＆ドロップ操作の間に転送されるデータです。

例
-

### 最小限のドラッグ＆ドロップの例

この例では、コンテナーの中にドラッグ可能な要素を入れています。この要素を掴んで、他のコンテナーの上にドラッグし、そして放してみましょう。

ここでは、 3 つのイベントハンドラーを使用しています。

* `dragstart` イベントハンドラーでは、ユーザーがドラッグした要素への参照を取得します。
* ターゲットコンテナーの `dragover` イベント ハンドラーでは、 `event.preventDefault()` を呼び出し、`drop` イベントを受信できるようにします。
* ドロップゾーンの `drop` イベント ハンドラーでは、ドラッグ可能な要素を元のコンテナーからドロップ ゾーンに移動する処理を行います。

ドラッグ＆ドロップのより完全な例については、`drag` イベントのページを参照してください。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">この div はドラッグ可</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* 例でユーザーがテキストを選択するのを防ぐ \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}
```

#### JavaScript

```js
let dragged = null;

const source = document.getElementById("draggable");
source.addEventListener("dragstart", (event) => {
  // ドラッグ中の要素の参照を保存
  dragged = event.target;
});

const target = document.getElementById("droptarget");
target.addEventListener("dragover", (event) => {
  // ドロップできるように既定の動作を停止
  event.preventDefault();
});

target.addEventListener("drop", (event) => {
  // 既定の動作（一部の要素でリンクとして開く）を行わないようにする。
  event.preventDefault();
  // ドラッグした要素を選択されたドロップターゲットに移動する
  if (event.target.className === "dropzone") {
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild(dragged);
  }
});
```

#### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # ix-handler-ondragover |
| HTML Standard # event-dnd-dragover |

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

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

関連情報
----

* その他のドラッグ＆ドロップイベント:
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragenter`
    + `dragleave`
    + `drop`
* 他を対象としたこのイベント:
    + `Window`: `dragover` イベント
    + `Document`: `dragover` イベント
    + `SVGElement`: `dragover` イベント


HTMLElement: toggle イベント - Web API

HTMLElement: toggle イベント
========================

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

**`toggle`** は `HTMLElement` インターフェイスのイベントで、ポップオーバー要素（すなわち有効な `popover` 属性がある要素）において、表示または非表示になった直後に発行されます。

* そのポップオーバー要素が非表示状態から表示状態に遷移した場合、`event.oldState` プロパティは `closed` に、`event.newState` プロパティは `open` にそれぞれ設定されます。
* そのポップオーバー要素が表示状態から非表示状態に遷移した場合、 `event.oldState` は `open` に、 `event.newState` は `closed` になります。

**メモ:** `toggle` イベントは `<details>` 要素で発行された場合、異なる形で動作します。この場合、ポップオーバーとは関連しておらず、`<details>` 要素の `open`/`closed` 状態が切り替わったときに発行されます。詳しくは `HTMLDetailsElement` の `toggle イベント`のページを参照してください。

構文
--

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

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

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

イベント型
-----

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

Event

ToggleEvent例
-

### 基本的な例

```js
const popover = document.getElementById("mypopover");

// ...

popover.addEventListener("toggle", (event) => {
  if (event.newState === "open") {
    console.log("Popover has been shown");
  } else {
    console.log("Popover has been hidden");
  }
});
```

### トグルイベントの合体に関するメモ

`toggle` イベントが合体していることを特筆に値するでしょう。イベントループが循環する前に複数の `toggle` イベントが発行された場合、単一のイベントしか発行されないということです。

例えば次のようになります。

```js
popover.addEventListener("toggle", () => {
  //...
});

popover.showPopover();
popover.hidePopover();
// `toggle` は 1 回しか発行されない
```

仕様書
---

| Specification |
| --- |
| HTML Standard # event-toggle |

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

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

関連情報
----

* ポップオーバー API
* 関連イベント: `beforetoggle`


HTMLElement: offsetWidth プロパティ - Web API

HTMLElement: offsetWidth プロパティ
==============================

**`HTMLElement.offsetWidth`** は読み取り専用プロパティで、要素のレイアウト幅を整数として返します。

通常、 `offsetWidth` は、境界線、パディング、および垂直スクロールバー（レンダリングされている場合）を含む、要素の CSS における幅のピクセル単位の計測値です。 `::before` や `::after` などの擬似要素の幅は含まれません。

要素が非表示の場合、（例えば、要素またはその祖先のいずれかで `style.display` を `"none"` に設定している場合） `0` が返されます。

値
-

要素の `offsetWidth` ピクセル値に対応する整数です。 `offsetWidth` プロパティは読み取り専用です。

**メモ:** このプロパティは、値を整数に丸めます。 小数値が必要な場合は、`element.getBoundingClientRect()` を使用してください。

例
-

![大きなパディング、境界、マージンを持つ要素の例です。offsetWidth` は、パディングと境界を含み、マージンを除いた要素のレイアウト幅である。](/ja/docs/Web/API/HTMLElement/offsetWidth/dimensions-offset.png)

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetwidth |

### メモ

`offsetWidth` は、MSIE によって最初に導入された DHTML オブジェクトモデルのプロパティです。 要素の物理的/グラフィカルな寸法、または要素の境界ボックスの幅 (border-box width) と呼ばれることもあります。

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

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

関連情報
----

* `Element.clientWidth`
* `Element.scrollWidth`
* 要素の寸法の決定


HTMLElement: tabIndex プロパティ - Web API

HTMLElement: tabIndex プロパティ
===========================

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

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

* Learn more
* See full compatibility
* Report feedback
**`tabIndex`** は `HTMLElement` インターフェイスのプロパティで、現在の要素のタブの順序を表します。

タブの順序は次のとおりです。

1. 正の `tabIndex` を持つ要素。 同一の `tabIndex` を持つ要素は、表示された順序でナビゲートすべきです。 ナビゲーションは、最も低い `tabIndex` から最も高い `tabIndex` に進みます。
2. `tabIndex` 属性に対応していない要素、または `tabIndex` 属性に対応しており、 `tabIndex` を `0` に割り当てる要素は、それらが表示された順序で。

無効になっている要素は、タブの順序に関与しません。

値は逐次的である必要はなく、特定の値で始まる必要もありません。 各ブラウザーは非常に大きな値を切り取りますが、値は負の値にすることもできます。

構文
--

整数です。

例
-

```js
const b1 = document.getElementById("button1");

b1.tabIndex = 1;
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-tabindex |

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

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

関連情報
----

* キーボードでナビゲート可能な JavaScript ウィジェットのアクセシビリティ
* HTML の `tabindex` グローバル属性


HTMLElement: cut イベント - Web API

HTMLElement: cut イベント
=====================

**`cut`** イベントは、ユーザーがブラウザーのユーザーインターフェイスから切り取り操作を行おうとした時に発行されます。

構文
--

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

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

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

イベント型
-----

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

Event

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

*親である `Event` から継承したプロパティもあります。*

`ClipboardEvent.clipboardData` 読取専用

`DataTransfer` オブジェクトで、ユーザーが行った `cut`, `copy`, `paste` 操作によって影響されたデータと MIME タイプが入ります。

例
-

この例では、テキストを `<textarea>` からコピーすることはできますが、テキストを切り取りすることはできません。また、コピーと切り取りをしようとしたことをそれぞれ記録します。

### HTML

```html
<h3>このテキストエリアで実行しましょう。</h3>
<textarea id="editor" rows="3">
このフィールド内でテキストのコピーや切り取りをしてみましょう。
</textarea>

<h3>ログ:</h3>
<p id="log"></p>
```

### JavaScript

```js
function logCopy(event) {
  log.innerText = `Copied!\n${log.innerText}`;
}

function preventCut(event) {
  event.preventDefault();
  log.innerText = `Cut blocked!\n${log.innerText}`;
}

const editor = document.getElementById("editor");
const log = document.getElementById("log");

editor.oncopy = logCopy;
editor.oncut = preventCut;
```

### 結果

仕様書
---

| Specification |
| --- |
| Clipboard API and events # clipboard-event-cut |
| HTML Standard # handler-oncut |

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

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

関連情報
----

* 関連イベント
    + `HTMLElement.copy_event`
    + `HTMLElement.paste_event`


HTMLElement: autofocus プロパティ - Web API

HTMLElement: autofocus プロパティ
============================

**`autofocus`** は `HTMLElement` のプロパティで、HTML の `autofocus` 属性を反映した論理値で、ページが読み込まれた時、または、 `<dialog>` 要素やポップオーバー属性が設定された要素の中で指定された場合は、ダイアログやポップオーバーが表示された時に、コントロールにフォーカスを当てるかどうかを表します。

この属性を指定することができるのは、1 つの文書内、または `<dialog>` 要素内、または `popover` 属性が設定された要素内のフォーム関連要素 1 つだけです。もし複数あった場合、属性が設定された最初の要素（通常は該当する要素のうちページで最初のもの）が初期のフォーカスを得ます。

**メモ:** このプロパティを設定しても、関連付けられた `<select>` 要素へフォーカスは設定されません。単純に文書へ*要素が挿入された*ときにブラウザーへフォーカスを移動するよう指示するだけです。挿入後に設定した場合、すなわち文書が読み込まれた後のほとんどの場合では、目に見える効果はありません。

値
-

論理値です。

仕様書
---

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

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

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


HTMLElement: focus() メソッド - Web API

HTMLElement: focus() メソッド
=========================

**`HTMLElement.focus()`** メソッドは、指定された要素にフォーカスを設定できる場合、フォーカスを設定します。フォーカスされた要素は、既定でキーボードや同様のイベントを受け取る要素です。

 既定では、ブラウザーは要素をフォーカスした後、スクロールして表示します。また、フォーカスした要素を可視的に示すこともあります（通常は、要素の周りに「フォーカスリング」を表示します）。
 既定では、スクロールを無効化し、要素に可視的な表示を強制するための引数オプションが提供されています。

構文
--

```js
focus()
focus(options)
```

### 引数

`options` 省略可

 フォーカス処理の制御の側面のためのオプションのオブジェクト。
 このオブジェクトには、次のプロパティが含まれる場合があります。

`preventScroll` 省略可

論理値で、ブラウザーが文書をスクロールして、新しくフォーカスされた要素を表示するかどうかを示します。`preventScroll` の値が `false`（既定値）の場合、ブラウザーは要素をフォーカスした後、その要素をスクロールして表示します。`preventScroll` が `true` に設定されている場合、スクロールしません。

`focusVisible` 省略可
Experimental

 論理値です。`true` に設定すると、要素にフォーカスが当たっていることを強制的に可視的に示すことができます。
 既定では、あるいはプロパティが `true` でない場合でも、ブラウザーがユーザーにとってのアクセシビリティを向上させると判断した場合は、可視表示を提供することがあります。

### 返値

なし (`undefined`)。

例
-

### テキストフィールドにフォーカス

この例は、ボタンを使用してテキストフィールドにフォーカスを設定します。

#### HTML

```html
<input id="myTextField" value="テキストフィールド" />
<button id="focusButton">クリックでテキストフィールドにフォーカスを設定</button>
```

#### JavaScript

 次のコードは、ボタンが押されたときにテキストフィールドにフォーカスを設定するイベントハンドラーを追加しています。
 ほとんどのブラウザーは、フォーカスされたテキストフィールドに自動的に可視表示（「フォーカスリング」）を追加するので、このコードでは `focusVisible` を `true` に設定していないことに注意してください。

```js
document.getElementById("focusButton").addEventListener("click", () => {
  document.getElementById("myTextField").focus();
});
```

#### 結果

ボタンを選択すると、テキストフィールドにフォーカスを設定します。

### ボタンにフォーカス

#### HTML

 まず、3 つのボタンを定義します。
 中と右のボタンは、どちらも一番左のボタンにフォーカスを設定します。
 一番右のボタンは `focusVisible` を指定します。

```html
<button id="myButton">クリックしてください</button>
<button id="focusButton">クリックで 「ボタン」にフォーカスを設定</button>
<button id="focusButtonVisibleIndication">
  クリックで「Button」にフォーカスと focusVisible を設定
</button>
```

#### JavaScript

下記コードでは、中ボタンと右ボタンのクリックイベントのハンドラーを設定しています。

```js
document.getElementById("focusButton").addEventListener("click", () => {
  document.getElementById("myButton").focus();
});

document
  .getElementById("focusButtonVisibleIndication")
  .addEventListener("click", () => {
    document.getElementById("myButton").focus({ focusVisible: true });
  });
```

#### 結果

一番左のボタンにフォーカスを設定するには、中央のボタンか一番右のボタンのいずれかを選択します。

 ブラウザーは通常、プログラムでフォーカスを設定する際にボタン要素に目に見えるフォーカスの表示をしないので、真ん中のボタンを選択した場合の効果は明らかではないかもしれません。
 しかし、`focusVisible` オプションがブラウザーで対応していれば、正しいボタンが選択されたときに、左端のボタンにフォーカスが変わるのが見えるはずです。

### スクロールありとなしのフォーカス

この例では、オプション `preventScroll` に `true` と `false`（既定値）を設定してフォーカスを設定した場合の効果を示しています。

#### HTML

HTML は、画面外にある 3 つ目のボタンのフォーカスを設定するために使用する、2 つのボタンを定義しています。

```html
<button id="focus\_scroll">クリックでボタンにフォーカス</button>
<button id="focus\_no\_scroll">
  クリックでスクロールせずにボタンにフォーカス
</button>

<div id="container">
  <button id="myButton" style="margin-top: 500px;">ボタン</button>
</div>
```

#### JavaScript

 このコードでは、最初のボタンと 2 つ目のボタンにクリックイベントハンドラーを設定し、最後のボタンにフォーカスを設定しています。
 最初のハンドラーでは `preventScroll` オプションを指定していないので、フォーカスされた要素へのスクロールが有効になることに注意してください。

```js
document.getElementById("focus\_scroll").addEventListener("click", () => {
  document.getElementById("myButton").focus(); // default: {preventScroll:false}
});

document.getElementById("focus\_no\_scroll").addEventListener("click", () => {
  document.getElementById("myButton").focus({ preventScroll: true });
});
```

#### 結果

 最初のボタンを選択すると、フォーカスが設定され、画面の内側のボタンまでスクロールします。
 2 つ目のボタンを選択すると、フォーカスは設定されますが、スクロールは無効です。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-focus-dev |

メモ
--

* `HTMLElement.focus()` をmousedown イベントハンドラーから呼び出した場合、 `HTMLElement` からフォーカスが外れないように `event.preventDefault()` を呼び出す必要があります。
* `tabindex` やシャドウ DOM など、これまで仕様が定まらないままだった様々な HTML 機能に関するフォーカスの挙動が、最近（2019 年 10 月に）更新されました。
 詳しくは WHATWG blog をチェックしてみてください。
ブラウザーの互換性
---------

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

関連情報
----

* `HTMLElement.blur` で要素からフォーカスを取り除きます。
* `document.activeElement` で現在フォーカスされている要素を知ることができます。


HTMLElement: offsetParent プロパティ - Web API

HTMLElement: offsetParent プロパティ
===============================

**`HTMLElement.offsetParent`** は読み取り専用プロパティで、最も近くにある（包含階層で最も近い）位置指定された祖先要素である要素への参照を返します。

位置指定された祖先とは、次のどちらかです。

* 静的配置ではない要素
* 要素自体が静的配置である場合の `td`、`th`、`table`

位置指定された祖先要素がない場合は、`body` を返します。

**メモ:** 次の状況では、`offsetParent` は `null` を返します。

* 要素またはその親要素の `display` プロパティが `none` に設定されている。
* 要素の `position` プロパティが `fixed`（固定位置指定）に設定されている（Firefox は `<body>` を返します）。
* 要素が `<body>` または `<html>` 要素である。

`offsetParent` が有用なのは、`offsetTop` と `offsetLeft` がパディング辺からの相対位置だからです。

値
-

現在の要素がオフセットされている要素へのオブジェクト参照です。

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetparent |

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

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


HTMLElement: change イベント - Web API

HTMLElement: change イベント
========================

`change` イベントは `<input>`, `<select>`, `<textarea>` 要素において、ユーザーが要素の値を変更したときに発行されます。 `input` イベントとは異なり、 `change` イベントは要素の値 (`value`) が変更されるたびに発生するとは限りません。

変更される要素の種類やユーザーが要素を操作する方法によって、 `change` イベントは異なる時点で発行されます。

* `<input type="checkbox">` 要素が（クリックやキーボードを使用して）チェックされたり解除されたりした場合
* `<input type="radio">` 要素がチェックされた場合（ただし解除された場合は発行されない）
* ユーザが明示的に変更を確定したとき（たとえば、 `<select>` のドロップダウンの値をマウスクリックで選択した場合、 `<input type="date">` の日付ピッカーで日付を選択した場合、 `<input type="file">` のファイル選択ダイアログでファイルを選択した場合など）。
* 要素の値が変更された後、その要素のフォーカスが失われたとき。ユーザーの操作が選択ではなく入力である要素、例えば `<textarea>` や `<input>` 要素の `text`, `search`, `url`, `tel`, `email`, `password` 型の要素で発生します。

HTML 仕様書には、 `change` イベントを発生させる `<input>` 型の一覧があります。

構文
--

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

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

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

イベント型
-----

一般的な `Event` です。

例
-

### <select> 要素

#### HTML

```html
<label>
  アイスクリームの味を選択してください。
  <select class="ice-cream" name="ice-cream">
    <option value="">1 つ選択してください …</option>
    <option value="chocolate">チョコレート</option>
    <option value="sardine">イワシ</option>
    <option value="vanilla">バニラ</option>
  </select>
</label>

<div class="result"></div>
```

```
body {
  display: grid;
  grid-template-areas: "select result";
}

select {
  grid-area: select;
}

.result {
  grid-area: result;
}
```

#### JavaScript

```js
const selectElement = document.querySelector(".ice-cream");
const result = document.querySelector(".result");

selectElement.addEventListener("change", (event) => {
  const result = document.querySelector(".result");
  result.textContent = `${event.target.value}が好きですね`;
});
```

#### 結果

### テキスト入力要素

`<input type="text">` など一部の要素では、コントロールがフォーカスを失うまで `change` イベントが発生しません。以下のフィールドに何かを入力してから、他の部分をクリックするとイベントが発行されます。

#### HTML

```html
<input placeholder="何かテキストを入力" name="name" />
<p id="log"></p>
```

#### JavaScript

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

input.addEventListener("change", updateValue);

function updateValue(e) {
  log.textContent = e.target.value;
}
```

#### 結果

仕様書
---

| Specification |
| --- |
| HTML Standard # event-change |
| HTML Standard # handler-onchange |

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

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

すべてのブラウザーにおいて、特定の操作で `change` イベントが発生するかどうかが同じであるとは限りません。例えば、 Gecko では `<select>` 要素をキーボードで操作すると、 `change` イベントは Enter を押すか `<select>` からフォーカスが離れるまで発生しませんでした（Firefox バグ 126379 を参照）。ただし、 Firefox 63 (Quantum) からは、すべての主要なブラウザーと同じ動作になりました。


HTMLElement: paste イベント - Web API

HTMLElement: paste イベント
=======================

**`paste`** イベントは、ユーザーがブラウザーのユーザーインターフェイスから貼り付け操作を行おうとした時に発行されます。

構文
--

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

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

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

イベント型
-----

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

Event

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

*親である `Event` から継承したプロパティもあります。*

`ClipboardEvent.clipboardData` 読取専用

`DataTransfer` オブジェクトで、ユーザーが行った `cut`, `copy`, `paste` 操作によって影響されたデータと MIME タイプが入ります。

例
-

この例では、 `<textarea>` からのすべてのコピーと貼り付けを記録します。

### HTML

```html
<h3>このテキストエリアで実行してみる</h3>
<textarea id="editor" rows="3">
このフィールドにテキストをコピー＆ペーストしてみてください。
</textarea>

<h3>ログ:</h3>
<p id="log"></p>
```

### JavaScript

```js
function logCopy(event) {
  log.innerText = `コピーされました。\n${log.innerText}`;
}

function logPaste(event) {
  log.innerText = `貼り付けされました。\n${log.innerText}`;
}

const editor = document.getElementById("editor");
const log = document.getElementById("log");

editor.oncopy = logCopy;
editor.onpaste = logPaste;
```

### 結果

仕様書
---

| Specification |
| --- |
| Clipboard API and events # clipboard-event-paste |
| HTML Standard # handler-onpaste |

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

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

関連情報
----

* 関連イベント:
    + `HTMLElement.copy_event`
    + `HTMLElement.cut_event`


HTMLElement: error イベント - Web API

HTMLElement: error イベント
=======================

`error` イベントは、リソースの読み取りに失敗したり、使用できなかったりした場合に要素に発生します。例えば、スクリプトの実行エラーがあったり、画像が見つからないか無効であった場合などです。

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

構文
--

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

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

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

イベント型
-----

イベントオブジェクトは、ユーザーインターフェイス要素から生成された場合は `UIEvent` のインスタンスとなり、それ以外の場合は `Event` となります。

Event

UIEvent例
-

### ライブデモ

#### HTML

```html
<div class="controls">
  <button id="img-error" type="button">Generate image error</button>
  <img class="bad-img" />
</div>

<div class="event-log">
  <label for="eventLog">Event log:</label>
  <textarea
 readonly
 class="event-log-contents"
 rows="8"
 cols="30"
 id="eventLog"></textarea>
</div>
```

```
body {
  display: grid;
  grid-template-areas: "control log";
}

.controls {
  grid-area: control;
  display: flex;
  align-items: center;
  justify-content: center;
}

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

.event-log-contents {
  resize: none;
}

label,
button {
  display: block;
}

button {
  height: 2rem;
  margin: 0.5rem;
}

img {
  width: 0;
  height: 0;
}
```

#### JavaScript

```js
const log = document.querySelector(".event-log-contents");

const badImg = document.querySelector(".bad-img");
badImg.addEventListener("error", (event) => {
  log.textContent += `${event.type}: Loading image\n`;
  console.log(event);
});

const imgError = document.querySelector("#img-error");
imgError.addEventListener("click", () => {
  badImg.setAttribute("src", "i-dont-exist");
});
```

#### 結果

仕様書
---

| Specification |
| --- |
| UI Events # event-type-error |

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

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

関連情報
----

* 関連イベント:
    + Window: `error` イベント
    + HTMLElement: `load` イベント


HTMLElement: offsetLeft プロパティ - Web API

HTMLElement: offsetLeft プロパティ
=============================

**`HTMLElement.offsetLeft`** プロパティは読み取り専用で、現在の要素の*左上隅*が `HTMLElement.offsetParent` ノード内で左へオフセットされるピクセル数を返します。

ブロックレベル要素では、 `offsetTop`, `offsetLeft`, `offsetWidth`, `offsetHeight` が `offsetParent` からの相対的な要素の境界ボックスを記述します。

しかし、 (**span** などの) インラインレベル要素は行をまたいで折り返すことがあるので、 `offsetTop` および `offsetLeft` は*最初の*境界ボックス (その幅と高さを取得するには `Element.getClientRects()` を使用) の位置を記述するのに対し、 `offsetWidth` および `offsetHeight` は*囲む*境界ボックス (位置を取得するには `Element.getBoundingClientRect()` を使用) の寸法を記述します。したがって、 `offsetLeft`, `offsetTop`, `offsetWidth`, `offsetHeight` による左、上、幅、高さは折り返されたテキストの区間を囲むボックスにはなりません。

値
-

整数です。

例
-

```js
const colorTable = document.getElementById("t1");
const tOLeft = colorTable.offsetLeft;

if (tOLeft > 5) {
  // large left offset: do something here
}
```

この例は、 div 内で折り返す「長い」文を青い境界線で表示し、 span の境界を記述すると考えられるものを赤いボックスで表示します。

![Short span. という文があります。このテキストは青い境界の div に完全に収まっています。Long span that wraps within this div. という文があります。"long span that wraps" の部分は赤い境界のボックスに入っています。"within this div" の部分は青い境界の div の中に入っています。](/ja/docs/Web/API/HTMLElement/offsetLeft/offsetleft.jpg)

```html
<div
 style="width: 300px; border-color:blue; border-style:solid; border-width:1;">
  <span>Short span. </span>
  <span id="longspan">Long span that wraps within this div.</span>
</div>

<div
 id="box"
 style="position: absolute; border-color: red; border-width: 1; border-style: solid; z-index: 10"></div>

<script>
 const box = document.getElementById("box");
 const longspan = document.getElementById("longspan");
 box.style.left = longspan.offsetLeft + document.body.scrollLeft + "px";
 box.style.top = longspan.offsetTop + document.body.scrollTop + "px";
 box.style.width = longspan.offsetWidth + "px";
 box.style.height = longspan.offsetHeight + "px";
</script>
```

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetleft |

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

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

関連情報
----

* `HTMLElement.offsetParent`, `HTMLElement.offsetTop`, `HTMLElement.offsetWidth`, `HTMLElement.offsetHeight`


Touch: radiusY プロパティ - Web API

Touch: radiusY プロパティ
====================

**`radiusY`** は `Touch` インターフェイスの読み取り専用プロパティで、タッチ面の連絡先を最も近く囲む楕円の Y 半径を返します。値は `Touch.screenX` と同じ倍率の CSS のピクセル値です。

この値と `Touch.radiusX` および `Touch.rotationAngle` の組み合わせにより、ユーザーと画面の接触領域のサイズと図形を近似した楕円が構成されます。これは、例えば、指先と画面の間の接触を表す大きな楕円であったり、スタイラスの先端を表す小さな領域であったりします。

値
-

数値です。

例
-

このプロパティの使い方の例については Touch.radiusX の例 を参照してください。

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-radiusy |

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

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


Touch: pageY プロパティ - Web API

Touch: pageY プロパティ
==================

**`Touch.pageY`** は読み取り専用プロパティで、スクロールオフセットを加味した、ビューポートに対するタッチ点の Y 座標を返します。

### 値

`double` 型の浮動小数点数で、スクロールオフセットを加味した、ビューポートに対するタッチ点の Y 座標を表します。

例
-

この例では、 `Touch` オブジェクトの `Touch.pageX` および `Touch.pageY` プロパティへのアクセス方法を示しています。 `Touch.pageX` プロパティは、ビューポートを基準としたタッチ点の水平座標（CSS ピクセル単位）で、スクロールオフセットを加味したものです。 `Touch.pageY` プロパティは、ブラウザーのビューポートを基準としたタッチ点の垂直座標（CSS ピクセル単位）で、スクロールオフセットを加味したものです。

以下の単純なコードスニペットでは、ユーザーが `source` 要素に 1 つ以上のタッチ接触を開始し、タッチ点を移動させた後、表面との接触をすべて解除することを想定しています。 `touchmove` イベントハンドラーが呼び出されると、各タッチ点の `Touch.pageX` と `Touch.pageY` の各座標がイベントの `TouchEvent.changedTouches` リスト経由でアクセスされます。

```js
// 'source' 要素に touchmove リスナーを登録する
const src = document.getElementById("source");

src.addEventListener(
  "touchmove",
  (e) => {
    // 移動されたタッチ点を反復処理し、各 pageX/Y 座標をログ出力する。
    // 各座標は CSS ピクセル単位。
    for (let i = 0; i < e.changedTouches.length; i++) {
      console.log(`touchpoint[${i}].pageX = ${e.changedTouches[i].pageX}`);
      console.log(`touchpoint[${i}].pageY = ${e.changedTouches[i].pageY}`);
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-pagey |

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

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


Touch: radiusX プロパティ - Web API

Touch: radiusX プロパティ
====================

**`radiusX`** は `Touch` インターフェイスの読み取り専用プロパティで、タッチ面の連絡先を最も近く囲む楕円の X 半径を返します。値は `Touch.screenX` と同じ倍率の CSS のピクセル値です。

この値と `Touch.radiusY` および `Touch.rotationAngle` の組み合わせにより、ユーザーと画面の接触領域のサイズと図形を近似した楕円が構成されます。これは、例えば、指先と画面の間の接触を表す比較的大きな楕円であったり、スタイラスの先端を表す小さな領域であったりします。

値
-

数値です。

例
-

この例では、 `Touch` インターフェイスの `Touch.radiusX`、`Touch.radiusX`、`Touch.rotationAngle` プロパティを使用する例を示します。 `Touch.radiusX` プロパティは、タッチ領域（指やスタイラスなど）を最も近く囲む楕円の、タッチ点の `Touch.rotationAngle` が**示す**軸上の半径です。同様に `Touch.radiusY` プロパティは、タッチ領域（指やスタイラスなど）を最も近く囲む楕円の、 `Touch.rotationAngle` で示される線に**直交する**軸の半径です。 `Touch.rotationAngle` は、 `radiusX` と `radiusY` で記述されている楕円を、その中心に対して時計回りに回転させたときの角度（度）です。

以下の単純なコードでは、 `touchstart`、`touchmove`、`touchend` イベントに対して単一のハンドラーを登録しています。 `src` 要素がタッチされると、タッチ点の `radiusX` と `radiusY` の値に基づいて要素の幅と高さが計算され、タッチ点の `rotationAngle` を使用して要素が回転します。

```html
<div id="src">…</div>
```

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

src.addEventListener("touchstart", rotate);
src.addEventListener("touchmove", rotate);
src.addEventListener("touchend", rotate);

function rotate(e) {
  const touch = e.changedTouches.item(0);

  // 既定のイベント処理を無効にする
  e.preventDefault();

  // 'src' 要素を回転する
  src.style.width = `${touch.radiusX \* 2}px`;
  src.style.height = `${touch.radiusY \* 2}px`;
  src.style.transform = `rotate(${touch.rotationAngle}deg)`;
}
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-radiusx |

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

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


Touch: pageX プロパティ - Web API

Touch: pageX プロパティ
==================

**`Touch.pageX`** は読み取り専用プロパティで、スクロールオフセットを加味した、ビューポートに対するタッチ点の X 座標を返します。

### 値

`double` 型の浮動小数点数で、スクロールオフセットを加味した、ビューポートに対するタッチ点の X 座標を表します。

例
-

この例では、 `Touch` オブジェクトの `Touch.pageX` および `Touch.pageY` プロパティへのアクセス方法を示しています。 `Touch.pageX` プロパティは、ビューポートを基準としたタッチ点の水平座標（CSS ピクセル単位）で、スクロールオフセットを加味したものです。 `Touch.pageY` プロパティは、ブラウザーのビューポートを基準としたタッチ点の垂直座標（CSS ピクセル単位）で、スクロールオフセットを加味したものです。

以下の単純なコードスニペットでは、ユーザーが `source` 要素に 1 つ以上のタッチ接触を開始し、タッチ点を移動させた後、表面との接触をすべて解除することを想定しています。 `touchmove` イベントハンドラーが呼び出されると、各タッチ点の `Touch.pageX` と `Touch.pageY` の各座標がイベントの `TouchEvent.changedTouches` リスト経由でアクセスされます。

```js
// 'source' 要素に touchmove リスナーを登録する
const src = document.getElementById("source");

src.addEventListener(
  "touchmove",
  (e) => {
    // 移動されたタッチ点を反復処理し、各 pageX/Y 座標をログ出力する。
    // 各座標は CSS ピクセル単位。
    for (let i = 0; i < e.changedTouches.length; i++) {
      console.log(`touchpoint[${i}].pageX = ${e.changedTouches[i].pageX}`);
      console.log(`touchpoint[${i}].pageY = ${e.changedTouches[i].pageY}`);
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-pagex |

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

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


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

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

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

構文
--

```js
new Touch(options)
```

### 引数

`touchInit`

以下のフィールドを持つオブジェクトです。

`identifier`

`long` 値で、タッチ点の識別番号です。

`target`

`EventTarget` オブジェクトで、タッチ点が最初に表面に置かれたときに開始したアイテムです。

`clientX` 省略可

既定値は `0`、型は `double` で、スクロールオフセットを除いた、ユーザー画面のクライアントウィンドウ上のタッチの水平位置です。

`clientY` 省略可

既定値は `0`、型は `double` で、スクロールオフセットを除いた、ユーザー画面のクライアントウィンドウ上のタッチの垂直位置です。

`screenX` 省略可

既定値は `0`、型は `double` で、ユーザーの画面上のタッチの水平位置です。

`screenY` 省略可

既定値は `0`、型は `double` で、ユーザーの画面上のタッチの垂直位置です。

`pageX` 省略可

既定値は `0`、型は `double` で、スクロールオフセットを含む、ユーザー画面のクライアントウィンドウ上のタッチの水平位置です。

`pageY` 省略可

既定値は `0`、型は `double` で、スクロールオフセットを含む、ユーザー画面のクライアントウィンドウ上でのタッチの垂直位置です。

`radiusX` 省略可

既定値は `0`、型は `float` で、 rotationAngle で示される軸に沿ったタッチ領域（指やスタイラスなど）を最も近く囲む楕円の半径を、screenX と同じ倍率の CSS ピクセル単位で指定します。値が不明な場合は `0` です。値は負であってはいけません。

`radiusY` 省略可

既定値は `0` で、タイプは `float` です。rotationAngle で示される軸に垂直な軸に沿って、タッチエリア（指やスタイラスなど）を最も近く囲む楕円の半径を、screenY と同じ倍率の CSS ピクセル単位で指定します。値が不明な場合は `0` です。値は負であってはいけません。

`rotationAngle` 省略可

既定値は `0` 、型は `float` で、 radiusX と radiusY で記述する楕円を、その中心を軸に時計回りに回転させた角度（度単位）です。値は `0` 以上、`90` 以下でなければなりません。radiusX と radiusY で記述される楕円が円の場合、 rotationAngle は影響しません。ユーザーエージェントはこの用途の値として `0` を使用してもよいですし、許容範囲内の他の値を使用してもかまいません。（例えば、ユーザーエージェントは突然の変化を避けるために、前回のタッチイベントの rotationAngle 値を使用することができます。）

`force` 省略可

既定値は `0`、型は `float` で、加えられる圧力の相対値です。範囲は `0` から `1` で、 `0` は圧力なし、 `1` はそのタッチ機器が感知できる最高レベルの圧力です。値が不明の場合は `0` です。力が既知である環境では、力属性によって表される絶対圧と、圧力のレベルの感度が異なる場合があります。

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-constructor |

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

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

関連情報
----

* `TouchEvent`: これを構築するオブジェクトのインターフェイス


Touch: screenX プロパティ - Web API

Touch: screenX プロパティ
====================

概要
--

画面を基準としたタッチ点の X 座標を返します。スクロールオフセットは含まれません。

値
-

数値です。

例
-

この例では、 `Touch` オブジェクトの `Touch.screenX` と `Touch.screenY` プロパティにアクセスする方法を示します。 `Touch.screenX` プロパティは、タッチ点の画面に対する水平 (x) 座標を CSS ピクセルで表したものです。 `Touch.screenY` プロパティは、タッチ点の画面に対する垂直座標を CSS ピクセル単位で表したものです。

以下の単純なコードでは、ユーザーが `source` という id を持つ要素に複数の接触を開始し、その後表面への接触を解除することを想定しています。 `touchstart` イベントハンドラーを呼び出すと、各タッチ点の `Touch.screenX` および `Touch.screenY` 座標にアクセスします。

```js
// 'source' 要素に touchstart リスナーを登録
const src = document.getElementById("source");

src.addEventListener(
  "touchstart",
  (e) => {
    // タッチ点を反復処理し、それぞれの screenX/Y 座標をログ出力する
    // 各座標は CSS ピクセル単位
    for (let i = 0; i < e.touches.length; i++) {
      console.log(`touchpoint[${i}].screenX = ${e.touches[i].screenX}`);
      console.log(`touchpoint[${i}].screenY = ${e.touches[i].screenY}`);
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-screenx |

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

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


Touch: clientX プロパティ - Web API

Touch: clientX プロパティ
====================

`Touch.clientX` は読み取り専用プロパティで、スクロールオフセットを含まない、ビューポートに対するタッチ点の X 座標を返します。

### 値

`double` 型の浮動小数点数で、スクロールオフセットを含まない、ビューポートに対するタッチ点の X 座標を表します。

例
-

この例では、 `Touch` オブジェクトの `Touch.clientX` および `Touch.clientY` プロパティを使用しています。 `Touch.clientX` プロパティは、ブラウザーのビューポートを基準としたタッチ点の水平座標で、スクロールオフセットを除いたものです。 `Touch.clientY` プロパティは、ブラウザーのビューポートを基準としたタッチ点の垂直座標で、スクロールオフセットを除いたものです。

この例では、 `source` という id の要素にタッチを開始し、要素内または要素外に移動した後、タッチ面から指を離したと仮定します。 `touchend` のイベントハンドラーが呼び出されると、タッチ開始点から終了点までの `Touch.clientX` 座標と `Touch.clientY` 座標の変化が計算されます。

```js
// 要素 'source' に touchstart リスナーと touchend リスナーを登録
const src = document.getElementById("source");
let clientX;
let clientY;

src.addEventListener(
  "touchstart",
  (e) => {
    // クライアント X/Y 座標をキャッシュ
    clientX = e.touches[0].clientX;
    clientY = e.touches[0].clientY;
  },
  false,
);

src.addEventListener(
  "touchend",
  (e) => {
    let deltaX;
    let deltaY;

    // X 座標と Y 座標の変化を計算
    // changedTouches リストの最初のタッチ点は、
    // 面から除去されたタッチ点です。
    deltaX = e.changedTouches[0].clientX - clientX;
    deltaY = e.changedTouches[0].clientY - clientY;

    // データを処理…
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-clientx |

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

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


Touch: target プロパティ - Web API

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

**`target`** は `Touch` インターフェイスの読み取り専用プロパティで、タッチ点がその要素の操作領域外に移動した場合や、文書から取り除かれた場合でも、タッチ点が最初に配置されたときに接触が開始された (`EventTarget`) を返します。対象要素が文書から除去されても、イベントはその要素を対象とし、ウィンドウや文書にバブルアップされるとは限らないことに注意してください。タッチしている間に要素が除去されるおそれがある場合は、タッチリスナーを対象に直接取り付けるのが最善の手法です。

値
-

`Touch` オブジェクトが適用される `EventTarget`。

例
-

この例では、`Touch` オブジェクトの `Touch.target` プロパティにアクセスする方法を示します。 `Touch.target` プロパティは `Element` (`EventTarget`) であり、表面に最初に連絡先が配置されたときにこの点を開始します。

以下の単純なコードでは、ユーザーが `source` 要素に 1 つ以上の接触を開始することを想定しています。この要素の `touchstart` イベントハンドラーが呼び出されると、各タッチ点の `Touch.target` プロパティは、イベントの `TouchEvent.targetTouches` リスト経由でアクセスします。

```js
// touchmove リスナーを 'source' 要素に登録
const src = document.getElementById("source");

src.addEventListener(
  "touchstart",
  (e) => {
    // この要素で有効化されたタッチ点を反復処理
    for (let i = 0; i < e.targetTouches.length; i++) {
      console.log(`touchpoint[${i}].target = ${e.targetTouches[i].target}`);
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-target |

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

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


Touch: identifier プロパティ - Web API

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

**`Touch.identifier`** はタッチ面に接触した点を識別する固有の値を返します。この値は、タッチ面上でのこの指（またはスタイラス）の動きに関わるすべてのイベントに対して、タッチ面から離れるまで一貫したものです。

値
-

`long` で、 `Touch` オブジェクトの固有の ID を表します。

例
-

```js
someElement.addEventListener(
  "touchmove",
  (e) => {
    // 最後のイベント以降に変更されたタッチ点のリストを反復処理し、
    // 各タッチ点の識別子を出力する。
    for (let i = 0; i < e.changedTouches.length; i++) {
      console.log(
        `changedTouches[${i}].identifier = ${e.changedTouches[i].identifier}`,
      );
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-identifier |

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

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


Touch: clientY プロパティ - Web API

Touch: clientY プロパティ
====================

**`Touch.clientY`** は読み取り専用プロパティで、スクロールオフセットを含まない、ブラウザーのビューポートに対するタッチ点の Y 座標を返します。

構文
--

`double` 型の浮動小数点数で、スクロールオフセットを含まない、ビューポートに対するタッチ点の Y 座標を表します。

例
-

この例では、 `Touch` オブジェクトの `Touch.clientX` および `Touch.clientY` プロパティを使用しています。 `Touch.clientX` プロパティは、ブラウザーのビューポートを基準としたタッチ点の水平座標で、スクロールオフセットを除いたものです。 `Touch.clientY` プロパティは、ブラウザーのビューポートを基準としたタッチ点の垂直座標で、スクロールオフセットを除いたものです。

この例では、 `source` という id の要素にタッチを開始し、要素内または要素外に移動した後、タッチ面から指を離したと仮定します。 `touchend` のイベントハンドラーが呼び出されると、タッチ開始点から終了点までの `Touch.clientX` 座標と `Touch.clientY` 座標の変化が計算されます。

```js
// 要素 'source' に touchstart リスナーと touchend リスナーを登録
const src = document.getElementById("source");
let clientX;
let clientY;

src.addEventListener(
  "touchstart",
  (e) => {
    // クライアント X/Y 座標をキャッシュ
    clientX = e.touches[0].clientX;
    clientY = e.touches[0].clientY;
  },
  false,
);

src.addEventListener(
  "touchend",
  (e) => {
    let deltaX;
    let deltaY;

    // X 座標と Y 座標の変化を計算
    // changedTouches リストの最初のタッチ点は、
    // 面から除去されたタッチ点です。
    deltaX = e.changedTouches[0].clientX - clientX;
    deltaY = e.changedTouches[0].clientY - clientY;

    // データを処理…
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-clienty |

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

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


Touch: force プロパティ - Web API

Touch: force プロパティ
==================

**`Touch.force`** は読み取り専用のプロパティで、タッチ点 (`Touch`) に対してユーザーがタッチ面に与えている圧力の大きさを返します。

値
-

`float` で、ユーザーがタッチ面に加える圧力の大きさを表します。これは `0.0` （圧力なし）と `1.0` （ハードウェアが認識できる最大の圧力）の間の値です。値が不明な場合（例えばタッチ機器がこのプロパティに対応していない場合）には `0.0` の値を返します。力が既知の環境では、 force 属性で表す絶対圧と、圧力のレベルでの感度は異なる場合があります。

例
-

この例では、 `Touch` インターフェイスの `Touch.force` プロパティを使用して示します。このプロパティは加えられる圧力の相対値で、範囲は `0.0` から `1.0` で、`0.0` は圧力なし、 `1.0` はタッチ機器が感知できる最高レベルの圧力です。

以下のコードスニペットでは、 `touchstart` イベントハンドラーは `targetTouches` リストを反復処理し、各タッチ点の `force` 値をログ出力していますが、このコードは値によって異なる処理を呼び出すことができます。

```js
someElement.addEventListener(
  "touchstart",
  (e) => {
    // タッチ点のリストを反復処理し、各タッチ点の力をログ出力する
    for (let i = 0; i < e.targetTouches.length; i++) {
      // 力の値に応じて「切り替える」コードを追加します。例えば、
      // 最小圧力と最大圧力で、ユーザー入力を異なる処理にすることが
      // できます。
      console.log(`targetTouches[${i}].force = ${e.targetTouches[i].force}`);
    }
  },
  false,
);
```

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-force |

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

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


Touch: rotationAngle プロパティ - Web API

Touch: rotationAngle プロパティ
==========================

**`rotationAngle`** は `Touch` インターフェイスの読み取り専用プロパティで、 `Touch.radiusX` と `Touch.radiusY` で定義する接触楕円の回転角度を度単位で返します。値は 0 から 90 の間です。これら 3 つの値を合わせて、ユーザーと画面の連絡先の大きさと図形を近似する楕円を記述します。これは例えば、指先と画面の連絡先を表す比較的大きな楕円にも、スタイラスの先端を表す小さな領域にもなりえます。

値
-

数値です。

例
-

このプロパティの使い方の例については Touch.radiusX の例を参照してください。

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-rotationangle |

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

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


Touch: screenY プロパティ - Web API

Touch: screenY プロパティ
====================

概要
--

画面を基準としたタッチ点の Y 座標を返します。スクロールオフセットは含まれません。

値
-

数値です。

例
-

Touch.screenX の例には、このプロパティの使用例が含まれています。

仕様書
---

| Specification |
| --- |
| Touch Events # dom-touch-screeny |

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

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


HTMLOutputElement: labels プロパティ - Web API

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

**`HTMLOutputElement.labels`** は読み取り専用プロパティで、この `<output>` 要素に関連付けられた `<label>` 要素の `NodeList` を返します。

値
-

この `<output>` 要素に関連付けられた `<label>` 要素の `NodeList` を返します。

例
-

### HTML

```html
<label id="label1" for="test">ラベル 1</label>
<output id="test">Output</output>
<label id="label2" for="test">ラベル 2</label>
```

### JavaScript

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

### 結果

仕様書
---

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

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

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


全画面 API のガイド - Web API

全画面 API のガイド
============

この記事では、全画面 API を使用して指定された要素を全画面モードにする方法と、ブラウザーの全画面モードへの移行と終了を検出する方法について説明します。

全画面モードの有効化
----------

全画面モードで表示したい要素（例えば `<video>` など）がある場合、その `requestFullscreen()` メソッドを呼び出すことによって、全画面モードで表示させることができます。

この `<video>` 要素について考えてみましょう。

```html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>
```

この video 要素を以下のように全画面化することができます。

```js
const elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}
```

このコードでは、`requestFullscreen()` メソッドが存在するかどうかを調べてから、それを呼び出しています。

### 表示の差異について

ここで、現時点での Gecko と WebKit の実装の重要な違いに注目しておきましょう。Gecko は自動的に CSS ルール "`width: 100%; height: 100%;`" を要素に追加し、画面の内側へ引き伸ばすようにします。 WebKit はこのようなことはせず、代わりに全画面表示の要素を同じ大きさで、それ以外は真っ黒な画面の中央に配置します。 WebKit で同じ全画面表示を取得するには、自分自身で "`width: 100%; height: 100%;`" を CSS ルールに追加する必要があります。

```css
#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}
```

一方、 WebKit の動作を Gecko 上で模倣しようとする場合、表示したい要素を別の要素の内部に配置し、その要素を代わりに全画面化し、 CSS ルールを使用して内側の要素を表示したい外観に一致するように調整する必要があります。

### 通知

全画面モードが正常に実行されると、その要素を含む文書は `fullscreenchange` イベントを受け取ります。全画面モードが終了すると、その文書は再び `fullscreenchange` イベントを受け取ります。なお、 `fullscreenchange` イベントは、文書が全画面モードに入るか抜けるかについての情報そのものは提供しませんが、もし文書に null ではない `fullscreenElement` があれば、全画面モードであることが分かります。

### 全画面リクエストに失敗した場合

全画面モードに切り替わることは保証されていません。例えば、`<iframe>` 要素には全画面モードでコンテンツを表示することを許可するための`allowfullscreen` 属性があります。また、ウィンドウ形式のプラグインなど、特定の種類の中身は全画面モードで表示することができません。全画面表示できない要素（またはその親や子孫）を全画面表示にしようとしても、これはうまくいきません。その代わりに、全画面表示をリクエストされた要素は `mozfullscreenerror` イベントを受け取ります。全画面表示に失敗した場合、 Firefox はウェブコンソールにエラーメッセージをログ出力し、なぜ失敗したのかを説明します。しかし、 Chrome や Opera の新しいバージョンでは、そのような警告は生成されません。

**メモ:** 全画面リクエストは、イベントハンドラー内で呼び出す必要があり、そうでない場合は拒否されます。

全画面モードからの脱出
-----------

ユーザーは常に自分自身で全画面モードを終了することができます。ユーザーが知りたいことを参照してください。また、 `Document.exitFullscreen()` メソッドを呼び出すことで、プログラム的にそうすることも可能です。

その他の情報
------

`Document` は、全画面表示のウェブアプリケーションを開発する際に有益な追加情報を提供します。

`Document.fullscreenElement` / `ShadowRoot.fullscreenElement`

`fullscreenElement` プロパティは、現在全画面表示されている `Element` を指示します。これが null でない場合、文書（またはシャドウ DOM）は全画面モードになっています。もしこれが null ならば、文書（またはシャドウ DOM）は全画面モードではありません。

`Document.fullscreenEnabled`

`fullscreenEnabled` プロパティは、現在文書内の全画面モードがリクエストされる状態であるかどうかを指示します。

### モバイルブラウザーのビューポートの拡大縮小

モバイルブラウザーによっては、全画面モードのときにビューポートメタタグの設定を無視し、ユーザーによる拡大縮小をブロックするものがあります。例えば、全画面モードでないときにピンチ操作で拡大縮小することができたとしても、全画面モードで表示されたページではピンチ操作で拡大縮小するジェスチャーが動作しないことがあります。

ユーザーが知りたいこと
-----------

ユーザーには、`Esc` キー（または `F11`）を押して全画面モードを終了できることを必ず伝えておくとよいでしょう。

また、全画面モード中に他のページに移動したり、タブを切り替えたり、他のアプリケーションに切り替える（例: `Alt`-`Tab` など）と、全画面モードも終了してしまいます。

例
-

この例では、ウェブページの中に動画を表示しています。`Return` または `Enter` キーを押すと、ユーザーは動画のウィンドウ表示と全画面表示を切り替えて表示することができます。

ライブ例の表示

### Enter キーの監視

ページが読み込まれると、このコードが実行され、 `Enter` キーを待ち受けるためのイベントリスナーが設定されます。

```js
document.addEventListener(
  "keydown",
  (e) => {
    if (e.keyCode === 13) {
      toggleFullScreen();
    }
  },
  false,
);
```

### 全画面モードのトグル切り替え

このコードは、上図のようにユーザーが `Enter` キーを押したときに呼び出されます。

```js
function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}
```

これは `document` の `fullscreenElement` 属性の値を調べることから始まります。もし `null` ならば、文書内のモードは現在ウィンドウモードなので、全画面モードに切り替える必要があります。全画面モードへの切り替えは `element.requestFullscreen()` を呼び出すことで行われます。

もし既に全画面モードが有効な場合（`fullscreenElement` が `null` でない場合）、 `document.exitFullscreen()` を呼び出すことになります。

接頭辞
---

今のところ、すべてのブラウザーが接頭辞なしバージョンの API を実装しているわけではありません（ベンダーに依存しない全画面 API へのアクセスには Fscreen を使用することができます）。以下は、接頭辞と名前の異なる形をまとめた表です。

| 標準 | WebKit (Safari) / Blink (Chrome & Opera) / Edge | Gecko (Firefox) | Internet Explorer |
| --- | --- | --- | --- |
| `Document.fullscreen`
非推奨
 | `webkitIsFullScreen` | `mozFullScreen` | - |
| `Document.fullscreenEnabled` | `webkitFullscreenEnabled` | `mozFullScreenEnabled` | `msFullscreenEnabled` |
| `Document.fullscreenElement` | `webkitFullscreenElement` | `mozFullScreenElement` | `msFullscreenElement` |
| `Document.exitFullscreen()` | `webkitExitFullscreen()` | `mozCancelFullScreen()` | `msExitFullscreen()` |
| `Element.requestFullscreen()` | `webkitRequestFullscreen()` | `mozRequestFullScreen()` | `msRequestFullscreen()` |

仕様書
---

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # dom-document-fullscreen |

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

### api.Document.fullscreenEnabled

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

### api.Document.fullscreen

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

関連情報
----

* 全画面モードの使用
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`


HTMLMetaElement: scheme プロパティ - Web API

HTMLMetaElement: scheme プロパティ
=============================

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

**`HTMLMetaElement.scheme`** プロパティは `HTMLMetaElement.content` 属性の値のスキームを定義します。
 `scheme` プロパティは、`content` プロパティの値を解釈するために使用する追加情報を提供できるようにするために作成されました。`scheme` プロパティはスキーム形式（`YYYY-MM-DD` など）、スキーム形式名（`ISBN` など）、またはスキーム形式に関する詳細情報を提供する URI を値として導きます。スキームは `content` 属性の値の形式を定義します。
 ブラウザーや ユーザーエージェントがスキームを認識している場合、`scheme` の内容は要素の `HTMLMetaElement.name` の拡張として解釈されます。

このプロパティは非推奨です。新しいウェブページでは使用しないでください。

値
-

文字列です。

例
-

 次の例は `name` 属性に `identifier` という値を持つ `<meta>` 要素を検索します。
 `scheme` 値がコンソールにログ出力され、メタデータの内容のスキームを表示します。

```js
// <meta name="identifier" content="1580081754" scheme="ISBN"> があるとする
let meta = document.querySelector("meta[name='identifier']");
console.log(meta.scheme);
// "ISBN"
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-meta-scheme |

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

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

関連情報
----

* `<meta>`


HTMLMetaElement: content プロパティ - Web API

HTMLMetaElement: content プロパティ
==============================

**`HTMLMetaElement.content`** プロパティは、`HTMLMetaElement.name` または `HTMLMetaElement.httpEquiv` との組み合わせによる、プラグマディレクティブと名前付き `<meta>` データの `content` 属性を取得または設定します。
 詳しくは、content 属性を参照してください。

値
-

文字列です。

例
-

### meta 要素の内容の読み取り

 次の例は `name` 属性に `keywords` という値を格納した `<meta>` 要素を問い合わせるものです。
 `content` の値がコンソールにログ出力され、文書の keywords が表示されます。

```js
// <meta name="keywords" content="documentation, HTML, web"> があるとします
let meta = document.querySelector("meta[name='keywords']");
console.log(meta.content);
// "documentation, HTML, web"
```

### 内容付きの meta 要素の作成

 次の例は、新しい `<meta>` 要素を `name` 属性に `description` に設定して作成します。
 `content` 属性に文書の説明を設定し、文書の `<head>` に追加されます。

```js
let meta = document.createElement("meta");
meta.name = "description";
meta.content =
  "<meta> 要素は、名前と値のペアで文書のメタデータを提供するのに使用できます。name 属性はメタデータの名前を与え、content 属性は値を与えます。";
document.head.appendChild(meta);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-meta-content |

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

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

関連情報
----

* `<meta>`
* `HTMLMetaElement.name`
* `HTMLMetaElement.httpEquiv`
* 学習: HTML のメタデータ


HTMLMetaElement: name プロパティ - Web API

HTMLMetaElement: name プロパティ
===========================

**`HTMLMetaElement.name`** プロパティは `HTMLMetaElement.content` との組み合わせで使用し、文書のメタデータを名前と値の組で定義します。
 `name` 属性はメタデータの名前を定義し、`content` 属性はその値を定義します。

値
-

文字列です。

例
-

### meta 要素のメタデータ名の読み取り

 次の例では、文書の最初の `<meta>` 要素を検索します。
 `name` の値をコンソールに出力します。これは文書で keywords を指定するものです。

```js
// <meta name="keywords" content="documentation, HTML, web technologies"> があるとする
let meta = document.querySelector("meta");
console.log(meta.name);
// "keywords"
```

### `author` メタデータの meta 要素を作成

 次の例は、新しい `<meta>` 要素を `name` 属性に `author` を設定して作成します。
 `content` 属性には文書の著者を設定し、この要素を文書の `<head>` に追加します。

```js
let meta = document.createElement("meta");
meta.name = "author";
meta.content = "Franz Kafka";
document.head.appendChild(meta);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-meta-name |

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

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

関連情報
----

* `<meta>`
* name 属性で取りうる値


HTMLMetaElement: media プロパティ - Web API

HTMLMetaElement: media プロパティ
============================

**`HTMLMetaElement.media`** プロパティで、`theme-color` メタデータのメディアを指定することができます。

`theme-color` プロパティで、このプロパティに対応しているブラウザーやオペレーティングシステムにおいて、ブラウザーのツールバーや UI の色を設定することができます。
 `media` プロパティにより、異なる `media` 値に対して異なるテーマカラーを設定することができます。

値
-

文字列です。

例
-

### テーマカラーをダークモードに設定

 次の例では、新しい `<meta>` 要素を作成して `name` 属性を `theme-color` に設定します。
 `content` 属性には `#3c790a` を設定し、`media` 属性には `prefers-color-scheme: dark` と設定し、それからその要素を文書の `<head>` に追加します。
 ユーザーがオペレーティングシステムでダークモードを指定している場合、`media` プロパティを使用して異なる `theme-color` を設定することができます。

```js
var meta = document.createElement("meta");
meta.name = "theme-color";
meta.content = "#3c790a";
meta.media = "(prefers-color-scheme: dark)";
document.head.appendChild(meta);
```

### 端末の大きさでテーマカラーを設定

ほとんどのメタプロパティは一度しか使用することができません。ただし `theme-color` は、固有の `media` 値が提供されていれば、複数回使用することができます。

 この例では、`theme-color` を持つ 2 つの meta 要素を追加しています。1 つはすべての端末用、もう 1 つは小さな画面用です。
 `media` クエリーに一致させる順番が重要ですので、下記に示すように、より詳細なクエリーが文書内で後になるように追加してください。

```js
// すべての端末向けの theme-color を追加
meta = document.createElement("meta");
meta.name = "theme-color";
meta.content = "#ffffff";
document.head.appendChild(meta);

// 小さな端末向けの theme-color を追加
var meta = document.createElement("meta");
meta.name = "theme-color";
meta.media = "(max-width: 600px)";
meta.content = "#000000";
document.head.appendChild(meta);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-meta-media |

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

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

関連情報
----

* `<meta>`
* メディアクエリーで取りうる値


HTMLMetaElement: httpEquiv プロパティ - Web API

HTMLMetaElement: httpEquiv プロパティ
================================

**`HTMLMetaElement.httpEquiv`** プロパティは、`HTMLMetaElement.content` 属性のプラグマディレクティブまたはレスポンスヘッダーの名前を取得または設定します。
 取りうる値の詳細は、http-equiv 属性を参照してください。

値
-

文字列です。

例
-

### meta 要素の `http-equiv` の値の読み取り

 次の例は `http-equiv` 属性のある `<meta>` 要素を検索します。
 `http-equiv` 属性をコンソールにログ出力し、`refresh` プラグマディレクティブ を表示します。これはブラウザーに、`content` 属性で定義された秒数の後でページを更新することを指示します。

```js
// <meta http-equiv="refresh" content="10" /> があるとする
let meta = document.querySelector("meta[http-equiv]");
console.log(meta.httpEquiv);
// refresh
console.log(meta.content);
// 10
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-meta-httpequiv |

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

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

関連情報
----

* `<meta>`


BackgroundFetchRegistration.failureReason - Web API

BackgroundFetchRegistration.failureReason
=========================================

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

**`failureReason`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、バックグラウンドフェッチが失敗した理由を示す値を文字列で返します。

このプロパティの値が変化したとき、関連する `BackgroundFetchRegistration` オブジェクトで、progress イベントが発火します。

値
-

下記文字列のいずれかの値をとります。

`""`

バックグラウンドフェッチが完了していない、もしくは成功したとき。

`"aborted"`

ユーザーによって操作がキャンセルされたとき、または `abort()` が呼び出されたとき。

`"bad-status"`

応答ステータスが OK ではないとき ( 200 ~ 299 の範囲外のとき)

`"fetch-error"`

その他の理由によりフェッチが失敗したとき。例えば、CORS 違反や、ネットワーク障害が理由の場合です。

`"quota-exceeded"`

途中でストレージ容量の上限に達したとき。

`"download-total-exceeded"`

バックグラウンドフェッチの登録時に指定された `downloadTotal` を超過したとき。

例
-

このプロパティをコンソールにログ出力すると、フェッチが失敗した理由が表示されます。フェッチが進行中または成功した場合は空文字列が表示されます。

```js
console.log(bgFetch.failureReason);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-failurereason |

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

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


BackgroundFetchRegistration.matchAll() - Web API

BackgroundFetchRegistration.matchAll()
======================================

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

`BackgroundFetchRegistration` インターフェイスの **`matchAll()`** メソッドは、マッチする `BackgroundFetchRecord` オブジェクトの配列を返します。

構文
--

```js
matchAll(request)
matchAll(request,options)
```

### 引数

`request`

取得したい record の `Request`。これは `Request` オブジェクトまたは URL です。

`options` 省略可

`match` 操作のオプションを指定するオブジェクトです。以下が利用可能です。

`ignoreSearch`

URL 中のクエリ文字列を無視するかどうか指定するbool 値です。例えば `true` のとき、`http://foo.com/?value=bar` の `?value=bar` 部分はマッチ処理で無視されます。デフォルトは `false` です。

`ignoreMethod`

bool 値です。`true` のとき、マッチ処理は `Request` の `http` メソッドを検証しません。`false` (デフォルト値)の場合、`GET` と `HEAD` のみ許可されます。

`ignoreVary`

bool 値です。`true` は `VARY` ヘッダーを無視することを意味します。デフォルトは `false` です。

### 返値

マッチした全ての `BackgroundFetchRecord` オブジェクトの配列で解決される `Promise` を返します。

### 例外

`InvalidStateError` `DOMException`

`recordsAvailable` フラグが `false` のとき、発生します。 これは、進行中のフェッチが存在しないことを意味します。

例
-

`matchAll()` を引数なしで呼び出すことで、バックグラウンドフェッチの全ての record を取得することができます。

```js
const records = await bgFetch.matchAll();
console.log(records); // BackgroundFetchRecord オブジェクトの配列
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-registration-match-all |

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

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


BackgroundFetchRegistration: progress イベント - Web API

BackgroundFetchRegistration: progress イベント
==========================================

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

`BackgroundFetchRegistration` インターフェイスの **`progress`** イベントは、関連するバックグラウンドフェッチに進捗があった際に投げられます。

実際には、このイベントは下記プロパティのいずれかが更新されるときに発火します。

* `uploaded`
* `downloaded`
* `result`
* `failureReason`
構文
--

`addEventListener()` 等のメソッドでイベント名を使用するか、関連する `BackgroundFetchRegistration` オブジェクトに `onprogress` というイベントプロパティを設定します。

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

イベント型
-----

追加のプロパティを持たない汎用 `Event`。

例
-

以下の例は、ダウンロードの進捗をログ出力する方法を示しています。このコードでは、バックグラウンドフェッチが登録された際に、まず `downloadTotal` が設定されていることを確認します。これは `downloaded` プロパティに基づいてダウンロードの進捗を計算するために使用されます。

```js
bgFetch.addEventListener("progress", () => {
  if (!bgFetch.downloadTotal) return;
  const percent = Math.round(
    (bgFetch.downloaded / bgFetch.downloadTotal) \* 100,
  );
  console.log(`ダウンロードの進捗： ${percent}%`);
});
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-registration-events |

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

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


BackgroundFetchRegistration.result - Web API

BackgroundFetchRegistration.result
==================================

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

**`result`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、バックグラウンドフェッチが成功したか失敗したかを表す文字列を返します。

このプロパティの値が変化したとき、関連する `BackgroundFetchRegistration` オブジェクトで、progress イベントが発火します。

値
-

下記文字列のいずれかの値をとります。

`""`

フェッチは進行中なので、結果は未確定です。

`"success"`

バックグラウンドのフェッチは成功しました。

`"failure"`

バックグラウンドのフェッチは失敗しました。これは、ブラウザーがリトライできないときにのみ返されます。

例
-

このプロパティをコンソールにログ出力すると、フェッチの進行中であれば空文字列が、そうでなければ結果を表す文字列が出力されます。

```js
console.log(bgFetch.result);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-result |

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

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


BackgroundFetchRegistration.uploadTotal - Web API

BackgroundFetchRegistration.uploadTotal
=======================================

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

**`uploadTotal`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、サーバーに送信される総バイト数を返します。

値
-

`number`。

例
-

`BackgroundFetchRegistration.uploadTotal` をコンソールにログ出力すると、 uploadTotal が出力されます。

```js
console.log(bgFetch.uploadTotal);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-uploadtotal |

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

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


BackgroundFetchRegistration.abort() - Web API

BackgroundFetchRegistration.abort()
===================================

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

`BackgroundFetchRegistration` インターフェイスの **`abort()`** メソッドは、アクティブなバックグラウンドフェッチを中止します。

構文
--

```js
abort()
```

### 引数

なし。

### 返値

フェッチの中止が成功したときに `true` で解決される `Promise` を返します。

例
-

進行中のバックグラウンドフェッチを終了させるには、`abort()` を呼び出します。

```js
bgFetch.abort();
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-registration-abort |

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

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


BackgroundFetchRegistration.downloaded - Web API

BackgroundFetchRegistration.downloaded
======================================

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

**`downloaded`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、 今までにダウンロードされた容量(バイト単位)を返します。初期値は `0` です。

このプロパティの値が変化したとき、関連する `BackgroundFetchRegistration` オブジェクトで、progress イベントが発火します。

値
-

`number`。

例
-

このプロパティをコンソールにログ出力すると、ダウンロードされたバイト数が出力されます。

```js
console.log(bgFetch.downloaded);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-downloaded |

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

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


BackgroundFetchRegistration.uploaded - Web API

BackgroundFetchRegistration.uploaded
====================================

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

**`uploaded`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、送信に成功したバイト数を返します。初期値は `0` です。

このプロパティの値が変化したとき、関連する `BackgroundFetchRegistration` オブジェクトで、progress イベントが発火します。

値
-

`number`。

例
-

このプロパティをコンソールにログ出力すると、アップロードされたバイト数が出力されます。

```js
console.log(bgFetch.uploaded);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-uploaded |

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

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


BackgroundFetchRegistration.recordsAvailable - Web API

BackgroundFetchRegistration.recordsAvailable
============================================

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

**`recordsAvailable`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、アクセス可能なリクエストや応答が存在するとき、`true` を返します。この値が `false` のとき、`match()` と `matchAll()` は使用できません。

値
-

`boolean`。

例
-

このプロパティをコンソールにログ出力すると、`true` または `false` を出力し、record が存在するかどうかを示します。

```js
console.log(bgFetch.recordsAvailable);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-recordsavailable |

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

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


BackgroundFetchRegistration.match() - Web API

BackgroundFetchRegistration.match()
===================================

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

`BackgroundFetchRegistration` インターフェイスの **`match()`** メソッドは、最初にマッチした `BackgroundFetchRecord` を返します。

構文
--

```js
match(request)
match(request, options)
```

### 引数

`request`

取得したい record の `Request`。これは `Request` オブジェクトまたは URL です。

`options` 省略可

`match` 操作のオプションを指定するオブジェクトです。以下が利用可能です。

`ignoreSearch`

URL 中のクエリ文字列を無視するかどうか指定するbool 値です。例えば `true` のとき、`http://foo.com/?value=bar` の `?value=bar` 部分はマッチ処理で無視されます。デフォルトは `false` です。

`ignoreMethod`

bool 値です。`true` のとき、マッチ処理は `Request` の `http` メソッドを検証しません。`false` (デフォルト値)の場合、`GET` と `HEAD` のみ許可されます。

`ignoreVary`

bool 値です。`true` は `VARY` ヘッダーを無視することを意味します。デフォルトは `false` です。

### 返値

最初に request にマッチした `BackgroundFetchRecord` か、または何もマッチしなかった場合には `undefined` で解決される `Promise` を返します。

**メモ:** `BackgroundFetchRegistration.match()` は、基本的には `BackgroundFetchRegistration.matchAll()` と同じですが、マッチする全ての record を配列で返すのではなく、最初にマッチした record のみで解決するという違いがあります。

### 例外

`InvalidStateError` `DOMException`

進行中の fetch がないときに `match()` を呼び出すと発生します。 この状態は、`BackgroundFetchRegistration.recordsAvailable` が `false` に設定されることで反映されます。

例
-

以下の例では URL に "/ep-5.mp3" を含む record を検索しており、`BackgroundFetchRecord` が見つかると、関連する情報を取得することができます。

```js
bgFetch.match("/ep-5.mp3").then(async (record) => {
  if (!record) {
    console.log("レコードは見つかりませんでした。");
    return;
  }

  console.log(`リクエスト： `, record.request);
  const response = await record.responseReady;
  console.log(`応答： `, response);
});
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-registration-match |

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

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


BackgroundFetchRegistration.downloadTotal - Web API

BackgroundFetchRegistration.downloadTotal
=========================================

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

**`downloadTotal`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、このダウンロード全体の容量をバイト単位で返します。このプロパティはバックグラウンドフェッチの登録時に設定されます。値が設定されなかった場合、`0` を返します。

値
-

`number`。

例
-

このプロパティをコンソールにログ出力すると、ダウンロード全体の容量(バイト単位)が出力されます。

```js
console.log(bgFetch.downloadTotal);
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-downloadtotal |

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

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


BackgroundFetchRegistration.id - Web API

BackgroundFetchRegistration.id
==============================

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

**`id`** は `BackgroundFetchRegistration` インターフェイスの読み取り専用プロパティで、バックグラウンドフェッチの `ID` をコピーした文字列を返します。

値
-

文字列。

例
-

このプロパティをコンソールにログ出力すると、 fetch を登録したときに設定された識別子が出力されます。今回の場合、`"my-fetch"` が出力されます。

```js
console.log(bgFetch.id); // "my-fetch"
```

仕様書
---

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchregistration-id |

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

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


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

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

**`ReadableStream()`** コンストラクターは、指定されたハンドラーから読み取り可能なストリームのオブジェクトを作成して返します。

すべての引数は技術的にオプションですが、 `underlyingSource` を省略すると、ソースを持たないストリームになり、そこから読み込むことができなくなることに注意してください（リーダーは決して解決されないプロミスを返します）。

構文
--

```js
new ReadableStream()
new ReadableStream(underlyingSource)
new ReadableStream(underlyingSource, queuingStrategy)
```

### 引数

`underlyingSource` 省略可

構築されたストリームのインスタンスの動作を定義するメソッドとプロパティを含むオブジェクト。 `underlyingSource` には次のものを含めることができます。

`start` (controller) 省略可

これは、オブジェクトが構築されるとすぐに呼び出されるメソッドです。 このメソッドの内容は開発者が定義し、ストリームのソースへのアクセスを取得し、ストリーム機能を設定するために必要な他のすべての操作を行う必要があります。 このプロセスを非同期で実行する場合、成功または失敗を通知するプロミスを返すことができます。このメソッドに渡される `controller` 引数は、 `ReadableStreamDefaultController` または `ReadableByteStreamController` を `type` プロパティの値に応じて指定します。開発者はこれを使用して、セットアップ中にストリームを制御できます。

`pull` (controller) 省略可

このメソッドは、開発者が定義し、ストリームの内部にあるチャンクのキューがいっぱいになっていない場合、最高水準点に達するまで繰り返し呼び出されます。 `pull()` がプロミスを返す場合、そのプロミスが満たされるまで再び呼び出されません。プロミスが拒否された場合、ストリームはエラーになります。このメソッドに渡される `controller` 引数は、 `ReadableStreamDefaultController` または `ReadableByteStreamController` を `type` プロパティの値に応じて指定します。開発者はこれを使用して、より多くのチャンクが読み取られるようストリームを制御できます。この関数は `start()` が完全に終了するまで呼び出されません。さらに、この関数は少なくとも一つのチャンクがキューに入れられるか、BYOB リクエストが履行された場合にのみ繰り返し呼び出されます。

`cancel` (reason) 省略可

このメソッドは、開発者が定義し、ストリームがキャンセルされることをアプリが通知した場合に呼び出されます（例えば、`ReadableStream.cancel()` が呼び出された場合）。 内容は、ストリームのソースへのアクセスを解放するために必要なことを行う必要があります。 このプロセスが非同期の場合、成功または失敗を通知するプロミスを返すことができます。 `reason` 引数には、ストリームがキャンセルされた理由を説明する文字列が含まれています。

`type` 省略可

このプロパティは、どの種類の読み取り可能なストリームが処理されるかを制御します。 `"bytes"` に設定された値が含まれている場合、渡されるコントローラーオブジェクトは、 BYOB （独自のバッファーを持ち込む）/バイトストリームを処理できる `ReadableByteStreamController` になります。 含まれていない場合、渡されるコントローラーは `ReadableStreamDefaultController` になります。

`autoAllocateChunkSize` 省略可

 バイトストリームの場合、開発者は `autoAllocateChunkSize` に正の整数値を設定して、ストリームの自動割り当て機能をオンにできます。
 これを設定すると、ストリームの実装は、必要なときに自動的に `ReadableByteStreamController.byobRequest` に指定したサイズのビューバッファーを確保するようになります。

 既定の `ReadableStreamDefaultReader` でゼロコピー転送を使用するためには、この設定をしなければなりません。
 設定されていない場合、既定のリーダーはデータをストリームしますが、 `ReadableByteStreamController.byobRequest` は常に `null` となり、コンシューマーへの転送はストリーム内のキューを経由しなければなりません。

`queuingStrategy` 省略可

オプションでストリームのキューイング戦略を定義するオブジェクト。 これには次の 2 つの引数が必要です。

`highWaterMark`

負でない整数 — これは、バックプレッシャーが適用される前に内部キューに含めることができるチャンクの総数を定義します。

`size(chunk)`

引数 `chunk` を含むメソッド — これは、各チャンクに使用するサイズをバイト単位で示します。

**メモ:** 独自のカスタム `queuingStrategy` を定義するか、このオブジェクト値に `ByteLengthQueuingStrategy` または `CountQueuingStrategy` のインスタンスを使用できます。 `queuingStrategy` が指定されていない場合、使用される既定値は、最高水準点が 1 の `CountQueuingStrategy` と同じです。

### 返値

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

### 例外

`RangeError`

指定された `type` 値が、 `"bytes"` でも `undefined` でもない場合に発生します。

例
-

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

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

```js
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-constructor⑤ |

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

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

関連情報
----

* `ReadableStream`
* `ReadableByteStreamController`
* `ReadableStreamDefaultController`
* 読み取り可能なストリームの使用


ReadableStream: getReader() メソッド - Web API

ReadableStream: getReader() メソッド
================================

**`getReader()`** は `ReadableStream` インターフェイスのメソッドで、リーダーを作成し、それでストリームをロックします。
 ストリームがロックされている間は、このリーダーが解放されるまで他のリーダーを取得できません。

構文
--

```js
getReader()
getReader(options)
```

### 引数

`options` 省略可

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

`mode` 省略可

 作成するリーダーの種類を指定するプロパティです。
 値は以下の通り。

* `"byob"`: 読み取り可能なバイトストリーム（内部ストリームバッファが空のときに、基礎となるバイトソースからリーダーへのゼロコピー転送に対応しているストリーム）を読み取ることができる `ReadableStreamBYOBReader` を作成します。
* `undefined` （または指定しない場合、既定値）。 これにより、ストリームから個々のチャンクを読み取ることができる `ReadableStreamDefaultReader` が作成されます。

### 返値

`mode` 値に応じて、`ReadableStreamDefaultReader` または `ReadableStreamBYOBReader` オブジェクトのインスタンス。

### 例外

`RangeError`

指定された `mode` 値が `"byob"` または `undefined` ではありません。

`TypeError`

 リーダーを作成しようとしているストリームが `ReadableStream` ではありません。
 これは、 BYOB リーダーが要求されたときに、ストリームコントローラーが `ReadableByteStreamController` でない（ストリームが `type="bytes"` で基礎ソースとして構築されていない）場合にも発生します。

例
-

次の簡単な例では、`getReader()` を使用して作成した `ReadableStreamDefaultReader` を使用して、以前に作成した独自の `ReadableStream` を読み取ります（完全なコードについては、単純なランダムストリームの例を参照）。 各チャンクを順番に読み取り、ストリームの読み取りが完了するまで UI に出力します。 ストリームの読み取りが完了すると、再帰関数から戻り、ストリーム全体を UI の別の部分に出力します。

```js
function fetchStream() {
  const reader = stream.getReader();
  let charsReceived = 0;

  // read() は、値を受け取ったときに解決する promise を返します
  reader.read().then(function processText({ done, value }) {
    // 結果オブジェクトには2つのプロパティが含まれます。
    // done - ストリームがすべてのデータを既に提供している場合は true。
    // value - 一部のデータ。 done が true の場合、常に undefined。
    if (done) {
      console.log("Stream complete");
      para.textContent = value;
      return;
    }

    // フェッチしたストリームの値は Uint8Array です
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent = `Received ${charsReceived} characters so far. Current chunk = ${chunk}`;
    list2.appendChild(listItem);

    result += chunk;

    // さらに読み、この関数を再度呼び出します
    return reader.read().then(processText);
  });
}
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-get-reader⑤ |

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

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

関連情報
----

* `ReadableStream()` コンストラクター
* `ReadableStreamDefaultReader`
* `ReadableStreamBYOBReader`
* 読み取り可能なストリームの使用
* 読み取り可能なバイトストリームの使用


ReadableStream: pipeTo() メソッド - Web API

ReadableStream: pipeTo() メソッド
=============================

**`pipeTo()`** は `ReadableStream` インターフェイスのメソッドで、現在の `ReadableStream` を与えられた `WritableStream` にパイプ接続します。返される `Promise` は、パイプのプロセスが正常に完了した場合は履行され、エラーが発生した場合は拒否されます。

ストリームをパイプ接続すると、通常、接続している間はストリームがロックされ、他のリーダーがロックできなくなります。

構文
--

```js
pipeTo(destination)
pipeTo(destination, options)
```

### 引数

`destination`

`ReadableStream` の最終的な宛先として機能する `WritableStream`。

`options` 省略可

`writable` ストリームにパイプ接続するときに使用するオプションです。
 利用できるオプションは以下の通りです。

`preventClose`

 これを `true` に設定すると、入力元の `ReadableStream` が閉じられても、出力先の `WritableStream` が閉じられることはなくなります。
 このメソッドは、この処理が完全に終了すると履行されるプロミスを返します。ただし、出力先を閉じる際にエラーが発生した場合は、そのエラーで拒否されます。

`preventAbort`

 この値を `true` に設定すると、入力元の `ReadableStream` でエラーが発生しても、出力先の `WritableStream` を中断させることがなくなります。
 このメソッドは、出力元のエラー、または出力先を中止する際に発生したエラーで拒否されるプロミスを返します。

`preventCancel`

 この値を `true` に設定すると、出力先の `WritableStream` でエラーが発生しても、入力元の `ReadableStream` を取り消すことができなくなります。
 この場合、メソッドは、入力元のエラー、または入力元を取り消す際に発生するエラーで拒否されるプロミスを返します。
 また、出力先の書き込み可能なストリームが閉じられたり開始されたりした場合、入力元の読み取り可能なストリームは取り消されなくなります。
 この場合、メソッドは、閉じられたストリームへのパイプ処理に失敗したことを示すエラー、または入力元を取り消す際に発生するエラーとともに、拒否されるプロミスを返します。

`signal`

`AbortSignal` オブジェクトを設定すると、進行中のパイプ操作が対応する `AbortController` から中止できます。

### 返値

パイプのプロセスが完了したときに解決する `Promise` です。

### 例外

`TypeError`

`writableStream` や `readableStream` オブジェクトは、書き込み可能なストリーム/読み取り可能なストリームではないか、ストリームの一方または両方がロックされています。

例
-

```js
// 元の画像を読み取る
fetch("png-logo.png")
  // その body を ReadableStream として取得
  .then((response) => response.body)
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => rs.pipeTo(new FinalDestinationStream()));
```

同じ例で `await` 使用すると次のようになります。

```js
(async () => {
  // 元の画像を読み取る
  const response = await fetch("png-logo.png");
  // その body を ReadableStream として取得
  response.body
    .pipeThrough(new PNGTransformStream())
    .pipeTo(new FinalDestinationStream());
})();
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-to④ |

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

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

関連情報
----

* `ReadableStream()` コンストラクター
* パイプチェーン


ReadableStream: pipeThrough() メソッド - Web API

ReadableStream: pipeThrough() メソッド
==================================

**`pipeThrough()`** は `ReadableStream` インターフェイスのメソッドで、変換ストリームまたはその他の書き込み可能/読み取り可能なペアを介して現在のストリームを接続する連鎖可能な方法を提供します。

ストリームを接続すると、通常、接続している間はストリームがロックされ、他のリーダーがロックできなくなります。

構文
--

```js
pipeThrough(transformStream)
pipeThrough(transformStream, options)
```

### 引数

`transformStream`

読み取り可能なストリームと書き込み可能なストリームで構成され、データをある形式から別の形式に変換する `TransformStream`（または構造 `{writable, readable}` のオブジェクト）。 書き込み可能なストリーム（`writable` stream）に書き込まれたデータは、読み取り可能なストリーム（`readable` stream）によって何らかの変換された状態で読み取ることができます。 例えば、`TextDecoder` ではバイトが書き込まれ、そこから文字列が読み取られ、動画デコーダーではエンコードされたバイトが書き込まれ、非圧縮動画フレームが読み取られます。

`options` 省略可

書き込み可能な (`writable`) ストリームに接続するときに使用するオプションです。利用可能なオプションは次の通りです。

`preventClose`

 これを `true` に設定すると入力元の `ReadableStream` を閉じても、出力先の `WritableStream` が閉じられることはなくなります。
 このメソッドは、出力先を閉じる際にエラーが発生しない限り、この処理が完全に終了すると、履行されたプロミスを返します。

`preventAbort`

 これを `true` に設定すると、入力元の `ReadableStream` でエラーが発生しても、出力先の `WritableStream` を中断させることができなくなります。
 このメソッドは、入力元のエラー、または出力先を停止させる際に発生したエラーを含むプロミスを返します。

`preventCancel`

 これを `true` に設定すると、出力先の `WritableStream` でエラーが発生しても、入力元の `ReadableStream` をキャンセルすることができなくなります。
 この場合、このメソッドは、入力元のエラー、または入力元を取り消す際に発生したエラーを含む拒否されたプロミス を返します。
 さらに、出力先の書き込み可能なストリームが閉じられたり開始された場合、入力元の読み取り可能なストリームは取り消されることはありません。
 この場合、このメソッドは、閉じられたストリームへの接続に失敗したことを示すエラー、または入力元を取り消す際に発生する任意のエラーと共に、拒否されたプロミスを返します。

`signal`

`AbortSignal` オブジェクトに設定されている場合、 進行中のパイプ操作は、対応する `AbortController` を介して中断することが可能です。

### 返値

`transformStream` の `readable` 側です。

### 例外

`TypeError`

`transformStream` の `writable` や `readable` プロパティが未定義です。

例
-

次の例（ライブ実行中の完全なコードについては PNG のチャンクをアンパック、ソースコードについては png-transform-stream を参照）では、画像が取得され、その本体が `ReadableStream` として取得されます。

次に、読み取り可能なストリームのコンテンツをログに記録し、`pipeThrough()` を使用して、グレースケールバージョンのストリームを作成する新しい関数に送信し、新しいストリームのコンテンツもログに記録します。

```js
// 元の画像を取得
fetch("png-logo.png")
  // その body を ReadableStream として取得
  .then((response) => response.body)
  .then((rs) => logReadableStream("Fetch Response Stream", rs))
  // 元の画像からグレースケール PNG ストリームを作成
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => logReadableStream("PNG Chunk Stream", rs));
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-through② |

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

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

関連情報
----

* `ReadableStream()` コンストラクター
* パイプチェーン


ReadableStream: locked プロパティ - Web API

ReadableStream: locked プロパティ
============================

**`locked`** は `ReadableStream` インターフェイスの読み取り専用プロパティで、読み取り可能なストリームがリーダーにロックされているかどうかを返します。

 読み取り可能なストリームは、一度に最大 1 つのアクティブなリーダーを持つことができ、それが解放されるまでそのリーダーにロックされます。
 リーダーは `ReadableStream.getReader()` を使用して取得し、リーダーの `releaseLock()` メソッドを使用して解放することができます。

値
-

論理値で、読み取り可能なストリームがロックされているかどうかを示します。

例
-

```js
const stream = new ReadableStream({
  // ...
});

const reader = stream.getReader();

stream.locked;
// ストリームがリーダーにロックされているため、true が返されるはずです
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-locked② |

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

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

関連情報
----

* `ReadableStream()` constructor
* 読み取り可能なストリームの使用


ReadableStream: cancel() メソッド - Web API

ReadableStream: cancel() メソッド
=============================

**`cancel()`** は `ReadableStream` インターフェイスのメソッドで、ストリームがキャンセルされたときに解決する `Promise` を返します。

キャンセルは、ストリームを完全に終了し、読み取り待ちのチャンクがキューに入れられている場合でも、それ以上データを必要としない場合に使用します。 キャンセルが呼び出された後、そのデータは失われ、ストリームは読み取り不能になります。 これらのチャンクをまだ読み取り、ストリームを完全に取り除くわけではない場合は、 `ReadableStreamDefaultController.close()` を使用してください。

構文
--

```js
cancel()
cancel(reason)
```

### 引数

`reason` 省略可

人間が読むことができるキャンセルの理由を提供する文字列です。

### 返値

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

### 例外

`TypeError`

キャンセルしようとしているストリームは `ReadableStream` ではないか、ロックされています。

例
-

Jake Archibald によるフェッチのキャンセルの例では、ストリームを使用して、チャンクごとに WHATWG HTML 仕様をフェッチします。 各チャンクで文字列 "service workers" を検索します。 検索用語が見つかると、`cancel()` を使用してストリームをキャンセルします — 仕事は終了しているため、ストリームは不要になります。

```js
const searchTerm = "service workers";
// 一致した結果の両側を表示する文字数
const contextBefore = 30;
const contextAfter = 30;
const caseInsensitive = true;
const url = "https://html.spec.whatwg.org/";

console.log(`'${searchTerm}' を '${url}' で検索`);

fetch(url)
  .then((response) => {
    console.log("ヘッダーを受信しました");

    const decoder = new TextDecoder();
    const reader = response.body.getReader();
    const toMatch = caseInsensitive ? searchTerm.toLowerCase() : searchTerm;
    const bufferSize = Math.max(toMatch.length - 1, contextBefore);

    let bytesReceived = 0;
    let buffer = "";
    let matchFoundAt = -1;

    return reader.read().then(function process(result) {
      if (result.done) {
        console.log("一致するものが見つかりませんでした");
        return;
      }

      bytesReceived += result.value.length;
      console.log(`これまでに ${bytesReceived} バイトのデータを受信しました`);

      buffer += decoder.decode(result.value, { stream: true });

      // 一致するものが既に見つかっており、コンテキストを収集していますか？
      if (matchFoundAt === -1) {
        matchFoundAt = (
          caseInsensitive ? buffer.toLowerCase() : buffer
        ).indexOf(toMatch);
      }

      if (matchFoundAt === -1) {
        buffer = buffer.slice(-bufferSize);
      } else if (
        buffer.slice(matchFoundAt + toMatch.length).length >= contextAfter
      ) {
        console.log("これが一致したものです:");
        console.log(
          buffer.slice(
            Math.max(0, matchFoundAt - contextBefore),
            matchFoundAt + toMatch.length + contextAfter,
          ),
        );
        console.log("フェッチのキャンセル");
        reader.cancel();
        return;
      } else {
        console.log("一致が見つかりましたが、さらにコンテキストが必要です…");
      }

      // 読み続ける
      return reader.read().then(process);
    });
  })
  .catch((err) => {
    console.error(
      "失敗しました。詳細については、開発者ツールを参照してください。 レスポンスから CORS ヘッダー抜けていませんか？",
    );
    throw err;
  });
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-cancel③ |

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

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

関連情報
----

* `ReadableStream()` コンストラクター
* 読み取り可能なストリームの使用


ReadableStream: tee() メソッド - Web API

ReadableStream: tee() メソッド
==========================

`ReadableStream` インターフェイスの **`tee()`** メソッドは、現在の読み取り可能なストリームを分配し、結果の 2 つの分岐を新しい `ReadableStream` インスタンスとして含む 2 つの要素の配列を返します。

これは、2 つのリーダーがストリームを同時に、おそらく異なる速度で読み取ることができるようにする場合に便利です。 例えば、サーバーからレスポンスを取得してブラウザーにストリーム入力したいが、サービスワーカーのキャッシュにもストリーム入力したい場合は、サービスワーカーでこれを行うことができます。レスポンスの本体を複数回使用することはできないため、これを行うには 2 つのコピーが必要です。

 分配したストリームは、 2 つの `ReadableStream` の分岐のうち、消費速度の速い方の速度で部分的に背圧の信号を出し、未読データは、制限や背圧なしに消費速度の遅い方の `ReadableStream` に内部で待ち行列に入れられます。
 つまり、両方の分岐の内部キューに未読の要素がある場合、元の `ReadableStream` のコントローラの内部キューが埋まり始め、その `desiredSize` ≤ 0 またはバイトストリームのコントローラーの `desiredSize` ≤ 0 になると、コントローラーは `pull(controller)` を呼び出すのを、新しい `new ReadableStream()` に渡された元の入力に対して停止します。一方の分岐のみが消費される場合、本文全体がメモリー上の待ち行列に入れられます。したがって、非常に大きなストリームを並列に異なる速度で読み込むために、組み込みの `tee()` を使用するべきではありません。その代わり、消費速度の遅い方の分岐の速度に完全に背圧するような実装を探しましょう。

ストリームを取り消すには、結果の分岐をどちらも取り消す必要があります。ストリームを分配すると、一般に、その間はそのストリームがロックされ、他のリーダーがロックするのを防ぎます。

構文
--

```js
tee()
```

### 引数

なし。

### 返値

2 つの `ReadableStream` インスタンスを含む `Array`。

### 例外

TypeError

ソースストリームは `ReadableStream` ではありません。

例
-

次の簡単な例では、以前に作成したストリームをティーイングした結果の両方のストリーム（生成された配列の 2 つのメンバーに含まれる）を、2 つのストリームからデータを読み取り、各ストリームのチャンクを UI の異なる部分に順番に印刷する関数に渡します。 完全なコードについては、単純な tee の例を参照してください。

```js
function teeStream() {
  const teedOff = stream.tee();
  fetchStream(teedOff[0], list2);
  fetchStream(teedOff[1], list3);
}

function fetchStream(stream, list) {
  const reader = stream.getReader();
  let charsReceived = 0;

  // read() は、値を受け取ったときに解決するプロミスを返します
  reader.read().then(function processText({ done, value }) {
    // 結果オブジェクトには 2 つのプロパティが含まれます。
    // done - ストリームがすべてのデータを既に提供している場合は true。
    // value - 一部のデータ。 done が true の場合、常に undefined。
    if (done) {
      console.log("Stream complete");
      return;
    }

    // フェッチしたストリームの値は Uint8Array です
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent = `Read ${charsReceived} characters so far. Current chunk = ${chunk}`;
    list.appendChild(listItem);

    // さらに読み、この関数を再度呼び出します
    return reader.read().then(processText);
  });
}
```

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-rs-tee② |

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

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

関連情報
----

* `ReadableStream()` コンストラクター
* ストリームの分岐