steps 与 step 把一段 Markdown 组织成编号教程。它们只呈现作者写下的静态内容。步骤本身没有 action、data binding 或写入行为。
本页是 feature live 指南。unit 页:steps、step。
Sample 合同
| 字段 | 值 |
|---|---|
| 用途 | 内容 Markdown 中的静态编号教程结构 |
| 边界 | 仅静态:无运行按钮、无 bind、无写入;不是跨设备 primitive 承诺 |
| 作者入口 | ::::steps 包裹 :::step{title=…} container |
| 表面 | Web Device document → view 的 mode=steps |
| 公共状态 | released |
| Fallback / 失败 | fence 深度错误会丢或误解析正文;leaf ::step 不能承载正文 |
| 验证 | 下列路由 · arc --version = 2.0.0-beta.32 |
先看 fence 规则
step 需要正文,因此必须是 container directive,至少使用三个冒号。包住它的 steps 再多用一个冒号。两个冒号的 ::step 是没有正文的 leaf directive,不能用来写步骤内容。
源代码:
::::steps
:::step{title="确定内容边界"}
先说明这个页面会呈现什么,也说明它不会执行什么。
:::
:::step{title="把 source 放在结果上方"}
让读者可以同时读到 Markdown 与实际输出。
:::
:::step{title="在浏览器中检查"}
确认编号、文字和窄屏布局都能正常出现。
:::
::::渲染结果:
确定内容边界
先说明这个页面会呈现什么,也说明它不会执行什么。
把 source 放在结果上方
让读者可以同时读到 Markdown 与实际输出。
在浏览器中检查
确认编号、文字和窄屏布局都能正常出现。
步骤体可以包含普通 Markdown block,例如段落、列表、代码块或 GitHub 风格提示。外层 steps 的冒号数必须大于最深一层 container 的冒号数,否则 parser 会把 fence 读成不同的 directive 结构。
失败与限制
| 情况 | 预期结果 |
|---|---|
两个冒号的 leaf ::step{title="…"} | 无正文;不是可用步骤 |
外层 :::steps 与内层 :::step 同深度 | 结构被误解析;正文可能丢失 |
| 期望 “运行此步” 控件 | 超出合同 — steps 是静态呈现 |
| 窄屏 | 编号与文字仍作为文档内容可读 |
steps 是内容读取器扩展出的 Web Device 文档结构,不是另一个可跨设备承诺的 AUP primitive。本站的 Web layout 边界见AUP layout 边界。
验证证据
| 项 | 值 |
|---|---|
| 基线 | 2026-08-12 · arc --version → 2.0.0-beta.32 |
| 能力行 | docs/aup/capability-matrix.md (internal, non-routed) · ::::steps / :::step |
| 实现 | providers/runtime/web-device/src/content-reader.ts(stepsDirectiveToAup);renderer/primitives/view.ts(mode=steps) |
| 公开路由 | /zh/docs/web-device/markdown-steps/ · /en/docs/web-device/markdown-steps/ |
| 本地运行 | arc service start --blocklet blocklets/arcblock --port 4900 · 桌面 + 约 390px |
| 验收 | 编号步骤与 source 的标题/正文一致;无 action/写入外壳 |