char-by-char

char-by-char 是一个面向录屏、教学和演示场景的 VS Code 扩展。它会读取本地源文件，然后按“像人在编辑代码”的方式，把内容逐步写入当前编辑器。

当前版本的重点不是“最后一次性排版正确”，而是“输入过程就像正常写代码”：

• HTML / CSS / JS / TS 会优先走结构化播放，不再默认一行打到底。
• 缩进、换行、正文内容会拆成独立步骤逐步插入。
• marker 模式支持把多个代码片段分批写入目标文件的不同位置。

核心能力

• 从本地文件读取内容并播放到当前编辑器。
• 支持 HTML / CSS / JavaScript / TypeScript / CSS 的结构化播放。
• 支持 marker 脚本，把多个片段插入到目标文件的不同占位符位置。
• 支持暂停、继续、取消。
• 支持开始前清空目标编辑器，或从当前光标继续追加。
• 支持输入过程中的 formatOnType，以及结束后的整篇格式化兜底。

命令

• char-by-char: 从文件开始逐字演示
• char-by-char: 清空当前活动编辑器
• char-by-char: 暂停逐字演示
• char-by-char: 继续逐字演示
• char-by-char: 取消逐字演示

这些命令同时会出现在编辑器标题栏和状态栏。

功能逻辑

1. 源文本解析

启动播放后，扩展会先读取你选择的源文件。

• 如果源文件是普通文本，就进入整文件播放模式。
• 如果源文件是 #marker 脚本，并且当前目标文件里存在对应占位符，就进入 marker 模式。

2. 结构化格式化

对于 HTML / CSS / JavaScript / TypeScript，扩展不会盲目原样播放。

它会优先尝试：

1. 使用 VS Code 当前环境中的 formatter
2. 如果 formatter 不可用或效果不理想，则使用扩展内置 fallback formatter

内置 fallback 目前覆盖：

• HTML
• CSS
• JavaScript
• TypeScript

对于这些结构化语言，扩展会比较 formatter 结果和 fallback 结果，优先选择“更像正常代码排版”的那一份，而不是默认接受单行结果。

3. 播放步骤拆分

源文本确定之后，不会直接把整段内容一次性写进去，而是先拆成播放步骤：

• 缩进是独立步骤
• 换行是独立步骤
• 正文内容按可感知字符逐步插入

这意味着：

• HTML 会按标签结构逐行写入
• CSS 会按 selector / declaration block 逐行写入
• JS / TS 会按语句、块、缩进逐行写入

所以视觉上更接近“正在写代码”，而不是“最后再统一格式化”。

4. 输入过程中的格式化

如果开启 charByChar.formatOnType，在输入到这些结构字符后会尝试触发编辑器的 on-type formatting：

• \n
• }
• ]
• )
• ;
• >

这一步主要用于让宿主编辑器参与局部整理，但它不是唯一依赖。即使 formatter 不可用，结构化播放本身也会尽量保持可读。

5. 换行与 Windows 兼容

扩展在播放时会按目标文档实际的换行风格推进光标位置：

• LF
• CRLF

这样在 Windows 环境下插入换行后，后续内容也会继续写在正确位置，不会出现“看起来没有回车、内容全挤成一行”的问题。

marker 模式

marker 模式适合做“分段演示”或“按位置填充代码”。

marker 脚本格式

源文件可以写成这样：

#title
<h1>Hello</h1>

#save

#body
<p>Content</p>

规则如下：

• 每个 #markerName 表示一个片段开始。
• 该标记下面直到下一个 #marker 之前的内容，会作为这个片段的正文。
• 如果某个片段正文为空，则它会被当成一次 save 动作。

目标文件占位符

目标文件里需要放对应占位符。当前支持这些形式：

• //title//
• /* title */
• <!-- title -->
• {//title//}

如果占位符单独占一整行，扩展会自动继承该行缩进，把片段内容按目标位置的缩进层级写进去。

marker 模式的执行逻辑

1. 读取源脚本中的各个 #marker
2. 在目标文件中寻找同名占位符
3. 对片段内容做结构化格式化
4. 按步骤逐步替换占位符
5. 遇到空片段时执行一次保存

配置

charByChar.defaultDelayMs

• 类型：number
• 默认值：120
• 范围：50-500

表示两个播放步骤之间的延迟时间。
注意这里的“步骤”不一定只是一个普通字符，也可能是一次缩进或一次换行。

charByChar.clearBeforeStart

• 类型：boolean
• 默认值：true

整文件模式开始前是否先清空当前活动编辑器。

charByChar.formatSourceBeforeTyping

• 类型：boolean
• 默认值：true

是否在播放前先对源内容做结构化格式化。
如果你希望 HTML / CSS / JS / TS 从第一行开始就保持正常代码形态，这个选项应该保持开启。

charByChar.formatOnType

• 类型：boolean
• 默认值：false

是否在输入关键结构字符时尝试触发 VS Code 的 on-type formatting。

charByChar.formatAfterFinish

• 类型：boolean
• 默认值：true

播放完成后是否再做一次整篇格式化兜底。

使用方式

整文件播放

1. 在 VS Code 中打开一个可编辑的目标文件。
2. 运行 char-by-char: 从文件开始逐字演示。
3. 选择本地源文件。
4. 输入播放延迟。
5. 扩展会按当前配置开始播放。

如果目标编辑器已有内容：

• 在 charByChar.clearBeforeStart = true 时会先清空
• 否则会提示你选择清空或从当前光标继续追加

marker 播放

1. 在目标文件中放好占位符。
2. 准备一个 #marker 源脚本。
3. 运行 char-by-char: 从文件开始逐字演示。
4. 选择这个脚本文件。
5. 扩展会自动识别为 marker 模式并分段执行。

调试

1. 在 VS Code 中打开本仓库。
2. 按 F5 启动扩展开发宿主。
3. 在新窗口里打开一个目标文件。
4. 运行 char-by-char 相关命令进行测试。

当前调试配置已经包含 --disable-extensions，这样可以减少其他已安装扩展对播放和日志的干扰。

适用场景

• 录制前端页面搭建过程
• 录制 HTML / CSS / JS 教程
• 录制代码讲解视频
• 演示“从占位符逐步填充模板文件”的过程

当前实现边界

• 这版已经支持结构化播放，但仍以“插入”为主，不是完整的 IDE 行为模拟器。
• 复杂重构动作，例如大段删除、移动代码块、随机回改，目前还没有内置。
• 如果某些语言依赖外部 formatter，最终观感仍会受本地 VS Code 环境影响。

如果目标是继续向 code-editing-simulation 那类“更像真实编辑”的演示效果靠近，下一步可以继续扩展删除、替换、停顿节奏和更细粒度的编辑动作。