交差オブザーバー API による要素の表示時間設定 - Web API

交差オブザーバー API による要素の表示時間設定
=========================

この記事では、ページのコンテンツ間に多数の広告が散在している模擬ブログを作成し、その後交差オブザーバー API を使用して、各広告がユーザーに表示される時間を追跡します。表示時間の 1 分を超えた広告は、新しい広告と置き換えられます。

この例の多くの側面は実際の使用状況とは一致しませんが（特に記事はすべて同じテキストであり、データベースからは読み込まれません。また、ほんの一握りの単なるテキストのみの広告が配列から選択されます）、これは自分のサイトに交差オブザーバー API を適用する方法をすばやく学ぶために十分な API を理解できるようにするためです。

この例で、広告の表示状況を追跡するという概念が使用されているのには、それなりの理由があります。ウェブ上の広告で Flash やその他のスクリプトを最もよく使用するのは、課金や収益の支払いのために、それぞれの広告が表示されている時間を記録することだとわかりました。交差オブザーバー API がなければ、これは個々の広告で interval や timeout、またはページが遅くなる傾向がある他の技術を使用して行われることになるでしょう。この API を使用すると、ブラウザーによってすべてが効率化され、パフォーマンスへの影響が大幅に軽減されます。

それでは、始めましょう。

サイトの構築
------

### サイト構造: HTML

サイトの構成はそれほど複雑ではありません。 CSS グリッドを使用してスタイル設定とレイアウトを行うので、ここではかなり素直に行うことができます。

```html
<div class="wrapper">
  <header>
    <h1>A Fake Blog</h1>
    <h2>Showing Intersection Observer in action!</h2>
  </header>

  <aside>
    <nav>
      <ul>
        <li><a href="#link1">A link</a></li>
        <li><a href="#link2">Another link</a></li>
        <li><a href="#link3">One more link</a></li>
      </ul>
    </nav>
  </aside>

  <main>…</main>
</div>
```

これは、サイト全体のフレームワークです。上部にはサイトのヘッダー領域があり、 `<header>` ブロックの中に含まれています。その下に、 `<aside>`ブロック内のリンクのリストとして、サイトのサイドバーを定義しています。

最後に、本体が来ます。ここでは、空の `<main>` 要素で始めます。このボックスには、後でスクリプトを使用してデータを入力します。

### CSS によるサイトのスタイル設定

サイトの構造を定義したら、次はサイトのスタイル設定です。ここでは、ページの各構成要素のスタイルを個別に見ていきましょう。

#### 基礎

`<body>` と `<main>` 要素にスタイルを指定し、サイトの背景と、サイトの様々な部分が配置されるグリッドを定義しています。

```css
body {
  font-family: "Open Sans", "Arial", "Helvetica", sans-serif;
  background-color: aliceblue;
}

.wrapper {
  display: grid;
  grid-template-columns: auto minmax(min-content, 1fr);
  grid-template-rows: auto minmax(min-content, 1fr);
  max-width: 700px;
  margin: 0 auto;
  background-color: aliceblue;
}
```

このサイトの `<body>` は、一般的なサンセリフフォントのうちの 1 つを使用し、背景色として `"aliceblue"` を使用するように設定します。次に、 `"wrapper"` クラスを定義します。これは、ヘッダー、サイドバー、本体コンテンツ（記事と広告）を含む、ブログ全体を包みます。

wrapper は、 2 つの列と 2 つの行からなる CSS グリッドを確立します。最初の列（そのコンテンツに基づいて自動的にサイズ調整されます）はサイドバーに使用され、 2 つ目の列（本体コンテンツに使用されます）は、少なくとも列のコンテンツの幅と、最大で残りのすべての利用できる空間となるようにサイズ調整されます。

最初の 1 行目は、サイトのヘッダーに特別に使用されます。行のサイズは列と同じです。最初の行は自動的にサイズ調整され、 2 つ目の行は残りのスペースを使用しますが、少なくとも行内のすべての要素のためのスペースを提供するのに十分なスペースが必要です。

ラッパーの幅は 700px に固定されており、下記の MDN でインライン表示されたときに利用できる空間に収まるようになっています。

#### ヘッダー

この例では、ヘッダーはいくつかのテキストを含むだけなので、かなり単純なものです。そのスタイル設定は次のようになります。

```css
header {
  grid-column: 1 / -1;
  grid-row: 1;
  background-color: aliceblue;
}
```

ヘッダーをサイトのグリッドの一番上の行に配置したいので、 `grid-row` は 1 に設定しています。さらに興味深いのは、ここで `grid-column` を使用していることです。ここでは、列を最初の列から始めて、最後のグリッド行を過ぎた最初の列で終わるように指定しています。他にも、ヘッダーはグリッド内のすべての列にまたがって配置されます。私たちのニーズにぴったりです。

#### サイドバー

サイドバーは、サイト内の他のページへのリンクを表示するために使用されています。この例ではどれも動作しませんが、ブログのような体裁を整えるために存在しています。サイドバーは `<aside>` 要素を使用して表しており、以下のようにスタイルを設定しています。

```css
aside {
  grid-column: 1;
  grid-row: 2;
  background-color: cornsilk;
  padding: 5px 10px;
}

aside ul {
  padding-left: 0;
}

aside ul li {
  list-style: none;
}

aside ul li a {
  text-decoration: none;
}
```

ここで最も重要なことは、サイドバーを画面の左側へ配置するために `grid-column` を 1 に設定していることです。これを -1 に変更すると、右側に表示されます（ただし、他にも正しい間隔を取得するために余白の調整が必要な要素があります）。 `grid-row` は 2 に設定し、サイト本体と横に並んだ状態にします。

#### コンテンツ本体

サイトの本体といえば、サイトのメインコンテンツは `<main>` 要素で保持されています。それには、以下のようなスタイルが適用します。

```css
main {
  grid-column: 2;
  grid-row: 2;
  margin: 0;
  margin-left: 16px;
  font-size: 16px;
}
```

ここでの一番の特徴は、本体コンテンツを 2 行目の 2 列目に配置するようグリッド位置を設定していることです。

#### 記事

各記事は `<article>` 要素に収め、このようなスタイルで表示されます。

```css
article {
  background-color: white;
  padding: 6px;
}

article:not(:last-child) {
  margin-bottom: 8px;
}

article h2 {
  margin-top: 0;
}
```

このようにして、青い背景の上に浮かぶ白い背景の記事ボックスが作成され、記事の周りに小さな余白ができます。コンテナーの最後の記事を除くすべての記事には、 8px の下マージンがあり、空間を隔てて配置されます。

#### 広告

最後に、広告には以下のような初期スタイルを設定します。後で説明するように、個々の広告でスタイルを多少カスタマイズすることがあります。

```css
.ad {
  height: 96px;
  padding: 6px;
  border-color: #555;
  border-style: solid;
  border-width: 1px;
}

.ad:not(:last-child) {
  margin-bottom: 8px;
}

.ad h2 {
  margin-top: 0;
}

.ad div {
  position: relative;
  float: right;
  padding: 0 4px;
  height: 20px;
  width: 120px;
  font-size: 14px;
  bottom: 30px;
  border: 1px solid black;
  background-color: rgba(255, 255, 255, 0.5);
}
```

何もマジックはありません。かなり基本的な CSS です。

### JavaScript との結合

このように、すべてをうまく動作させるための JavaScript のコードを紹介します。まず、グローバル変数から始めましょう。

```js
let contentBox;

let nextArticleID = 1;
const visibleAds = new Set();
let previouslyVisibleAds = null;

let adObserver;
let refreshIntervalID = 0;
```

これらは以下のように使用されます。

`contentBox`

DOM 内の `<main>` 要素の `HTMLElement` オブジェクトへの参照です。この中に、記事や広告を挿入していきます。

`nextArticleID`

各記事には固有の ID 番号が指定されており、この変数は 1 から順に、次に使用する ID を追跡します。

`visibleAds`

画面に現在表示されている広告を追跡するために使用する `Set` です。

`previouslyVisibleAds`

文書が表示されていない間（例えば、ユーザーが別のページにタブ移動した場合など）、表示されている広告のリストを一時的に格納するために使用されます。

`adObserver`

広告と `<main>` 要素の境界との交差を追跡するために使用される `IntersectionObserver` が格納されます。

`refreshIntervalID`

`setInterval()` によって返されるインターバル ID を格納するために使用されます。このインターバルは、広告の内容を定期的に更新する際に発生させるために使用されます。

#### セットアップ

設定をするために、ページが読み込まれたときに下記の `startup()` 関数を実行します。

```js
window.addEventListener("load", startup, false);

function startup() {
  contentBox = document.querySelector("main");

  document.addEventListener("visibilitychange", handleVisibilityChange, false);

  const observerOptions = {
    root: null,
    rootMargin: "0px",
    threshold: [0.0, 0.75],
  };

  adObserver = new IntersectionObserver(intersectionCallback, observerOptions);

  buildContents();
  refreshIntervalID = setInterval(handleRefreshInterval, 1000);
}
```

まず、コンテンツを包む `<main>` 要素への参照を取得し、コンテンツをそこに挿入できるようにします。次に `visibilitychange` イベントに対するイベントリスナーを設定します。このイベントは、ユーザーがブラウザー内のタブを切り替えたときなど、文書が隠されたり見えるようになったりしたときに送られます。交差はページの表示状態に影響されないため、交差オブザーバー API は交差を検出する際にこれを考慮しません。したがって、ページがタブで切り替わる間、タイマーを一時停止する必要があります。

次に、 `IntersectionObserver` の対象要素（この例では広告）の文書内の相対的な交差の変化を監視するためのオプションを設定します。このオプションは、文書内のビューポートとの交差を監視するように構成します（`root` を `null` に設定することで）。交差ルートの矩形を伸縮させるマージンは設定しません。交差の目的上、文書内のビューポートの境界線と正確に一致させたいからです。そして、 `threshold` には、 0.0 と 0.75 の値を含む配列を設定します。これは、対象とする要素が完全に見えなくなる、または見え始める（交差量の比 0.0）か、 75% が見える状態を（どちらの方向にも）通過する（交差量の比 0.75）たびに、コールバックが実行されるようにするものです。

オブザーバーである `adObserver` は、 `IntersectionObserver` のコンストラクターを呼び出して、コールバック関数である `intersectionCallback` とオプションを渡すことで作成します。

次に、後で定義する `buildContents()` という関数を呼び出して、表示したい記事や広告を実際に生成し、文書内に挿入しています。

最後に、必要な更新を処理するために、 1 秒に 1 回発生させるインターバルを設定します。そのため、この例では、表示されているすべての広告にタイマーを表示しているので、 1 つ目の更新が必要です。インターバルはすべて必要ないかもしれませんし、異なる形で使用したり、異なる時刻間隔を使用することもできます。

#### 文書の可視性の変更の処理

`visibilitychange` イベント用のハンドラーを見てみましょう。このスクリプトは、文書自体が可視または不可視になったときに、このイベントを受け取ります。ここで最も重要なシナリオは、ユーザーがタブを切り替えたときです。交差オブザーバーは、対象となる要素と交差ルートとの間の交差にのみ関心があり、タブが可視かどうかには関心がないので（これは完全に異なる問題です）、これらのタブ切り替えを検出するためにページ可視性 API を使用して、その間のタイマーを無効にする必要があります。

