レイアウト不安定性 API

let perFrameLayoutShiftData = [];
let cumulativeLayoutShiftScore = 0;

function updateCLS(entries) {
  for (const entry of entries) {
    // Only count layout shifts without recent user input.
    if (entry.hadRecentInput)
      return;

    perFrameLayoutShiftData.push({
      score: entry.value,
      timestamp: entry.startTime
    });
    cumulativeLayoutShiftScore += entry.value;

    // Sources are sorted by impact area in descending order.
    // The first element contributed most to the layout shift.
    if (entry.sources && entry.sources.length > 0) {
      console.log('Largest contributing element:', entry.sources[0].node);
    }
  }
}

// Observe all layout shift occurrences.
const observer = new PerformanceObserver((list) => {
  updateCLS(list.getEntries());
});
observer.observe({type: 'layout-shift', buffered: true});

// Send final data to an analytics back end once the page is hidden.
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    // Force any pending records to be dispatched.
    updateCLS(observer.takeRecords());

    // Send data to your analytics back end (assumes `sendToAnalytics` is
    // defined elsewhere).
    sendToAnalytics({perFrameLayoutShiftData, cumulativeLayoutShiftScore});
  }
});

2. 用語

2.1. 基本概念

始点（starting point）は、座標空間 C における Node N の始点として次のように定義される：

• もし N が、1つ以上のボックスを生成する Element であれば、C における N の始点は、C の原点から フロー相対の始まりのコーナーまでの ピクセル単位での2次元オフセットであり、 それはNの主ボックスの最初の フラグメントのコーナーを指す。

• もし N がテキストノード であれば、C における N の始点は ピクセル単位 での原点から フロー相対なコーナーまでの 2次元オフセットであり、それは N によって生成された 最初のラインボックス のコーナーである。

変形非依存始点（transform-indifferent starting point）は、 Node N の C における 始点を、 すべての変形要素が 変換行列を単位行列とするかのように計算したものとする。

注: ノードがシフトしたかどうかを判断する際には、 トランスフォームを考慮した場合としない場合の始点を比較し、ノードがトランスフォームの変化のみで 不安定になることを防ぐ。ただし、視覚的表現やビューポート外への除外の計算には 常にCSSのトランスフォームが考慮される。

視覚的表現（visual representation） は Node N について以下のように定義される：

• もし N が1つ以上のボックスを生成する Element であれば、 N の視覚的表現は N が生成した全てのフラグメント内に存在する点の集合であり、 これはビューポートの座標空間において ビューポート外の点を除外したものである。

• もし N がテキストノード であれば、 N の視覚的表現は、N によって生成された全ての ラインボックス の内側にある各点の集合であり、 ビューポート の座標空間で、ビューポートの外の点は除外する。

ある条件が前フレーム時点で（in the previous frame）成立するとき、 それは直近のレイアウトシフト報告アルゴリズムの完了直後の 時点にその条件が真であったことを意味する。

前フレームの始点（previous frame starting point）は、 座標空間CにおけるNode Nについて、 前フレーム時点における 始点を指す。

前フレームの変形非依存始点（previous frame transform-indifferent starting point）は、 座標空間Cにおける Node Nについて、 前フレーム時点 での変形非依存始点を指す。

前フレームの視覚的表現（previous frame visual representation）は、 Node Nについて、 前フレーム時点 での視覚的表現の集合である。

各ユーザーエージェントは、レイアウトシフトと見なすかどうかを判定するのに使われる整数値 意義ありピクセル数（number of pixels to significance）を定義する。 この柔軟性により、ユーザーエージェントはパフォーマンスやユーザー体験を考慮して調整できる。

点Aが点Bと大きく異なる（differs significantly）とは、 AとBが 意義ありピクセル数以上だけ 水平または垂直方向のいずれかで ピクセル単位で異なる場合を指す。

注: Chrome では 意義ありピクセル数 を 3 と定義している。

2.2. 不安定ノード

Node N は座標空間 C で シフトした（has shifted）とみなされるのは、次の場合である：

• C における N の始点が、 大きく異なる値で N の前フレームの始点と異なり、かつ

