ClipboardItem.presentationStyle - Web API

ClipboardItem.presentationStyle
===============================

**`presentationStyle`** は `ClipboardItem` インターフェイスの読み取り専用プロパティで、アイテムをどう表示すべきかを示す文字列を返します。

値
-

`"unspecified"`, `"inline"`, `"attachment"` のいずれかです。

例
-

以下の例では、 `clipboard.read()` メソッドによってクリップボード上のすべての項目を返し、 `presentationStyle` プロパティをログ出力しています。

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      console.log(clipboardItem.presentationStyle);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

仕様書
---

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-presentationstyle |

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

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

関連情報
----

* クリップボード API
* Async Clipboard API demo on Glitch
* Image support for Async Clipboard article


ClipboardItem.types - Web API

ClipboardItem.types
===================

**`types`** は `ClipboardItem` インターフェイスの読み取り専用プロパティで、この `ClipboardItem` の内容で利用できるMIME タイプの配列 (`Array`) を返します。

値
-

利用できるMIME タイプの配列 (`Array`) です。

例
-

以下の例では、 `clipboard.read()` メソッドによってクリップボード上のすべての項目を返しています。次に、 `types` プロパティで利用可能な型を確認し、 `ClipboardItem.getType()` メソッドを使用して `Blob` オブジェクトを返しています。指定されたタイプに対応するクリップボードのコンテンツが見つからない場合は、エラーが返されます。

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      for (const type of clipboardItem.types) {
        const blob = await clipboardItem.getType(type);
        // we can now use blob here
      }
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

仕様書
---

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-types |

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

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

関連情報
----

* クリップボード API
* Async Clipboard API demo on Glitch
* Image support for Async Clipboard article


ClipboardItem.getType() - Web API

ClipboardItem.getType()
=======================

**`getType()`** は `ClipboardItem` インターフェイスのメソッドで、要求された MIME タイプ の `Blob` で解決するプロミス (`Promise`) を返します。 MIME タイプが見つからない場合はエラーになります。

構文
--

```js
getType(type);
```

### 引数

`type`

有効な MIME タイプです。

### 返値

`Blob` オブジェクトで解決するプロミス (`Promise`)です。

### 例外

`NotFoundError` `DOMException`

`type` が既知の MIME タイプに一致しない。

`TypeError`

 引数が指定されなかった、または `type` が
 `ClipboardItem` のものではない。

例
-

次の例では、 `clipboard.read()` メソッドによってクリップボード上のすべてのアイテムを返しています。そして、 `ClipboardItem.types` プロパティを利用して `getType()` 引数をセットし、対応する blob オブジェクトを返します。

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      for (const type of clipboardItem.types) {
        const blob = await clipboardItem.getType(type);
        // we can now use blob here
      }
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

仕様書
---

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-gettype |

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

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

関連情報
----

* クリップボード API
* Async Clipboard API demo on Glitch
* Image support for Async Clipboard article


CustomElementRegistry.whenDefined() - Web API

CustomElementRegistry.whenDefined()
===================================

**`whenDefined()`** は `CustomElementRegistry` インターフェイスのメソッドで、指定した名前の要素が定義されたときに解決されるプロミス (`Promise`) を返します。

構文
--

```js
customElements.whenDefined(name): Promise<CustomElementConstructor>;
```

### 引数

name

カスタム要素の名前。

### 返値

指定された名前のカスタム要素が定義された時に、カスタム要素のコンストラクターで履行されるプロミス (`Promise`) です。（そのようなカスタム要素が既に定義されている場合、返されるプロミスは直ちに履行されます。）

例外
--

| 例外 | 説明 |
| --- | --- |
| `SyntaxError` | 指定された名前が有効なカスタム要素名でなかった場合、プロミスは `SyntaxError` で拒否されます。 |

例
-

以下の例では、 `whenDefined()` を用いてメニューを生成するカスタム要素が定義されたタイミングを検出しています。実際にメニューコンテンツの表示準備が完了するまでは、メニューはプレースホルダーのコンテンツを表示します。

```html
<nav id="menu-container">
  <div class="menu-placeholder">Loading...</div>
  <nav-menu>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
    ...
    <menu-item>Item N</menu-item>
  </nav-menu>
</nav>
```

```js
const container = document.getElementById("menu-container");
const placeholder = container.querySelector(".menu-placeholder");
// まだ定義されていないメニューの子を取得する
const undefinedElements = container.querySelectorAll(":not(:defined)");

async function removePlaceholder() {
  const promises = [...undefinedElements].map((button) =>
    customElements.whenDefined(button.localName),
  );

  // すべての子がアップグレードされるまで待つ
  await Promise.all(promises);
  // それからプレースホルダーを削除
  container.removeChild(placeholder);
}

removePlaceholder();
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-whendefined-dev |

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

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


CustomElementRegistry.get() - Web API

CustomElementRegistry.get()
===========================

**`get()`** は `CustomElementRegistry` インターフェイスのメソッドで、以前定義したカスタム要素のコンストラクターを返します。

構文
--

```js
constructor = customElements.get(name);
```

### 引数

name

コンストラクターの参照を返したいカスタム要素の名前です。

### 返値

名前付きのカスタム要素のコンストラクター、またはその名前のカスタム要素がない場合は `undefined` です。

例
-

```js
customElements.define(
  "my-paragraph",
  class extends HTMLElement {
    constructor() {
      let templateContent = document.getElementById("my-paragraph").content;
      super() // このスコープの要素を返す
        .attachShadow({ mode: "open" }) // this.shadowRoot を設定して返す
        .append(templateContent.cloneNode(true));
    }
  },
);

// my-paragraph のコンストラクターの参照を返す
let ctor = customElements.get("my-paragraph");
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-get-dev |

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

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


CustomElementRegistry.define() - Web API

CustomElementRegistry.define()
==============================

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
**`define()`** は `CustomElementRegistry` インターフェイスのメソッドで、新しいカスタム要素を定義します。

作成することができるのは、次の 2 種類のカスタム要素です。

* **自律カスタム要素** (Autonomous custom element): 独立した要素です。組み込みの HTML 要素を継承していません。
* **カスタム組み込み要素** (Customized built-in element): 組み込みの HTML 要素を継承し、拡張した要素です。
構文
--

```js
customElements.define(name, constructor, options);
```

### 引数

* name
    + : 新しいカスタム要素の名前です。カスタム要素の名前は、少なくとも 1 つのハイフンを含まなければならないことに注意してください。
* constructor
    + : 新しいカスタム要素のコンストラクターです。
* options 省略可
    + : 要素の定義の仕方を制御するオブジェクト。現在は、次の 1 つのオプションのみに対応しています。
* `extends`: 拡張する組み込み要素の名前を示す文字列。*カスタム組み込み要素*を作成するのに使われる。
### 返値

なし。

### 例外

`NotSupportedError` `DOMException`

`CustomElementRegistry` に既に同じ名前の項目または同じコンストラクターが含まれている（または既に定義されている）、または `extends` で有効なカスタム要素名が指定されていた場合、または `extends` で未知の要素を拡張しようとした場合に発生します。

`SyntaxError` `DOMException`

指定された名前が有効なカスタム要素名ではなかった場合に発生します。

`TypeError` `DOMException`

参照されたコンストラクターがコンストラクターではなかった場合に発生します。

**メモ:** `NotSupportedError` 例外が多く発生する場合、 `define()` が失敗しているように思えるかもしれませんが、多くの場合は `Element.attachShadow()` に問題があります。

例
-

### 自律カスタム要素

 以下のコードは popup-info-box-web-component
 の例から取ったものです (ライブでもご覧ください)。

```js
// 要素のクラスを作成
class PopUpInfo extends HTMLElement {
  constructor() {
    // コンストラクターでは常に super を最初に呼び出す
    super();

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

    // span を生成
    var wrapper = document.createElement("span");
    wrapper.setAttribute("class", "wrapper");
    var icon = document.createElement("span");
    icon.setAttribute("class", "icon");
    icon.setAttribute("tabindex", 0);
    var info = document.createElement("span");
    info.setAttribute("class", "info");

    // 属性の中身を取り出し、 info の span の中に入れる
    var text = this.getAttribute("text");
    info.textContent = text;

    // アイコンを挿入
    var imgUrl;
    if (this.hasAttribute("img")) {
      imgUrl = this.getAttribute("img");
    } else {
      imgUrl = "img/default.png";
    }
    var img = document.createElement("img");
    img.src = imgUrl;
    icon.appendChild(img);

    // いくらかの CSS を生成してシャドウ DOM に適用
    var style = document.createElement("style");

    style.textContent =
      ".wrapper {" +
      "position: relative;" +
      "}" +
      ".info {" +
      "font-size: 0.8rem;" +
      "width: 200px;" +
      "display: inline-block;" +
      "border: 1px solid black;" +
      "padding: 10px;" +
      "background: white;" +
      "border-radius: 10px;" +
      "opacity: 0;" +
      "transition: 0.6s all;" +
      "position: absolute;" +
      "bottom: 20px;" +
      "left: 10px;" +
      "z-index: 3;" +
      "}" +
      "img {" +
      "width: 1.2rem" +
      "}" +
      ".icon:hover + .info, .icon:focus + .info {" +
      "opacity: 1;" +
      "}";

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

    shadow.appendChild(style);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

// 新しい要素を定義
customElements.define("popup-info", PopUpInfo);
```

```html
<popup-info
 img="img/alt.png"
 text="Your card validation code (CVC) is an extra
 security feature — it is the last 3 or 4
 numbers on the back of your card."></popup-info>
```

**メモ:** 自律カスタム要素のコンストラクターは `HTMLElement` を継承していなければなりません。

### カスタム組み込み要素

 以下のコードは word-count-web-component
 の例から取ったものです (ライブでもご覧ください)。

```js
// 要素のクラスを作成
class WordCount extends HTMLParagraphElement {
  constructor() {
    // コンストラクターでは常に super を最初に呼び出す
    super();

    // 要素の親要素の語数を数える
    var wcParent = this.parentNode;

    function countWords(node) {
      var text = node.innerText || node.textContent;
      return text.split(/\s+/g).length;
    }

    var count = "語数: " + countWords(wcParent);

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

    // テキストノードを生成し、語数を追加
    var text = document.createElement("span");
    text.textContent = count;

    // シャドウルートに追加
    shadow.appendChild(text);

    // 要素の内容が変化した際に語数を更新
    setInterval(function () {
      var count = "語数: " + countWords(wcParent);
      text.textContent = count;
    }, 200);
  }
}

// 新しい要素を定義
customElements.define("word-count", WordCount, { extends: "p" });
```

```html
<p is="word-count"></p>
```

### シャドウルートを取り付けられないようにする要素の作成

要素に使用されているクラスが、文字列 `shadow` を返す静的プロパティ `disabledFeatures` を含んでいる場合、 `Element.attachShadow()` は `DOMException` の `NotSupportedError` を返すようになります。

```js
class PopUpInfo extends HTMLElement {
  static get disabledFeatures() {
    return ["shadow"];
  }

  constructor() {
    super();

    var shadow = this.attachShadow({ mode: "open" });
    // これは要素が定義されたときにエラーが発生するようになります。
  }
}
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-define-dev |

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

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


CustomElementRegistry.upgrade() - Web API

CustomElementRegistry.upgrade()
===============================

**`upgrade()`** は `CustomElementRegistry` インターフェイスのメソッドで、 `Node` サブツリー内のすべてのシャドウを含むカスタム要素を、メイン文書に接続する前であってもアップグレードします。

構文
--

```js
customElements.upgrade(root);
```

### 引数

`root`

アップグレードされる、シャドウを含む子孫要素を持つ `Node` インスタンス。アップグレード可能な子孫要素がない場合、エラーは発生しません。

### 返値

なし。

例
-

HTML
仕様書 から取りました。

```js
const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // not yet upgraded

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // upgraded!
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-upgrade-dev |

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

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