```js
function handleVisibilityChange() {
  if (document.hidden) {
    if (!previouslyVisibleAds) {
      previouslyVisibleAds = visibleAds;
      visibleAds = [];
      previouslyVisibleAds.forEach((adBox) => {
        updateAdTimer(adBox);
        adBox.dataset.lastViewStarted = 0;
      });
    }
  } else {
    previouslyVisibleAds.forEach((adBox) => {
      adBox.dataset.lastViewStarted = performance.now();
    });
    visibleAds = previouslyVisibleAds;
    previouslyVisibleAds = null;
  }
}
```

このイベント自体は、文書が可視から不可視に切り替わったか、またはその逆かを表明しないため、文書が現在表示されていないかどうかを確認するために `document.hidden` プロパティをチェックします。理論的には複数回呼び出される可能性があるため、タイマーを一時停止して既存の広告の表示状態を保存していない場合にのみ処理を進めます。

タイマーを一時停止するために必要なことは、可視広告の集合 (`visibleAds`) から広告を削除し、不活性としてマークすることです。そのためには、まず、表示されている広告のセットを変数 `previouslyVisibleAds` に保存して、ユーザーがこの文書にタブで戻ったときにそれらを復元できるようにし、次に `visibleAds` セットを空にして、それらが表示されていないように扱います。次に、一時停止されている各広告について、広告の合計表示時間カウンターを更新する `updateAdTimer()` 関数を呼び出してから、その広告の `dataset.lastViewStarted` プロパティを 0 に設定し、そのタブのタイマーが実行されていないことを表します。

文書が表示されたばかりの場合は、このプロセスを逆にします。まず、 `previouslyVisibleAds`を調べて、それぞれの `dataset.lastViewStarted` に `performance.now()` メソッドを使用して現在の文書の時刻（文書作成後のミリ秒単位の時刻）を設定します。次に、 `visibleAds` を `previouslyVisibleAds` に設定し直し、後者を `null` に設定します。これで広告がすべて再開され、現在の時刻に表示されるようになったことがわかるように設定されました。これにより、次に広告が更新されたときに、ページがタブで移動された時間が加算されなくなります。

#### 交差状態の変化の処理

ブラウザーのイベントループを通過するたびに、それぞれの `IntersectionObserver` は、その対象要素のどれかがオブザーバーの交差比率の閾値のどれかを通過したかどうか調べます。それぞれのオブザーバーについて、対象のリストがコンパイルされ、オブザーバーのコールバックに `IntersectionObserverEntry` オブジェクトの配列として送信されます。コールバックである `intersectionCallback()` は以下のようにしています。

```js
function intersectionCallback(entries) {
  entries.forEach((entry) => {
    const adBox = entry.target;

    if (entry.isIntersecting) {
      if (entry.intersectionRatio >= 0.75) {
        adBox.dataset.lastViewStarted = entry.time;
        visibleAds.add(adBox);
      }
    } else {
      visibleAds.delete(adBox);
      if (
        entry.intersectionRatio === 0.0 &&
        adBox.dataset.totalViewTime >= 60000
      ) {
        replaceAd(adBox);
      }
    }
  });
}
```

前回述べたように、 `IntersectionObserver` コールバックは、交差オブザーバーの比率の 1 つよりも可視性が高くなった、または低くなったオブザーバーの対象要素のすべての配列を入力として受け取ります。これらの各項目は `IntersectionObserverEntry` 型であり、反復処理されます。対象要素がルートと交差している場合、不明瞭な状態から可視状態に遷移したことがわかります。75% 以上可視状態になった場合は、広告を可視状態とみなし、広告の `dataset.lastViewStarted` 属性を `entry.time` の遷移時刻に設定し、広告を `visibleAds` セットに追加して、時間の経過と共に処理することが分かるようにタイマーを開始します。

広告が交差しない状態に遷移した場合、その広告を表示可能な広告の集合から削除します。次に、1 つの特別な動作があります。`entry.ratio` が 0.0 であるかどうか調べます。0 である場合、その要素は完全に見えなくなったということを意味します。この場合、広告が少なくとも合計 1 分間表示されていれば、これから作成する `replaceAd()` という関数を呼び出して、既存の広告を新しい広告に置き換えます。こうすることで、ユーザーは時刻とともに様々な広告を目にすることになりますが、広告は見えない間だけ置き換えるので、結果的にスムーズな使い勝手になります。

#### 定期的なアクションの処理

インターバルハンドラーである `handleRefreshInterval()` は、 `startup()` 関数（上記）の中で `setInterval()` を呼び出すことにより、 1 秒に 1 回程度呼び出されるようになります。この関数の主な仕事は、 1 秒ごとにタイマーを更新し、各広告内で描画するタイマーを更新するために再描画をスケジュールすることです。

```js
function handleRefreshInterval() {
  const redrawList = [];

  visibleAds.forEach((adBox) => {
    const previousTime = adBox.dataset.totalViewTime;
    updateAdTimer(adBox);

    if (previousTime !== adBox.dataset.totalViewTime) {
      redrawList.push(adBox);
    }
  });

  if (redrawList.length) {
    window.requestAnimationFrame((time) => {
      redrawList.forEach((adBox) => {
        drawAdTimer(adBox);
      });
    });
  }
}
```

配列 `redrawList` は、この更新サイクルの間に再描画する必要があるすべての広告のリストを保持するために使用されます。システムの活動によって、または間隔を 1000 ミリ秒ごと以外に設定したために経過時間とまったく同じにならないことがあるからです。

次に、表示されている広告ごとに、 `dataset.totalViewTime` の値（前回更新された時点で広告が表示されていた総時間）を保存し、 `updateAdTimer()` を呼び出して時刻を更新します。時間が変更された場合、広告を `redrawList` にプッシュし、次のトランジションフレームで広告を更新する必要があることを知らせます。

最後に、再描画する要素が一つでもあれば、 `requestAnimationFrame()` を使用して、次のアニメーションフレームで `redrawList` にある各要素を再描画する関数をスケジュールしています。

#### 広告の可視性タイマーの更新

前回（文書の可視性の変更の処理および定期的なアクションの処理を参照）、広告の「合計表示時間」カウンターを更新する必要があるときに、 `updateAdTimer()` という名前の関数を呼び出して更新することを見てきました。この関数は、広告の `HTMLDivElement` オブジェクトを入力として受け取ります。これがその例です。

```js
function updateAdTimer(adBox) {
  const lastStarted = adBox.dataset.lastViewStarted;
  const currentTime = performance.now();

  if (lastStarted) {
    const diff = currentTime - lastStarted;

    adBox.dataset.totalViewTime =
      parseFloat(adBox.dataset.totalViewTime) + diff;
  }

  adBox.dataset.lastViewStarted = currentTime;
}
```

要素の表示時間を追跡するために、すべての広告で 2 つのカスタムデータ属性（`data-*` を参照）を使用しています。

`lastViewStarted`

文書が作成された時刻を基準にして、広告の表示回数が最後に更新された、または広告が最後に表示されるようになった時刻をミリ秒単位で指定します。広告を最後に調べた時刻に広告が表示されていなかった場合は 0 です。

`totalViewTime`

広告が表示されていた総時間（ミリ秒単位）です。

この属性は、各カスタム属性の名前とその値を割り当てた `DOMStringMap` を提供します。実際、JavaScript で通常は自動的に変換されますが、1 つだけ私たち自身が変換しなければならない場合があります。

まず、広告の前回の表示状態を調べる時刻 (`adBox.dataset.lastViewStarted`) をローカル変数 `lastStarted` に取り込むところから始めます。また、`performance.now()` を使用して作成してからの現在の時刻値を `currentTime` に取得しています。

`lastStarted` がゼロでない場合、つまりタイマーが現在実行されている場合、現在の時刻と開始時刻の差を計算し、タイマーが前回表示されてから何ミリ秒表示されていたかを判断します。この値を広告の `totalViewTime` の現在の値に追加して、合計を最新にします。ここで `parseFloat()` を使用していることに注意してください。これらの値は文字列であるため、 JavaScript ではこれを使用せずに加算の代わりに文字列の連結を行おうとします。

最後に、広告の最終表示時刻を現在の時刻に更新します。これは、この関数が呼び出されたときに広告が実行されていたかどうかに関係なく行います。これにより、この関数が返すときには、広告のタイマーは常に実行されていることになります。この関数は、広告が表示されている場合にのみ呼び出され、たとえそれがたった今表示されるようになったとしても、これは理にかなっています。

#### 広告のタイマーの表示

各広告の内部では、デモのために、分と秒に変換された `totalViewTime` の現在の値を描画しています。これは、広告の要素を `drawAdTimer()` 関数に渡すことで処理しています。

```js
function drawAdTimer(adBox) {
  const timerBox = adBox.querySelector(".timer");
  const totalSeconds = adBox.dataset.totalViewTime / 1000;
  const sec = Math.floor(totalSeconds % 60);
  const min = Math.floor(totalSeconds / 60);

  timerBox.innerText = `${min}:${sec.toString().padStart(2, "0")}`;
}
```

このコードでは、広告のタイマーをその ID である `"timer"` を使用して見つけ、広告の `totalViewTime` を 1000 で割って経過した秒数を計算します。次に、タイマーの `innerText` にその時刻を表す文字列を m:ss 形式で設定する前に経過した分と秒の値を計算します。 `String.padStart()` メソッドを使用して、秒数が 10 未満の場合は 2 桁になるようにパディングしています。

### ページコンテンツの構築

`buildContents()` 関数は、スタートアップコードから呼び出され、表示する記事や広告を選択して文書内に挿入します。

```js
const loremIpsum =
  "<p>Lorem ipsum dolor sit amet, consectetur adipiscing" +
  " elit. Cras at sem diam. Vestibulum venenatis massa in tincidunt" +
  " egestas. Morbi eu lorem vel est sodales auctor hendrerit placerat" +
  " risus. Etiam rutrum faucibus sem, vitae mattis ipsum ullamcorper" +
  " eu. Donec nec imperdiet nibh, nec vehicula libero. Phasellus vel" +
  " malesuada nulla. Aliquam sed magna aliquam, vestibulum nisi at," +
  " cursus nunc.</p>";

function buildContents() {
  for (let i = 0; i < 5; i++) {
    contentBox.appendChild(createArticle(loremIpsum));

    if (!(i % 2)) {
      loadRandomAd();
    }
  }
}
```

変数 `loremIpsum` には、すべての記事のコンテナー本体に使用するテキストが収められています。もちろん、現実の世界では、データベースなどから記事を取得するためのコードを持つことになるでしょうが、この目的ではこれで十分です。すべての記事には同じテキストを使用します。もちろん、簡単に変更することができます。

`buildContents()` は 5 つの記事を持つページを作成します。奇数番目の各記事の後で、広告が「読み込まれ」、ページに挿入されます。記事は、次に見ていく `createArticle()` というメソッドで作成した後、コンテンツボックス（つまり、サイトのすべてのコンテンツを収める `<main>` 要素）に挿入します。

広告は `loadRandomAd()` と呼ばれる関数を使って作成し、広告の作成とページへの挿入を行います。この同じ関数が既存の広告を置き換えることもできることは後で説明しますが、今回は既存のコンテンツに広告を追加しています。

#### 記事の作成

記事のための `<article>` 要素（とそのすべてのコンテンツ）を作成するために、 `createArticle()` 関数を使用します。この関数はページに追加する記事の全文を入力として受け取ります。

```js
function createArticle(contents) {
  const articleElem = document.createElement("article");
  articleElem.id = nextArticleID;

  const titleElem = document.createElement("h2");
  titleElem.innerText = `Article ${nextArticleID} title`;
  articleElem.appendChild(titleElem);

  articleElem.innerHTML += contents;
  nextArticleID += 1;

  return articleElem;
}
```

