Live Preview Wizard
左欄分步表單、右欄即時預覽畫布的雙欄 onboarding 版面;輸入即時 morph 反映到預覽,步驟切換時表單方向滑動、預覽交叉淡變。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
<LivePreviewWizard />
安裝
npx shadcn@latest add https://webberui.com/r/live-preview-wizard.json或在 components.json 設定 registries 後,改用 @webberui/live-preview-wizard 安裝。
安裝依賴後,從 registry JSON(/r/live-preview-wizard.json 的 files[0].content)複製 live-preview-wizard.tsx 原始碼到你的 components/ui/ 目錄:
npm install motion lucide-react clsx tailwind-merge使用
用 <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 樣式。 - 使用者開啟「減少動態效果」時,滑動改為淡入淡出、彈簧過場停用,不影響版面結構。