ElementInternals: setValidity() メソッド - Web API

ElementInternals: setValidity() メソッド
====================================

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

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

* Learn more
* See full compatibility
* Report feedback
**`setValidity()`** は `ElementInternals` インターフェイスのメソッドで、この要素の妥当性を設定します。

構文
--

```js
setValidity(flags)
setValidity(flags, message)
setValidity(flags, message, anchor)
```

### 引数

`flags` 省略可

要素の有効状態を示す、 1 つ以上のフラグを含む辞書オブジェクトです。

`valueMissing`

論理値で、要素に `required` 属性があって値がない場合は `true` となり、そうでない場合は `false` となります。もし `true` なら、その要素は CSS の `:invalid` の擬似クラスに一致します。

`typeMismatch`

論理値で、値が必要とされる構文でない場合（`type` が `email` または `url` の場合）は `true` となり、構文が正しい場合は `false` となります。 `true` の場合、その要素は CSS の `:invalid` の擬似クラスに一致します。

`patternMismatch`

論理値で、指定された `pattern` に一致しない場合は `true` となり、一致する場合は `false` となります。 `true` の場合、その要素は CSS の `:invalid` の擬似クラスに一致します。

`tooLong`

論理値で、値が `HTMLInputElement` または `HTMLTextAreaElement` オブジェクトで指定された `maxlength` を超える場合は `true` となり、最大の長さ以下の場合は `false` となります。 `true` の場合、その要素は CSS の `:invalid` および `:out-of-range` 擬似クラスに一致します。

`tooShort`

論理値で、値が `HTMLInputElement` または `HTMLTextAreaElement` オブジェクトで指定された `minlength` に満たない場合は `true` となり、最小の長さ以上の場合は `false` となります。 `true` の場合、その要素は CSS の `:invalid` および `:out-of-range` 擬似クラスに一致します。

`rangeUnderflow`

論理値で、値が `min` 属性で指定された最小値より小さい場合は `true` となり、最小値以上の場合は `false` となります。 `true` の場合、要素は CSS の `:invalid` および `:out-of-range` 擬似クラスに一致します。

`rangeOverflow`

論理値で、値が `max` 属性で指定された最大値より大きい場合は `true` となり、最大値以下であれば `false` となります。 `true` の場合、要素は CSS の `:invalid` および `:out-of-range` 擬似クラスに一致します。

`stepMismatch`

論理値で、値が `step` 属性によって決定されるルールに適合しない（つまり、ステップ値で均等に割り切れない）場合は `true` となり、ステップのルールに適合する場合は `false` となります。 `true` の場合、要素は CSS の `:invalid` および `:out-of-range` 擬似クラスに一致します。

`badInput`

論理値で、ブラウザーが変換できない入力をユーザーが入力した場合に `true` となります。

`customError`

論理値で、この要素の `setCustomValidity()` メソッドを呼び出すことで、要素のカスタム有効性メッセージが空でない文字列に設定されたかどうかを示します。

**メモ:** すべてのフラグを `false` に設定し、この要素がすべての制約の検証に合格したことを示すには、空のオブジェクト `{}` を渡してください。この場合、 `message` も渡す必要はありません。

`message` 省略可

`flags` が `true` の場合に設定されるメッセージを含む文字列。すべての `flags` が `false` の場合のみ、この引数はオプションとなります。

`anchor` 省略可

このフォーム送信に関する問題を報告するためにユーザーエージェントが使用する `HTMLElement` です。

### 返値

なし (`undefined`)。

### 例外

`NotSupportedError` `DOMException`

要素の `formAssociated` プロパティが `true` に設定されていない場合に発生します。

`TypeError`

1 つ以上の `flags` が `true` の場合に発生します。

`NotFoundError` `DOMException`

`anchor` が与えられているが、そのアンカーが要素のシャドウを含む子孫でない場合に発生します。

例
-

次の例では、 `setValidity` を空の `flags` 引数を指定して呼び出して、この要素が制約検証ルールを満たしていることを示します。

```js
this.internals_.setValidity({});
```

次の例では、 `valueMissing` フラグを `true` に設定して `setValidity` を呼び出しています。その際、 `message` 引数にメッセージを渡す必要があります。

```js
this.internals_.setValidity({ valueMissing: true }, "my message");
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-setvalidity |

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

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


ElementInternals: labels プロパティ - Web API

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

**`labels`** は `ElementInternals` インターフェイスのプロパティで、要素に関連付けられたラベルを返します。

値
-

この要素に関連付けられたすべてのラベル要素の入った `NodeList` です。

例
-

 次の例は、カスタムチェックボックスコンポーネントに `<label>` 要素をリンクしたものです。
 `labels` の値をコンソールに出力すると、このラベルを表す1つのエントリを持つ `NodeList` が返されます。

```html
<form id="myForm">
  <custom-checkbox id="custom-checkbox"></custom-checkbox>
  <label for="custom-checkbox">Join newsletter</label>
</form>
```

```js
let element = document.getElementById("custom-checkbox");
console.log(element.internals_.label);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-labels |

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

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


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

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

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

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

* Learn more
* See full compatibility
* Report feedback
**`reportValidity()`** は `ElementInternals` インターフェイスのメソッドで、適用された制約検証ルールをこの要素が満たしているかどうかをチェックします。

`reportValidity` が `false` を返した場合、キャンセル可能な invalid イベントが要素で発生します。

このメソッドは `ElementInternals.checkValidity()` と同様の振る舞いをしますが、 `ElementInternals.validationMessage` (en-US) の値をユーザーエージェントに送信して表示させます。

構文
--

```js
reportValidity()
```

### 引数

なし。

### 返値

論理値で、要素がすべての検証される制約に合格していれば `true` を返します。

### 例外

`NotSupportedError` `DOMException`

要素の `formAssociated` プロパティが `true` に設定されていない場合に発生します。

例
-

以下の例では、 `ElementInternals.setValidity()` を使用して、要素が検証ルールを満たしていないことを示します。 `reportValidity()` を呼び出すと `false` が返され、 "メッセージ" という値がユーザーエージェントに送られ、表示されます。

再度 `setValidity` を呼び出し、今度はすべてのルールが false になっていることを示すと、`reportValidity()` は `true` を返します。

```js
let element = document.getElementById("join-checkbox");
element.internals_.setValidity({ valueMissing: true }, "メッセージ");
console.log(element.internals_.reportValidity()); // false
element.internals_.setValidity({});
console.log(element.internals_.reportValidity()); // true
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-reportvalidity |

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

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


ElementInternals: setFormValue() メソッド - Web API

ElementInternals: setFormValue() メソッド
=====================================

**`setFormValue()`** は `ElementInternals` インターフェイスのメソッドで、このメソッドは、要素の送信値と状態を設定し、これらをユーザーエージェントに伝えます。

構文
--

```js
setFormValue(value)
setFormValue(value, state)
```

### 引数

`value`

サーバに送信する値として、`File`、文字列、`FormData` のいずれかを指定します。

`state` 省略可

`File`、文字列、`FormData` のいずれかで、ユーザーの入力を表します。
 これにより、アプリケーションは必要に応じて、ユーザーが送信した情報を、ユーザーが入力した形式で再表示することができます。

**メモ:** 一般的に、 `state` はユーザがー指定した情報を渡すために、 `value` はサニタイズ後、サーバーに送信するのに適した情報を渡すために使用されます。
 たとえば、カスタム要素で日付の入力を求められた場合、ユーザーは「3/15/2019」と入力するかもしれません。
 これは `state` です。
 サーバーは `2019-03-15` という日付書式を期待しているので、この書式の日付が `value` として渡されます。

### 返値

undefined です。

### 例外

`NotSupportedError` `DOMException`

要素の `formAssociated` プロパティが `true` に設定されていない場合に発生します。

例
-

次の例では、チェックボックスのカスタム要素で、サーバーに送信する値として `on` を、状態として `checked` を設定しています。

```js
this.internals_.setFormValue("on", "checked");
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-setformvalue |

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

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


ElementInternals: ariaDisabled プロパティ - Web API

ElementInternals: ariaDisabled プロパティ
====================================

**`ariaDisabled`** は `ElementInternals` インターフェイスのプロパティで、`aria-disabled` 属性の値を反映し、要素が知覚可能だが無効であり、編集や他の処理をすることはできないことを示します。

**メモ:** `ElementInternals` に aria 属性を設定することで、カスタム要素に既定値を定義することができます。これらは作成者が定義した属性によって上書きされる可能性がありますが、作成者が属性を削除したり、追加しなかった場合でも確実に既定値を定義することができます。より詳しい情報は、 Accessibility Object Model explainer を参照してください。

値
-

以下のいずれかの値を持つ文字列です。

`"true"`

要素とフォーカス可能なすべての子孫は無効ですが、知覚可能であり、それらの値はユーザーによって変更できません。

`"false"`

要素が有効になっています。

例
-

この例では、 `ariaDisabled` の値を "true" に設定しています。

```js
this.internals_.ariaDisabled = "true";
```

仕様書
---

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariadisabled |

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

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


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

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

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

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

* Learn more
* See full compatibility
* Report feedback
**`checkValidity()`** は `ElementInternals` インタフェイスのメソッドで、要素が適用された制約検証のルールを満たしているかどうかをチェックします。

もし `checkValidity` が `false` を返したら、キャンセル可能な invalid イベントが要素で発生します。

構文
--

```js
checkValidity()
```

### 引数

なし。

### 返値

論理値で、要素がすべての検証される制約に合格していれば `true` を返します。

### 例外

`NotSupportedError` `DOMException`

要素の `formAssociated` プロパティが `true` に設定されていない場合に発生します。

例
-

以下の例では、 `ElementInternals.setValidity()` を使用して、要素が検証ルールを満たしていないことを示します。 `checkValidity()` を呼び出すと `false` が返されます。再度 `setValidity` を呼び出し、今度はすべてのルールが false になっていることを示すと、`checkValidity()` は `true` を返します。

```js
let element = document.getElementById("join-checkbox");
element.internals_.setValidity({ valueMissing: true }, "メッセージ");
console.log(element.internals_.checkValidity()); // false
element.internals_.setValidity({});
console.log(element.internals_.checkValidity()); // true
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-checkvalidity |

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

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


ElementInternals: form プロパティ - Web API

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

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

値
-

`HTMLFormElement` です。

例
-

 次の例では、 ID が `myForm` のフォーム内にカスタムチェックボックスコンポーネントを配置しています。
 コンソールに `form.length` を出力すると、 `HTMLFormElement.length` という値が得られます。

```html
<form id="myForm">
  <custom-checkbox id="custom-checkbox"></custom-checkbox>
  <custom-label for="custom-checkbox">Join newsletter</custom-label>
</form>
```

```js
class CustomCheckbox extends HTMLElement {
  static formAssociated = true;
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
  }

  connectedCallback() {
    console.log(this.#internals.form.length);
  }
}

