performance.measure()
=====================

**`measure()`** メソッドは、マーク間、ナビゲーション開始時刻、または現在時刻の間に、ブラウザーの*パフォーマンスエントリーバッファー*に名前付き `timestamp` を作成します。

2 つのマーク間を測定するときは、それぞれ*開始マーク*と*終了マーク*があります。名前付きタイムスタンプは、*メジャー*と呼ばれます。

`measure` は、`Performance` インターフェイスのうち、
 (`getEntries()`,
 `getEntriesByName()`,
 `getEntriesByType()`) のいずれかを使用して取得できます。

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

構文
--


```js
measure(measureName);
measure(measureName, MeasureOptions);
measure(measureName, startMark);
measure(measureName, startMark, endMark);
```


`measureName` のみが指定された場合、開始タイムスタンプはゼロに設定され、（時間を計算するために使用される）終了タイムスタンプは `Performance.now()` から返される値になります。

### 引数

`measureName`

`DOMString` で、メジャーの名前を表します。

`MeasureOptions` 省略可

メジャーのすべてのオプションを含むオブジェクトです（`startMark` と `endMark` はこのオブジェクト内で指定することも、独自の引数で指定することもできます）。

`detail`

メジャーに含める任意のメタデータです。

`start`

 開始時刻として使用される `DOMHighResTimeStamp` のタイムスタンプ、または開始マークとして使用される `DOMString` です。
 これが開始マークの名前を表す場合は、 `startMark` の場合と同じように定義します（すなわち、既存のマークまたは `PerformanceTiming` プロパティの名前でなければなりません）。


`duration`

開始マークと終了マークのそれぞれの時刻 (`DOMHighResTimeStamp`) 間の時間.

`end`

 終了時刻として使用される `DOMHighResTimeStamp` のタイムスタンプ、または終了マークとして使用される `DOMString` です。
 これが終了マークの名前を表す場合は、 `endMark` の場合と同じように定義します（すなわち、既存のマークまたは `PerformanceTiming` プロパティの名前でなければなりません）。



`startMark` 省略可

`DOMString` で、このメジャーの開始マークの名前を表します。
 `PerformanceTiming` プロパティの名前にすることもできます。
 既存の `PerformanceMark` または `PerformanceTiming` を表していない名前を指定すると `SyntaxError` の `DOMException` が発生します。


`endMark` 省略可

`DOMString` で、このメジャーの終了マークの名前を表します。
 `PerformanceTiming` プロパティの名前にすることもできます。
 既存の `PerformanceMark` または `PerformanceTiming` を表していない名前を指定すると `SyntaxError` の `DOMException` が発生します。


### 返値

生成された `PerformanceMeasure` のエントリーです。

返される*メジャー*には、以下のプロパティ値になります。

* `entryType` - "`measure`" が設定されます。
* `name` - "`name`" 引数が設定されます。
* `startTime` - 以下のように設定されます。
    + `MeasureOptions.start` で指定された場合は `timestamp`。
    + `MeasureOptions.start` または `startMark` で指定された場合は、開始マークのタイムスタンプ。
    + `MeasureOptions.end` と `MeasureOptions.duration` から計算されたタイムスタンプ（`MeasureOptions.start` が指定されていない場合）。
    + 指定されておらず、他の値から特定することができない場合は 0。
* `duration` - `DOMHighResTimeStamp` で、終了タイムスタンプから `startTime` を引いて計算されたメジャーの時間を設定します。
 終了タイムスタンプは以下のいずれかになります。
    + `MeasureOptions.end` で指定された場合は `timestamp`。
    + `MeasureOptions.end` または `endMark` で指定された場合は、終了マークのタイムスタンプ。
    + `MeasureOptions.start` と `MeasureOptions.duration` から計算されたタイムスタンプ（`MeasureOptions.end` が指定されていない場合）。
    + 終了マークが指定されていないか、他の値から特定することができない場合は、 `Performance.now()` で返される値。
* `detail` - `MeasureOptions` で渡された値に設定されます。
例外
--

`TypeError` `DOMException`

start, end, duration の何れかが曖昧になる場合に発生します。

* `endMark` と `MeasureOptions` の両方が指定された。
* `MeasureOptions` が指定されたが、 `start` および `end` メンバーが指定されなかった。
* `MeasureOptions` が `start`, `end`, `duration` のメンバーすべてある状態（そして不整合な状態）で指定された。

`SyntaxError` `DOMException`

その名前のマークが存在しない場合に発生します。

* `endMark` または `MeasureOptions.end` のどちらかを使用してエンドマークが指定されたが、一致する名前のパフォーマンスバッファーに `PerformanceMark`がない。
* `endMark` または `MeasureOptions.end` のどちらかを使用してエンドマークが指定されたが、 `PerformanceTiming` インターフェイスの読み取り専用属性に変換することができない。
* 開始マークが `startMark` または `MeasureOptions.start` のどちらかで指定されているが、一致する名前のパフォーマンスバッファーに `PerformanceMark`がない。
* 開始マークが `startMark` または `MeasureOptions.start` のどちらかで指定されているが、 `PerformanceTiming` インターフェイスの読み取り専用属性に変換することができない。

`DataCloneError` `DOMException`

`MeasureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズできない場合です。

`RangeError`

`MeasureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズする際にメモリーが割り当てられなかった場合です。

例
-

次の例は、ブラウザーのパフォーマンスエントリーバッファーに `measure()` を使用して新しい*メジャー*`パフォーマンスエントリー`を作成する方法を示しています。


```js
const markerNameA = "example-marker-a"
const markerNameB = "example-marker-b"

// いくつかのネストしたタイムアウトを実行し、それぞれに対して PerformanceMark を作成します。
performance.mark(markerNameA);
setTimeout(function() {
  performance.mark(markerNameB);
  setTimeout(function() {

    // さまざまな測定値を作成します。
    performance.measure("measure a to b", markerNameA, markerNameB);
    performance.measure("measure a to now", markerNameA);
    performance.measure("measure from navigation start to b", undefined, markerNameB);
    performance.measure("measure from the start of navigation to now");

    // すべての測定値を引き出します。
    console.log(performance.getEntriesByType("measure"));

    // 最後に、エントリ-
    を整理します。
    performance.clearMarks();
    performance.clearMeasures();
  }, 1000);
}, 1000);
```

仕様書
---

| Specification |
| --- |
| User Timing # dom-performance-measure |

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

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