3D 裝置舞台

產品頁最常見的一幕：把 App 畫面裝進一台手機或筆電，讓它在頁面上動起來。這個元件的手機、平板、筆電外框全部用 CSS 畫成（圓角、邊框、動態島、側鍵、鍵盤底座），沒有任何圖片；螢幕裡放的是真 DOM，文字可選取、按鈕可點、螢幕閱讀器讀得到。五種編排可切換：游標傾斜、捲動環繞、Y 軸翻轉（背面可放第二個畫面或畫出背殼）、三台扇形陣列，以及捲動時從微距特寫拉回全景。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<DeviceStage3D/>

    </div>
  );
}

安裝

使用

import { DeviceStage3D } from "@/components/ui/device-stage-3d";

<DeviceStage3D
  device="phone"
  mode="flip"
  screens={[<HomeScreen key="home" />, <SettingsScreen key="settings" />]}
  caption={<p>點擊手機看設定頁</p>}
  maxTilt={8}
/>;

orbit 與 macro 由捲動驅動；舞台放在可捲動的區塊裡時，把該區塊的 ref 傳給 container：

const scrollerRef = React.useRef<HTMLDivElement>(null);

<div ref={scrollerRef} className="h-[480px] overflow-y-auto">
  <div className="h-[320px]" />
  <DeviceStage3D mode="macro" container={scrollerRef} screens={[<HomeScreen key="home" />]} />
  <div className="h-[320px]" />
</div>;

Props

另外具名匯出 DeviceStage3DDevice、DeviceStage3DMode 與 DeviceStage3DProps 型別。

CSS 變數

細節

• tilt：游標相對舞台中心換算成 −1 到 1，映射成 rotateY ±maxTilt、rotateX ∓maxTilt，經 stiffness 150／damping 18 的彈簧平滑，離開舞台回正。觸控裝置（pointer: coarse）預設不跟隨；開啟 gyro 後改讀 deviceorientation，iOS 會在使用者第一次觸控後請求權限
• orbit：捲動進度 0 到 1 映射 rotateY −30° 到 30°，translateZ 在中段推到 40px 最靠前
• flip：rotateY 0 到 180°，正面 screens[0]、背面 screens[1]；只有一個畫面時背面畫成背殼（鏡頭模組與霧面）。點到螢幕裡的按鈕、連結時不會翻面
• lineup：三台扇形排開，左右兩台往內轉 18°、往外移 60%、退後 80px、縮到 0.9；進入視口時每台間隔 0.12 秒從下方彈上來
• macro：捲動到舞台中心對齊視窗中心的過程中，整組從 1.6 倍拉回 1 倍、位移 12% 歸零；背景裝飾與側機（screens 多於一個時）從 depthBlur 模糊到清晰
• 筆電開蓋：螢幕面板以底邊為軸從 −90° 打開；一般模式在進入視口時以彈簧開蓋，orbit／macro 改綁捲動前 30%

可及性

• 最外層為 role="group"，aria-roledescription="裝置展示"；外框、側鍵、鏡頭、鍵盤等裝飾都是 aria-hidden，螢幕內容保持可讀、可聚焦
• flip 模式提供一顆鍵盤用的翻面按鈕（aria-pressed 表示是否顯示背面），平常隱藏、Tab 聚焦時浮現，可用 Enter／空白鍵觸發；沒朝向使用者的那一面會設為 inert，不會被 Tab 到
• macro 的側機只是裝飾，設為 aria-hidden 與 inert
• 使用者系統開啟「減少動態效果」時，所有模式固定正面、不跟隨游標與捲動，lineup 直接到位，筆電直接開蓋，flip 改為兩面原地交叉淡接