window.customElements.define("custom-checkbox", CustomCheckbox);
```

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-elementinternals-form |

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

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


CSSStyleValue.parse() - Web API

CSSStyleValue.parse()
=====================

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

**`parse()`** は `CSSStyleValue` インターフェイスのメソッドで、特定の CSS プロパティを指定された値に設定し、最初の値を `CSSStyleValue` オブジェクトとして返します。

構文
--

```js
parse(property, cssText)
```

### 引数

`property`

設定する CSS プロパティ

`cssText`

指定されたプロパティに適用する 1 つ以上の値を含む、カンマで区切られた文字列。

### 返値

最初に与えられた値を格納した `CSSStyleValue` オブジェクトです。

例
-

 下記のコードは `transform` プロパティに対する一連の宣言を解釈します。
 2 つ目のコードブロックは、返されたオブジェクトの構造を、開発者ツールのコンソールに表示したものです。

```js
const css = CSSStyleValue.parse(
  "transform",
  "translate3d(10px,10px,0) scale(0.5)",
);
```

```css
CSSTransformValue {0: CSSTranslate, 1: CSSScale, length: 2, is2D: false}
```

仕様書
---

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

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

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

関連情報
----

* `CSSStyleValue.parseAll()`
* CSS 型付きオブジェクトモデルの使用
* CSS 型付きオブジェクトモデル API


CSSStyleValue.parseAll() - Web API

CSSStyleValue.parseAll()
========================

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

**`parseAll()`** は `CSSStyleValue` インターフェイスのメソッドで、出現したすべての特定の CSS プロパティを指定された値に設定し、それぞれが与えられた値の 1 つを格納した `CSSStyleValue` オブジェクトの配列を返します。

構文
--

```js
parseAll(property, value)
```

### 引数

`property`

設定する CSS プロパティです。

`value`

指定されたプロパティに適用される 1 つ以上の値を格納したカンマ区切りの文字列。

### 返値

`CSSStyleValue` オブジェクトの配列で、それぞれが与えられた値の 1 つを格納します。

仕様書
---

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssstylevalue-parseall |

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

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

関連情報
----

* `CSSStyleValue.parse()`
* CSS 型付きオブジェクトモデルの使用
* CSS 型付きオブジェクトモデル API


BackgroundFetchManager.getIds() - Web API

BackgroundFetchManager.getIds()
===============================

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

`BackgroundFetchManager` インターフェイスの **`getIds()`** メソッドは、登録済みのすべてのバックグラウンドフェッチの ID を返します。

構文
--

```js
getIds()
```

### 引数

なし。

### 返値

`文字列`の配列 (`Array`) で解決される `Promise` を返します。

### 例外

なし。

例
-

下記の例は、登録済みのすべてのバックグラウンドフェッチの ID を取得する方法を紹介しています。アクティブなサービスワーカーの `ServiceWorkerRegistration.backgroundFetch` プロパティを参照して `BackgroundFetchManager` オブジェクトにアクセスし、その `getIds()` メソッドを呼び出しています。

```js
navigator.serviceWorker.ready.then(async (swReg) => {
  const ids = await swReg.backgroundFetch.getIds();
});
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-manager-get-ids |

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

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


BackgroundFetchManager.fetch() - Web API

BackgroundFetchManager.fetch()
==============================

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

**`fetch()`** は `BackgroundFetchManager` インターフェイスのメソッドで、指定された 1 つ以上の URL または `Request` オブジェクトを取り、バックグラウンドのフェッチ操作を開始します。

構文
--

```js
fetch(id, requests)
fetch(id, requests, options)
```

### 引数

`id`

この操作の `BackgroundFetchRegistration` を取得するために、他のメソッドに渡すことができる、開発者定義の識別子です。

`requests`

`RequestInfo` オブジェクトまたは `RequestInfo` お武衛ジェクトの配列です。

それぞれの `RequestInfo` オブジェクトは `Request` オブジェクト、または `Request()` コンストラクターの `input` 引数として与えられる文字列です。

`options` 省略可

ブラウザーの表示するフェッチ進捗ダイアログをカスタマイズするために使用されるオブジェクトです。以下のプロパティがあります。

`title`

文字列で、進捗ダイアログのタイトルとして使われます。

`icons`

ブラウザーの進捗ダイアログに使用するアイコンを表すオブジェクトの配列です。各オブジェクトには、以下のプロパティがあります。

`src`

アイコンファイルの URL を表す文字列。

`sizes`

画像の大きさを表す文字列で、 `<link>` 要素の `sizes` 属性と同じ構文を使用して表します。 省略可

`type`

アイコンの MIME タイプを表す文字列です。 省略可

`label`

アイコンのアクセシブル名を表す文字列です。 省略可

`downloadTotal`

フェッチ操作の推定総ダウンロードサイズを表す数値（バイト単位）。これは、ダウンロードの大きさをユーザーに示すため、また、ユーザーのダウンロードの進捗状況を示すために使用されます。

ダウンロードサイズの合計が `downloadTotal` を超えると、すぐに取得が中止されます。

### 返値

`BackgroundFetchRegistration` オブジェクトで解決される `Promise` 。

### 例外

`TypeError`

次のような場合に発生します。リクエストが与えられていない場合、リクエストのモードが 'no-cors' の場合、サービスワーカーが存在しない場合、リクエストされた `id` のリクエストが既に存在する場合、またはリクエストが失敗した場合。

`AbortError` `DOMException`

fetch が失敗したことを示します。

`NotAllowedError` `DOMException`

バックグラウンド fetch を作成するためのユーザー権限が与えられていないことを示します。

例
-

下記の例は `fetch()` を使用してバックグラウンドフェッチ操作を行う方法を方法を示しています。アクティブな サービスワーカー で、 `ServiceWorkerRegistration.backgroundFetch` プロパティを使用して `BackgroundFetchManager` オブジェクトにアクセスし、その `fetch()` メソッドを呼び出しています。

```js
navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.fetch(
    "my-fetch",
    ["/ep-5.mp3", "ep-5-artwork.jpg"],
    {
      title: "Episode 5: Interesting things.",
      icons: [
        {
          sizes: "300x300",
          src: "/ep-5-icon.png",
          type: "image/png",
          label: "Downloading a show",
        },
      ],
      downloadTotal: 60 \* 1024 \* 1024,
    },
  );
});
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-manager-fetch |

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

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


BackgroundFetchManager.get() - Web API

BackgroundFetchManager.get()
============================

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

**`get()`** は `BackgroundFetchManager` インターフェイスのメソッドで、引数に与えられた `id` に紐づく `BackgroundFetchRegistration` で解決される `Promise` を返します。 `id` が見つからない場合は `undefined` を返します。

構文
--

```js
get(id)
```

### 引数

`id`

`fetch()` を呼び出すことで定義された `backgroundFetchRegistration` の ID 。

### 返値

`BackgroundFetchRegistration` で解決される `Promise` または `undefined` 。

例
-

下記の例では、 `get()` を呼び出して `BackgroundFetchRegistration` を取得する方法を紹介しています。アクティブな `service worker` の `ServiceWorkerRegistration.backgroundFetch` を参照して `BackgroundFetchManager` オブジェクトにアクセスし、その `get()` メソッドを呼び出しています。

```js
navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.get("my-fetch");
});
// my code block
```

仕様書
---

| Specification |
| --- |
| Background Fetch # background-fetch-manager-get |

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

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


HTMLDataElement: value プロパティ - Web API

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

**`value`** は `HTMLDataElement` インターフェイスのプロパティで、HTML の `value` 属性を反映する文字列を返します。

値
-

文字列です。

仕様書
---

| Specification |
| --- |
| HTML Standard # dom-data-value |

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

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


IDBIndex: get() メソッド - Web API

IDBIndex: get() メソッド
====================

`IDBIndex` の **`get()`** メソッドは `IDBRequest` オブジェクトを返し、別スレッドで参照先のオブジェクトストアから指定のキーに対応する値、もしくは `key` が `IDBKeyRange` に設定された場合は対応する最初の値を検索します。

値が見つかった場合は、その構造化複製を作成し、要求オブジェクトの `result` に設定します。これにより、キーに対応するレコードを返します。

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

構文
--

```js
get()
get(key)
```

### 引数

`key` 省略可

取得するレコードを特定するキーまたは `IDBKeyRange` です。`null` であったり省略された場合は、ブラウザーは無限のキー範囲を用います。

### 返値

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

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

### 例外

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

`TransactionInactiveError` `DOMException`

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

`DataError` `DOMException`

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

`InvalidStateError` `DOMException`

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

例
-

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

そして、`myIndex.get('Bungle')` により `lName` が `Bungle` であるレコードを取得し、`success` コールバックで要求の結果をコンソールに記録します。

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

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

  const myIndex = objectStore.index("lName");
  const getRequest = myIndex.get("Bungle");
  getRequest.onsuccess = () => {
    console.log(getRequest.result);
  };

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-get① |

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

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

関連情報
----

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


IDBIndex: objectStore プロパティ - Web API

IDBIndex: objectStore プロパティ
===========================

`IDBIndex` インターフェイスの **`objectStore`** プロパティは、現在のインデックスが参照するオブジェクトストアを返します。

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

値
-

`IDBObjectStore` です。

例
-

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

現在のオブジェクトストアをコンソールに記録します。これは以下のようなものになるはずです。

```json
IDBObjectStore { name: "contactsList", keyPath: "id", indexNames: DOMStringList[7], transaction: IDBTransaction, autoIncrement: false }
```

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

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.objectStore);

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-objectstore① |

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

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

関連情報
----

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


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

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

`IDBIndex` インターフェイスの **`count()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドでキー範囲内のレコードの数を返します。

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

構文
--

```js
count()
count(key)
```

### 引数

`key` 省略可

カウント対象のレコードを特定するキーもしくはキー範囲です。

### 返値

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

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

### 例外

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

`TransactionInactiveError` `DOMException`

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

`DataError` `DOMException`

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

`InvalidStateError` `DOMException`

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

例
-

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

そして、`myIndex.count()` を用いてインデックス内のレコードの数を数え、`success` コールバックで要求の結果をコンソールに記録します。

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

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

  const myIndex = objectStore.index("lName");
  const countRequest = myIndex.count();
  countRequest.onsuccess = () => {
    console.log(countRequest.result);
  };

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

      cursor.continue();
    } else {
      console.log("全レコードを表示しました。");
    }
  };
}
```

仕様書
---

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

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

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

関連情報
----

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


IDBIndex: keyPath プロパティ - Web API

IDBIndex: keyPath プロパティ
=======================

`IDBIndex` インターフェイスの **`keyPath`** プロパティは、現在のインデックスのキーパスを返します。`null` の場合は、このインデックスは自動生成されません。

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

値
-

キーパスとして用いることができる任意のデータ型です。

例
-

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

現在のインデックスのキーパスをコンソールに記録します。これは `lName` になるはずです。

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

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.keyPath);

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbindex-keypath |

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

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

関連情報
----

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


IDBIndex: multiEntry プロパティ - Web API

IDBIndex: multiEntry プロパティ
==========================

`IDBIndex` インターフェイスの読み取り専用プロパティ **`multiEntry`** は、インデックスのキーパスを評価した結果が配列になったときこのインデックスがどのようにふるまうかに影響する論理値を返します。

この値は、インデックスの作成時、`IDBObjectStore.createIndex` メソッドにより決定されます。このメソッドは、`multiEntry` プロパティを `true` または `false` に設定した省略可能な引数 `options` をとります。

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

値
-

以下の論理値です。

| 値 | 効果 |
| --- | --- |
| true | キーの配列の各要素それぞれをインデックスのレコードにします。 |
| false | 配列である各キーを 1 個のレコードにします。 |

例
-

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

このインデックスの複数エントリー状態をコンソールに記録します。これは `false` になるはずです。

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

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.multiEntry);

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbindex-multientry |

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

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

関連情報
----

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


IDBIndex: locale プロパティ - Web API

IDBIndex: locale プロパティ
======================

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

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

`IDBIndex` インターフェイスの読み取り専用プロパティ **`locale`** は、生成時に `locale` の値を指定されていた場合、インデックスのロケール (たとえば `en-US` や `pl`) を返します。(`IDBObjectStore.createIndex()` の引数 `options` を参照してください) なお、このプロパティは常にこのインデックスで現在使用されているロケールを返します。すなわち、`"auto"` を返すことはありません。

値
-

文字列です。

例
-

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

`locale` の値をコンソールに記録します。

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.locale);

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

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

仕様書
---

現在どの仕様にも含まれていません。

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

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

関連情報
----

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


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

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

`IDBIndex` インターフェイスの **`openKeyCursor()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで、指定のキー範囲をこのインデックスの順で走査するカーソルを生成します。