まず、`<article>` 要素を作成し、その ID を固有の値 `nextArticleID` に設定します（これは 1 から始まり、各記事ごとに増えていきます）。次に、記事のタイトルのために `<h2>` 要素を作成して追加し、`contents` の HTML をこの記事に追加しています。最後に、 `nextArticleID` をインクリメントして（次の要素が新しい固有の ID を取得するように）、新しい `<article>` 要素を呼び出し元に返します。

#### 広告の作成

`loadRandomAd()` 関数は、広告を読み込んでページに追加するシミュレーションを行います。 `replaceBox` に値を渡さない場合、広告を収める新しい要素が作成されます。そして、広告がページに追加されます。 `replaceBox` を指定すると、そのボックスは既存の広告要素として扱われます。新しい要素を作成する代わりに、既存の要素を変更して新しい広告のスタイルやコンテンツ、他にもデータを収めるようにします。これは、広告を更新するときに、最初に古い要素を削除してから新しい要素を挿入した場合に起こりうる、長いレイアウト作業が行われるリスクを避けることができます。

```js
function loadRandomAd(replaceBox) {
  const ads = [
    {
      bgcolor: "#cec",
      title: "Eat Green Beans",
      body: "Make your mother proud—they're good for you!",
    },
    {
      bgcolor: "aquamarine",
      title: "MillionsOfFreeBooks.whatever",
      body: "Read classic literature online free!",
    },
    {
      bgcolor: "lightgrey",
      title: "3.14 Shades of Gray: A novel",
      body: "Love really does make the world go round…",
    },
    {
      bgcolor: "#fee",
      title: "Flexbox Florist",
      body: "When life's layout gets complicated, send flowers.",
    },
  ];
  let adBox, title, body, timerElem;

  const ad = ads[Math.floor(Math.random() \* ads.length)];

  if (replaceBox) {
    adObserver.unobserve(replaceBox);
    adBox = replaceBox;
    title = replaceBox.querySelector(".title");
    body = replaceBox.querySelector(".body");
    timerElem = replaceBox.querySelector(".timer");
  } else {
    adBox = document.createElement("div");
    adBox.className = "ad";
    title = document.createElement("h2");
    body = document.createElement("p");
    timerElem = document.createElement("div");
    adBox.appendChild(title);
    adBox.appendChild(body);
    adBox.appendChild(timerElem);
  }

  adBox.style.backgroundColor = ad.bgcolor;

  title.className = "title";
  body.className = "body";
  title.innerText = ad.title;
  body.innerHTML = ad.body;

  adBox.dataset.totalViewTime = 0;
  adBox.dataset.lastViewStarted = 0;

  timerElem.className = "timer";
  timerElem.innerText = "0:00";

  if (!replaceBox) {
    contentBox.appendChild(adBox);
  }

  adObserver.observe(adBox);
}
```

最初のものは配列 `ads` です。この配列には、各広告を作成するために必要なデータが収められています。ここでは 4 つのデータを保有しており、そこからランダムに選ぶことができます。実際のシナリオでは、もちろん、広告はデータベースから、あるいは、 API を使用して広告をフェッチする広告サービスから来る可能性がより高いでしょう。背景色 (`bgcolor`)、タイトル (`title`)、本文文字列 (`body`) の 3 つのプロパティを持つオブジェクトで、各広告を表現します。

そして、いくつかの変数を定義します。

`adBox`

これを、広告を表わす要素に設定します。ページに追加される新しい広告の場合、これは `Document.createElement()` で作成されます。既存の広告を置き換える場合、これは指定された広告要素 (`replaceBox`) に設定します。

`title`

広告のタイトルを表す `<h2>` 要素を保持します。

`body`

広告の本文を表す `<p>` を保持します。

`timerElem`

広告がこれまでに表示された時間を格納する `<div>` 要素を保持します。

`Math.floor(Math.random() * ads.length)` の計算により、ランダムな広告が選択されます。結果は 0 から広告の数より 1 少ない値になります。これで、対応する広告が `adBox` と呼ばれるようになりました。

もし `replaceBox` に値が指定された場合、それを広告要素として使用します。そのためには、まず `IntersectionObserver.unobserve()` を呼び出して要素の監視を終了させます。次に、広告を構成する各要素（広告ボックス自体、タイトル、本体、およびタイマーボックス）のローカル変数がすべて、既存の広告の対応する要素に設定されます。

replaceBox に値が指定されなかった場合は、新しい広告要素を作成します。広告の新しい `<div>` 要素を作成し、そのクラス名を `"ad"` に設定することでプロパティを確立します。次に、広告のタイトル要素を、本体や表示タイマーと共に作成します。これらは、それぞれ `<h2>`, `<p>`, `<div>` 要素になります。これらの要素を `adBox` 要素に付加します。

その後、コードのパスは再び繰り返しになります。広告の背景色は新しい広告のレコードで指定された値に設定され、要素のクラスとコンテンツも適切に設定されます。

次に、広告の可視性データを追跡するカスタムデータプロパティを設定するため、 `adBox.dataset.totalViewTime` と `adBox.dataset.lastViewStarted` を 0 に設定します。

最後に、広告の表示時間を示すタイマーを表示している `<div>` の ID を設定し、クラス `"timer"` を指定します。 0 分 0 秒の開始時刻を表すために初期テキストを「0:00」に設定し、広告に追加します。

既存の広告を置き換えない場合は、`Document.appendChild()` を使用して、ページのコンテンツ領域に要素を追加する必要があります。広告を置き換える場合は、すでにその広告があり、そのコンテンツを新しい広告に置き換えます。次に、交差オブザーバーである `adObserver` の `observe()` メソッドを呼び出して、広告とビューポートの交差が変更されないか監視を開始します。これで、広告が 100% 見えなくなったり、 1 ピクセルでも見えるようになったり、広告が何らかの方法で 75% 見える状態を通過するたびに、オブザーバーのコールバックが実行されるようになります。

#### 既存の広告を置き換える

オブザーバーのコールバックは、広告が 100% 見えなくなり、かつ表示時間の合計が 1 分以上になった場合に目を光らせています。そうなった場合、その広告の要素を入力として `replaceAd()` 関数を呼び出し、古い広告を新しい広告に置き換えます。

```js
function replaceAd(adBox) {
  updateAdTimer(adBox);

  const visibleTime = adBox.dataset.totalViewTime;
  console.log(
    `Replacing ad: ${
 adBox.querySelector("h2").innerText
 } - visible for ${visibleTime}`,
  );

  loadRandomAd(adBox);
}
```

`replaceAd()` は、まず既存の広告の `updateAdTimer()` を呼び出して、そのタイマーが最新であることを確認します。これにより、 `totalViewTime` を読み取る際に、広告がユーザーに表示されていた時間の正確な最終値を確認することができます。この場合、コンソールにログ出力しますが、現実の世界では、広告サービスの API に情報を送信したり、データベースに保存したりすることになります。

次に、置き換える広告を引数に指定して `loadRandomAd()` を呼び出すことで新しい広告を読み込ませています。前回見たように、 `loadRandomAd()` は、入力引数として既存の広告の要素を指定すると、新しい広告に対応したコンテンツや データで、既存の広告を置き換えます。

新しい広告の要素オブジェクトは、必要に応じて呼び出し側に返されます。

### 結果

出来上がったページは、このようになります。上下にスクロールして、可視性の変化が各広告のタイマーにどのように影響するかを試してみてください。また、各広告は表示されてから 1 分後に置き換えられること（ただし、広告を最初にスクロールして表示から外し、再び戻す必要があります）、文書内のタブがバックグラウンドにある間はタイマーが一時停止することに注意してください。ただし、ブラウザーを別のウィンドウで覆っても、タイマーは一時停止しません。

関連情報
----

* 交差オブザーバー API
* ページ可視性 API


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

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

**`Text()`** コンストラクターは新しい `Text` オブジェクトを返します。これは、引数で与えられたオプションの文字列をテキストコンテンツとして使用します。

構文
--

```js
new Text()
new Text(string)
```

### 引数

* `string` 省略可
### 返値

新しい `Text` オブジェクトで、`string` 引数の内容、引数が与えられなかった場合は空文字列を持ったものです。

例
-

```js
let text = new Text("Test");
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-text-text① |

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

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

関連情報
----

* DOM API


Text: wholeText プロパティ - Web API

Text: wholeText プロパティ
=====================

**`wholeText`** は `Text` インターフェイスのプロパティで、そのノードに論理的に隣接するすべての `Text` ノードのすべてのテキストを返すものです。
 テキストは文書中の順序で連結されます。
 これにより、任意のテキストノードを指定し、隣接するすべてのテキストを 1 つの文字列として取得することができます。

**メモ:** これは `Node.normalize()` を呼び出してそのテキストノードの値を読み取るのに似ていますが、ツリーを変更することはありません。

値
-

接続されたテキストの文字列です。

例
-

ウェブページに次のような簡単な段落があったとします。

```html
<p>
  Through-hiking is great!
  <strong>No insipid election coverage!</strong> However,
  <a href="https://en.wikipedia.org/wiki/Absentee\_ballot">casting a ballot</a>
  is tricky.
</p>
```

中央の文章が気に入らないと判断し、削除します。

```js
const paragraph = document.querySelector("p"); // 段落を読み取る
paragraph.removeChild(para.childNodes[1]); // strong のテキストを削除
```

これで *"Through-hiking is great! However, casting a ballot is tricky."* となり、ハイパーリンクの前はノード 2 つになります。

1. `Text` で、`"Through-hiking is great!"` という文字列を含むもの
2. 2 番目の `Text` ノードで、`" However, "` という文字列を含むもの

これらの 2 つのノードを一度に取得するには、 `para.childNodes[0].wholeText` を呼び出します。

```js
console.log(`'${paragraph.childNodes[0].wholeText}'`); // 'Through-hiking is great! However, '
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-text-wholetext① |

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

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

関連情報
----

* 所属先の `Text` インターフェイス


Text: splitText() メソッド - Web API

Text: splitText() メソッド
======================

**`splitText()`** は `Text` インターフェイスのメソッドで、この `Text` ノードを指定したオフセットで 2 つに分割し、両方のノードを兄弟としてツリーの中に保持します。

 分割後、現在のノードには指定したオフセット位置までのすべてのコンテンツが設定され、新規作成された同じ種類のノードには残りのテキストが設定されます。新しく作成されたノードは呼び出し元に返されます。
 元のノードに親があった場合、新しいノードは元のノードの次の兄弟として挿入されます。
 オフセットが元のノードの長さと等しい場合、新しく作成されたノードにはデータがありません。

分割されたテキストノードは、 `Node.normalize()` メソッドを用いて結合することができます。

構文
--

```js
newNode = textNode.splitText(offset)
```

### 引数

`offset`

テキストノードを分割する直前の位置。

### 返値

新しく生成された `Text` ノードを返し、指定されたオフセット位置以降のテキストが格納されます。

### 例外

`IndexSizeError` `DOMException`

指定されたオフセットが負の値であるか、ノードのテキストの 16 ビット単位の文字数よりも大きい場合に発生します。

`NoModificationAllowedError` `DOMException`

ノードが読取専用の場合に発生します。

例
-

この例では、 `<p>` のテキストが 2 つのテキストノードに分割され、 `<u>` がその間に挿入されます。

```html
<p>foobar</p>
```

