编辑栏合并成一套,顺手补上撤销重做

liulinhai 2026.10.28 8:24 18 0
Django技术 Django Markdown 博客改造 编辑体验 JavaScript

收录于《把博客搬回家》第 9 篇

上一篇 《收尾两件事》 把评论层和高亮方案各自收成一套,收尾时我顺手问了一句:编辑栏是不是也该统一?查下来答案是——确实不是一套,是两套,而且两边的按钮还不一样。

这一篇就讲怎么把它们合并成一份公共库,以及合并过程中补上的撤销 / 重做。有意思的是,撤销这个功能写完"看起来能用",实测才暴露出两个 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 条

两边按钮集不一样:后台有标题、表格、分隔线,前台没有——评论里大概用不上表格,做的时候就没加。速查表条数也不一样。

真正麻烦的不是重复,是重复带来的不一致:

  1. 加粗、插入链接这类插入逻辑写了两遍,逻辑一旦有偏差,两边行为就不一样;
  2. 状态栏的"未闭合标记"检查也写了两遍——意味着我在评论那边修掉的问题,后台这边照样存在,只是还没人踩;
  3. 改一处要动两个文件,改完还要分别测两边。

这和上一篇处理评论渲染层时是同一个道理:只要出口有两条,不一致迟早会发生。所以合并的理由不是"少写代码",是"少留一条会分叉的路"。

二、合并后的分层

合并的思路是公共库只做控件,装配层只做差异。分完之后是这样:

文件 职责
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。不行,三个原因:

  1. 按钮触发不了原生撤销。能触发它的是 document.execCommand('undo'),这个方法早已废弃,且各浏览器行为不一致,Chrome 里对 textarea 也不保证可用。要做成按钮,就必须自己维护历史。
  2. 脚本改过的内容,原生栈会乱。后台切换格式时,整个 textarea 的值被替换成转换结果——这时候按 Ctrl+Z,浏览器很可能回退到切换前的源码,而不是作者期望的"上一步编辑"。
  3. 快捷键只能覆盖键盘用户,按钮还得有——两个入口必须走同一条路径,否则行为会分叉(这一点后面就咬了我一口)。

所以自己维护快照栈。核心是这么几行:

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 还是没开,那个待办继续挂着。)

Last Modified·2026年10月28日 08:24

暂无评论

您尚未登录,请先才能评论。