このメソッドは、指定された方向に基づいて、カーソルの位置を適切なキーに設定します。

キー範囲が指定されないか `null` の場合は、範囲は全レコードを含みます。

**メモ:** `openKeyCursor()` が返すカーソルは、`IDBIndex.openCursor` とは違い、参照される値を用意しません。
 これにより、キーのリストをより効率よく得ることができます。

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

構文
--

```js
openKeyCursor()
openKeyCursor(range)
openKeyCursor(range, direction)
```

### 引数

`range` 省略可

カーソルの範囲として使用するキーまたは `IDBKeyRange` です。省略した場合は、このオブジェクトストア内の全レコードを選択するキー範囲になります。

`direction` 省略可

カーソルの方向です。取りうる値は、IDBCursor の定数を参照してください。

### 返値

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

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

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

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

`TransactionInactiveError` `DOMException`

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

`TypeError`

引数 `direction` の値が無効であるとき投げられます。

`DataError` `DOMException`

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

`InvalidStateError` `DOMException`

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

例
-

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

最後に、各レコードを走査し、ラストネームと対応するレコードの主キーを HTML テーブルに挿入します。

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

  const myIndex = objectStore.index("lName");

  myIndex.openKeyCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.innerHTML =
        `<td>${cursor.key}</td>` + `<td>${cursor.primaryKey}</td>`;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("全ラストネームを表示しました。");
    }
  };
}
```

仕様書
---

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

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

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

関連情報
----

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


IDBIndex: unique プロパティ - Web API

IDBIndex: unique プロパティ
======================

読み取り専用プロパティ **`unique`** は、このインデックスが重複するキーを許すかを表す論理値を返します。

これは、インデックスの生成時、`IDBObjectStore.createIndex` メソッドにより決定されます。このメソッドは省略可能なパラメーター `unique` をとり、これを `true` に設定するとインデックスは重複するエントリーを受け入れられなくなります。

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

値
-

以下の論理値です。

| 値 | 効果 |
| --- | --- |
| `true` | 現在のインデックスはキーの値の重複を許しません。 |
| `false` | 現在のインデックスはキーの値の重複を許します。 |

例
-

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

このインデックスの一意性状態をコンソールに記録します。これは `false` になるはずです。

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

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.unique);

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbindex-unique |

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

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

関連情報
----

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


IDBIndex: name プロパティ - Web API

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

`IDBIndex` インターフェイスの **`name`** プロパティは、このインデックスの名前を表す文字列が入っています。

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

値
-

このインデックスの名前を表す文字列です。

### 例外

インデックスの名前を変更しようとすると発生しうる例外がいくつかあります。

`InvalidStateError` `DOMException`

インデックスか対応するオブジェクトストアが削除済であるとき、または現在のトランザクションがアップグレードトランザクションでないとき投げられます。インデックスの名前の変更はアップグレードトランザクション、すなわちモードが `"versionchange"` であるトランザクションでのみ可能です。

`TransactionInactiveError` `DOMException`

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

`ConstraintError` `DOMException`

指定の `name` を用いるインデックスが既に存在するとき投げられます。

例
-

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

このインデックスの名前をコンソールに記録します。これは `lName` になるはずです。

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

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.name);

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-name① |

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

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

関連情報
----

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


IDBIndex: isAutoLocale プロパティ - Web API

IDBIndex: isAutoLocale プロパティ
============================

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

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

`IDBIndex` インターフェイスの読み取り専用プロパティ **`isAutoLocale`** は、このインデックスの生成時に `locale` の値を `auto` に設定したかを表す論理値を返します。(`IDBObjectStore.createIndex()` の引数 `options` を参照してください)

値
-

論理値です。

例
-

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

`isAutoLocale` の値をコンソールに記録します。

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

  const myIndex = objectStore.index("lName");
  console.log(myIndex.isAutoLocale);

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

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

仕様書
---

現在どの仕様にも含まれていません。

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

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

関連情報
----

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


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

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

`IDBIndex` インターフェイスの **`getKey()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドでこのインデックス内の与えられたキーに対応する主キー、もしくは `key` が `IDBKeyRange` に設定された場合は対応する最初の主キーを検索します。

主キーが見つかった場合は、これを要求オブジェクトの `result` に設定します。`IDBIndex.get` と違ってレコード全体は返さないことに注意してください。

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

構文
--

```js
getKey()
getKey(key)
```

### 引数

`key` 省略可

取得するレコードを特定するキーまたは `IDBKeyRange` です。この値が `null` または省略された場合は、ブラウザーは無限のキー範囲を使用します。

### 返値

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

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

### 例外

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

`TransactionInactiveError` `DOMException`

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

`DataError` `DOMException`

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

`InvalidStateError` `DOMException`

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

例
-

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

そして、`myIndex.getKey('Bungle')` を用いて `lName` が `Bungle` であるレコードの主キーを取得し、`success` コールバックで要求の結果をコンソールに記録します。

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

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

  const myIndex = objectStore.index("lName");
  const getKeyRequest = myIndex.getKey("Bungle");
  getKeyRequest.onsuccess = () => {
    console.log(getKeyRequest.result);
  };

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

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

仕様書
---

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

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

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

関連情報
----

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


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

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

`IDBIndex` インターフェイスの **`getAll()`** メソッドは、インデックス内の全オブジェクトを取得します。

オブジェクトは遅延評価で作られるので、カーソルの `value` プロパティを参照するのに比べてパフォーマンスのコストがかかります。`getAll()` のような機能を用いるには、ブラウザーはすべてのオブジェクトを一度に作らなければなりません。たとえば、単に各キーを参照したい場合は、カーソルを用いるほうが効率的です。しかし、オブジェクトストア内の全オブジェクトの配列を取得しようとしている場合は、`getAll()` を用いるべきです。

構文
--

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

### 引数

`query` 省略可

取得するレコードを特定するキーまたは `IDBKeyRange` です。この値が `null` または省略された場合は、ブラウザーは無限のキー範囲を用います。

`count` 省略可

返すレコードの数です。この値が問い合わせ結果のレコード数を超える場合は、ブラウザーは問い合わせ結果のレコードのみを取得します。この値が `0` 未満や `2^32 - 1` 超の場合は、`TypeError` 例外が投げられます。

### 返値

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

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

### 例外

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

`TransactionInactiveError` `DOMException`

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

`InvalidStateError` `DOMException`

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

引数 `count` が `0` から `2^32 - 1` の範囲 (両端を含む) 外のときは、`TypeError` 例外が投げられます。

例
-

```js
const myIndex = objectStore.index("index");
const getAllRequest = myIndex.getAll();
getAllRequest.onsuccess = () => {
  console.log(getAllRequest.result);
};
```

仕様書
---

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

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

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

関連情報
----

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


IDBIndex: openCursor() メソッド - Web API

IDBIndex: openCursor() メソッド
===========================

`IDBIndex` インターフェイスの **`openCursor()`** メソッドは、`IDBRequest` オブジェクトを返し、別スレッドで、指定のキー範囲を走査するカーソルを生成します。

このメソッドは、指定された方向に基づいて、カーソルの位置を適切なレコードに設定します。

キー範囲が指定されないか `null` の場合は、範囲は全レコードを含みます。

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

構文
--

```js
openCursor()
openCursor(range)
openCursor(range, direction)
```

### 引数

`range` 省略可

カーソルの範囲として使用するキーまたは `IDBKeyRange` です。省略した場合は、このオブジェクトストア内の全レコードを選択するキー範囲になります。

`direction` 省略可

カーソルの方向です。取りうる値は、IDBCursor の定数を参照してください。

### 返値

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

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

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

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

`TransactionInactiveError` `DOMException`

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

`TypeError`

引数 `direction` の値が無効であるとき投げられます。

`DataError` `DOMException`

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

`InvalidStateError` `DOMException`

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

例
-

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

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

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

  const myIndex = objectStore.index("lName");

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

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

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-opencursor② |

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

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

関連情報
----

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


IDBIndex: getAllKeys() メソッド - Web API

IDBIndex: getAllKeys() メソッド
===========================

`IDBIndex` インターフェイスの **`getAllKeys()`** メソッドは、非同期でインデックス内の全オブジェクトの主キーを取得し、要求オブジェクトの `result` に設定します。

構文
--

```js
getAllKeys()
getAllKeys(query)
getAllKeys(query, count)
```

### 引数

`query` 省略可

取得するキーを特定するキーもしくは `IDBKeyRange` です。この値が `null` または省略された場合は、ブラウザーは無限のキー範囲を用います。

`count` 省略可

返すレコードの数です。この値が問い合わせ結果のレコード数を超える場合は、ブラウザーは最初のアイテムのみを取得します。この値が `0` 未満や `2^32 - 1` 超の場合は、`TypeError` 例外が投げられます。

### 返値

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

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

### 例外

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

`TransactionInactiveError` `DOMException`

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

`InvalidStateError` `DOMException`

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

引数 `count` が `0` から `2^32 - 1` の範囲 (両端を含む) 外のときは、`TypeError` 例外が投げられます。

例
-