• C における N の変形非依存始点が 大きく異なる値で 前フレームの変形非依存始点と異なるとき。

それ以外の場合、N は シフトしなかった（has not shifted）とみなされる。

Node N は 不安定候補（unstable-candidate）であるのは次の場合である：

• N は次のいずれかである

  • 1つ以上のボックスを生成する Element 、または

  • テキストノード、かつ

• 現在および前フレーム時点の computed value の visibility プロパティが "visible" であり、かつ

• 現在および前フレーム時点の computed value の opacity プロパティが N およびすべての先祖で 0 ではない、かつ

• N はシフトした 状態にあり、その座標空間は ビューポートである、かつ

• N はシフトした 状態にあり、その座標空間は 初期コンテインブロックである、かつ

• 次をみたす Element P が存在しない：

  1. 現在および前フレーム時点の P が コンテインブロックチェーン上で N の先祖であり、かつ

  2. 現在および前フレーム時点の P が スクロール可能オーバーフロー領域を持ち、かつ

  3. P が不安定候補でなく、かつ

  4. N は シフトしなかった 状態であり、その座標空間は P のスクロール可能オーバーフロー領域である。

注: スクロール可能オーバーフロー領域に関する条件は、 単なるスクロール操作によってノードが不安定とみなされるのを防ぐためのものです。

Node N は、 不安定候補であって、 インライン・クリップ・クロッサーでない場合、 不安定（unstable）である。

Node N は インライン・クリップ・クロッサー（inline clip crosser）であるのは：

• N が不安定候補であり、

• N の視覚的表現または前フレームの視覚的表現 のいずれかが空であり、かつ