```js
const p = document.querySelector("p");

// <p> の中身をテキストノードとして取得
const foobar = p.firstChild;

// 'foobar' を二つのテキストノード 'foo' と 'bar' に分割し、
// 'bar' を const として保存
const bar = foobar.splitText(3);

// <u> 要素を作成して ' new content ' を含める
const u = document.createElement("u");
u.appendChild(document.createTextNode(" new content "));

// <u> を 'bar' の前に追加
p.insertBefore(u, bar);

// 結果: <p>foo<u> new content </u>bar</p>
```

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-text-splittext① |

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

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

関連情報
----

* 所属先の `Text` インターフェイス
* 逆のメソッド: `Node.normalize`


Text: assignedSlot プロパティ - Web API

Text: assignedSlot プロパティ
========================

**`assignedSlot`** は `Text` インターフェイスの読み取り専用プロパティで、要素に関連付けられた `HTMLSlotElement` オブジェクトを返します。

値
-

`HTMLSlotElement`、またはテキストノードに関連付けられている `<slot>` 要素がない場合は `null`。

仕様書
---

| Specification |
| --- |
| DOM Standard # dom-slotable-assignedslot |

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

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


PerformanceResourceTiming.renderBlockingStatus - Web API

PerformanceResourceTiming.renderBlockingStatus
==============================================

**`renderBlockingStatus`** は読み取り専用のプロパティで、リソースのレンダーブロッキング状態を返します。

次のようなリソースを特定するのに有用です。

* レンダーブロッキングでなかったために遅延する可能性があった
* レンダーブロッキングであったために先読みできた
解説
--

レンダーブロッキングリソースとは、フォント、CSS、JavaScript などの静的ファイルで、ブラウザがページのコンテンツを画面に描画するのを妨害したり、遅らせたりするものです。ブラウザーはこれらのブロックリソースを自動的に判断し、すべてのスタイルシートと同期スクリプトが読み込まれ評価される前に、画面にピクセルを描画しないようにします。これにより、スタイル未設定のコンテンツが一瞬現れること（以下、FOUC）を防ぐことができます。

自動的なレンダーブロック機構に加えて、`blocking="render"` を属性と値として `<script>`, `<style>`, `<link>` 要素に提供して、明示的にレンダーブロックを設定することができます。例えば次のようにします。

```html
<link blocking="render" href="critical-font.woff2" as="font" />
```

値
-

`renderBlockingStatus` プロパティは以下の値を取ります。

`"blocking"`

このリソースがレンダリングをブロックする可能性がある。

`"non-blocking"`

このリソースはレンダリングをブロックしない。

例
-

### レンダリングをブロックするリソースをログ出力

`renderBlockingStatus` プロパティを使用すると、レンダリングをブロックしているリソースを確認することができます。

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.renderBlockingStatus === "blocking") {
      console.log(`${entry.name} is render-blocking.`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  if (entry.renderBlockingStatus === "blocking") {
    console.log(`${entry.name} is render-blocking.`);
  }
});
```

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-renderblockingstatus |

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

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


PerformanceResourceTiming.responseStatus - Web API

PerformanceResourceTiming.responseStatus
========================================

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

**`responseStatus`** は読み取り専用のプロパティで、リソースを読み取る際に返される HTTP レスポンスステータスコードを表します。

このプロパティはフェッチ API の `Response.status` に対応します。

値
-

`responseStatus` プロパティは以下の値を取ります。

* リソースを読み取った際に返された HTTP レスポンスステータスコードを示す数値。
* CORS のチェックに失敗した場合は `0`。
* 別オリジンの `<iframe>` オブジェクトの場合は `0`。
例
-

### キャッシュがヒットしたかどうかをチェック

`responseStatus` プロパティをお使用して、`304` `Not Modified` でキャッシュされたリソースを確認することができます。

`PerformanceObserver` を使用した例です。これは、ブラウザーのパフォーマンスタイムラインに新しい `resource` パフォーマンス項目が記録されると、それを通知するものです。オブザーバーが作成される前の項目にアクセスするには `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.responseStatus === 304) {
      console.log(`${entry.name} was loaded from cache`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  if (entry.responseStatus === 304) {
    console.log(`${entry.name} was loaded from cache`);
  }
});
```

また、 `responseStatus` が利用できない場合は、 `transferSize` プロパティは `0` を返します。

### オリジン間のレスポンスステータスコード

`responseStatus` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジンの外へのレスポンスステータスコードの表示を許可するには、CORS の HTTP の `Access-Control-Allow-Origin` レスポンスヘッダを設定する必要があります。

例えば、`https://developer.mozilla.org` にレスポンスステータスコードを取得させるためには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-responsestatus |

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

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

関連情報
----

* HTTP レスポンスステータスコード
* `Response.status`
* CORS


PerformanceResourceTiming.redirectStart - Web API

PerformanceResourceTiming.redirectStart
=======================================

**`redirectStart`** は読み取り専用プロパティで、リダイレクトを開始するフェッチの開始時間を表す `timestamp` を返します。

リソースの取得時に HTTP リダイレクトがあり、いずれかのリダイレクトが現在の文書と同じ起点からのものではないが、タイミング許可チェックアルゴリズムがリダイレクトされた各リソースに合格した場合、このプロパティはリダイレクトを開始するフェッチの開始時間を返します。そうでなければ、ゼロが返されます。

リダイレクトの回数を取得する場合は、 `PerformanceNavigationTiming.redirectCount` (en-US) も参照してください。

値
-

`redirectStart` プロパティは以下の値を取ります。

* リダイレクトを開始したフェッチの開始時刻を表す `timestamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### リダイレクト時間の計測

`redirectStart` と `redirectEnd` プロパティを使用して、リダイレクトにどれだけ時間がかかったかを測定することができます。

```js
const redirect = entry.redirectEnd - entry.redirectStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const redirect = entry.redirectEnd - entry.redirectStart;
    if (redirect > 0) {
      console.log(`${entry.name}: Redirect time: ${redirect}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const redirect = entry.redirectEnd - entry.redirectStart;
  if (redirect > 0) {
    console.log(`${entry.name}: Redirect time: ${redirect}ms`);
  }
});
```

### オリジン間のタイミング情報

`redirectStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-redirectstart |

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

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

関連情報
----

* `PerformanceNavigationTiming.redirectCount` (en-US)
* `Timing-Allow-Origin`


PerformanceResourceTiming.domainLookupEnd - Web API

PerformanceResourceTiming.domainLookupEnd
=========================================

**`domainLookupEnd`** は読み取り専用プロパティで、ブラウザーがリソースのドメイン名検索を終了した直後の `timestamp` を返します。

ユーザーエージェントのキャッシュにドメイン情報があった場合、`domainLookupStart` と `domainLookupEnd` はユーザーエージェントがキャッシュからのドメインデータの取得を開始および終了した時刻を表します。

値
-

`domainLookupEnd` プロパティは、以下の値を取ります。

* ブラウザーがリソースのドメイン名検索を完了した直後の時刻を表す `DOMHighResTimeStamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### DNS ルックアップ時間の計測

`domainLookupEnd` と `domainLookupStart` プロパティを使用すると、 DNS ルックアップの発生に対してどれだけ時間がかかるかを計測することができます。

```js
const dns = entry.domainLookupEnd - entry.domainLookupStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const dns = entry.domainLookupEnd - entry.domainLookupStart;
    if (dns > 0) {
      console.log(`${entry.name}: DNS lookup duration: ${dns}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const dns = entry.domainLookupEnd - entry.domainLookupStart;
  if (dns > 0) {
    console.log(`${entry.name}: DNS lookup duration: ${dns}ms`);
  }
});
```

### オリジン間のタイミング情報

`domainLookupEnd` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-domainlookupend |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.encodedBodySize - Web API

PerformanceResourceTiming.encodedBodySize
=========================================

**`encodedBodySize`** は読み取り専用プロパティで、適用されたコンテンツコーディング（gzip や Brotli など）を削除する前の、ペイロード本体のフェッチ（HTTP またはキャッシュ）から受信したサイズ（オクテット単位）を表します。リソースがアプリケーションキャッシュまたはローカルリソースから取得された場合は、適用されたコンテンツコーディングを削除する前にペイロードボディのサイズを返す必要があります。

値
-

`encodedBodySize` プロパティは、以下の値を取ります。

* フェッチ（HTTP またはキャッシュ）から受け取ったペイロード本体のサイズ（オクテット単位）を表す数値で、適用されたエンコーディングを削除する前のものです。
* リソースがオリジン間リクエストで、HTTP の `Timing-Allow-Origin` ヘッダーが使用されていない場合は `0`。
例
-

### コンテンツが圧縮されているかどうかのチェック

もし `encodedBodySize` と `decodedBodySize` プロパティが null でなく異なっていれば、コンテンツは（例えば gzip や Brotli などの）圧縮されたものです。

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const uncompressed =
      entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
    if (uncompressed) {
      console.log(`${entry.name} was not compressed!`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const uncompressed =
    entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
  if (uncompressed) {
    console.log(`${entry.name} was not compressed!`);
  }
});
```

### オリジン間のコンテンツサイズ情報

`encodedBodySize` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-encodedbodysize |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.domainLookupStart - Web API

PerformanceResourceTiming.domainLookupStart
===========================================

**`domainLookupStart`** は読み取り専用プロパティで、ブラウザーがリソースのドメイン名検索を開始する直前の `timestamp` を返します。

値
-

`domainLookupStart` プロパティは以下の値を取ります。