```js
const myIndex = objectStore.index("index");
const getAllKeysRequest = myIndex.getAllKeys();
getAllKeysRequest.onsuccess = () => {
  console.log(getAllKeysRequest.result);
};
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbindex-getallkeys① |

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

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

関連情報
----

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


MIDIConnectionEvent: port プロパティ - Web API

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

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

`MIDIConnectionEvent` インターフェイスの読み取り専用プロパティ **`port`** は、切断または接続されたポートを返します。

値
-

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

例
-

`Navigator.requestMIDIAccess()` メソッドは、`MIDIAccess` オブジェクトで解決する `Promise` を返します。ポートの状態が変わると、`MIDIConnectionEvent` が `statechange` イベントに渡されます。これにより、ポートの情報をコンソールに出力できます。

```js
navigator.requestMIDIAccess().then((access) => {
  access.onstatechange = (event) => {
    console.log(event.port.name, event.port.manufacturer, event.port.state);
  };
});
```

仕様書
---

| Specification |
| --- |
| Web MIDI API # dom-midiconnectionevent-port |

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

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


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

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

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

**`MIDIConnectionEvent()`** コンストラクターは、新しい `MIDIConnectionEvent` オブジェクトを生成します。イベントは新しいポートが利用可能になった時に生成され、オブジェクトが `statechange` イベントに渡されるので、通常このコンストラクターは使用されません。

構文
--

```js
new MIDIConnectionEvent(type)
new MIDIConnectionEvent(type, midiConnectionEventInit)
```

### 引数

`type`

`"connect"` または `"disconnect"` のいずれかの文字列です。

`midiConnectionEventInit` 省略可

以下のフィールドを含む辞書です。

`port`

接続または切断されたポートを表す `MIDIPort` のインスタンスです。

`bubbles` 省略可

イベントがバブリングするかを表す論理値です。デフォルトは `false` です。

`cancelable` 省略可

イベントがキャンセル可能かを表す論理値です。デフォルトは `false` です。

`composed` 省略可

イベントがシャドールートより外側のリスナーで発火するかを表す論理値です。(詳細は `Event.composed` を参照してください) デフォルトは `false` です。

仕様書
---

| Specification |
| --- |
| Web MIDI API # dom-midiconnectionevent-constructor |

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

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


Screen.left - Web API

Screen.left
===========

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

メイン画面の左端から現在の画面の左端までの距離をピクセル単位で返します。

値
-

数値です。

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

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

関連情報
----

* `screen.top`


Screen.top - Web API

Screen.top
==========

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

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

現在の画面の上端からの距離をピクセル単位で返します。

値
-

数値です。

仕様書
---

仕様書の一部ではありません。

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

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

関連情報
----

* `Screen.left`


Screen.availLeft - Web API

Screen.availLeft
================

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

画面の左端から利用できる最初の有効ピクセルを返します。

値
-

数値です。

例
-

```js
let setX = window.screen.width - window.screen.availLeft;
let setY = window.screen.height - window.screen.availTop;
window.moveTo(setX, setY);
```

メモ
--

ほとんどの場合においてこのプロパティは、 0 を返します。

このプロパティを 2 画面で使用した場合、右側の画面については左側の画面の幅のピクセル数の値（したがって、右側の画面の左端の X 座標を示す）として評価されます。

Windows では、このプロパティはどの画面が主画面として設定されているかによって異なり、主画面に対して左端の利用可能なピクセルのX座標を返します。つまり、主画面の左端は、左端の画面でなくても常に X 座標が 0 になります。副画面が主画面の左側にある場合は、補正するために負の X 座標になります。

[1] [2] - 左の画面では *availLeft* は **0** を返し、右の画面では左の画面の **width** を返す

[2] [1] - 左の画面では *availLeft* は右画面の **-width** を返し、右の画面では **0** を返す

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

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


Screen.availTop - Web API

Screen.availTop
===============

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

固定あるいは半固定されているユーザーインターフェイス部分を含まない、最初のピクセルの Y 座標を示します。

値
-

数値です。

例
-

```js
let setX = window.screen.width - window.screen.availLeft;
let setY = window.screen.height - window.screen.availTop;
window.moveTo(setX, setY);
```

メモ
--

ほとんどの場合において、このプロパティは、 `0` を返します。

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

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


CookieStore: set() メソッド - Web API

CookieStore: set() メソッド
=======================

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

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

**`set()`** は `CookieStore` インターフェイスのメソッドで、渡された名前またはオプションオブジェクトに一致する Cookie のリストを返します。

構文
--

```js
set(name, value)
set(options)
```

### 引数

このメソッドは、以下のいずれかが必要です。

`name`

Cookie の名前の文字列です。

`value`

Cookie の値の文字列です。

または

`options`

オブジェクトは次のものを含みます。

`domain` 省略可

Cookie のドメインが入った文字列です。

`expires` 省略可

ミリ秒単位の Unix 時間によるタイムスタンプで、Cookie の有効期限が入ります。

`name`

Cookie の名前が入った文字列です。

`partitioned` 省略可

論理値で、既定値は `false` です。`true` に設定すると、設定された Cookie はパーティション化された Cookie になります。詳しくは Cookies Having Independent Partitioned State (CHIPS) (en-US) を参照してください。

`path` 省略可

Cookie のパスの入った文字列です。

`sameSite` 省略可

以下の `SameSite` のいずれかの値です。

`"strict"`

Cookie は、ファーストパーティのコンテキストでのみ送信され、サードパーティのウェブサイトによるリクエストと一緒に送信されることはありません

`"lax"`

Cookie は、通常のクロスサイトサブクエスト（例えば、画像やフレームをサードパーティのサイトにロードするため）には送信されません。しかし、ユーザーが元のサイト内を移動しているとき（すなわち、リンクをたどっているとき）には送信されます。

`"none"`

Cookie は、すべてのコンテキストで送信されます。

`value`

Cookie の値が入った文字列です。

### 返値

Cookie の設定が完了すると `Undefined` に解決される `Promise` です。

### 例外

`TypeError`

与えられた値での Cookie の設定に失敗した場合に発生します。

`SecurityError` の `DOMException`

オリジンが URL に serialize (en-US) されない場合に発生します。

例
-

次の例では `name`、`value`、`expires`、`domain` を持つオブジェクトを渡して Cookie を設定します。

```js
const day = 24 \* 60 \* 60 \* 1000;
cookieStore.set({
  name: "cookie1",
  value: "cookie1-value",
  expires: Date.now() + day,
  domain: "example.com",
});
```

仕様書
---

| Specification |
| --- |
| Cookie Store API # dom-cookiestore-set |

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

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


CookieStore: delete() メソッド - Web API

CookieStore: delete() メソッド
==========================

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

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

**`delete()`** は `CookieStore` インターフェイスのメソッドで、与えられた名前またはオプションオブジェクトを持つ Cookie を削除します（下記参照）。`delete()` メソッドは日付を過去のものに変更することで Cookie を失効させます。

構文
--

```js
delete(name)
delete(options)
```

### 引数

このメソッドは、以下のいずれかが必要です。

`name`

Cookie の名前が入っている文字列です。

または

`options`

オブジェクトは以下のプロパティを含みます。

`name`

Cookie の名前が入っている文字列です。

`partitioned` 省略可

論理値で、既定値は `false` です。`true` に設定すると、削除するクッキーがパーティション化 Cookie であることを表します。詳しくは Cookies Having Independent Partitioned State (CHIPS) (en-US) を参照してください。

`path`省略可

パスを含む文字列です。

`url`省略可

Cookie の URL が入っている文字列です。

**メモ:** `url` オプションは、特定の URL をスコープとした Cookie の変更を可能にします。サービスワーカーは、自分のスコープ下にある任意の URL に送信される Cookie を取得できます。ドキュメントからは現在の URL の Cookie しか取得できないので、ドキュメントコンテキストで有効な URL はドキュメントの URL のみとなります。

### 返値

削除が完了すると `undefined` に解決される `Promise` です。

### 例外

`TypeError`

与えられた `name` や `options` で表される Cookie の削除に失敗した場合に発生します。

例
-

この例では、`delete()` メソッドに名前を渡すことで、Cookie を削除しています。

```js
let result = cookieStore.delete("cookie1");
console.log(result);
```

仕様書
---

| Specification |
| --- |
| Cookie Store API # dom-cookiestore-delete |

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

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


CookieStore: change イベント - Web API

CookieStore: change イベント
========================

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

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

`change` イベントは、任意の Cookie に変更が加えられると、`CookieStore` オブジェクトで発生します。

構文
--

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

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

cookieStore.onchange = (event) => { }
```

例
-

次のように `cookieStore` インスタンスに対して `addEventListener()` を使ってハンドラーを追加すると、Cookie が変更されたときに通知を受けることができます。

```js
cookieStore.addEventListener("change", (event) => {
  console.log("1 change event");
});
```

あるいは、`CookieStore.onchange` イベントハンドラープロパティを使用して、`change` イベントのハンドラーを確立することができます。

```js
cookieStore.onchange = (event) => {
  console.log("1 change event");
};
```

仕様書
---

| Specification |
| --- |
| Cookie Store API # intro-monitor |
| Cookie Store API # dom-cookiestore-onchange |

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

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


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

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

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

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

**`getAll()`** は `CookieStore` インターフェイスのメソッドで、渡された名前またはオプションに一致する Cookie のリストを返します。何も引数を渡さなければ、現在のコンテキストのすべての Cookie を返します。

構文
--

```js
getAll(name)
getAll(options)
```

### 引数

`name` 省略可

Cookie の名前が入っている文字列です。

または

`options` 省略可

以下のプロパティを持つ文字列です。

`name`

Cookie の名前が入っている文字列です。

`url`

Cookie の URL が入っている文字列です。

**メモ:** `url` オプションは、特定の URL をスコープとした Cookie の変更を可能にします。サービスワーカーは、自分のスコープ下にある任意の URL に送信される Cookie を取得できます。文書からは現在の URL の Cookie しか取得できないので、文書コンテキストで有効な URL は文書の URL のみとなります。

### 返値

指定された名前またはオプションに一致するクッキーを表すオブジェクトの配列で解決する `Promise` です。

各オブジェクトは、以下のプロパティを持ちます。

`domain`

クッキーのドメインを持つ文字列です。

`expires`

クッキーの期限が入ったタイムスタンプで、ミリ秒単位の Unix 時刻です。

`name`

クッキーの名前が入った文字列です。

`partitioned`

論理値で、クッキーがパーティション化クッキーであるか (`true`) そうでないか (`false`) を表します。詳しくは Cookies Having Independent Partitioned State (CHIPS) (en-US) を参照してください。

`path`

クッキーのパスが入った文字列です。

`sameSite`

以下の `SameSite` 値のうちの何れかです。

`"strict"`

クッキーはファーストパーティのコンテキストにのみ送られ、サードパーティのウェブサイトに対するリクエストには送られません。

`"lax"`

クッキーは、通常のサイト間サブリクエスト（例えば、サードパーティーのサイトに画像やフレームを読み込むためのもの）には送信されませんが、ユーザーがオリジン間サイト内を移動しているとき（リンクを追跡するとき）には送信されます。

`"none"`

クッキーはすべてのコンテキストで、送信されます。

`secure`

論理値で、このクッキーが安全なコンテキストでのみ使用されるか (`true`) またはそうではないか (`false`) を示します。

`value`

このクッキーの値が入った文字列です。

### 例外

`TypeError`

与えられた `name` や `options` で表される Cookie の取得に失敗した場合にスローされます。

例
-

この例では、引数なしで `getAll()` を使用しています。このコンテキストのすべての Cookie をオブジェクトの配列として返します。

```js
let cookies = await cookieStore.getAll();
if (cookies) {
  console.log(cookies);
} else {
  console.log("Cookie not found");
}
```

仕様書
---

| Specification |
| --- |
| Cookie Store API # dom-cookiestore-getall |

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

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


CookieStore: get() メソッド - Web API

CookieStore: get() メソッド
=======================

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

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

**`get()`** は `CookieStore` インターフェイスのメソッドは、与えられた名前またはオプションオブジェクトを持つ 1 つの Cookie を返します（下記参照）。このメソッドは渡された引数に最初に一致する Cookie を返します。

構文
--

```js
get(name)
get(options)
```

### 引数

このメソッドは、以下のいずれかが必要です。

`name`

Cookie の名前が入っている文字列です。

または

`options`

オブジェクトは以下のプロパティを含みます。

`name`

Cookie の名前が入っている文字列です。

`url`

Cookie の URL が入っている文字列です。

**メモ:** `url` オプションは、特定の URL をスコープとした Cookie の変更を可能にします。サービスワーカーは、自分のスコープ下にある任意の URL に送信される Cookie を取得できます。文書からは現在の URL の Cookie しか取得できないので、文書コンテキストで有効な URL は文書の URL のみとなります。

### 返値

与えられた名前またはオプションに一致する最初の Cookie を含むオブジェクトに解決される `Promise` です。このオブジェクトは以下のプロパティを含んでいます。

`domain`

Cookie のドメインを含む文字列です。

`expires`

Cookie の期限が入ったタイムスタンプで、ミリ秒単位の Unix 時刻です。

`name`

Cookie の名前を含む文字列です。

`partitioned`

論理値で、Cookie がパーティション化 Cookie であるか (`true`) そうでないか (`false`) を表します。詳しくは Cookies Having Independent Partitioned State (CHIPS) (en-US) を参照してください。

`path`

Cookie のパスを含む文字列です。

`sameSite`

以下の `SameSite` 値のうちの何れかです。

`"strict"`

Cookie はファーストパーティのコンテキストにのみ送られ、サードパーティのウェブサイトに対するリクエストには送られません。

