Stepper

把有序步骤渲染成一次显示一步 + Prev/Next 翻页的引导组件。 适合教程 / 配置向导 / 烹饪步骤 / 算法 walkthrough — 明确告诉读者 "走这条路、按顺序"。

When to use

• ✅ 教程（安装 → 配置 → 第一次使用）
• ✅ 多阶段流程（多步表单 / onboarding wizard / 部署 checklist）
• ✅ 算法 walkthrough（一次走一步看状态变化）
• ✅ 烹饪 / 实验步骤（食材 → 准备 → 烹饪 → 装盘）
• ❌ 多视图选一（不是序列，是并列选项）→ 用 Tabs
• ❌ 时间事件（带日期的历史 / roadmap）→ 用 Timeline
• ❌ 不严格序列（步骤可任选顺序）→ 用 Layout 或普通列表

Basic syntax

\```stepper
:::step title="安装 Rho"
\```bash
brew install rho
\```
:::

:::step title="打开 .md 文件"
File → Open → 选你的 `.md`
:::

:::step title="开始写"
直接在编辑器里写 markdown / Rho format。
:::
\```

渲染：顶部 progress bar 显示 "Step 1 of 3"，下方一次只显示一步内容；底部 Prev / Next 按钮翻页。

All options

Block-level: ```stepper

Step-level: :::step

title 含空格请加引号：title="Install Rho"。

Examples

Example 1：3 步 tutorial

\```stepper
:::step title="第 1 步：安装"
打开终端跑：

\```bash
brew install rho      # macOS
sudo apt install rho  # Ubuntu/Debian
\```
:::

:::step title="第 2 步：创建第一个文件"
\```bash
echo "# Hello Rho" > demo.md
rho demo.md
\```

应用会打开窗口显示渲染结果。
:::

:::step title="第 3 步：写第一个 interact 块"
在 `demo.md` 里加：

\```\```interact
slider x 0 10 5 1
template stl:
[选中值] -> [{x}]
\```\```

刷新——你看到了一个滑块。
:::
\```

渲染：顶部 "Step 1 of 3" → "Step 2 of 3" → "Step 3 of 3" 进度条；点 Next 推进。每一步内容含丰富 markdown（代码块、嵌套 fence）。

Example 2：linear wizard（onboarding）

\```stepper linear=true
:::step title="欢迎"
🎉 欢迎使用 Rho！本向导将带你 5 分钟搞定基础设置。

点 **Next** 继续。
:::

:::step title="账号"
请填写你的邮箱（cloud.rho.md 同步用）：

\```interact
input email "[email protected]"
template stl:
[邮箱] -> [{email}]
\```
:::

:::step title="主题偏好"
\```interact
select theme "dark" "light" "system"
template stl:
[主题] -> [{theme}]
\```
:::

:::step title="完成"
✅ 全部就绪。点击 **Done** 进入主界面。
:::
\```

渲染：4 步严格 linear 向导，未完成上一步不能跳到下一步。配合 interact 控件做轻量表单（注意：state 不会真的被提交到后端——纯客户端，只是 UI 演示）。

Example 3：算法 walkthrough（带状态展示）

\```stepper
:::step title="初始数组"
原始数组：`[5, 2, 8, 1, 9, 3]`

我们要做冒泡排序，比较相邻两元素，大的下沉。
:::

:::step title="第 1 轮"
比较：
- (5,2) → 交换 → `[2, 5, 8, 1, 9, 3]`
- (5,8) → 不变
- (8,1) → 交换 → `[2, 5, 1, 8, 9, 3]`
- (8,9) → 不变
- (9,3) → 交换 → `[2, 5, 1, 8, 3, 9]`

最大值 9 已经"沉"到末尾。
:::

:::step title="第 2 轮"
对前 5 个再走一遍 ……
:::

:::step title="完成"
排序后：`[1, 2, 3, 5, 8, 9]`
:::
\```

渲染：算法步进展示，每步看一个轮次的中间状态。比看一大段静态描述清晰得多。

Example 4：含 optional + disabled 步

\```stepper
:::step title="必做：基础配置"
配置 base config……
:::

:::step title="可选：高级配置" optional=true
高级用户可设的项……
（可点 Skip 跳过）
:::

:::step title="必做：保存"
点 **Save** 落盘。
:::

:::step title="未来步骤" disabled=true
🚧 v0.7 推出
:::
\```

渲染：第 2 步有 "Skip" 按钮；第 4 步灰显不可访问。

Plain-text fallback behavior

:::step 是 markdown directive 容器。在不支持的 reader 里：

:::step title="第 1 步：安装"
content
:::

→ :::step title=... 显示为字面量；step 内容正常渲染。所有 step 顺序展开成长页面——读者看得到全部步骤，只是失去 "一次一步翻页" 的交互。

具体各 reader：

读者永远能读到所有步骤——这正是 plain-text fallback 的意义。

Common pitfalls

1. step 顺序乱

\```stepper
:::step title="第 3 步"
:::
:::step title="第 1 步"
:::
:::step title="第 2 步"
:::
\```

→ Rho 按文档顺序渲染（不会自动排序）。写之前先把步骤捋顺。

2. step 数过多

3. 各 step 内容深度极不均衡

\```stepper
:::step title="第 1 步"
（10 段长描述）
:::
:::step title="第 2 步"
点 Next。
:::
:::step title="第 3 步"
（又 8 段长描述）
:::
\```

→ 进度条节奏假——5 步看着平均，实际工作量天差地别。让每步耗时大致相当（< 3 分钟阅读 / 1-2 个动作）。

4. 缺 ::: 关闭

\```stepper
:::step title="A"
A 内容
                ← ❌ 缺 :::
:::step title="B"
B 内容
:::
\```

→ 整 stepper 解析失败。每个 :::step 必须配对 :::。

5. linear=true 但用户找不到 Skip

\```stepper linear=true
:::step title="必填邮箱"
\```interact
input email ""    ← ⚠️ 无默认值，用户没填又跳不过 → 卡死
template stl:
[邮箱] -> [{email}]
\```
:::
\```

→ linear 模式下用户没填 email 就进不了下一步，但 Rho 不会自动检测 input 是否有值。linear 步必须：

• 给所有控件一个合理默认值，或
• 在 step 加 optional=true，或
• 不用 linear 模式

6. stepper 套 stepper

\```stepper
:::step title="外层"
\```stepper       ← ⚠️ stepper 套 stepper，UI 极易混乱
\```
:::
\```

→ 技术上 Nested DSL 支持，但两层 progress bar 视觉冲突。 改进：内层用 Tabs 或顺序列表代替 stepper。

7. 第一步是介绍，不是动作

\```stepper
:::step title="介绍"
这是 Rho 的入门 tutorial......（200 字介绍）
:::
:::step title="第 1 步：安装"
...
:::
\```

→ 用户进 step 1 期待"动作"，看到大段 prose 会困惑。 改进：把介绍放在 stepper 之前 作普通段落；step 1 直接是第一个动作。

Stepper vs Tabs vs Timeline — 选择依据

See also

• Tabs — 多视图同空间切换（无序）
• Modal — 隐藏内容按需展开
• Timeline — 时间序列（不是教程）
• Interact controls — stepper 里嵌 input/select 做轻量表单
• Nested DSL
• Plain-text fallback principle