本文へスキップ
Unveilydocs

折りたたみポスチャ

折りたたみ・デュアルスクリーン端末の折り曲げ状態(posture)を検知し、Web レイアウトを適応させます。

概要

ポスチャ Bridge は、折りたたみ端末の折り曲げ状態を Web に伝えます。端末が本のように半分に折れたり(縦ヒンジ)、ノート PC のように倒れたり(横ヒンジ)すると、Web はその状態に合わせてレイアウトを 2 分割したり、コントロールの位置を変えたりできます。

状態(posture)意味推奨レイアウト
flat完全に開いた状態(または通常のスマホ・タブレット)通常の単一レイアウト
book縦ヒンジ(左右分割、ブックモード)左右 2 分割(一覧 + 詳細)
tabletop横ヒンジ(上下分割、ノート PC モード)上部コンテンツ / 下部コントロール
folded折りたたみ(カバー画面) — iOS 専用コンパクト UI
unknown判別不可flat として扱う

無停止 — 使うときだけ動作

この機能は既存の動作を変更しません。通常のスマホ・タブレットや旧バージョンの OS では常に flat であり、Web がポスチャ API を呼び出したときにのみ反映されます。折りたたみ対応が必要になるまで導入しなくて構いません。


Bridge API

// 現在の posture を取得(async — コールバックで応答)。コールバック名を省略すると既定の 'onPosture'
window.unveilyBridge.getPosture('onPosture');

// getPosture の応答ハンドラ — Web 側で実装
window.onPosture = function (result) { applyPosture(result); };

// native が posture を変更したときに呼ぶ push ハンドラ — Web 側で実装
window.onPostureChange = function (result) { applyPosture(result); };

result の形

{
  "postureContractVersion": 1,
  "posture": "flat",                 // flat | book | tabletop | folded | unknown
  "isFoldable": true,
  "hingeAngle": 128,                 // iOS: 数値 / Android: 常に null
  "hingeOrientation": "vertical",    // vertical | horizontal | null
  "orientation": "portrait",         // portrait | landscape
  "segments": [ { "x": 0, "y": 0, "width": 540, "height": 960 } ]  // iOS のみ提供
}
  • book = 縦ヒンジ(左右分割)・tabletop = 横ヒンジ(上下分割)
  • 非折りたたみ端末 → { "isFoldable": false, "posture": "flat" }、push なし

⚠️ 必ず守るプラットフォーム互換処理

iOS と Android は分割領域を異なる方法で提供します。片方のプラットフォームで壊れないよう、以下をすべて許容してください。

分割領域(segments)はフォールバック順で

いずれか一方のソースだけを前提にしないでください。次の順で処理します。

  1. CSS Viewport Segments API(env(viewport-segment-*))があれば使用 — Android(Chromium WebView)で対応
  2. なければブリッジ result の segments を使用 — iOS(WKWebView は CSS API 非対応のため、代わりに native segments を提供)
  3. どちらもなければ posture enum で分岐

さらに:

  • hingeAngle は null の場合があります(Android は常に null)。数値だと仮定しないでください。
  • folded が来ないことがあります(Android は閉じた状態を検知できません — iOS のカバー画面専用)。folded の受信に主要なロジックを依存させないでください。
  • Android には segments キー自体が無い場合があり、iOS には CSS Viewport Segments API がありません。 両方を許容してください。
  • 未知のフィールド・値は無視してください(前方互換)。

ロード時に 1 回呼ぶ(重要)

ページがロードされる前に起きた posture の変化は push で受け取れません。そのため、ロード時に getPosture() を一度呼び出して現在の状態を取得してください。

window.addEventListener('unveilyGlueReady', () => {
  try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });

unveilyGlueReady は、SDK がブリッジグルーの注入を終えたときに発火するイベントです。(詳細: ナビゲーション — タイミング)


push トリガーと回転の関係

onPostureChange の push は、posture / isFoldable / hingeOrientation のいずれかが変わると発火します。

  • 折りたたまない端末(isFoldable: false)は、回転しても push がありません。 回転対応は従来どおり window.onOrientationChanged / CSS メディアクエリ / window.resize で処理してください。
  • 折りたたみ端末は回転すると hingeOrientation が変わり push が来ます(両プラットフォーム共通):
    • 半折り状態で回転 → posture も book ↔ tabletop に変化
    • 開いた状態(flat)で回転 → posture は flat のまま、hingeOrientation のみ vertical ↔ horizontal

push を受けたら再読み込み

push を受けたら、posture が同じでも hingeOrientation/orientation を読み直してレイアウトに反映してください。


適用例

function applyPosture(result) {
  const { posture, hingeOrientation } = result;
  const root = document.documentElement;

  switch (posture) {
    case 'book':      // 縦ヒンジ → 左右 2 分割
      root.dataset.layout = 'split-horizontal';
      break;
    case 'tabletop':  // 横ヒンジ → 上下分割
      root.dataset.layout = 'split-vertical';
      break;
    case 'folded':    // iOS カバー画面
      root.dataset.layout = 'compact';
      break;
    default:          // flat / unknown
      root.dataset.layout = 'single';
  }
}

// ロード時に 1 回 + 変化時に push
window.onPosture = applyPosture;
window.onPostureChange = applyPosture;
window.addEventListener('unveilyGlueReady', () => {
  try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });

デモ

SDK テストページ(test_bridge)の「Foldable Posture」カードで実際の動作を確認できます。iPhone Duo シミュレータ / Pixel Fold エミュレータで、折りたたみ・回転時の値の変化を見られます。

On this page