`"lax"`

Cookie は、通常のサイト間サブリクエスト（例えば、サードパーティーのサイトに画像やフレームを読み込むためのもの）には送信されませんが、ユーザーがオリジン間サイト内を移動しているとき（リンクを追跡するとき）には送信されます。

`"none"`

Cookie はすべてのコンテキストで、送信されます。

`secure`

論理値で、この Cookie が安全なコンテキストでのみ使用されるか (`true`) またはそうではないか (`false`) を示します。

`value`

この Cookie の値が入った文字列です。

### 例外

`TypeError`

与えられた `name` や `options` で表される Cookie の取得に失敗した場合に発生します。

例
-

この例では、"cookie1" という名前の Cookie を返します。もし Cookie が見つかれば、プロミスの結果は 1 つの Cookie の詳細を含むオブジェクトになります。

```js
let cookie = cookieStore.get("cookie1");
if (cookie) {
  console.log(cookie);
} else {
  console.log("Cookie not found");
}
```

仕様書
---

| Specification |
| --- |
| Cookie Store API # dom-cookiestore-get |

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

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


WebVR の概要 - Web API

WebVR の概要
=========

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

**メモ:** WebVR API は WebXR API に置き換えられました。 WebVR は標準として批准されることはなく、ごく少数のブラウザーでしか既定で実装・有効化されず、少数の端末しか対応していませんでした。

この文書は、バーチャルリアリティ (VR) の背景にある概念と理論について述べています。もしあなたがこの分野の初学者なら、コードを書き始める前に、これらのトピックを理解すると役に立つでしょう。

VR の歴史
------

VR は全く新しいというわけではありません —その概念は 2012 年の Oculus Rift Kickstartar キャンペーンよりずっと前にさかのぼります。人々は数十年の間その実験を続けてきました。

1939 年 View-Master device が作られ、3D ピクチャを見ることができるようになりました。そのデバイスは、ステレオ立体視の小さなカラー写真のペアを持つ厚紙のディスクに記録された画像を表示していました。数年の開発ののち、軍はそのテクノロジーの使用に興味を、持ち、そして Headsight プロジェクトが 1961 年に生まれました — これはビデオスクリーンとヘッドトラッキングシステムを合体させたヘルメットに影響を与えました。

その後の数十年、さまざまな実験がなされましたが、もはや科学ラボや戦場に限定されませんでした。最終的に、映画監督がバーチャルリアリティのビジョンを示すポップカルチャーに引き継がれました。Tron (1982) や The Matrix (1999) のような映画が制作され、そこではまったく新しいサイバー世界へ転送されたり、サイバー世界と知ることなくとらわれてそれを現実世界として受け入れる世界が描かれました。

最初の VR ゲームの試みは大きく高価なものでした — 1991 年、 Virtuality Group はゴーグルを持つ VR レディなアーケードマシンを作成し、パックマンのような人気のタイトルを VR へ移植しました。セガは VR グラスを 1993 年の CES(Consumer Electronics Show )で発表しました。企業は実験をしていましたが、市場や消費者を納得させられませんでした — 実際に成功した VR プロジェクトの事例を見るには 2012 年まで待つ必要がありました。

### 最近の VR

では何が新しいのでしょう？ 十分なユーザ体験を提供するには、VR ハードウェアは高精度、低レイテンシでデータを届ける必要があります; VR アプリケーションを動かすコンピュータはこれらすべての情報を扱うため、十分強力でなければなりません。そのような精度とパワーがあったとしても、手頃な価格で利用できるようになったのは最近のことです。早期の VR プロトタイプは何万ドルもコストがかかりましたが、HTC VIVE や Oculus Rift のような近年の HMD は数百ドルで利用でき、さらに Gear VR や Google Cardboard のようなモバイルベースのソリューションみたいに、もっと安価なソリューションもあります。

ソフトウェアの面では、Valve は、VIVE や他のソリューションで互換性のある SteamVR を作成し、利用しやすい VR UI のようなソフトウェアへのアクセスを提供しています。

テクノロジー自体はすでにあるので、将来的には、より高価なヘッドセットが時間をかけて安価になっていき、多くの人々が VR 体験できるようになります。

### 入力機器

VR アプリケーションの入力を扱うことは興味深いトピックです — それは専用のユーザインターフェイスがデザインされなければならないのでまったく新しい体験となります。現時点でも古典的なキーボードとマウスから、Leap Motion や VIVE コントローラのような新しいものまで様々なアプローチがあります。これは特定の状況でどのように動作するかそしてあなたのゲームタイプにはどのような入力が最適なのかを確認する試行錯誤の事柄です。

VR ハードウェアのセットアップ
----------------

主に、モバイルタイプとコンピュータ接続タイプの 2 種類のセットアップがあります。最小のハードウェアセットアップは次のようなものです:

* モバイル: Google Cardboard のように VR マウントにスマートフォン — スマートフォンは VR ディスプレイとして機能する — をマウントして作られるヘッドマウントディスプレイ (HMD) で、モバイルスクリーンをステレオビジョンへ投影するのに必要なレンズが含まれています。
 ![Mobile based VR setup](/ja/docs/Web/API/WebVR_API/Concepts/mobilebasedvrsetup.png)
* コンピュータ接続: コンピュータに接続する VR セットアップです — 右目と左目の両方に表示される映像を映す高解像度の横向きスクリーンを持つ HMD で構成されています。HMD は右目と左目のシーン（ステレオビジョン）を分割するためのレンズも備えています。セットアップは分離型の位置センサも含まれています。位置センサは頭の位置/向き/速度/加速度を取得して、コンピュータへ絶えずその情報を渡します。
 ![Computer based VR Setup](/ja/docs/Web/API/WebVR_API/Concepts/computerbasedvrsetup.png)

**メモ:** コンピュータ接続システムは位置センサーを含んでいない場合もありますが、通常は含まれています。

その他の VR 体験を補うハードウェア:

* **手認識センサー**: 手の位置と動きをトラッキングするセンサーで、あなたの手を興味深いコントローラや VR ゲーム世界内のオブジェクトにすることができます。もっとも先進的なものは Leap Motion で、（Oculus Rift と接続した）コンピュータ上で動作し、（実験的な段階ですが）モバイルデバイスと接続して使うことも可能です。
* **ゲームパッド**: XBox コントローラおよびその類似コントローラをブラウザ内でキーボードとして動作するように設定できます。これは VR ウェブページとのインタラクションの可能性を広げます。モバイル環境で使えるゲームパッドも存在しますが、それらは Bluetooth 接続であるため、WebVR では動作しません。
* **アイトラッキングセンサー（実験的）**: FOVE プロジェクトは、眼球のかすかな動きを読み取る最初のヘッドセットです。
* **顔の表情追跡（実験的）**: 南カリフォルニア大学や Facebook の Oculus 部門の研究者は、表情をトラッキングして、バーチャルキャラクターの表情へ適用する新しい方法をテストしています。
* **もっと複雑な位置センサシステム**: 1 つの例といて、HTC VIVE は空間の対角上に配置した 2 つの位置センサを備えており、マッピングをしているので、最大 5m x 5m までの空間で VR 体験を楽しむことができます。
位置、向き、速度、加速度
------------

前述のように、位置センサは HMD に関する情報を検出して常にそれを出力しているので、頭の動きや回転などに追従してシーンを連続的に更新することができます。しかしその情報とは正確には何でしょうか？

![Position and Orientation VR setup](/ja/docs/Web/API/WebVR_API/Concepts/positionorientationvr.png)

出力情報は、4 つのカテゴリに分類できます。

1. 位置 — 3D 空間の 3 つの座標軸に沿った HMD の位置です。位置センサから見て、x は左右、y は上下、z は前後となります。WebVR では、x, y, z 座標は `VRPose.position` 内の配列として表現されます。
2. 向き — 3D 空間の 3 つの座標軸周りの HMD の回転です。ピッチは x 軸周り、ヨーは y 軸周り、ロールは z 軸周りの回転を意味します。WebVR では ピッチ、ヨー、ロールは
 `VRPose.orientation` 内の配列の最初の 3 要素で表されます。
3. 速度 — VR で考慮する速度は 2 種類あります:
    * 速度（線速度） — 任意の 1 つの軸に沿った HMD の移動速度です。この情報は `VRPose.linearVelocity` を用いて取得できます。
    * 角速度 — 任意の 1 つの軸周りの HMD の回転速度です。この情報は `VRPose.angularVelocity` を用いて取得できます。
4. 加速度 — VR で考慮する加速度は 2 種類あります:
    * 加速度（線加速度） — 任意の 1 つの軸に沿った HMD の移動の加速度です。この情報には `VRPose.linearAcceleration` を用いてアクセスできます。
    * 角加速度 — 任意の 1 つの軸周りの HMD の回転加速度です。この情報には `VRPose.angularAcceleration` を用いてアクセスできます。
視界
--

視界 (FOV; field of view) は、ユーザの各目で見られる（と期待されている）範囲です。その形状は、おおよそピラミッド型になっていて、（前後の）側面はユーザの頭の内部を頂点として、残りはユーザの目の位置から広がっています（訳注； 原文では eminate と書かれていますが、emanate の誤字と判断しました）。 それぞれの目は固有の FOV を持っていて、もう一方にわずかに重なっています。

![FOV related properties](/ja/docs/Web/API/WebVR_API/Concepts/fovrelatedproperties.png)

FOV は次の値で定義されています:

* `VRFieldOfView.upDegrees`: FOV の上方へ広げる角度値です。
* `VRFieldOfView.rightDegrees`: FOV の右側へ広げる角度値です。
* `VRFieldOfView.downDegrees`: FOV を下方へ広げる角度値です。
* `VRFieldOfView.leftDegrees`: FOV を左側へ広げる角度値です。
* zNear `VRDisplay.depthNear`: ユーザの頭の中央から FOV の可視範囲開始まで距離。
* zFar `VRDisplay.depthFar`: ユーザの頭の中央から FOV の可視範囲末端までの距離。

**メモ:** The user can potentially see all the way around them, which is a brand new concept for apps and games. Try to give people a reason to look around and see what's behind them — make them reach out and find things that are not visible at the very beginning. Describe what's behind their backs.

これらのプロパティのデフォルト値は、VR ハードウェアによって微妙に異なりますが、上下方向は 53°、左右方向は 47°、zNear と zFar はそれぞれ 0.1m から 10000m くらいになっています。

**メモ:** ユーザは潜在的に周囲全体を見渡すことができます。それはまったく新しいアプリやゲームのコンセプトです。人々が見回したり背後にある何かを見たりする理由を与えることにトライしてみましょう — 最初は見えていないものを見つける手助けをしてあげてください。背後になにがあるか説明しましょう。

VR アプリのための概念
------------

このセクションでは、通常のモバイルやデスクトップを開発するときにはほとんど考慮する必要がないけれど、VR アプリを開発するときに知っておきたい概念について説明します。

### 立体視

立体視は、人間や（おそらく）動物が持つ通常のビジョンで、（両目のそれぞれから見える）僅かに異なる 2 つの画像を 1 つの画像として知覚するものです。結果として奥行きを認識でき、見事な 3D の世界を見る手助けをしています。VR アプリでこれを再現するには、ユーザが HMD を使っている時に左右の目のそれぞれに与える、本当にわずかに異なるビューを横に並べた画像をレンダリングする必要があります。

![How to create stereoscopic 3D images](/ja/docs/Web/API/WebVR_API/Concepts/createstereoscopicimages.png)

