版面構圖
Live Preview Wizard
左欄分步表單、右欄即時預覽畫布的雙欄 onboarding 版面；輸入即時 morph 反映到預覽，步驟切換時表單方向滑動、預覽交叉淡變。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add live-preview-wizardPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
編輯中的呼叫預設屬性
<LivePreviewWizard/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/live-preview-wizard.json或在 components.json 設定 registries 後，改用 @webberui/live-preview-wizard 安裝。
使用
用 <LivePreviewWizardStep> 宣告每一步的表單欄位，preview 提供右欄的即時預覽。步驟內的欄位透過 useLivePreviewWizard 讀寫共享的 values，輸入會即時反映到預覽。
import {
LivePreviewWizard,
LivePreviewWizardStep,
useLivePreviewWizard,
} from "@/components/ui/live-preview-wizard";
type Form = {
name: string;
};
function NameField() {
const { values, setValue } = useLivePreviewWizard<Form>();
return (
<input
value={values.name}
onChange={(e) => setValue("name", e.target.value)}
/>
);
}
function Preview() {
const { values } = useLivePreviewWizard<Form>();
return <h1>{values.name || "你的產品"}</h1>;
}
export function Example() {
return (
<LivePreviewWizard<Form>
defaultValues={{ name: "" }}
preview={<Preview />}
onComplete={(values) => console.log(values)}
>
<LivePreviewWizardStep label="品牌">
<NameField />
</LivePreviewWizardStep>
</LivePreviewWizard>
);
}Props
LivePreviewWizard
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
children | ReactNode | — | 步驟宣告，皆為 <LivePreviewWizardStep> |
preview | ReactNode | (ctx) => ReactNode | — | 預設的即時預覽內容；步驟未自訂時使用 |
values | T | — | 受控表單資料；不傳則內部管理（非受控） |
defaultValues | T | {} | 非受控模式的初始資料 |
onValuesChange | (values: T) => void | — | 資料變更時觸發，帶入最新完整資料 |
step | number | — | 受控目前步驟索引；不傳則內部管理 |
defaultStep | number | 0 | 非受控模式的初始步驟 |
onStepChange | (step, direction) => void | — | 步驟變更時觸發（direction：1 前進、-1 後退） |
onComplete | (values: T) => void | — | 最後一步按「完成」時觸發 |
progress | "dots" | "bar" | false | "dots" | 進度指示款式；false 不顯示 |
controls | boolean | true | 是否渲染內建的上一步／下一步控制列 |
previewSide | "left" | "right" | "right" | 寬螢幕時預覽畫布置於哪一側 |
previewLabel | string | "preview.app" | 預覽外框 faux 網址列文字 |
backLabel / nextLabel / completeLabel | string | 上一步 / 下一步 / 完成 | 控制列按鈕文字 |
className | string | — | 追加到外層 grid 的樣式 |
LivePreviewWizardStep
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
label | string | — | 進度指示顯示的步驟標題 |
children | ReactNode | — | 本步驟的表單欄位 |
preview | ReactNode | (ctx) => ReactNode | — | 本步驟專屬預覽，覆寫容器的 preview |
className | string | — | 追加到步驟容器的樣式 |
useLivePreviewWizard<T>()
回傳目前的 values、setValue(key, value)、setValues(partial)，以及 step／total／direction／isFirst／isLast／goTo／next／back 等導覽狀態。需在 <LivePreviewWizard> 內呼叫。
細節
- 雙模式：
values與step皆支援受控（傳入 prop）與非受控（defaultValues／defaultStep）兩種用法。 - 即時 morph：欄位透過
setValue寫入共享values，同一步驟內預覽會即時重繪；顏色類變化建議搭配 CSStransition-colors讓 morph 更平滑。 - 方向感知：
next／back／goTo會推導切換方向，表單以水平滑動、預覽以交叉淡變過場。 - 每步預覽：在
<LivePreviewWizardStep>上設定preview可讓不同步驟強調不同重點，切換時自然交叉淡變。
可及性
- 進度圓點／進度條帶
role與aria-*；已抵達的步驟可點擊跳轉，未抵達者停用。 - 步驟區塊帶
aria-roledescription="步驟"與aria-label，並以aria-live="polite"朗讀目前步驟。 - 預覽畫布帶
aria-label="即時預覽"；控制列按鈕皆可鍵盤操作並具 focus 樣式。 - 使用者開啟「減少動態效果」時，滑動改為淡入淡出、彈簧過場停用，不影響版面結構。