• 次を仮定した場合 N はもはや不安定候補でなくなる：

  — 大きく異なる の定義内の「水平方向または垂直方向」の表現を、(ブロック軸が縦書きの場合は「垂直方向」に、 ブロック軸が横書きの場合は「水平方向」に 置き換える。

注: インライン・クリップ・クロッサーの例としては、インライン方向に クリップ境界をまたぐようにしてビュー内またはビュー外へ移動する要素が挙げられる。 こうした要素はブロックフロー方向にずれない限り、不安定ノード集合から除外される。 これにより「カルーセル」型UIコントロールのようなものを簡単に構築できる。

不安定ノード集合（unstable node set）は、 Document D において、 D の不安定な シャドウを含む子孫すべてを含む集合である。

注: 最初のフレームでは、前フレームの始点が存在しないため、どのノードも不安定ノード集合に含まれない。

2.3. レイアウトシフト値

ビューポート基準距離とは、 ビジュアルビューポートの幅 と ビジュアルビューポートの高さ のうち大きい方である。

移動ベクトルは、Node Nについて、ピクセル単位での2次元オフセットである。

• N の 前フレームの始点（ビューポートの座標空間内）から、

• 同じくN の始点（ビューポートの座標空間内）まで。

移動距離は Node N について、次のうち大きい方である：

• N の 移動ベクトルの水平成分の絶対値、

• または 移動ベクトルの垂直成分の絶対値。

最大移動距離は Document D の不安定ノード集合 内のすべてのNode についての移動距離の最大値、または集合が空の場合は0。

距離率は Document Dについて、次の小さい方：

• D の最大移動距離を ビューポート基準距離 で割った値（ビューポート基準距離が0なら0）、

• 1.0

ノード影響領域は 不安定 なNode Nに対し、次の点の集合：

• N の視覚的表現内のすべての点、

• N の前フレームの視覚的表現内のすべての点。

影響領域は Document Dについて、 不安定ノード集合内の 全Node のノード影響領域中の すべての点の集合。

影響率は Document Dについて、 影響領域の面積を ビューポートの面積で割った値（ビューポートの面積が0なら0）。

注: 影響領域の面積計算は2次元における Klee measure problemにあたる。 掃引線とセグメントツリーを用いて O(n lg n) 時間で （nは不安定ノード数）、このように解ける。

レイアウトシフト値は Document Dについて、 影響率に 距離率を掛けたものとする。

注: レイアウトシフト値は、 レイアウト不安定性がビューポートのどれほどの割合に影響したかと 各要素がどれくらい移動したかの最大値を両方考慮に入れている。 大きな要素が少しだけずれた場合は、ページ全体の不安定感が低い とみなされるケースに対応している。

2.4. 入力除外

除外入力とは、 ドキュメントへのユーザーの積極的な操作を示す入力デバイスからの イベント、またはビューポートのサイズを直接変化させるイベントである。

除外入力には、主に mousedown、 keydown、 pointerdown、 changeイベントなどが含まれる。 ただし、フリックやスクロールジェスチャーの開始や更新のみの効果を持つ イベントは除外入力に該当しない。

ユーザーエージェントは、 pointerdownイベント発生後、 そのイベントがフリックもしくはスクロールの開始でないと判明するまで レイアウトシフトの報告を遅延させてもよい。

mousemove および pointermove イベントも除外入力ではない。

3. LayoutShift インターフェイス

[Exposed=Window]
interface LayoutShift : PerformanceEntry {
  readonly attribute double value;
  readonly attribute boolean hadRecentInput;
  readonly attribute DOMHighResTimeStamp lastInputTime;
  readonly attribute FrozenArray<LayoutShiftAttribution> sources;
  [Default] object toJSON();
};

すべての属性値はレイアウトシフトを報告する ステップによって設定される。

sources属性は FrozenArray （LayoutShiftAttribution オブジェクトの配列）を返す。 この配列は影響領域の大きい順にソートされ、先頭要素が最もノード影響領域 の大きな要素、すなわちレイアウトシフトに最も寄与した要素を表す。

Layout Instability APIを実装するユーザーエージェントは、 supportedEntryTypes に "layout-shift" を Window コンテキストで必ず含めなければならない。 これにより開発者は Layout Instability API のサポートを検知できる。

4. LayoutShiftAttribution インターフェイス

[Exposed=Window]
interface LayoutShiftAttribution {
  readonly attribute Node? node;
  readonly attribute DOMRectReadOnly previousRect;
  readonly attribute DOMRectReadOnly currentRect;
};

注: previousRect および currentRect 属性はCSSピクセル単位で長方形を報告し、 getBoundingClientRect()、 IntersectionObserver、 ResizeObserver など他のWebプラットフォームAPIと同様である。 これにより、レイアウトシフトと他のDOM測定値の相関が容易になるデバイス非依存の座標系が提供される。

各LayoutShiftAttribution は、そのNode （対応ノード）と結びついている。

LayoutShiftAttribution インスタンスAの node属性のgetterは、 Aの対応ノードと そのノードドキュメントを入力に、 要素取得アルゴリズムを呼び出し、その結果を返す。

注: 要素取得アルゴリズムにより、 属性づけられたノードが現在接続されていない、もしくはシャドウルート内である場合は node属性がnullになることが保証される。

要素取得アルゴリズムは Element Timing 仕様から 本仕様で再利用しやすい場所に移すべきである。

要素取得アルゴリズムは Elementではなく Node を受け付けるよう一般化すべきである。

previousRect およびcurrentRect の各属性値は帰属を作成するステップによって設定される。

5. 処理モデル

レンダリングの更新 ステップ内で、Layout Instability API を実装するユーザーエージェントは ペイントタイミングをマーク アルゴリズムの実行後、次の処理を行わなければならない：

1. すべての fully active なDocument について レイアウトシフトを報告する アルゴリズムを呼ぶ。

5.1. レイアウトシフトを報告する

5.2. レイアウトシフト要素情報の報告

6. セキュリティとプライバシーに関する考慮事項

レイアウト不安定性は リソースタイミング と間接的な関係を持つ。なぜなら遅いリソースがなければ発生しなかった一時的なレイアウトを引き起こす可能性もあるためだ。 リソースタイミング情報は、統計的フィンガープリント 目的で悪意あるウェブサイトに利用されうる。レイアウト不安定性APIは 現在のブラウジングコンテキストの不安定性のみを報告する。複数のブラウジングコンテキストをまたいだ 不安定性スコアの集約情報は直接提供しない。開発者は手動でこのような集約を実装できるが、 オリジンの異なる オリジンの ブラウジングコンテキスト同士は、不安定性スコアを共有するには協調が必要となる。