### ヘッドトラッキング Head tracking

 360° シーンの臨場感をつくりだす主要なテクノロジは、HMD に搭載されているジャイロスコープや加速度センサ、磁気センサ（コンパス）によって実現されています。
 それによって目が球面上のスクリーンの前にいると信じることができるので、アプリのキャンバス内に現実的な没入感を与えることができます。

### 眼精疲労

HMD のメジャーな障害として VR でよく使われる用語です。私たちはアプリキャンバス内で見せ続けることで常に目を欺いていますが、通常よりも眼を酷使することになるため、VR アプリを長時間利用し続けると眼精疲労を招きます。

望ましくない影響を最小化するするために、つぎのようなことが必要です。

* 異なる深さへの焦点合わせを避ける（例: たくさんのパーティクルを異なる深度（奥行き）に使うのを避ける）。
* eye convergion を避ける（例: もしカメラに向かってくる物体があると、目はそれを追って 1 点に集中してしまいます）
* できるだけ落ち着いた色の暗い背景を使う; 明るいスクリーンは目の疲れが増えます。
* 明度の激しい変化を避ける。
* 大量のテキストを読ませることを避ける。目（カメラ）の位置と読ませたいテキストとの距離にも注意しなければいけません。0.5m は近すぎて不快で、2m 以上だと立体効果が感じられないので、その間に配置することをお勧めします。
* 一般に、物体とカメラと距離には注意してください、Oculus は、フォーカスの最小距離として 0.75m を推奨しています。
* シーン内のオブジェクトとのインタラクションが必要なときは、ポインタを使います。これは少ない労力で正しく物体を指定するのに役立つでしょう。

一般に、ビジュアルエフェクトが少ないほど、ユーザに与える疲れは軽減されます。

### モーション酔い

開発者が細心の注意を払っていないと、VR アプリはユーザの気分の悪化を実際に引き起こします。これは、目から受け取る刺激と、体が受け取る（と期待するもの）が違う場合に発生します。

ユーザのモーション酔いの発生を避けるために（あるいは最小化するために）、次のことが必要です:

* 常にヘッドトラッキングを維持する（これは最も重要です、特に体験の最中で発生する場合）。
* 一定の速度を使う; 加速や減速するようなカメラの動きを避ける（線形の加速度を使い、できるだけ easing を避ける）。
* 高フレームレートを維持する（30fps 以下は不快です）。
* 急激な、あるいは予期できないカメラの回転を避ける。
* 固定オブジェクト用の固定点を追加する（そうしなければ、ユーザはそれらが移動していると感じてしまいます）
* どこに焦点を合わせていいか分からなくなるので、DoF (Depth of Feild; 被写界深度)やモーションブラーのポスト処理を使用しない。
* 明るさの変化を避ける（スムースに照明を変化させるため、低周波のテクスチャやフォグエフェクトを使います）。

全体的に、体に反射的な行動を引き起こすような信号を目が脳に送るべきではありません。

### 遅延

遅延は、物理的な頭の動きと、HMD スクリーンが更新されて表示が目に届くまでの間にかかる時間のことです。これは現実感の体験を提供する上で最も重要な要素のひとつです。人間は非常に小さな遅延を検出することができ、知覚させないためには遅延を 20 ミリ秒以下を維持する必要があります（例えば 60Hz のモニタは 16 ミリ秒で応答します）。

Oculus Rift ヘッドセットの遅延は 20 ミリ秒以下ですが、モバイル・デバイスベースの環境ではスマートフォンの CPU パワーやその他の性能に大きく依存します。

### フレームレート (Frames per second / FPS)

Wikipedia の定義に基づくと、フレームレートは、連続した別々の画像（フレームと呼ぶ）をイメージングデバイスが生成する周波数のことです。60fps は、スムースなユーザ体験のために許容できるフレームレートですが、アプリが動作しているマシン性能や見せたいコンテンツの複雑さによっては、急激に低下する可能性があります。30fps 未満では、一般にジッタがあると考えられていて、ユーザーをいらだたせます。

最も困難なタスクの 1 つは、一定の高フレームレートを維持することで、それを実現するために、可能なかぎり効率的に動作するようにコードを最適化しなければなりません。一定のフレームレートを保てなかったり急激にフレームレートが変化するようなことが無いよう、適切なフレームレートにすることが好ましいです； このために、シーンに配置するオブジェクトを必要最小限にしたり、(WebGL の場合では)ドローコールを削減することが必要となります。

### 瞳孔間距離 (IPD)

Wikipedia の定義に基づくと、IPD は両目の瞳孔の中心間の距離です。IPD は両眼目視装置の設計においてクリティカルで、両目の瞳孔とも目視装置の射出ひとみ (exit pupils) に位置合わせする必要があります。

WebVR においては、IPD は `VREyeParameters.offset` を使って算出でき、これは IPD のちょうど半分の値になっています。

この値は HMD によって返され、60mm から 70mm くらいでしょう； Oculus Rift のようないくつかの HMD では、ユーザ固有の IPD をセット可能です。通常この値は変化しませんが、シーン全体のスケールを変更するためにそれを実施するかもしれません。例えば、IPD が 6000mm にセットされていると、小人の世界を見る巨人のように、ユーザーはシーンを見るでしょう。

### 自由度 (DoF)

DoF は空間内の剛体の動きを示します。この用語の値を作る決まった方法はありません — 3DoF という記述は、ヘッドトラッキングで回転のみを検出するセンサの文脈で発見でき、6DoF という記述を、位置と回転を同時に制御できる入力について書かれている文脈で見つけることができます。ジャイロセンサ、加速度センサ、コンパスのような 3 つのセンサを持つハードウェアで、9DoF という記述がされていることがありますが、3 x 3 DoF の結果として得られるものは、実際には 6 自由度のトラッキングとなります。

DoF は ユーザの頭の動きのトラッキングに直接関係します。

### フォーカスコーン

私たちの実際の FOV は非常に広いですが（約 180°）、シンボルを感じ取れる範囲（中心 60°）やテキストを読める範囲（中心 10°）は小さな部分だけだと知っておく必要があります。視線追跡センサを備えていない場合、ユーザの目がフォーカスしている場所をスクリーンの中心であると仮定します。

アプリキャンバス上のどこに映像要素を配置するかを決定する際に、この制限を考慮することが重要となります。フォーカスコーンの端っこが遠すぎる場合は、非常に急速な眼精疲労につながります。MozVR.com に、これに関する興味深い記事が（他のものに混ざってですが）あります — Quick VR Mockups with Illustrator を参照してください。

### 立体音響

立体音響は、3 次元空間内でどのように音が聞こえるかをシミュレーションするための音響操作エフェクトです。

これはウェブオーディオ API と直接関係していて、キャンバス内にあるオブジェクト上にサウンドを配置したり、ユーザの移動方向や見ているシーンの部分に応じてオーティオを再生することが可能です。


WebVR での VR ゲームパッドの使用 - Web API

WebVR での VR ゲームパッドの使用
=====================

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

多くの WebVR ハードウェアは、ヘッドセットとゲームパッドがセットになっています。WebVR アプリにおいては、ヘッドセットとゲームパッドはゲームパッド APIを通じて接続されます。中でも、ゲームパッド拡張 API は、ゲームパッドの状態(controller pose (en-US))、触覚アクチュエータ(haptic actuators)などの情報を取得します。この記事では、その基礎となる部分を解説します。

**メモ:** WebVR API は WebXR API に置き換えられました。 WebVR は標準として批准されることはなく、ごく少数のブラウザーでしか既定で実装・有効化されず、少数の端末しか対応していませんでした。

WebVR API
---------

WebVR API は初期段階ではあるが、開発者がウェブベースのバーチャルリアリティー経験を生み出すことのできるとても興味深いウェブの新しい機能です。コンピュータとつながっている VR ヘッドセット（VR ディスプレイ）へのアクセスを与えることで、ディスプレイをスタートしたり、ストップする操作ができます。動きのデータ（例：方向や位置）へアクセスして得られたデータは、各アニメーションループのフレームごとにディスプレイをアップデートするためなどに使用されます。

この記事を読む前提として、Web VR API の基礎についてすでに知っていることを想定しています。 — もしまだ WebVR API の使用にを読んでいない場合には、まずはそちらを読んでみましょう。その記事の中では、ブラウザ側がハードウェアの設定をサポートしたり、設定を要求したりすることについて詳しく説明しています。

ゲームパッド API
----------

ゲームパッド API はよくサポートされた API であり、 これを使用することで PC につながっているゲームパッドやゲームパッドに開発者がアクセスすることができるようになります。また、ウェブアプリケーションをゲームパッドやゲームパッドを通じて操作することもできるようになります。基本としてゲームパッド API は、ゲームパッドオブジェクトとしてつながっているゲームパッドに対してアクセスの許可を与えます。そしてどのボタンが押されているか、軸がどの方向に向いているかなどの情報を取得するよう要求します。

ゲームパッド API の基本的な使い方については、ゲームパッド API の使用やゲームパッド API を使用した制御の実装の中で詳しく知ることができます。

しかしながら、この記事では主に、位置、方向、触覚アクチュエーター（バイブレーション）などの高度なゲームパッド情報へのアクセスのような、ゲームパッド拡張 API で与えられたいくつかの新しい特徴に注目します。この API はとても新しく、Firefox 55+ Beta や Firefox Nightly のブラウザでのみデフォルトで WebVR API がサポートされています。

ゲームパッドの種類
---------

VR ハードウェアに付随するゲームパッドには、２つの種類があります。

* ６軸に対して自由度を持つゲームパッドは位置と方向のデータを取得することができる。具体的には、ゲームパッドが VR シーンや動きや回転のある物体を操作することができる。例えば、HTC VIVE のゲームパッドがそれにあたる。
* ３軸に対して自由度を持つゲームパッドは、位置データは取得できないが方向のデータを取得することができる。例えば Google Daydream のゲームパッドである。具体的には、3D 空間で異なる物体をレーザーポインターのように指し示すことはできるが、3D 空間を動き回ることはできない。
ゲームパッドへのアクセス方法
--------------

ここではいくつかのコードを紹介します。まず、Gamepad API を使用して VR ゲームパッドへの基本的なアクセス方法を見ていきましょう。いくつかのおかしなニュアンスを心に留めておきましょう、それは後から調べる価値があるものです。

シンプルな例を紹介します。-vr-controller-basic-info のソースコード (see it running live here also) を御覧ください。この例は VR ディスプレイやコンピューターと接続したゲームゲームパッドへ情報を出力するシンプルなものです。

### ディスプレイの情報を取得

最初のコードです。

```js
let initialRun = true;

if (navigator.getVRDisplays && navigator.getGamepads) {
  info.textContent = "WebVR API and Gamepad API supported.";
  reportDisplays();
} else {
  info.textContent =
    "WebVR API and/or Gamepad API not supported by this browser.";
}
```

ここでは、`initialRun`　というトラッキングの変数を使います。これは、「このページを初めてロードした」ことを示します。この点については、あとで詳しく述べます。次に、`Navigator.getVRDisplays()` と `Navigator.getGamepads()`メソッドがあるかないかをチェックして、WebVR と Gamepad APIs がサポートされているかどうかを検知します。もし、サポートされていれば、検知するプロセスを OFF にするために、カスタム機能である `reportDisplays()` を実行します。 `reportDisplays()` は、以下のような構成になっています。