* ブラウザーがリソースのドメイン名検索を始める直前の `DOMHighResTimeStamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### DNS ルックアップ時間の計測

`domainLookupStart` と `domainLookupEnd` プロパティを使用すると、 DNS ルックアップの発生に対してどれだけ時間がかかるかを計測することができます。

```js
const dns = entry.domainLookupEnd - entry.domainLookupStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const dns = entry.domainLookupEnd - entry.domainLookupStart;
    if (dns > 0) {
      console.log(`${entry.name}: DNS lookup duration: ${dns}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const dns = entry.domainLookupEnd - entry.domainLookupStart;
  if (dns > 0) {
    console.log(`${entry.name}: DNS lookup duration: ${dns}ms`);
  }
});
```

### オリジン間のタイミング情報

`domainLookupStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-domainlookupstart |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.secureConnectionStart - Web API

PerformanceResourceTiming.secureConnectionStart
===============================================

**`secureConnectionStart`** は読み取り専用プロパティで、現在の接続を保護するためにブラウザーがハンドシェイクプロセスを開始する直前に `timestamp` を返します。安全な接続が使用されていない場合、このプロパティはゼロを返します。

値
-

`secureConnectionStart` プロパティは以下の値を取り得ます。

* リソースが安全な接続を介して取得された場合、ブラウザーが現在の接続を安全にするためにハンドシェイク処理を始める直前の時刻を示す `DOMHighResTimeStamp` です。
* 安全な接続が使用されていない場合は `0` です。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### TLS ネゴシエーション時間の測定

`secureConnectionStart` と `requestStart` プロパティを使用して、TLS ネゴシエーションにどれだけ時間がかかったかを測定することができます。

```js
const tls = entry.requestStart - entry.secureConnectionStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザー上のパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const tls = entry.requestStart - entry.secureConnectionStart;
    if (tls > 0) {
      console.log(`${entry.name}: TLS negotiation duration: ${tls}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const tls = entry.requestStart - entry.secureConnectionStart;
  if (tls > 0) {
    console.log(`${entry.name}: TLS negotiation duration: ${tls}ms`);
  }
});
```

### オリジン外へのタイミング情報の公開

`secureConnectionStart` プロパティの値が `0` の場合、リソースは安全な接続を使用していないか、オリジン間リクエストであるかのどちらかです。オリジンを跨いでタイミング情報の確認できるようにするには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` に時刻リソースを確認することを許可するには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-secureconnectionstart |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.decodedBodySize - Web API

PerformanceResourceTiming.decodedBodySize
=========================================

**`decodedBodySize`** は読み取り専用プロパティで、適用されたコンテンツエンコーディング（gzip や Brotli など）を削除した後、メッセージ本体のフェッチ（HTTP またはキャッシュ）で受信したサイズ（オクテット単位）を返します。リソースがアプリケーションキャッシュまたはローカルリソースから取得された場合、適用されたコンテンツコーディングを削除した後でペイロードのサイズを返します。

値
-

`decodedBodySize` プロパティは、以下の値を取ります。

* フェッチ（HTTP またはキャッシュ）から受け取ったペイロード本体のサイズ（オクテット単位）を表す数値で、適用されたエンコーディングを削除した後のものです。
* リソースがオリジン間リクエストで、HTTP の `Timing-Allow-Origin` ヘッダーが使用されていない場合は `0`。
例
-

### コンテンツが圧縮されているかどうかのチェック

もし `decodedBodySize` と `encodedBodySize` プロパティが null でなく異なっていれば、コンテンツは（例えば gzip や Brotli などの）圧縮されたものです。

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const uncompressed =
      entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
    if (uncompressed) {
      console.log(`${entry.name} was not compressed!`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const uncompressed =
    entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
  if (uncompressed) {
    console.log(`${entry.name} was not compressed!`);
  }
});
```

### オリジン間のコンテンツサイズ情報

`decodedBodySize` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-decodedbodysize |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.redirectEnd - Web API

PerformanceResourceTiming.redirectEnd
=====================================

**`redirectEnd`** は読み取り専用プロパティで、最後のリダイレクトのレスポンスの最後のバイトを受信した直後に `timestamp` を返します。

リソースを取得するとき、複数の HTTP リダイレクトがあり、いずれかのリダイレクトが現在のドキュメントとは異なる起点を持ち、タイミング許可チェックアルゴリズムがリダイレクトされたリソースごとに渡される場合、このプロパティは、最後のリダイレクトのレスポンスの最後のバイトを受信した直後の時間を返します。そうでなければ、ゼロが返されます。

リダイレクトの回数を取得する場合は、 `PerformanceNavigationTiming.redirectCount` (en-US) も参照してください。

値
-

`redirectEnd` プロパティは以下の値を取ります。

* 最後のリダイレクトのレスポンスの最後のバイトを受け取った直後の `timestamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### リダイレクト時間の測定

`redirectEnd` と `redirectStart` プロパティを使用して、リダイレクトにどれだけ時間がかかったかを測定することができます。

```js
const redirect = entry.redirectEnd - entry.redirectStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const redirect = entry.redirectEnd - entry.redirectStart;
    if (redirect > 0) {
      console.log(`${entry.name}: Redirect time: ${redirect}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const redirect = entry.redirectEnd - entry.redirectStart;
  if (redirect > 0) {
    console.log(`${entry.name}: Redirect time: ${redirect}ms`);
  }
});
```

### オリジン間のタイミング情報

`redirectStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-redirectend |

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

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

関連情報
----

* `PerformanceNavigationTiming.redirectCount` (en-US)
* `Timing-Allow-Origin`


PerformanceResourceTiming.responseEnd - Web API

PerformanceResourceTiming.responseEnd
=====================================

**`responseEnd`** は読み取り専用プロパティで、ブラウザーがリソースの最後のバイトを受信した直後、または転送接続が閉じられる直前のどちらか早い方の `timestamp` を返します。

他の多くの `PerformanceResourceTiming` プロパティとは異なり、 `responseEnd` プロパティは `Timing-Allow-Origin` がなくてもオリジン間リクエストで利用することができます。

値
-

ブラウザーがリソースの最後のバイトを受け取った直後、またはトランスポート接続が閉じられる直前のいずれか最初の `DOMHighResTimeStamp` です。

例
-

### フェッチする時間の計測（リダイレクトなし）

`responseEnd` と `fetchStart` プロパティを使用すると、（リダイレクトなしで）最終リソースを取得するのにかかった全体の時間を計測することができます。リダイレクトを含めるために、フェッチにかかった全体の時間は `duration` プロパティで提供されます。

```js
const timeToFetch = entry.responseEnd - entry.fetchStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const timeToFetch = entry.responseEnd - entry.fetchStart;
    if (timeToFetch > 0) {
      console.log(`${entry.name}: Time to fetch: ${timeToFetch}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const timeToFetch = entry.responseEnd - entry.fetchStart;
  if (timeToFetch > 0) {
    console.log(`${entry.name}: Time to fetch: ${timeToFetch}ms`);
  }
});
```

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-responseend |

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

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


PerformanceResourceTiming.responseStart - Web API

PerformanceResourceTiming.responseStart
=======================================

**`responseStart`** は読み取り専用プロパティで、ブラウザーがサーバ、キャッシュ、またはローカルリソースからレスポンスの最初のバイトを受信した直後の `timestamp` を返します。

値
-

`responseStart` プロパティは以下の値を取ります。

* サーバーからのレスポンスの最初のバイトをブラウザーが受信した直後の `DOMHighResTimeStamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### リクエスト時間の計測

`responseStart` と `requestStart` プロパティを使用して、リクエストにかかる時間を測定することができます。

```js
const request = entry.responseStart - entry.requestStart;
```

ブラウザーのパフォーマンスタイムラインに記録される新しい `resource` パフォーマンス項目を通知する `PerformanceObserver` を使用した例です。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const request = entry.responseStart - entry.requestStart;
    if (request > 0) {
      console.log(`${entry.name}: Request time: ${request}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const request = entry.responseStart - entry.requestStart;
  if (request > 0) {
    console.log(`${entry.name}: Request time: ${request}ms`);
  }
});
```

### オリジン間のタイミング情報

`responseStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、`Timing-Allow-Origin` HTTP レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-responsestart |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.toJSON() - Web API

PerformanceResourceTiming.toJSON()
==================================

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

構文
--

```js
toJSON()
```

### 引数

なし。

### 返値

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

例
-

### toJSON メソッドの使用

この例では、`entry.toJSON()` の呼び出しが `PerformanceResourceTiming` オブジェクトの JSON 表現を返します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    console.log(entry.toJSON());
  });
});

observer.observe({ type: "resource", buffered: true });
```

これはこのような JSON オブジェクトをログ出力します。

```json
{
  "name": "https://upload.wikimedia.org/wikipedia/en/thumb/4/4a/Commons-logo.svg/31px-Commons-logo.svg.png",
  "entryType": "resource",
  "startTime": 110.80000001192093,
  "duration": 11.599999994039536,
  "initiatorType": "img",
  "nextHopProtocol": "h2",
  "renderBlockingStatus": "non-blocking",
  "workerStart": 0,
  "redirectStart": 0,
  "redirectEnd": 0,
  "fetchStart": 110.80000001192093,
  "domainLookupStart": 110.80000001192093,
  "domainLookupEnd": 110.80000001192093,
  "connectStart": 110.80000001192093,
  "connectEnd": 110.80000001192093,
  "secureConnectionStart": 110.80000001192093,
  "requestStart": 117.30000001192093,
  "responseStart": 120.40000000596046,
  "responseStatus": 200,
  "responseEnd": 122.40000000596046,
  "transferSize": 0,
  "encodedBodySize": 880,
  "decodedBodySize": 880,
  "serverTiming": [
    {
      "name": "cache",
      "duration": 0,
      "description": "hit-front"
    },
    {
      "name": "host",
      "duration": 0,
      "description": "cp3061"
    }
  ]
}
```

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-tojson |

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

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

関連情報
----

* `JSON`


PerformanceResourceTiming.transferSize - Web API

PerformanceResourceTiming.transferSize
======================================

**`transferSize`** は読み取り専用プロパティで、取得したリソースのサイズ（オクテット数）を表します。サイズには、レスポンスヘッダーフィールドとレスポンスのペイロード本体（RFC7230 で定義されているとおり）が含まれます。

リソースがローカルキャッシュから取得された場合、またはオリジンを跨いだリソースの場合、このプロパティはゼロを返します。

値
-

`workerStart` プロパティは以下の値を取ることがあります。

* 取得したリソースのサイズ（オクテット数）を表します。サイズには、レスポンスヘッダーフィールドとレスポンスのペイロード本体（RFC7230 で定義されているとおり）が含まれます。
* サービスワーカーが使用されていない場合は `0`。
* リソースがオリジン間リクエストで、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されていない場合は `0`。
例
-

### キャッシュがヒットしたかどうかをチェック

`responseStatus` プロパティに対応していない環境では、`transferSize` プロパティを使用してキャッシュヒットを判定することができます。transferSize` がゼロで、リソースがゼロ以外のデコード本体サイズを持っている場合（リソースがsame-originであるか、`Timing-Allow-Origin`があるという意味）、リソースはローカルキャッシュからフェッチされたものであることを示します。

ブラウザーのパフォーマンスタイムラインに記録された新しい `resource` パフォーマンス項目を通知する `PerformanceObserver` を使用した例です。オブザーバーが作成される前の項目にアクセスするには、`buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.transferSize === 0 && entry.decodedBodySize > 0) {
      console.log(`${entry.name} was loaded from cache`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  if (entry.transferSize === 0 && entry.decodedBodySize > 0) {
    console.log(`${entry.name} was loaded from cache`);
  }
});
```

### オリジン間のコンテンツサイズの情報

`transferSize` プロパティの値が `0` で、ローカルキャッシュから読み込まれなかったものである場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間リクエストのコンテンツサイズ情報を公開するには、`Timing-Allow-Origin` HTTP レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にコンテンツサイズを表示することを許可するには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-transfersize |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.initiatorType - Web API

PerformanceResourceTiming.initiatorType
=======================================

**`initiatorType`** は読み取り専用プロパティで、リソースの読み込みを開始したウェブプラットフォームの機能を表す文字列です。

**メモ:** このプロパティは、読み込まれるコンテンツの種類を表すものではありません。`.css` ファイルは `<link>` 要素を使用して読み込むことができ、 `initiatorType` が `link` となります。CSS ファイルで `background: url()` を使用して画像を読み込んだ場合、 `initiatorType` は `img` ではなく `css` になります。

値
-

`initatorType` プロパティは以下の値を取ることができ、どの条件にも一致しない場合は `other` を取ることができます。

`audio`

このリクエストが `<audio>` 要素の `src` 属性によって開始された場合。

`beacon`

このリクエストが `navigator.sendBeacon()` メソッドによって開始された場合。

`body`

このリクエストが `<body>` 要素の `background` 属性によって開始された場合。

`css`

このリクエストが CSS の `url()` 関数によって開始された場合。

`early-hint`

このリクエストが `103` の `Early Hint` レスポンスによって開始された場合。

`embed`

このリクエストが `<embed>` 要素の `src` 属性によって開始された場合。

`fetch`

このリクエストが `fetch()` メソッドによって開始された場合。

`frame`

このリクエストが `<frame>` 要素の読み込みによって開始された場合。

`iframe`

このリクエストが `<iframe>` 要素の `src` 属性によって開始された場合。

`icon`
Non-standard

このリクエストがファビコンによって開始された場合。標準外であり、Safari でのみ報告されます。

`image`

このリクエストが `<image>` 要素によって開始された場合。

`img`

このリクエストが `<img>` 要素の `src` または `srcset` 属性によって開始された場合。

`input`

このリクエストが `<input>` 要素の `image` 型によって開始された場合。

`link`

このリクエストが `<link>` 要素によって開始された場合。

`navigation`

このリクエストがナビゲーションリクエストによって開始された場合。

`object`

このリクエストが `<object>` 要素によって開始された場合。

`ping`

このリクエストが `<a>` 要素の `ping` によって開始された場合。

`script`

このリクエストが `<script>` 要素によって開始された場合。

`track`

このリクエストが `<track>` 要素の `src` によって開始された場合。

`video`

このリクエストが `<video>` 要素の `poster` または `src` によって開始された場合。

`xmlhttprequest`

このリクエストが `XMLHttpRequest` によって開始された場合。

例
-

### リソースのフィルタリング

`initiatorType` プロパティを使用すると、特定のリソー スタイミング項目のみを取得することができます。例えば、`<script>` 要素によって開始されたものだけを取得することができます。

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  const scripts = list.getEntries().filter((entry) => {
    return entry.initiatorType === "script";
  });
  console.log(scripts);
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const scripts = performance.getEntriesByType("resource").filter((entry) => {
  return entry.initiatorType === "script";
});
console.log(scripts);
```

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-initiatortype |

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

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


PerformanceResourceTiming.requestStart - Web API

PerformanceResourceTiming.requestStart
======================================

**`requestStart`** は読み取り専用プロパティで、ブラウザーがサーバ、キャッシュ、またはローカルリソースにリソースのリクエストを開始する直前の `timestamp` を返します。トランスポート接続が失敗してブラウザーがリクエストを終了すると、返される値は再試行要求の開始になります。

`requestStart` には *end* プロパティはありません。リクエスト時間を計測するには、 `responseStart` - `requestStart` を計算してください（下記の例を参照してください）。

値
-

`requestStart` プロパティは以下の値を取ります。

* ブラウザーがサーバーからリソースのリクエストを始める直前の時刻を表す `DOMHighResTimeStamp` です。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### リクエスト時間の計測

`requestStart` と `responseStart` プロパティを使用して、、リクエストにかかる時間を測定することができます。

```js
const request = entry.responseStart - entry.requestStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const request = entry.responseStart - entry.requestStart;
    if (request > 0) {
      console.log(`${entry.name}: Request time: ${request}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const request = entry.responseStart - entry.requestStart;
  if (request > 0) {
    console.log(`${entry.name}: Request time: ${request}ms`);
  }
});
```

### オリジン間のタイミング情報

`requestStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、`Timing-Allow-Origin` HTTP レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-requeststart |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.connectStart - Web API

PerformanceResourceTiming.connectStart
======================================

**`connectStart`** は読み取り専用プロパティで、リソースを取得するためにユーザーエージェントがサーバへの接続の確立を開始する直前の `timestamp` を返します。

値
-

`connectStart` プロパティは以下の値を取ります。

* ブラウザーがリソースを取得するためにサーバーとのコネクションを確立し始める直前の `DOMHighResTimeStamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### TCP ハンドシェイク時間の計測

`connectStart` と `connectEnd` プロパティを使用して、 TCP ハンドシェイクが発生したときにどれくらいかかるかを計測することができます。

```js
const tcp = entry.connectEnd - entry.connectStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const tcp = entry.connectEnd - entry.connectStart;
    if (tcp > 0) {
      console.log(`${entry.name}: TCP handshake duration: ${tcp}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const tcp = entry.connectEnd - entry.connectStart;
  if (tcp > 0) {
    console.log(`${entry.name}: TCP handshake duration: ${tcp}ms`);
  }
});
```

### オリジン間のタイミング情報

`connectStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-connectstart |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.connectEnd - Web API

PerformanceResourceTiming.connectEnd
====================================

**`connectEnd`** は読み取り専用プロパティで、ブラウザーがリソースを取得するためにサーバーへの接続を確立し終わった直後の `timestamp` を返します。このタイムスタンプ値には、トランスポート接続を確立するための時間、TLS ハンドシェイクや SOCKS 認証などの他の時間が含まれます。

値
-

`connectEnd` プロパティは以下の値を取ります。

* 接続が確立された後の時間を表す `DOMHighResTimeStamp`。
* リソースがキャッシュから即座に取得された場合は `0` です。
* リソースがオリジン間リクエストで取得され、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されなかった場合は `0` となります。
例
-

### TCP ハンドシェイク時間の計測

`connectEnd` と `connectStart` プロパティを使用して、 TCP ハンドシェイクが発生したときにどれくらいかかるかを計測することができます。

```js
const tcp = entry.connectEnd - entry.connectStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const tcp = entry.connectEnd - entry.connectStart;
    if (tcp > 0) {
      console.log(`${entry.name}: TCP handshake duration: ${tcp}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const tcp = entry.connectEnd - entry.connectStart;
  if (tcp > 0) {
    console.log(`${entry.name}: TCP handshake duration: ${tcp}ms`);
  }
});
```

### オリジン間のタイミング情報

`connectEnd` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-connectend |

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

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

関連情報
----

* `Timing-Allow-Origin`


PerformanceResourceTiming.serverTiming - Web API

PerformanceResourceTiming.serverTiming
======================================

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

**`serverTiming`** は読み取り専用プロパティで、サーバーのタイミング測定が入った `PerformanceServerTiming` (en-US) 項目の配列を返します。

サーバーのタイミング測定では、サーバーが次のような `Server-Timing` ヘッダーを送信する必要があります。

```http
Server-Timing: cache;desc="Cache Read";dur=23.2
```

`serverTiming` の項目は、 `navigation` と `resource` の項目で使用することができます。

値
-

`PerformanceServerTiming` (en-US) 項目の配列です。

例
-

### サーバータイミング項目のログ出力

`PerformanceObserver` を使用して、 `PerformanceServerTiming` (en-US) 項目を監視することができます。各サーバー項目の時間は、コンソールにログ出力されます。

ブラウザーに記録された新しい `resource` パフォーマンス項目を通知する `PerformanceObserver` を使用した例です。オブザーバーが作成される前の項目にアクセスするには `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    entry.serverTiming.forEach((serverEntry) => {
      console.log(`${serverEntry.name} duration: ${serverEntry.duration}`);
    });
  });
});

