R1.12.2runnable examples设计
示例需可运行，静态截图会与实现脱节
别名: 活示例 · 可执行样例 · living example · executable snippet
概念解释
可运行示例（runnable example）和组件走同一份构建产物：同一入口、同一版本、点一下就能在当前实现上执行。静态截图是某一次提交留下的像素，和源码没有绑定，实现改了它不会自己报废。示例需要可运行，是因为它同时承担「看起来怎样」和「现在这样写对不对」；截图只承担前者，而且前者还会在下一次发版后变成谎言。
可运行不是「仓库里有一段示例代码」。那段代码若不能在文档页或沙箱里被构建、被点击、被断言，它与截图的差别只是多了一层可能过期的文字。运行起来的那一次，才把示例从插图变回接口的活副本。
机制
截图与实现之间没有编译器。属性改名、默认值翻转、插槽结构调整，截图仍显示旧画面，阅读的人会按旧画面去写新代码。过期没有信号：没有红构建、没有失效标签，只有下一位使用方在产品里撞上「文档里有、包里没有」的属性。
可运行示例挂在同一构建图上。组件的测试失败，示例页也失败；入口被删，示例导入报错。失效被提前到发布之前。它还能被交互：键盘、焦点、空态不是一张图能假装出来的，必须真的跑。截图在评审时便宜，便宜的来源是它把「与实现同步」这份工作推到了未来的某个人身上，而那个人通常不会出现。
边界
印刷品、幻灯、无执行环境的设计评审里，截图是唯一能带上桌的东西；这时要在图上标明包版本和提交，并在会后用可运行副本替换。视觉回归测试本身就会产截图，那些截图是断言用的基线，不是给人抄写的用法。动画与指针轨迹难以在文档页完整复现时，允许用短视频补「过程」，但仍需旁边放一份可运行的静止终点。示例若依赖线上账号或付费数据，可运行会在对外文档里失败，需要一份脱敏的本地夹具，而不是退回截图了事。
怎么落地
- 文档页的每个用法块绑定到一条可构建入口，和组件测试同一套工具跑；构建失败即文档失败。
- 禁止把未绑定提交哈希的截图当作唯一示例。必须出现的静帧，文件名或旁注写上包版本，并链到可运行副本。
- 示例代码从源文件引用，不从文档里手工粘贴一份平行拷贝。
- 验证：改一个公开属性的名字并跑文档构建，所有还在用旧名的示例必须红。拿一张三个月前的截图对照当前沙箱：像素仍对但代码已跑不起来的，就是脱节样本。再在示例里走一遍键盘和空态——截图里画过、运行时没有的路径，全部记为谎言。