两套按钮合并成一套,顺手补上的撤销重做,才是每天用得上的功能。
上一篇 《收尾两件事》 把评论层和高亮方案各自收成一套,收尾时我顺手问了一句:编辑栏是不是也该统一?查下来答案是——确实不是一套,是两套,而且两边的按钮还不一样。
这一篇就讲怎么把它们合并成一份公共库,以及合并过程中补上的撤销 / 重做。有意思的是,撤销这个功能写完"看起来能用",实测才暴露出两个 bug,其中一个还相当隐蔽。
一、两套编辑栏是怎么长出来的
它们是分两次、各写一遍长出来的,不是一开始就设计成两套:
- 先做的是前台评论:评论框要 Markdown,于是有了
md-editor.js,类名前缀mdce-,11 个按钮,速查表 9 条。 - 后来做后台文章:文章编辑也要提示和快捷插入,于是有了
admin-md-hints.js,类名前缀md-,14 个按钮,速查表 11 条。
后台还有第三个脚本 admin-markdown.js,管的是格式切换(CKEditor ↔ Markdown)、分屏和预览——这部分是后台特有的,不该合并。
于是站上真实的状态是这样:
| 位置 | 文件 | 类名 | 按钮 | 速查表 |
|---|---|---|---|---|
| 前台评论 / 回复 | md-editor.js |
mdce-* |
11 个 | 9 条 |
| 后台文章 | admin-md-hints.js |
md-* |
14 个 | 11 条 |
两边按钮集不一样:后台有标题、表格、分隔线,前台没有——评论里大概用不上表格,做的时候就没加。速查表条数也不一样。
真正麻烦的不是重复,是重复带来的不一致:
- 加粗、插入链接这类插入逻辑写了两遍,逻辑一旦有偏差,两边行为就不一样;
- 状态栏的"未闭合标记"检查也写了两遍——意味着我在评论那边修掉的问题,后台这边照样存在,只是还没人踩;
- 改一处要动两个文件,改完还要分别测两边。
这和上一篇处理评论渲染层时是同一个道理:只要出口有两条,不一致迟早会发生。所以合并的理由不是"少写代码",是"少留一条会分叉的路"。
二、合并后的分层
合并的思路是公共库只做控件,装配层只做差异。分完之后是这样:
| 文件 | 职责 |
|---|---|
md-core.js(新) |
公共库:按钮集、insert()、速查表、状态栏与标记检查、createHistory() |
md-editor.js |
前台装配:评论框容器、预览(走评论接口)、输入自动展开预览 |
admin-md-hints.js |
后台装配:认领已有容器、只在 Markdown 模式显示 |
admin-markdown.js |
后台特有:格式切换、分屏、预览(职责不变) |
md-core.css(新) |
公共样式,类名统一为 mdc-* |
md-editor.css / admin-markdown.css |
各留容器与主题差异 |
剩下三处差异确实该留在各自的装配层里,硬合并反而别扭:
- 容器怎么来:前台的评论框要自己建(
.md-comment-editor);后台的容器是admin-markdown.js建好的(.md-editor),admin-md-hints.js只是去认领它。 - 预览接口不同:前台评论是读者输入,必须经
bleach白名单净化;后台是作者自己写,走的是后台预览接口,不做净化——这条界限在上一篇已经划清了,合并时不能糊掉。 - 显示时机不同:前台评论框常驻;后台只在 Markdown 模式下显示,切回 HTML(CKEditor 接管)就得把控件摘掉,否则会出现"富文本编辑器上面挂一排 Markdown 按钮"。
样式同理:公共部分抽到 md-core.css(类名统一 mdc-*),两份主题 CSS 只保留各自的容器与布局差异——前台是评论框的圆角与宽度,后台是字段列对齐(margin-left: 170px)和分屏。
顺带修掉了一个以前没注意的不一致:后台预览里的表格、代码块样式,和前台读者看到的不是同一份。现在后台预览正文也用 mdc-preview-body,跟前台共用一套排版规则——预览的意义就在于"所见即所得",样式都对不上,预览就等于白做。
三、撤销 / 重做:为什么不能用浏览器自带的
编辑栏一直缺撤销 / 重做。这里有个看似省事的做法:不管它,反正浏览器自带 Ctrl+Z。不行,三个原因:
- 按钮触发不了原生撤销。能触发它的是
document.execCommand('undo'),这个方法早已废弃,且各浏览器行为不一致,Chrome 里对textarea也不保证可用。要做成按钮,就必须自己维护历史。 - 脚本改过的内容,原生栈会乱。后台切换格式时,整个
textarea的值被替换成转换结果——这时候按Ctrl+Z,浏览器很可能回退到切换前的源码,而不是作者期望的"上一步编辑"。 - 快捷键只能覆盖键盘用户,按钮还得有——两个入口必须走同一条路径,否则行为会分叉(这一点后面就咬了我一口)。
所以自己维护快照栈。核心是这么几行:
function apply(rec) {
suppress = true; // 恢复期间不打快照
area.value = rec.value;
area.focus();
try { area.setSelectionRange(rec.start, rec.end); } catch (e) { /* ignore */ }
fireInput(area); // 让预览与状态栏跟着更新
suppress = false;
notify(); // 刷新撤销/重做按钮的可用状态
}
配套的几个决策:
- 停顿 400ms 打一个快照,不是每敲一个字符一个。后者一步一撤太碎,撤十次还在同一句话里。
- 撤销时若当前内容还没入栈,先补一个再回退。否则刚敲完还没到 400ms 就撤销,最新那次编辑会丢。
- 恢复时置
suppress:恢复动作自己也会触发input事件,不拦住就会又打一个快照,把 redo 栈冲掉。 - 恢复后派发
input事件,预览和状态栏才会跟着变——否则撤销完内容回退了,右边的预览还停在旧版本。 - 快照上限 200 步,超了丢最早的。
- 快捷键
Ctrl+Z/Ctrl+Shift+Z/Ctrl+Y直接调api.undo()/api.redo(),与按钮同一条路径。 - 后台切格式后重置栈底:
admin-markdown.js在转换完成时派发自定义事件md:reset,编辑栏收到后调history.reset(),把当前内容设为新的"起点"。不然一撤销就退回切换前的 HTML 源码,非常吓人。 - 无可撤销内容时按钮置灰但仍占位,不让工具条在有无历史之间来回跳动。
四、两个 bug,都是"看起来能用"的
功能写完,我用无头 Chrome 加载真实源码做了一遍夹具测试。两个 bug 都是这么抓出来的,而且只走一遍浏览器才能发现——服务端没有任何信号。
4.1 撤销按钮点了没反应,Ctrl+Z 却好使
现象很怪:敲几个字,点「↶」没动静;按 Ctrl+Z 却正常回退。
原因在事件监听的顺序。notify()(刷新按钮可用状态)原本只在 snapshotNow() 里调用,而快照要等 400ms 停顿才打。也就是说——刚敲下第一个字符的那一刻,"可以撤销"这个事实已经成立,但按钮还是灰的,点了自然没反应。快捷键不走按钮,所以照样工作。
area.addEventListener('input', function () {
notify(); // 先刷新按钮状态:可撤销是立刻成立的事实
if (suppress) { return; }
schedule(); // 再排下一个快照(要等 400ms 停顿)
});
教训:凡是"按钮 + 快捷键"双入口的功能,两条路都要单独测。快捷键绕过按钮,会把按钮路径的问题盖住——而用户多半是先点按钮的。
4.2 前台整个编辑栏压根没装配
第二个更严重:评论框下面一个控件都没有,页面上什么提示也没有。
原因是这一行:
area.addEventListener('keyup', status.update);
status.update 作为回调传入时立刻求值,而此时 status 还是 null(它在后面的语句里才被赋值)→ TypeError → 脚本整个中断 → 后面的装配代码一行都没执行。
修法是包一层,把求值推迟到事件真正发生时:
function updateStatus() { if (status) { status.update(); } }
area.addEventListener('keyup', updateStatus);
这类错误只在浏览器控制台里可见,服务端日志干干净净。所以前端改动必须在真实浏览器里跑一遍,光看"代码逻辑对不对"不够——逻辑对,但求值时机不对,一样全盘失效。
五、验证
分两层做,第二层是这次新想出来的办法:
夹具测试(无头 Chrome 直接加载真实源码文件)
- 后台:17 个按钮齐全,撤销 / 重做存在且初始置灰;加粗 → 撤销回退 → 重做恢复;
Ctrl+Z/Ctrl+Shift+Z生效;插表格、插围栏、状态栏报"表格缺分隔行";切回 HTML 后控件被摘除。 - 前台:18 个按钮(17 + 预览);输入后预览自动展开,手动收起后本页不再自动展开;撤销 / 重做生效;零 JS 错误。
端到端(把真实页面喂给浏览器)
评论框模板包在 {% if user.is_authenticated %} 里,匿名访问的文章页根本没有 <textarea>——直接让浏览器打开 /post/252/ 会得出"编辑栏没装配"的错误结论。办法是用 Django 的测试客户端 force_login 后把渲染好的页面导到 static/ 下,再让 Chrome 用 --host-resolver-rules="MAP siliu.online 127.0.0.1" 加载,测完删掉。这样验的是真实页面,不是我手搓的简化 HTML。
结果:/post/252/ 的容器、工具条、18 个按钮、撤销 / 重做 / 预览、速查表、状态栏齐全;后台 change 页的 md-editor 容器、分屏工具条、17 个插入按钮、速查、状态栏、预览区齐全。四个 JS 文件 node --check 通过,全站 13 个页面 200。
六、现在的状态
| 文件 | 行数 | 说明 |
|---|---|---|
md-core.js |
475 | 公共库:17 个按钮、插入、速查、状态栏、历史栈 |
md-editor.js |
177 | 前台装配(从原来的完整实现瘦下来) |
admin-md-hints.js |
125 | 后台装配(同上) |
admin-markdown.js |
449 | 后台特有,职责不变 |
按钮统一成 17 个(撤销 ↶ / 重做 ↷ / 粗体 / 斜体 / 删除线 / 行内代码 / H2 / H3 / 段落 / 无序 / 有序 / 引用 / 链接 / 图片 / 代码块 / 表格 / 分隔线),前台再多一个「预览」,共 18 个。加一个按钮现在只需要改 ACTIONS 数组一处,前后台同时生效。
回过头看,这两轮做的事其实是同一件:把重复的出口收成一条。评论渲染层收成一条,代码高亮收成一套,编辑栏收成一份。每收一处,就少一处"两边不一致"的可能——而这类不一致最烦人的地方在于,它通常不会报错,只是某天你发现评论里的表格和文章里的表格长得不一样,才想起来去查。
(HTTPS 还是没开,那个待办继续挂着。)
定稿于 2026.10.28
本书目录
- 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
- 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
- 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
- 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
- 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
- 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
- 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
- 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
- 09 编辑栏合并成一套,顺手补上撤销重做
- 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
- 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
- 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
- 13 把文章编成书:给博客加一个「文集」板块
- 14 网站开发里程碑小结:siliu.online 的架构与特点
- 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
- 16 本站功能与使用指南:siliu.online 一览
- 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器