["navigation", "resource"].forEach((type) =>
  observer.observe({ type, buffered: true }),
);
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
for (const entryType of ["navigation", "resource"]) {
  for (const { name: url, serverTiming } of performance.getEntriesByType(
    entryType,
  )) {
    if (serverTiming) {
      for (const { name, duration } of serverTiming) {
        console.log(`${url}: ${name} duration: ${duration}`);
      }
    }
  }
}
```

### オリジン外へのサーバータイミング情報の公開

サーバーのタイミング情報へのアクセスは、同じオリジン内に制限されます。オリジンをまたいでタイミング情報を公開するには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にサーバーのタイミング情報を見ることを許可するには、cross-origin リソースを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Server Timing # servertiming-attribute |

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

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

関連情報
----

* `PerformanceServerTiming` (en-US)
* `Server-Timing`


PerformanceResourceTiming.nextHopProtocol - Web API

PerformanceResourceTiming.nextHopProtocol
=========================================

**`nextHopProtocol`** は読み取り専用プロパティで、リソースを取得するために使用されるネットワークプロトコルを表す ALPN プロトコル ID (RFC7301) で識別される文字列です。

プロキシーが使用されている場合、トンネル接続が確立されていると、このプロパティはトンネリングプロトコルの ALPN プロトコル ID を返します。それ以外の場合、このプロパティはプロキシーへの最初のホップの ALPN プロトコル ID を返します。

値
-

`nextHopProtocol` プロパティは、以下の値を取ります。

* リソースを取得するために使用されるネットワークプロトコルを表す ALPN プロトコル ID (RFC7301) で識別される文字列。よくある値は次の通りです。
    + `"http/0.9"`
    + `"http/1.0"`
    + `"http/1.1"`
    + `"h2"`
    + `"h2c"`
    + `"h3"`
* リソースがオリジン間リクエストで、HTTP の `Timing-Allow-Origin` ヘッダーが使用されていない場合は空文字列。
例
-

### HTTP/2 も HTTP/3 も使用していないリソースを記録

`nextHopProtocol` プロパティを使用すると、HTTP/2 や HTTP/3 プロトコルを使用しないリソースを確認することができます。

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const protocol = entry.nextHopProtocol;
    if (protocol && !(protocol === "h2" || protocol === "h3")) {
      console.log(`${entry.name} uses ${protocol}.`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const protocol = entry.nextHopProtocol;
  if (protocol && !(protocol === "h2" || protocol === "h3")) {
    console.log(`${entry.name} uses ${protocol}.`);
  }
});
```

### オリジン間のネットワークプロトコル情報

`nextHopProtocol` プロパティの値が空文字列である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間のタイミング情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` にタイミングリソースを見ることを許可するには、オリジン間リソースで次のものを送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-nexthopprotocol |

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

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

関連情報
----

* `Timing-Allow-Origin`
* HTTP/2
* HTTP/3


PerformanceResourceTiming.fetchStart - Web API

PerformanceResourceTiming.fetchStart
====================================

**`fetchStart`** は読み取り専用プロパティで、ブラウザーがリソースの取得を開始する直前の `timestamp` を表します。

HTTP リダイレクトがある場合、このプロパティは、ユーザーエージェントがリダイレクトの最後のリソースの取得を開始する直前の時間を返します。

他の多くの `PerformanceResourceTiming` プロパティとは異なり、 `fetchStart` プロパティは `Timing-Allow-Origin` がなくてもオリジン間リクエストで利用することができます。

値
-

ブラウザーがリソースの取得を開始する直前の `DOMHighResTimeStamp`。

例
-

### フェッチ時間の計測（リダイレクトを除く）

`fetchStart` と `responseEnd` プロパティを使用すると、（リダイレクトなしで）最終リソースを取得するのにかかった全体の時間を計測することができます。リダイレクトを含めるために、フェッチにかかった全体の時間は `duration` プロパティで提供されます。

```js
const timeToFetch = entry.responseEnd - entry.fetchStart;
```

`PerformanceObserver` を使用した例です。このオブジェクトは、新しい `resource` パフォーマンス項目がブラウザーのパフォーマンスタイムラインに記録されると、それを通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const timeToFetch = entry.responseEnd - entry.fetchStart;
    if (timeToFetch > 0) {
      console.log(`${entry.name}: Time to fetch: ${timeToFetch}ms`);
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const timeToFetch = entry.responseEnd - entry.fetchStart;
  if (timeToFetch > 0) {
    console.log(`${entry.name}: Time to fetch: ${timeToFetch}ms`);
  }
});
```

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-fetchstart |

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

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


PerformanceResourceTiming.workerStart - Web API

PerformanceResourceTiming.workerStart
=====================================

**`workerStart`** は `PerformanceResourceTiming` インターフェイスの読み取り専用プロパティで、サービスワーカーのスレッドが既に実行されている場合は `FetchEvent` を送出する直前、またはサービスワーカーのスレッドがまだ実行されていない場合は、開始される直前に `DOMHighResTimeStamp` を返します。このリソースがサービスワーカーに介入されない場合、このプロパティは常に 0 を返します。

値
-

`workerStart` プロパティは以下の値を取ることがあります。

* `DOMHighResTimeStamp`
* サービスワーカーが使用されていない場合は `0`。
* リソースがオリジン間リクエストで、HTTP の `Timing-Allow-Origin` レスポンスヘッダーが使用されていない場合は `0`。
例
-

### サービスワーカーの処理時間の計測

