explain-with-code-walkthrough

通过代码演练进行说明

左侧的简短步骤从右侧固定的代码面板旁滚过，代码面板保持在视口垂直方向的中央。 对于每个步骤，面板都会显示对应文件，并高亮该步骤涉及的代码行。读者可以看到 现有代码逐步变为提议的代码。

适用场景

• 用户要求通过代码演练直观地说明变更。
• 编排器通过代码演练直观地说明变更。

步骤

• 按照读者理解内容的顺序安排 4–8 个步骤（通常是：现有代码 → 变更位置 → 新代码 → 使用者）。
• 每个步骤：用一个加粗句子说明该步骤展示的内容，然后最多补充 1–2 行简短说明。
• 当前步骤使用轻微标记（工具包的 ev-step.is-active：强调色边缘和淡色背景）。不要调暗其他步骤。
• 更深入的说明、表格和跟踪信息放在每个步骤的一个 ev-more 开关中，其摘要要说明其中的内容 （例如“为什么 5 行就够 · Tick 跟踪”）。读者无需点击就能知道里面有什么。
• 让开关内容直观易读：使用高亮代码、分组、状态标签和紧凑表格。不要堆砌大段文字。

代码面板

• 显示代码库中的真实代码（或提议的代码），并在面板标题中注明文件路径。提供 3–4 段代码片段，每段不超过 15 行即可。
• 通过高亮而非内容位移来制作动画：调暗未聚焦的代码行，将焦点带平滑移至新范围；切换文件时使用交叉淡入淡出效果。读者查看时，不要增减代码行。
• 面板的初始状态（文件和高亮行）对应第 1 步，且在第 1 步处于当前状态时必须保持不变。第 2 步成为当前步骤时，才首次更改面板。
• 向上滚动时，恢复之前步骤对应的文件和高亮，必须与原先完全一致：只根据步骤编号设置面板，绝不依据先前状态设置。
• 新增行使用绿色 + 行号栏标记，删除行使用 − 标记。
• 根据稳定 ID 选择代码行（在代码数据中为代码行添加标签），不要手动计数行号，因为行号会变动。
• 代码片段只保留相关行及少量上下文；跳过的部分用标记注明（“⋯ 已隐藏 12 行”），不要展示整个文件。尽量避免出现需要横向滚动的代码行。

手机

• 在手机上，为代码面板添加 ev-side--pin，使其固定在步骤上方；保持代码行简短（≤ 70 个字符），避免横向滚动。

构建

• 使用 explainer-kit 技能将其构建为一个片段（其中的 SCRIPTS-AND-TABS.md 涵盖 EV.steps）。使用工具包的代码块（ev-code，配合 data-add、 data-hl、data-groups、data-marks）展示行内代码和开关中的代码。
• 使用工具包的 ev-side（左侧放置步骤）和 ev-stick（右侧放置代码面板，并固定在顶部栏下方的垂直中央）进行布局。第一个步骤从所在列的顶部开始，与代码面板齐平（不加顶部内边距或间隔）；添加底部内边距，让最后一个步骤能够滚动到中间。将步骤设为 ev-step 框，并使用 EV.steps(steps, function (i) { … }) 驱动面板（不要使用 IntersectionObserver，它会错误处理反向滚动）。在 EV.onShow 中初始化，并在调整大小时重新测量焦点带。
• 为每个步骤设置 id 和 data-toc，使其显示在章节列表中。