```js
function reportDisplays() {
  navigator.getVRDisplays().then((displays) => {
    console.log(`${displays.length} displays`);
    displays.forEach((display, i) => {
      const cap = display.capabilities;
      // cap is a VRDisplayCapabilities object
      const listItem = document.createElement("li");
      listItem.innerHTML =
        `<strong>Display ${i + 1}</strong><br>` +
        `VR Display ID: ${display.displayId}<br>` +
        `VR Display Name: ${display.displayName}<br>` +
        `Display can present content: ${cap.canPresent}<br>` +
        `Display is separate from the computer's main display: ${cap.hasExternalDisplay}<br>` +
        `Display can return position info: ${cap.hasPosition}<br>` +
        `Display can return orientation info: ${cap.hasOrientation}<br>` +
        `Display max layers: ${cap.maxLayers}`;
      list.appendChild(listItem);
    });

    setTimeout(reportGamepads, 1000);
    // For VR, controllers will only be active after their corresponding headset is active
  });
}
```

この関数は最初にプロミスベースの `Navigator.getVRDisplays()` メソッドを使用し、接続されたディスプレイを表す `VRDisplay` オブジェクトを含む配列を使用して解決します。次に、各ディスプレイの `VRDisplay.displayId` と `VRDisplay.displayName` 値、およびそのディスプレイに関連付けられた `VRCapabilities` オブジェクトに格納されている多くの有用な値が表示されます。これらのうち最も有益なのは `hasOrientation` と `hasPosition` で、これにより機器が向きと位置のデータを返すことができるかどうかを検出し、それに応じてアプリを設定することができます。

この関数に含まれる最後の行は `setTimeout()` 呼び出しで、 1 秒後に `reportGamepads()` 関数を実行します。なぜこのようなことが必要なのでしょうか？まず第一に、 VR コントローラーは関連する VR ヘッドセットがアクティブになって初めて準備が整います。そのため、`getVRDisplays()`が呼び出されてディスプレイ情報を返した後に、この関数を呼び出す必要があります。 2 つ目として、ゲームパッド API は WebVR API よりもずっと古く、プロミスベースではありません。後ほど説明しますが、`getGamepads()` メソッドは同期型で、`Gamepad` オブジェクトをすぐに返すだけです - コントローラーが情報を報告する準備ができるまで待つことはありません。少し待たないと、返された情報は正確ではないかもしれません（少なくとも、我々のテストではそうでした）。

### ゲームゲームパッドの情報を取得

`reportGamepads()` 関数は、このような構成になっています。

```js
function reportGamepads() {
  const gamepads = navigator.getGamepads();
  console.log(`${gamepads.length} controllers`);
  for (const gp of gamepads) {
    const listItem = document.createElement("li");
    listItem.classList = "gamepad";
    listItem.innerHTML =
      `<strong>Gamepad ${gp.index}</strong> (${gp.id})<br>` +
      `Associated with VR Display ID: ${gp.displayId}<br>` +
      `Gamepad associated with which hand: ${gp.hand}<br>` +
      `Available haptic actuators: ${gp.hapticActuators.length}<br>` +
      `Gamepad can return position info: ${gp.pose.hasPosition}<br>` +
      `Gamepad can return orientation info: ${gp.pose.hasOrientation}`;
    list.appendChild(listItem);
  }
  initialRun = false;
}
```

これは `reportDisplays()` と同じように動作します。プロミスでない `getGamepads()` メソッドを使用して `Gamepad` オブジェクトの配列を取得し、それぞれのオブジェクトを循環して情報を表示しています。

* `Gamepad.displayId` プロパティは、コントローラーが関連付けられているヘッドセットの `displayId` と同じなので、コントローラーとヘッドセットの情報を結び付けて使用するのに有益な情報です。
* `Gamepad.index` プロパティは、接続された各コントローラーを識別するための固有の数値インデックスです。
* `Gamepad.hand`は、コントローラーがどちらの手で握られることを想定しているかを返すプロパティです。
* `Gamepad.hapticActuators` は、コントローラーで利用できるハプティックアクチュエータの配列を返します。ここでは、それぞれが利用できる数を確認するために、その長さを返しています。
* 最後に、コントローラーが位置と方向のデータを返すことができるかどうかを示すために、`GamepadPose.hasPosition` (en-US) と `GamepadPose.hasOrientation` を返すようにしています。これはディスプレイの場合と同じように動作しますが、ゲームパッドの場合、これらの値は capabilities オブジェクトではなく pose オブジェクトで利用できます。

コントローラー情報を含むリスト項目には、それぞれ `gamepad` というクラス名を付けていることに注意してください。これが何のためにあるのかは、後で説明します。

最後に、`initialRun` 変数を `false` に設定します。これで初期実行は終わりです。

### ゲームパッドのイベント

この章の仕上げとして、ゲームパッドに関連するイベントを見ていきます。1 人または 2 人です - `gamepadconnected` と `gamepaddisconnected` - そしてこれらが行うことはかなり明白です。

この例の終わりには、まず `removeGamepads()` 関数を記載しています。

```js
function removeGamepads() {
  const gpLi = document.querySelectorAll(".gamepad");
  for (let i = 0; i < gpLi.length; i++) {
    list.removeChild(gpLi[i]);
  }
  reportGamepads();
}
```

この関数は、クラス名が `gamepad` であるすべてのリスト項目への参照を取得し、DOM から削除します。その後、`reportGamepads()` を再実行して、接続されているコントローラのリストを更新しています。

`removeGamepads()` は、ゲームパッドが接続または切断されるたびに、以下のイベントハンドラーで実行されます。

```js
window.addEventListener("gamepadconnected", (e) => {
  info.textContent = `Gamepad ${e.gamepad.index} connected.`;
  if (!initialRun) {
    setTimeout(removeGamepads, 1000);
  }
});

window.addEventListener("gamepaddisconnected", (e) => {
  info.textContent = `Gamepad ${e.gamepad.index} disconnected.`;
  setTimeout(removeGamepads, 1000);
});
```

ここでは、スクリプト上部の初期化コードで行ったように `setTimeout()` を所有しており、各ケースで `reportGamepads()` が呼び出されたときにゲームパッドが情報を報告する準備ができていることを確認することができます。

しかし、もう一つメモがあります。 `gamepadconnected` ハンドラーの内部では、 `initialRun` が `false` のときだけタイムアウトが実行されることがわかると思います。これは、文書内の最初のロード時にゲームパッドが接続されている場合、ゲームパッドごとに `gamepadconnected` が発行されるため、 `removeGamepads()`/`reportGamepads()` が複数回実行されることになるからです。そのため、`removeGamepads()`は `gamepadconnected` ハンドラーの中で、最初の実行時ではなく、実行後に実行するようにしたいです。そのために `initialRun` があります。

実際のデモの紹介
--------

実際の WebVR のデモで使用された Gamepad API を見てみましょう。このデモはraw-webgl-controller-example (ライブデモご覧ください).で見ることができます。

私達のraw-webgl-example (詳しくは Using the WebVR API を御覧ください。)と同じ方法で、このデモにおいても回転する 3D 立方体をレンダリングしています。また、これを VR ディスプレイへ投影することもできます。唯一の違いとしては、VR ディスプレイへ投影モードでは、VR ゲームパッドを使って立方体を動かすことができます。（オリジナルのデモ動画では、VR ヘッドセットを動かすことで、立方体を動かすことができる。）

以下に、このバージョンでのコードの違いをより詳しく紹介します。webgl-demo.js を御覧ください。

### ゲームパッドデータへのアクセス

`drawVRScene()` 関数についてのコードの一部です。

```js
const gamepads = navigator.getGamepads();
const gp = gamepads[0];

if (gp) {
  const gpPose = gp.pose;
  const curPos = gpPose.position;
  const curOrient = gpPose.orientation;
  if (poseStatsDisplayed) {
    displayPoseStats(gpPose);
  }
}
```

`Navigator.getGamepads`を利用して、ゲームパッドが接続されました。また `gp` 変数の中に最初に認識したゲームパッドを保存します。 デモでは、ゲームパッドを一つしか使用しないので、その他のゲームパッドは無視します。

次に行うことは、gpPose に格納されているコントローラーの `GamepadPose` (en-US) オブジェクトを取得し (`Gamepad.pose` をクエリーして)、またこのフレームの現在のゲームパッドの位置と方向を変数に格納して、後で容易にアクセスできるようにすることです。また、 `displayPoseStats()` 関数を使用して、このフレームのポスト統計情報を DOM に表示します。この処理はすべて `gp` が実際に値を保有している場合（ゲームパッドが接続されている場合）にのみ行われ、ゲームパッドを接続していない場合にデモがエラーにならないようにしています。

コードの少し後に、このブロックを見つけることができます。

```js
if (gp && gpPose.hasPosition) {
  mvTranslate([
    0.0 + curPos[0] \* 15 - curOrient[1] \* 15,
    0.0 + curPos[1] \* 15 + curOrient[0] \* 15,
    -15.0 + curPos[2] \* 25,
  ]);
} else if (gp) {
  mvTranslate([0.0 + curOrient[1] \* 15, 0.0 + curOrient[0] \* 15, -15.0]);
} else {
  mvTranslate([0.0, 0.0, -15.0]);
}
```

ここでは、接続されたコントローラーから受け取った `position` (en-US) と `orientation` (en-US) データに従って、画面上のCubeの位置を変更します。これらの値(`curPos` と `curOrient` に格納されます)は X、Y、Z の値を含む `Float32Array`s です (ここでは X である [0] と Y である [1] だけ使用しています)。

変数 `gp` の中に `Gamepad` オブジェクトがあり、位置値を返すことができる場合 (`gpPose.hasPosition`) は、6DoF コントローラーを示しているので、位置と方向の値を使ってキューブの位置を変更しま す。前者のみが真の場合、3DoF コントローラーを示し、方向値のみを使用してキューブの位置を変更します。ゲームパッドが接続されていない場合、キューブの位置はすべて変更されません。

### ゲームパッドの姿勢データの表示

`displayPoseStats()` 関数では、`GamepadPose` (en-US) オブジェクトのうちの表示したいすべての情報を取得することができます。そして、そのようなデータを表示するためのデモの中に存在する UI パネルに表示します。

```js
function displayPoseStats(pose) {
  const pos = pose.position;

  const formatCoords = ([x, y, z]) =>
    `x ${x.toFixed(3)}, y ${y.toFixed(3)}, z ${z.toFixed(3)}`;

  posStats.textContent = pose.hasPosition
    ? `Position: ${formatCoords(pose.position)}`
    : "Position not reported";

  orientStats.textContent = pose.hasOrientation
    ? `Orientation: ${formatCoords(pose.orientation)}`
    : "Orientation not reported";

  linVelStats.textContent = `Linear velocity: ${formatCoords(
 pose.linearVelocity,
 )}`;
  angVelStats.textContent = `Angular velocity: ${formatCoords(
 pose.angularVelocity,
 )}`;

  linAccStats.textContent = pose.linearAcceleration
    ? `Linear acceleration: ${formatCoords(pose.linearAcceleration)}`
    : "Linear acceleration not reported";

  angAccStats.textContent = pose.angularAcceleration
    ? `Angular acceleration: ${formatCoords(pose.angularAcceleration)}`
    : "Angular acceleration not reported";
}
```

まとめ
---

この記事は、WebVR アプリの中で VR ゲームパッドを使うためには、どのように Gamepad Extensions を用いればよいのかというとても基本的な概念を解説したものです。実際の WebVR アプリの中では、VR ゲームパッドのボタンに紐付けられたゲームパッドにより、おそらくより複雑なコントロールシステムをもたせることになるでしょう。 そして、ディスプレイとゲームパッドの両方の情報（位置や方向）を同期的にディスプレイへフィードバックするという複雑な処理を行うことになります。しかし、この記事でやりたかったのは、Gamepad Extensions の中の純粋な Gamepad Extensions 部分を切り分けるということです。

関連項目
----

* WebVR API
* ゲームパッド API
* WebVR API の使用
* ゲームパッド API を使用した制御の実装