`workerStart` および `fetchStart` プロパティを使用して、 `ServiceWorker` の処理時間を計測することができます。

```js
const workerProcessingTime = entry.fetchStart - entry.workerStart;
```

`PerformanceObserver` の使用例で、ブラウザーのパフォーマンスタイムラインに記録された新しい `resource` パフォーマンス項目を通知します。オブザーバーが作成される前の項目にアクセスするために `buffered` オプションを使用します。

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    const workerProcessingTime = entry.fetchStart - entry.workerStart;
    if (workerProcessingTime > 0) {
      console.log(
        `${entry.name}: Worker processing time: ${workerProcessingTime}ms`,
      );
    }
  });
});

observer.observe({ type: "resource", buffered: true });
```

`Performance.getEntriesByType()` を使用した例です。このメソッドを呼び出した時点でブラウザー上のパフォーマンスタイムラインに存在する `resource` パフォーマンス項目のみを表示します。

```js
const resources = performance.getEntriesByType("resource");
resources.forEach((entry) => {
  const workerProcessingTime = entry.fetchStart - entry.workerStart;
  if (workerProcessingTime > 0) {
    console.log(
      `${entry.name}: Worker processing time: ${workerProcessingTime}ms`,
    );
  }
});
```

### オリジン間のタイミング情報

`workerStart` プロパティの値が `0` である場合、そのリソースはオリジン間リクエストである可能性があります。オリジン間の時刻情報を見るためには、HTTP の `Timing-Allow-Origin` レスポンスヘッダーを設定する必要があります。

例えば、`https://developer.mozilla.org` に時刻リソースを見ることを許可するには、オリジン間リソースが送信する必要があります。

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

仕様書
---

| Specification |
| --- |
| Resource Timing # dom-performanceresourcetiming-workerstart |

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

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

関連情報
----

* `Timing-Allow-Origin`


MediaQueryList: change イベント - Web API

MediaQueryList: change イベント
===========================

`MediaQueryList` インターフェイスの **`change`** イベントは、メディアクエリーの状態が変化した時に発生します。

構文
--

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

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

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

イベントタイプ
-------

`MediaQueryListEvent` (en-US) です。 `Event` から継承します。

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

*`MediaQueryListEvent` インタフェースは、親インタフェースである `Event` からプロパティを継承します。*

`MediaQueryListEvent.matches`読取専用

`Boolean`。 `document` が現在メディアクエリーのリストに一致していれば `true` を返し、そうでなければ `false` を返します。

`MediaQueryListEvent.media`読取専用

`DOMString` で、シリアライズされたメディアクエリーを表します。

例
-

```js
var mql = window.matchMedia("(max-width: 600px)");

mql.onchange = (e) => {
  if (e.matches) {
    /\* ビューポートが 600 ピクセル幅以下 \*/
    console.log("This is a narrow screen — less than 600px wide.");
  } else {
    /\* ビューポートが 600 ピクセル幅より広い \*/
    console.log("This is a wide screen — more than 600px wide.");
  }
};
```

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-mediaquerylist-onchange |

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

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

関連情報
----

* メディアクエリー
* プログラムによるメディアクエリーの評価
* `window.matchMedia()`
* `MediaQueryList`
* `MediaQueryListEvent` (en-US)


MediaQueryList.media - Web API

MediaQueryList.media
====================

**`media`** は `MediaQueryList` インターフェイスの読取専用プロパティであり、 文字列で、シリアライズされたメディアクエリーを表します。

### 値

文字列で、シリアライズされたメディアクエリーを表します。

例
-

この例では、 `(max-width: 600px)` のメディアクエリーを実行し、 `MediaQueryList` の `media` プロパティの結果の値を `<span>` の中に表示します。

### JavaScript

```js
let mql = window.matchMedia("(max-width: 600px)");

document.querySelector(".mq-value").innerText = mql.media;
```

この JavaScript コードは一致させるメディアクエリーを単に `matchMedia()` に渡してコンパイルし、それから `<span>` の `innerText` に `media` プロパティの結果の値を設定します。

### HTML

```html
<span class="mq-value"></span>
```

シンプルな `<span>` は出力を受け取るためのものです。
```

.mq-value {
  font:
    18px arial,
    sans-serif;
  font-weight: bold;
  color: #88f;
  padding: 0.4em;
  border: 1px solid #dde;
}
```

### 結果

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-mediaquerylist-media |

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

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

関連情報
----

* メディアクエリー
* プログラムによるメディアクエリーの評価
* `window.matchMedia()`
* `MediaQueryList`
* `MediaQueryListEvent` (en-US)


MediaQueryList.matches - Web API

MediaQueryList.matches
======================

**`matches`** は `MediaQueryList` インターフェイスの読み取り専用プロパティで、 `boolean` であり、文書が現在メディアクエリーリストと一致している場合は `true` を返し、一致していない場合は `false` を返します。

`matches` の値が変化した場合は、 `MediaQueryList` で発生する `change` イベントを監視することで通知を受けることができます。

### 値

boolean。 `document` が現在メディアクエリーのリストに一致していれば `true` を返し、そうでなければ `false` を返します。

例
-

この例では `orientation` メディア特性を使用したメディアクエリーを作成することにより、ビューポートの向きの変化を検出します。

```js
function addMQListener(mq, callback) {
  if (mq.addEventListener) {
    mq.addEventListener("change", callback);
  } else {
    mq.addListener(callback);
  }
}

addMQListener(window.matchMedia("(orientation:landscape)"), (event) => {
  if (event.matches) {
    /\* 横向きの画面になった \*/
  } else {
    /\* 縦向きの画面になった \*/
  }
});
```

仕様書
---

| Specification |
| --- |
| CSSOM View Module # dom-mediaquerylist-matches |

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

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

関連情報
----

* メディアクエリー
* プログラムによるメディアクエリーの評価
* `window.matchMedia()`
* `MediaQueryList`
* `MediaQueryListEvent` (en-US)


USBDevice: isochronousTransferIn() メソッド - Web API

USBDevice: isochronousTransferIn() メソッド
=======================================

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

`USBDevice` インターフェイスの **`isochronousTransferIn()`** メソッドは、時間が重要な情報の USB デバイスへの送信 (USB デバイスによる受信) が完了したら `USBIsochronousInTransferResult` で解決する `Promise` を返します。

構文
--

```js
isochronousTransferIn(endpointNumber, packetLengths)
```

### 引数

`endpointNumber`

デバイス固有のエンドポイント (バッファー) の番号です。

`packetLengths`

受信するパケットの長さの配列です。

### 返値

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

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-isochronoustransferin |

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

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


USBDevice: isochronousTransferOut() メソッド - Web API

USBDevice: isochronousTransferOut() メソッド
========================================

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

`USBDevice` インターフェイスの **`isochronousTransferOut()`** メソッドは、時間が重要な情報の USB デバイスからの転送が完了したら `USBIsochronousOutTransferResult` で解決する `Promise` を返します。

構文
--

```js
isochronousTransferOut(endpointNumber, data, packetLengths)
```

### 引数

`endpointNumber`

デバイス固有のエンドポイント (バッファー) の番号です。

`data`

デバイスに送信するデータが格納された `TypedArray` です。

`packetLengths`

送信するパケットの長さの配列です。

### 返値

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

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-isochronoustransferout |

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

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


USBDevice: configuration プロパティ - Web API

USBDevice: configuration プロパティ
==============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`configuration`** は、ペアリングした USB デバイスの現在選択されているインターフェイスを表す `USBConfiguration` オブジェクトを返します。

値
-

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

例
-

以下の例では、インターフェイスを要求する前にコンフィギュレーションを選択するため、`USBConfiguration` プロパティの存在を確認するためにこのプロパティを使用しています。

```js
async function connectDevice(usbDevice) {
  await usbDevice.open();
  if (usbDevice.configuration === null) await usbDevice.selectConfiguration(1);
  await usbDevice.claimInterface(0);
}
```

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-configuration① |

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

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


USBDevice: vendorId プロパティ - Web API

USBDevice: vendorId プロパティ
=========================

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

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

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`vendorId`** は、usb.org で割り当てられた公式なベンダー ID です。

値
-

usb.org で割り当てられた公式なベンダー ID です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-vendorid |

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

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


USBDevice: forget() メソッド - Web API

USBDevice: forget() メソッド
========================

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

`USBDevice` インターフェイスの **`forget()`** メソッドは、すべての実行中の操作が中止され、すべての開いているインターフェイスが解放され、デバイスのセッションが終了し、許可をリセットしたら解決する `Promise` を返します。

構文
--

```js
forget()
```

### 引数

なし

### 返値

デバイスのアクセス許可を取り消したら `undefined` で解決する `Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # dom-usbdevice-forget |

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

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


USBDevice: deviceVersionMajor プロパティ - Web API

USBDevice: deviceVersionMajor プロパティ
===================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceVersionMajor`** は、セマンティックバージョニングスキームによるデバイスのメジャーバージョン番号です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionmajor |

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

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


USBDevice: transferIn() メソッド - Web API

USBDevice: transferIn() メソッド
============================

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

`USBDevice` インターフェイスの **`transferIn()`** メソッドは、USB デバイスからバルクまたはインタラプトデータを受信したら `USBInTransferResult` で解決する `Promise` を返します。

構文
--

```js
transferIn(endpointNumber, length)
```

### 引数

`endpointNumber`

デバイス固有のエンドポイント (バッファー) の番号です。

`length`

デバイスから受信する最大のバイト数です。実際のデータは、解決したプロミス内の `USBInTransferResult` に格納されています。

### 返値

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

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-transferin① |

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

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


USBDevice: manufacturerName プロパティ - Web API

USBDevice: manufacturerName プロパティ
=================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`manufacturerName`** は、この USB デバイスを製造した組織の名前です。

値
-

文字列です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-manufacturername |

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

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


USBDevice: selectConfiguration() メソッド - Web API

USBDevice: selectConfiguration() メソッド
=====================================

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

`USBDevice` インターフェイスの **`selectConfiguration()`** メソッドは、指定のコンフィギュレーションが選択されたら解決する `Promise` を返します。

構文
--

```js
selectConfiguration(configurationValue)
```

### 引数

`configurationValue`

デバイス固有のコンフィグレーションの番号です。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # dom-usbdevice-selectconfiguration |

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

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


USBDevice: deviceClass プロパティ - Web API

USBDevice: deviceClass プロパティ
============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceClass`** は、デバイスとともに動く USB ドライバーのロード用に USB デバイスを特定する 3 個のプロパティのうちの 1 個です。他の 2 個のプロパティは `USBDevice.deviceSubclass` と `USBDevice.deviceProtocol` です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceclass |

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

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


USBDevice: controlTransferOut() メソッド - Web API

USBDevice: controlTransferOut() メソッド
====================================

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

`USBDevice` インターフェイスの **`controlTransferOut()`** メソッドは、コマンドまたは状態の操作の USB デバイスからの転送が完了したら `USBOutTransferResult` で解決する `Promise` を返します。

構文
--

```js
controlTransferOut(setup, data)
```

### 引数

`setup`

オプションを設定するオブジェクトです。以下のオプションが使用可能です。

`requestType`

転送の性質を示します。`"standard"` (すべての USB デバイスに共通)、`"class"` (業界標準のクラスまたはデバイスに共通)、`"vendor"` のいずれかの値でなければなりません。

`recipient`

デバイス上の転送の対象を指定します。`"device"`、`"interface"`、`"endpoint"`、`"other"` のいずれかです。

`request`

ベンダー固有のコマンドです。

`value`

ベンダー固有のリクエストパラメーターです。

`index`

宛先のインターフェイス番号です。

`data`

デバイスに転送されるデータが格納された `TypedArray` です。すべてのコマンドで `data` が必要なわけではありません。引数 `value` だけでデータを送ることができるコマンドもあります。特定の要求に何が必要かは、デバイスを確認してください。

### 返値

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

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-controltransferout① |

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

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


USBDevice: transferOut() メソッド - Web API

USBDevice: transferOut() メソッド
=============================

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

`USBDevice` インターフェイスの **`transferOut()`** メソッドは、USB デバイスにバルクまたはインタラプトデータを送信したら `USBOutTransferResult` で解決する `Promise` を返します。

構文
--

```js
transferOut(endpointNumber, data)
```

### 引数

`endpointNumber`

デバイス固有のエンドポイント (バッファー) の番号です。

`data`

デバイスに送信するデータが格納された `TypedArray` です。

### 返値

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

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-transferout |

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

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


USBDevice: deviceVersionMinor プロパティ - Web API

USBDevice: deviceVersionMinor プロパティ
===================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceVersionMinor`** は、セマンティックバージョニングスキームによるデバイスのマイナーバージョン番号です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionminor |

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

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


USBDevice: releaseInterface() メソッド - Web API

USBDevice: releaseInterface() メソッド
==================================

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

`USBDevice` インターフェイスの **`releaseInterface()`** メソッドは、要求済みのインターフェイスが排他アクセスから解放されたら解決する `Promise` を返します。

構文
--

```js
releaseInterface(interfaceNumber)
```

### 引数

`interfaceNumber`

現在要求済みのインターフェイスのデバイス固有のインデックスです。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-releaseinterface① |

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

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


USBDevice: configurations プロパティ - Web API

USBDevice: configurations プロパティ
===============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`configurations`** は、ペアリングした USB デバイスの制御用のデバイス固有のインターフェイスの `array` を返します。

値
-

`USBConfiguration` オブジェクトの `array` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-configurations① |

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

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


USBDevice: opened プロパティ - Web API

USBDevice: opened プロパティ
=======================

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

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

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`opened`** は、ペアリングした USB デバイスとのセッションが開始しているかを表します。デバイスは、ウェブページから制御する前に開かれなければなりません。

値
-

`boolean` です。

例
-

この例では、複数の色がある LED を搭載した仮想の USB デバイスを扱います。この例は、`USBDevice.controlTransferOut` を呼び出して LED の色を設定する前にデバイスが開かれているかを確認する方法を示します。

**メモ:** USB デバイスにどのようなデータを渡すか、そしてどのようにそれを渡すかは、各デバイスに固有で独特です。

```js
async function setDeviceColor(usbDevice, r, g, b) {
  if (device.opened) {
    // この仮想 USB デバイスに渡すデータは Uint8Array でなければならない
    const payload = new Uint8Array([r, g, b]);

    await usbDevice.controlTransferOut(
      {
        requestType: "vendor",
        recipient: "device",
        request: 1,
        value: 0,
        index: 0,
      },
      payload,
    );
  }
}
```

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-opened |

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

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


USBDevice: serialNumber プロパティ - Web API

USBDevice: serialNumber プロパティ
=============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`serialNumber`** は、製造元が定義する、特定の USB デバイスのシリアル番号です。

値
-

特定の USB デバイスのシリアル番号です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-serialnumber |

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

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


USBDevice: usbVersionMajor プロパティ - Web API

USBDevice: usbVersionMajor プロパティ
================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`usbVersionMajor`** は、デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの 1個です。他の 2 個のプロパティは `USBDevice.usbVersionMinor` と `USBDevice.usbVersionSubminor` です。

値
-

デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの最後です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-usbversionmajor |

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

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


USBDevice: clearHalt() メソッド - Web API

USBDevice: clearHalt() メソッド
===========================

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

`USBDevice` インターフェイスの **`clearHalt()`** メソッドは、停止状態のクリアが完了したら解決する `Promise` を返します。停止状態はデバイスへ、またはデバイスからのデータ転送が `'stall'` 状態であるときであり、ウェブページ (USB の用語では *ホスト* システム) がこの状態をクリアする必要があります。詳細を参照してください。

構文
--

```js
clearHalt(direction, endpointNumber)
```

### 引数

`direction`

デバイスの入力または出力のどっちをクリアするかを表します。有効な値は `'in'` および `'out'` です。

`endpointNumber`

クリアするエンドポイントの番号を表します。無効なエンドポイントが指定された場合は、プロミスは拒否されます。

### 返値

`promise` です。

例
-

以下の例は、データ転送の結果の `'stall'` 状態をチェックしてクリアする方法を示します。

**メモ:** USB デバイスにどのようなデータを渡すことができ、それをどのように渡すかは、デバイスに固有で独特です。

```js
while (true) {
  let result = await data.transferIn(1, 6);

  if (result.data && result.data.byteLength === 6) {
    console.log(`チャンネル 1: ${result.data.getUint16(0)}`);
    console.log(`チャンネル 2: ${result.data.getUint16(2)}`);
    console.log(`チャンネル 5: ${result.data.getUint16(4)}`);
  }

  if (result.status === "stall") {
    console.warn("エンドポイントがストールしました。クリアします。");
    await device.clearHalt("in", 1);
  }
}
```

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-clearhalt① |

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

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


USBDevice: deviceVersionSubminor プロパティ - Web API

USBDevice: deviceVersionSubminor プロパティ
======================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceVersionSubminor`** は、セマンティックバージョニングスキームによるデバイスのパッチバージョン番号です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionsubminor |

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

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


USBDevice: selectAlternateInterface() メソッド - Web API

USBDevice: selectAlternateInterface() メソッド
==========================================

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

`USBDevice` インターフェイスの **`selectAlternateInterface()`** メソッドは、指定のオルタナティブエンドポイントが選択されたら解決する `Promise` を返します。

構文
--

```js
selectAlternateInterface(interfaceNumber, alternateSetting)
```

### 引数

`interfaceNumber`

デバイスが対応しているインターフェイスのうちの 1 個のインデックスです。インターフェイスはデバイス固有です。

`alternateSetting`

選択されたインターフェイスのコンフィグレーションです。

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-selectalternateinterface |

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

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


USBDevice: usbVersionSubminor プロパティ - Web API

USBDevice: usbVersionSubminor プロパティ
===================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`usbVersionSubminor`** は、デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの 1個です。他の 2 個のプロパティは `USBDevice.usbVersionMajor` と `USBDevice.usbVersionMinor` です。

値
-

デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの最初です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-usbversionsubminor |

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

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


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

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

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

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

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

`USBDevice` インターフェイスの **`close()`** メソッドは、すべての開いているインターフェイスが解放され、デバイスのセッションが終了したら解決する `Promise` を返します。

構文
--

```js
close()
```

### 引数

なし

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-close |

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

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


USBDevice: controlTransferIn() メソッド - Web API

USBDevice: controlTransferIn() メソッド
===================================

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

`USBDevice` インターフェイスの **`controlTransferIn()`** メソッドは、コマンドまたは状態の操作の要求の USB デバイスへの送信 (USB デバイスでの受信) が完了したら `USBInTransferResult` で解決する `Promise` を返します。

構文
--

```js
controlTransferIn(setup, length)
```

### 引数

`setup`

オプションを設定するオブジェクトです。以下のオプションが使用可能です。

`requestType`

転送の性質を示します。`"standard"` (すべての USB デバイスに共通)、`"class"` (業界標準のクラスまたはデバイスに共通)、`"vendor"` のいずれかの値でなければなりません。

`recipient`

デバイス上の転送の対象を指定します。`"device"`、`"interface"`、`"endpoint"`、`"other"` のいずれかです。

`request`

ベンダー固有のコマンドです。

`value`

ベンダー固有のリクエストパラメーターです。

`index`

宛先のインターフェイス番号です。

`length`

デバイスから読み取る最大のバイト数です。実際のデータは、解決したプロミス内の `USBInTransferResult` に格納されます。

### 返値

`USBInTransferResult` で解決する `promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-controltransferin |

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

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


USBDevice: deviceSubclass プロパティ - Web API

USBDevice: deviceSubclass プロパティ
===============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceSubclass`** は、デバイスとともに動く USB ドライバーのロード用に USB デバイスを特定する 3 個のプロパティのうちの 1 個です。他の 2 個のプロパティは `USBDevice.deviceClass` と `USBDevice.deviceProtocol` です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-devicesubclass |

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

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


USBDevice: claimInterface() メソッド - Web API

USBDevice: claimInterface() メソッド
================================

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

`USBDevice` インターフェイスの **`claimInterface()`** メソッドは、要求したインターフェイスの排他アクセスを獲得したら解決する `Promise` を返します。

構文
--

```js
claimInterface(interfaceNumber)
```

### 引数

`interfaceNumber`

デバイスが対応しているインターフェイスのうち 1 個のインデックスです。インターフェイスはデバイス固有です。

### 返値

`promise` です。

例
-

以下の例では、USB デバイスへの接続時に使用される `claimInterface()` を示します。

```js
async function connectDevice(usbDevice) {
  await usbDevice.open();
  if (usbDevice.configuration === null) await usbDevice.selectConfiguration(1);
  await usbDevice.claimInterface(0);
}
```

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-claiminterface② |

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

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


USBDevice: reset() メソッド - Web API

USBDevice: reset() メソッド
=======================

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

`USBDevice` インターフェイスの **`reset()`** メソッドは、デバイスがリセットされ、アプリケーションによる操作がすべてキャンセルされ、それらのプロミスが拒否されたら解決する `Promise` を返します。

構文
--

```js
reset()
```

### 引数

なし

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-reset |

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

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


USBDevice: deviceProtocol プロパティ - Web API

USBDevice: deviceProtocol プロパティ
===============================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`deviceProtocol`** は、デバイスとともに動く USB ドライバーのロード用に USB デバイスを特定する 3 個のプロパティのうちの 1 個です。他の 2 個のプロパティは `USBDevice.deviceClass` と `USBDevice.deviceSubclass` です。

値
-

数値です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceprotocol |

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

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


USBDevice: open() メソッド - Web API

USBDevice: open() メソッド
======================

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

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

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

`USBDevice` インターフェイスの **`open()`** メソッドは、デバイスのセッションが開始したら解決する `Promise` を返します。

構文
--

```js
open()
```

### 引数

なし

### 返値

`Promise` です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-open① |

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

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


USBDevice: usbVersionMinor プロパティ - Web API

USBDevice: usbVersionMinor プロパティ
================================

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`usbVersionMinor`** は、デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの 1個です。他の 2 個のプロパティは `USBDevice.usbVersionMajor` と `USBDevice.usbVersionSubminor` です。

値
-

デバイスが対応している USB のプロトコルバージョンを表す 3 個のプロパティのうちの 2 番目です。

仕様書
---

| Specification |
| --- |
| WebUSB API # dom-usbdevice-usbversionminor |

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

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


USBDevice: productId プロパティ - Web API

USBDevice: productId プロパティ
==========================

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

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

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`productId`** は、製造元が定義する、USB デバイスを識別するコードです。

値
-

製造元が定義する、USB デバイスを識別するコードです。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-productid |

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

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


USBDevice: productName プロパティ - Web API

USBDevice: productName プロパティ
============================

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

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

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

`USBDevice` インターフェイスの読み取り専用プロパティ **`productName`** は、製造元が定義する、USB デバイスを識別する名前です。

値
-

製造元が定義する、USB デバイスを識別する名前です。

仕様書
---

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-productname |

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

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