Electron-OH 鸿蒙实战:笔记应用里的代码高亮,50 行 tokenizer 就够了

笔记应用要贴代码,代码块就得有颜色——引第三方 highlight.js 太重,还和自写 Markdown 渲染器的安全模型打架。这篇文章用一个跑在鸿蒙平板上的 Electron-OH 笔记应用,把「怎么在不破坏 XSS 防线的前提下做一套 50 行的轻量 tokenizer」一次讲透:语言家族怎么归并、正则怎么拼、空匹配怎么防死循环、以及我在 \b 上白白耗掉的半天。

  • 工程:ohos_hap,渲染层代码在 web_engine/src/main/resources/resfile/resources/app/src/
  • 本文对应场景:04-轻量代码高亮Tokenizer
  • 渲染层:自写 Markdown 渲染器(renderer.js),跑在 ArkWeb 里

0. 环境与实测设备

项版本/型号
DevEco Studio6.0.0(build 6.0.0.858,API 20)
应用版本ohos_hap 1.0.12(versionCode 1000012)
compatibleSdkVersion6.0.0(20)
目标平台HarmonyOS 平板 / 2in1
渲染层ArkWeb + 自写 Markdown 渲染器(renderer.js)
高亮方案自写 tokenizer,约 50 行 JS,零依赖

表格里的每一行都会在后文出现:compatibleSdkVersion 决定了 Web 组件的能力下限,应用版本 1.0.12 是这次高亮方案上线的那一版,真机是鸿蒙平板和 2in1——这套 tokenizer 是在键盘齐全的 2in1 上反复贴代码贴出来的。

1. 「代码块不就是换个字体吗」——这个问题是怎么找上我的

我一开始也以为代码高亮是小事:笔记应用嘛,代码块用 <pre><code> 一包、等宽字体一上、背景一灰,齐活。头两个月的真实使用也确实支撑这个判断——我自己贴的多是几行的 shell 命令和 ArkTS 片段,没颜色也能看。

直到有天往笔记里贴了一段四十多行的 ArkTS 页面代码,回头翻的时候发现:没有颜色的大段代码,找关键行全靠肉眼扫。if 和变量名长得一模一样,注释和逻辑混在一起,十秒钟定位不到想改的那行。这时候才意识到,高亮不是装饰,是检索工具——人扫读代码靠的是颜色预分类,不是逐行读字。

那就引第三方库?highlight.js 是标准答案。但我在评估的时候卡住了,卡点有两个:

第一,体积。highlight.js 全量包(common 语言集)压完也有大几十 KB,而我的笔记渲染层是自写的 Markdown 渲染器,整个 renderer.js 也就一千多行。为一个功能引入一个比自己渲染器还大的依赖,不值。

第二,也是更麻烦的:安全模型冲突。我的渲染器是「先 escapeHtml 整段、再按白名单规则拼 HTML」的模型,任何用户输入在进 HTML 之前都先被转义。highlight.js 的工作方式是拿到 DOM 里的原文本,自己生成带 <span class="..."> 的富 HTML 再塞回去——它的 class 名和输出结构是它说了算,我这个「所有入 HTML 的东西都过我自己的转义」的防线就被绕开了。社区里 highlight.js 因为语言定义的解析问题出过安全通告,我这种「笔记内容来自各种外部帖子」的场景,不想赌。

所以这个题目的边界很清楚:自己写一个零依赖的轻量 tokenizer,输出全部经过 escapeHtml,span 是代码写死的受控输出,不引入任何第三方解析库;牺牲语法精度,换安全模型和体积。

拆下来是三件事:

  • 一个「语言后缀 → 高亮规则家族」的映射,30 多种后缀归并成少数几个家族;
  • 一个按家族构造的正则,一次扫描切出注释/字符串/关键字/数字四类 token;
  • 接进现有 Markdown 渲染器的围栏状态机,闭合时切一刀。

下面是干完之后的完整记录,包括我踩的每一个坑。

先埋一个第 6 节要回收的现场。第一版写完,我在笔记里贴了段代码测试,结果是这样的:

// 笔记预览里的实际渲染结果(第一版)
const list: number[] = [1, 2, 3];
// 期望:const、number 有蓝色,"1, 2, 3" 有色
// 实际:整段灰底黑字,一个颜色都没有,和没实现一样

不报错、不崩溃、控制台干干净净,就是没颜色。这个「静默失效」的现场,第 6 节坑一会展开。

2. 效果展示

按老规矩,先给效果再讲原理。

请添加图片描述

这张图是贴了一段 ArkTS 组件代码之后的预览效果。这里每一块颜色都不是装饰:@Entry、struct、build 前面的蓝色来自 .tok-kw(#0550ae,加粗 600),双引号里的绿色来自 .tok-string(#1a7f37),最上面那两行斜体灰是 .tok-comment(#86909c),1、2、3 这些数字是 .tok-num 的棕色(#b3541e)。四个 class、四条 CSS,就是全部的「主题」。

请添加图片描述

这张图验证的是家族切换。同一套 tokenizer,python 和 sh 围栏走的是 # 注释规则,ts 走的是 // 和 /* */。没有为 Python 单写一套引擎,只是换了一条注释正则和一个关键字表。

请添加图片描述
这张图是刻意的降级:围栏后面不写语言、或者写了个我没登记的后缀(比如 text、diff),代码块照样能渲染——转义照做、排版照做,只是没颜色。未登记的语言不炸、不高亮,这是设计出来的行为,不是漏了。

请添加图片描述

说明一下边界:截图都是平板上的预览态,编辑态里 Markdown 源文本仍然是纯文本,高亮只发生在预览渲染这条链路上。另外这几个颜色是我按 GitHub Light 的色系挑的,浅色背景下对比度够,没有做暗色主题——暗色主题要另配一组色值,本文不展开。

请添加图片描述

请添加图片描述

3. 原理:一次扫描到底切出了什么

轻量 tokenizer 的原理一句话就能说清:用一条「四选一」的正则在源码上反复 exec,每命中一段就按命中的是第几个捕获组决定它是什么 token,命中段之外的部分照常转义。

整条流水线是这样的:

笔记源文本(用户输入)
  │
  ▼
renderMarkdown 逐行扫描 ── ```开围栏:记下 codeLang,进入收集模式
  │                        ```闭围栏:codeBuf.join('\n') 交给 highlightCode
  ▼
highlightCode(src, lang)
  ├── LANG_FAM[lang.toLowerCase()] ── 查语言家族;查不到 → escapeHtml(src) 直接返回
  ├── buildCodeRe(fam) ── 按家族拼注释规则、选关键字表,new RegExp(..., 'g')
  └── while (re.exec) 逐段切:
        命中段之间 → escapeHtml(slice)
        命中段本身 → escapeHtml(m[0]) 后包 <span class="tok-xxx">
  │
  ▼
<pre><code class="lang-xxx">…带 span 的 HTML…</code></pre>

把它和标准 tokenizer(highlight.js 这类)对比一下,就知道我在哪些地方「偷懒」、偷懒换来的是什么:

维度标准库(highlight.js 等)本方案
解析单位词法规则集 + 启发式语言识别一条家族级正则
token 类别十几种(属性、标签、函数名……)4 种:注释/字符串/关键字/数字
输出方式自己生成富 HTML 注回 DOM命中段转义后包受控 span
依赖体积几十 KB 起步0,约 50 行
安全模型信任库的输出所有进 HTML 的文本都过自己的 escapeHtml
精度高(嵌套高亮、作用域)低(字符串里出现 if 也会被……不会,正则顺序保证了字符串优先)

最后一行要多说两句。有人会问:字符串里出现 return 这种词怎么办?答案是正则的交替顺序替我解决了——(comment)|(string)|(kw)|(num) 四个分支按这个顺序排,正则引擎从左往右试,注释和字符串永远先于关键字被匹配走。"return value" 整段会命中字符串分支,return 这个词根本轮不到关键字分支。这就是为什么一条正则也敢自称 tokenizer:顺序就是优先级。

这个模型判断值得加粗钉死:先转义、后拼接,span 的 class 是代码写死的常量——用户输入没有任何一条路能进 HTML 标签的属性位置。 安全性不是靠「检查再放行」获得的,是靠「结构上不存在注入通道」获得的。第 5.4 节会把这条防线逐字拆开。

而这套方案能立住的两个细节,直接决定了后面所有的降级逻辑:一是家族归并粒度够粗(粗到一套规则能覆盖绝大多数帖子代码),二是未登记语言的退路是纯转义。这两条分别在 5.2 和坑四里展开。

4. 工程怎么搭

先看渲染层在工程里的位置。这是个 ArkWeb 承载 Web 内容的结构,Web 资源放在 resfile 里随 HAP 分发:

web_engine/src/main/resources/resfile/resources/app/
├── index.html                 // 页面骨架:编辑区 + 预览区(md-preview)
├── src/
│   ├── renderer.js            // 自写 Markdown 渲染器:escapeHtml、inlineMd、
│   │                          //   renderMarkdown、LANG_FAM、buildCodeRe、highlightCode
│   ├── style.css              // .md-body 排版 + .tok-* 四个高亮 class(1117-1133 行)
│   └── main.js               // 编辑器胶水:开关预览、附件、事件绑定
└── (其他静态资源)

这次高亮相关的代码全部落在 renderer.js 的 882–925 行和 renderMarkdown 的围栏分支里,外加 style.css 里的四条规则。改动清单是:

  • renderer.js:新增 escapeHtml、LANG_FAM、KW_C/KW_PY/KW_JSON、buildCodeRe、highlightCode,约 50 行;
  • renderer.js 的 renderMarkdown:围栏闭合分支从「escapeHtml 后塞进 <pre>」改成「交给 highlightCode」;
  • style.css:新增 .tok-comment/.tok-string/.tok-kw/.tok-num 四条。

工程化上有个前提值得单独说:高亮函数必须是纯函数。highlightCode(src, lang) 输入字符串、输出字符串,不碰 DOM、不碰全局状态。这保证了它可以被任何调用方复用(围栏渲染用、以后想做「选中片段预高亮」也能用),也保证它可以直接进单元测试——坑五里那个断言失配的测试就是这么测出来的,不需要起 Web 组件。

最小接入路径就三步。第一步,渲染入口拿到笔记源文本:

// src/renderer.js - 预览开关处理(节选)
btnMdToggle.addEventListener('click', () => {
  mdPreviewOn = !mdPreviewOn;
  if (mdPreviewOn) {
    mdPreviewEl.innerHTML = renderMarkdown(noteText);
  }
});

第二步,renderMarkdown 里围栏开合(完整状态机见 5.5)。第三步,CSS 四条规则上线,高亮就算接完了。

容易被忽略的一点是 mdPreviewEl.innerHTML = ... 这个赋值点。它是整个渲染器唯一的 HTML 注入出口,所以渲染器内部所有函数的共同契约就是:返回值里的用户输入必须已经转义。highlightCode 作为这条链路的一环,签名上的承诺就是「输出可安全 innerHTML」。这个契约约束了后面所有的实现决策。

5. 把代码讲透

这一节是全文最值钱的部分。五个小节,对应五个具体的实现决策,代码全部原样来自 renderer.js。

5.1 escapeHtml:整条防线的第一块砖

先看地基。整段只有五行:

// src/renderer.js - escapeHtml()(882-886 行,原样)
function escapeHtml(s) {
  return String(s).replace(/[&<>"']/g, (c) => (
    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
  ));
}

五个字符、五个实体,没有第三个分支。有人会问:为什么不转义反斜杠、为什么不处理别的Unicode?因为要防的注入向量就藏在这五个字符里:& 是实体解析的入口,< 开标签,> 闭标签," 和 ' 进属性值。其余字符在「不进标签、不进属性」的前提下都是死文本。这五个就是全集,多转义一个都是噪音。

三个细节值得单独说:

第一,先转义后解析的顺序不可动摇。 看 renderMarkdown 里段落是怎么拼的(973 行):html += '<p>' + inlineMd(escapeHtml(para.join(' '))) + '</p>'——先 escapeHtml 整段,inlineMd 拿到的已经是转义后的世界,它后面拼出的 <strong>、<a> 都是基于「用户输入里已经不可能出现裸 <」这个前提工作的。顺序反了,整个安全模型塌掉。

第二,行内代码用了占位符护法。 inlineMd 里行内 code 先被替换成 \u0000序号\u0000 占位符(930-933 行),等粗体斜体都处理完再还原成 <code>...</code>。这是防止「先解析出的内容被后续规则二次加工」。围栏代码块不需要这层——它在逐行扫描时就被隔离进 codeBuf 了,物理隔离比占位符更彻底。

第三,这个函数是全文被调用最多的函数。 段落转义用它,codeLang 进 class 用它,token 命中段用它,兜底尾段还用它。它的正确性就是整条链路的正确性,所以我给它写的测试比其他任何函数都多。

5.2 LANG_FAM:30 多种后缀归并 4 个家族

家族表是整套方案的「路由层」:

// src/renderer.js - LANG_FAM(890-895 行,原样)
const LANG_FAM = {
  js: 'c', javascript: 'c', ts: 'c', typescript: 'c', ets: 'c', json5: 'c',
  java: 'c', c: 'c', cpp: 'c', h: 'c', cs: 'c', go: 'c', rust: 'c', swift: 'c', kotlin: 'c', dart: 'c',
  py: 'py', python: 'py', sh: 'py', bash: 'py', shell: 'py', yml: 'py', yaml: 'py', conf: 'py', ini: 'py',
  json: 'json', css: 'css', html: 'css'
};

30 多个后缀,4 个家族。归并的依据不是语法相似度,是注释规则和关键字集合的相似度:

家族注释规则关键字表覆盖的后缀
c// 和 /* */KW_C(60+ 词)js/ts/ets/java/c/cpp/go/rust/dart/swift/kotlin 等约 16 种
py#KW_PY(30 词)py/sh/bash/yaml/yml/conf/ini 等 9 种
json无注释KW_JSON(3 词)json
css/* */(借 c 家族)KW_Ccss/html

归并粒度粗,是有意为之。我统计过自己笔记里贴过的语言:ArkTS、JS、Python、shell、JSON 五种占九成以上。而这些语言在「注释长什么样、常用关键字是哪些」这个层面,恰好能压进上面四格。为每种语言单独养一套关键字表的收益,覆盖不了维护成本。

这里有一个容易较真的点:yaml 标注符是 #,shell 也是 #,但 yaml 的字符串通常不带引号——拿 c 家族那套「双引号字符串」规则去切 yaml 会漏掉大部分字符串。对,就是会漏。但漏掉的后果只是「字符串没变绿」,注释和关键字照样有色,可读性损失可以接受。轻量方案的哲学就在这:宁可粗而全,不要精而漏。

再看查表那一行(910-911 行):

// src/renderer.js - highlightCode() 开头(910-911 行,原样)
const fam = LANG_FAM[String(lang || '').toLowerCase()];
if (!fam) return escapeHtml(src);

三重防御:lang 可能是空串(围栏没写语言)、可能是用户随手写的 TS(大写)、可能压根没登记(```diff)。String(lang || '') 吃掉 null/undefined,toLowerCase() 吃掉大小写,!fam 吃掉未登记——三条路殊途同归,落到 escapeHtml(src)。这就是效果展示里第三张截图的来源:查表失败不是错误,是一个明确定义的降级终点。

5.3 buildCodeRe:一条正则吃四类 token

核心正则的构造函数:

// src/renderer.js - buildCodeRe()(900-907 行,原样)
function buildCodeRe(fam) {
  const comment = fam === 'py' ? '#[^\\n]*' : '\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/';
  const kw = fam === 'py' ? KW_PY : fam === 'json' ? KW_JSON : KW_C;
  return new RegExp(
    '(' + comment + ')|("(?:\\\\.|[^"\\\\])*")|(?:\\b(' + kw + ')\\b)|\\b(\\d+(?:\\.\\d+)?)\\b',
    'g'
  );
}

把拼出来的正则翻译成人类语言,四条分支按优先级排:

1. (comment)                    注释:py 家族用 #...,其余用 //... 或 /* ... */
2. ("(?:\\.|[^"\\])*")          双引号字符串,支持 \" 转义
3. (?:\b(kw)\b)                 关键字,词边界包住,不捕获外层
4. \b(\d+(?:\.\d+)?)\b          整数或小数

四个细节值得单独说:

第一,注释分支为什么按家族切换。 py 家族一条 #[^\\n]* 到行尾;其余家族 \\/\\/[^\\n]* 吃行注释、\\/\\*[\\s\\S]*?\\*\\/ 吃块注释。块注释用 [\s\S] 而不是 .,因为 . 不匹配换行,跨行的 /* ... */ 会切不断;用非贪婪 *? 而不是贪婪 .*,否则同屏两个块注释会被从第一个 /* 一路吃到最后一个 */。这一对组合是块注释正则的标准答案,抄就行。

第二,字符串分支的 (?:\\.|[^"\\])* 是转义感知的关键。 \\. 先匹配「反斜杠+任意字符」,把 \" 这种转义引号先吃掉,剩下的 [^"\\] 匹配普通字符。如果写成朴素的 "[^"]*","他说:\"你好\"" 会在第一个 \" 处被切断,后半段被当成代码处理。顺序同样不可换:把 [^"\\] 放前面,碰到反斜杠就断。

第三,关键字分支外层 (?:...) 不捕获。 捕获组会占用编号,把后面数字分支的 m[4] 顶成 m[5],下游按编号取值的代码全乱。用非捕获组占位,捕获组编号和 token 类别的映射才稳定:m[1] 注释、m[2] 字符串、m[3] 关键字、m[4] 数字。

第四,\b 词边界让关键字表可以偷懒。 KW_C 里有个 c(c 语言的后缀映射进 c 家族,关键字表共用 KW_C),如果没有 \b,变量名里的字母组合会被误杀。有 \b 兜底,关键字表里就算混进单字母词也不会出事。当然坑一会讲,这个 \b 自己也差点把我埋了。

json 家族没有注释分支吗?有,comment 变量在 fam === 'json' 时走的是 else 分支,拿到的是 // 那套——JSON 标准里没有注释,但实际帖子里常出现带 // 的 json5 风格片段,留着这条规则是容错,不是错误。css 家族同理走的 KW_C,CSS 的属性名大多不是关键字,但它有 /* */ 注释和大量数字值(12px 的 12、#fff 里命不中的部分),归进 c 家族是性价比最高的选择。

5.4 highlightCode:while + exec 逐段切,转义在每个路口把关

主循环,全文最核心的 17 行:

// src/renderer.js - highlightCode()(909-925 行,原样)
function highlightCode(src, lang) {
  const fam = LANG_FAM[String(lang || '').toLowerCase()];
  if (!fam) return escapeHtml(src);
  const re = buildCodeRe(fam);
  let out = '';
  let last = 0;
  let m;
  while ((m = re.exec(src)) !== null) {
    if (m.index > last) out += escapeHtml(src.slice(last, m.index));
    const cls = m[1] ? 'tok-comment' : m[2] ? 'tok-string' : m[3] ? 'tok-kw' : 'tok-num';
    out += '<span class="' + cls + '">' + escapeHtml(m[0]) + '</span>';
    last = m.index + m[0].length;
    if (m[0].length === 0) re.lastIndex++;   // 防御:空匹配死循环
  }
  out += escapeHtml(src.slice(last));
  return out;
}

逻辑分三段:命中段之前的间隙照常转义(917 行);命中段按捕获组编号定 class、转义后包 span(918-919 行);循环结束后把最后一段尾巴转义收尾(923 行)。三段合起来,src 的每一个字符都恰好经过一次 escapeHtml,无一遗漏,无一重复。

三个细节值得单独说:

第一,escapeHtml(m[0]) 这个位置是安全模型的心脏。 注意顺序:是先转义、再包 span,不是先包 span 再转义整段(那会把 span 标签自己转掉)。命中段是用户输入的一部分,它里面的 <、& 必须死在这里;span 的 class 来自 cls,而 cls 是四个字符串字面量的三目表达式链——这个三元链就是「受控输出」的全部含义:进入标签内部的每一个字节都能在源码里指着说这是常量。用户输入进 span 只有一条路:作为 span 的文本内容,且已被转义。

第二,捕获组编号决定 class 的三目链是有顺序依赖的。 m[1] ? ... : m[2] ? ... : ... 依赖「正则四条分支互斥、编号固定」这个上游承诺(5.3 第三点)。如果哪天在中间插了一条新分支,这里必须同步改——这是本方案里唯一的「魔法数字」耦合,50 行规模下值得,500 行就不值了。

第三,921 行是保命行。 if (m[0].length === 0) re.lastIndex++。带 g 标志的正则遇到零宽匹配时 lastIndex 不前进,exec 永远返回同一个空匹配,while 死循环,渲染进程直接卡死。这条防御现在看起来是多余的——当前四条分支都能匹配非空内容——但它防的是未来:哪天往正则里加了一条可空匹配的规则(比如 (?:xx)?),这条 921 行就是唯一把它拦下来的人。防御性代码的注释里我特意写了「防御:空匹配死循环」,就是给未来的自己留的便条。坑三有实战化的展开。

5.5 renderMarkdown 的围栏状态机:高亮的接入口

最后看 tokenizer 怎么接进 Markdown 渲染。围栏处理在 renderMarkdown 的逐行循环里(984-1005 行):

// src/renderer.js - renderMarkdown() 围栏分支(984-1005 行,原样)
for (let lineNo = 0; lineNo < lines.length; lineNo++) {
  const line = lines[lineNo];
  const fence = /^```(\S*)/.exec(line);
  if (fence) {
    if (inCode) {
      html += '<pre><code' + (codeLang ? ' class="lang-' + escapeHtml(codeLang) + '"' : '')
        + '>' + highlightCode(codeBuf.join('\n'), codeLang) + '</code></pre>';
      codeBuf = [];
      codeLang = '';
      inCode = false;
    } else {
      flushPara();
      closeList();
      inCode = true;
      codeLang = fence[1] || '';
    }
    continue;
  }
  if (inCode) {
    codeBuf.push(line);
    continue;
  }
  // ……标题/列表/段落的常规解析
}

一个布尔 inCode、一个字符串 codeLang、一个数组 codeBuf,三样东西构成状态机。开围栏时 flushPara() 和 closeList() 先把未闭合的段落和列表收掉——围栏出现在段落中间时,前面的文字要先落成 <p>,否则顺序错乱。开围栏到闭围栏之间的所有行原样进 codeBuf,不经过任何 Markdown 解析:代码块里的 # 标题、**粗体** 都是死文本。这是物理隔离,比 5.1 说的占位符方案更硬。

三个细节值得单独说:

第一,codeLang 进 class 也过了 escapeHtml。 989 行那个 ' class="lang-' + escapeHtml(codeLang) + '"' 看起来多此一举——codeLang 来自 /^```(\S*)/,\S* 不匹配空格,引号 <>"' 里只有引号算 \S……不对," 和 ' 都是 \S!```" onmouseover="alert(1) 这样的围栏头,codeLang 就会带上引号。虽然预览区不可交互、真要利用还得绕 CSP,但「属性值位置必须转义」这条纪律不该有例外。一行转义买断一类攻击面,值。

第二,闭合时才切,不是开围栏时就处理。 代码块必须收齐所有行才知道全貌(跨行块注释、多行字符串),所以 codeBuf.join('\n') 延迟到闭围栏。副作用是未闭合的围栏(用户忘写第二个 ```)会让后面整篇都进 codeBuf——这是 Markdown 的标准行为,预览上表现为「从那行起全是代码块」,用户看得懂,不需要聪明地自动闭合。

第三,codeBuf.join('\n') 还原了换行。 逐行收集时行尾换行符被 split 吃掉了,join 用 \n 补回来。这一步不做,块注释正则 [\s\S]*? 里的换行就没了着落。renderMarkdown 开头的 replace(/\r\n/g, '\n')(963 行)先统一了换行符,Windows 下写的笔记贴进来也不会出现 \r 残留干扰正则。

最后把 CSS 一并交代,四个 class 对应四条规则:

/* src/style.css - 代码块语法高亮(1117-1133 行,原样) */
.tok-comment {
  color: #86909c;
  font-style: italic;
}

.tok-string {
  color: #1a7f37;
}

.tok-kw {
  color: #0550ae;
  font-weight: 600;
}

.tok-num {
  color: #b3541e;
}

色值是我按 GitHub Light 色系调的:关键字蓝 #0550ae 加粗 600,字符串绿 #1a7f37,注释灰 #86909c 斜体,数字棕 #b3541e。选这四色的标准只有一个:浅灰代码底(.md-body pre)上对比度都过线,且四色互相不混淆。没有暗色主题,prefers-color-scheme 的适配在待办里。

6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。

坑一:\b 是退格符——一屏代码一个色都没有

坑一:正则写在字符串里少打一个反斜杠,\b 静默变成退格符,关键字全军覆没。

现象就是第 1 节埋的那个现场:贴了一段 ArkTS,预览里灰底黑字,const、class、struct 一个颜色都没有。不报错、不崩溃、控制台干干净净。

我的第一版是这么拼的:

// 第一版 buildCodeRe(有 bug)
return new RegExp(
  '(' + comment + ')|("(?:\\\\.|[^"\\\\])*")|(?:\b(' + kw + ')\b)|\b(\d+(?:\.\d+)?)\b',
  'g'
);

排查过程很曲折。一开始以为是关键字表没接上,把 kw 变量打出来看——内容好好的,const|let|var|... 一个不少。又怀疑家族查表失败,在 highlightCode 入口打日志——fam 返回的是 'c',路由正常。再怀疑正则整体失配,拿一段 "hello world" 测字符串分支——居然是有色的!

这个现象很关键:字符串分支有色、关键字分支没色,说明正则本身在跑,只有第三、四条分支是死的。盯着这两条分支和字符串分支的差异看,唯一的区别就是 \b。突然反应过来:字符串里写 '\b',那是 chr(8) 退格符,不是词边界。正则字面量里 /\bkw\b/ 的 \b 是词边界元字符;但放进 JS 字符串再 new RegExp,\b 在字符串层面就先被解释成了退格符,传给正则引擎的已经是「匹配一个退格字符」的正则。源代码里根本没有退格符,所以永远匹配不上,而且不报任何错。

对照验证一分钟就锁死了:

// 排查时的最小复现
/\bconst\b/.test('const a = 1')            // true —— 字面量没问题
new RegExp('\bconst\b').test('const a = 1') // false —— 字符串里 \b 是退格符
new RegExp('\\bconst\\b').test('const a = 1') // true —— \\b 才是词边界

修复就是把第三、四分支里的 \b 全部改成 \\b,也就是现在 904 行的样子('(?:\\b(' + kw + ')\\b)|\\b(\\d+(?:\\.\\d+)?)\\b')。改完一保存,满屏的蓝绿灰棕立刻回来了,前面耗掉的半天显得格外讽刺。

字符串里造正则,\b 必须写成 \\b;退格符不报错、只是静默失效,是最坑的那一类 bug。

坑二:tokenizer 的输出要进 innerHTML,安全模型必须重新过一遍

坑二:高亮意味着输出富 HTML,第一版差点把「直接拼 span」当成理所当然。

这不是一个报错坑,是一个设计坑,但比报错坑重要。高亮的本质是往 <pre><code> 里塞 <span class="...">,而我的渲染器安全模型只有一条:所有用户输入先进 escapeHtml,再拼 HTML。tokenizer 一引入 span,「拼接 HTML」这个动作本身就突破了原来的流程,必须回答一个问题:span 从哪来、里面装什么、有没有用户输入能进标签结构?

第一版我顺手写成了这样:

// 反面教材(没上线,写完自己叫停了)
out += '<span class="tok-kw">' + m[0] + '</span>';  // m[0] 没转义就进 span

推演一个攻击面就明白了:笔记里贴一段 const s = "<img src=x onerror=alert(1)>",字符串分支命中后 m[0] 是带尖括号的原文,直接拼进 HTML,innerHTML 一赋值,img 标签就活了。注释里写 <!-- 之类同理。预览区虽然禁了脚本执行(CSP 挡着),但 img 外链请求、布局破坏这类非脚本向量是活的。

现在的实现(919 行)是:

// src/renderer.js - highlightCode()(919 行,原样)
out += '<span class="' + cls + '">' + escapeHtml(m[0]) + '</span>';

逐字审计这个模板字符串:cls 来自 m[1] ? 'tok-comment' : ... 三目链,四个候选全是源码里的字符串字面量,用户输入零参与;m[0] 是用户输入,进 span 前已过 escapeHtml,< 变 &lt;,不可能重新构成标签。用户输入在整个 tokenizer 里能到达的位置只有一处:span 的文本内容,且必然已转义。 span 是受控输出,不破坏安全模型——这句注释就写在 889 行,是给代码审计者看的,也是给三个月后的我看的。

先转义整段、命中 token 再 escapeHtml(m[0]) 后包受控 span——span 的 class 是代码写死的常量,没有用户输入能进标签属性,所以不破坏 XSS 防线。

坑三:空匹配死循环——一行防御换整个渲染进程的命

坑三:正则可零宽匹配时 re.exec 的 lastIndex 不前进,while 死循环。

这个坑是我从另一个项目的旧伤里带过来的教训,这次是主动防御,但值得完整讲一遍机理。带 g 标志的正则,exec 从 lastIndex 开始找匹配,找到后把 lastIndex 设为 match.index + match[0].length。问题在 match[0].length === 0 时:lastIndex 停在原地不动,下一次 exec 还在同一位置找到同一个空匹配,循环条件永远为真:

// 最小复现:可空分支导致的死循环
const re = /(a?)*b/g;        // 经典可空匹配
// 若把 'b' 分支去掉、文本没有 b:
// exec 永远在 lastIndex 处返回空匹配,while 循环体无限执行
// 表现:页面卡死,ArkWeb 渲染进程吃满 CPU,笔记预览无响应

在我的四分支正则里,当前没有任何分支能匹配空串(注释至少 1 字符、字符串至少 2 个引号、关键字至少 1 词、数字至少 1 位),所以死循环「现在」不会发生。但 921 行还是写了:

// src/renderer.js - highlightCode()(921 行,原样)
if (m[0].length === 0) re.lastIndex++;   // 防御:空匹配死循环

为什么明知不会触发还写?因为这条正则是活的——buildCodeRe 按家族拼规则,以后加家族、加 token 类型(比如给 markdown 家族加 (?:^|\s) 这类含位置的规则),零宽匹配随时可能被引入。这种 bug 的表现是整个预览卡死且无任何报错,真机上一旦上线,排查成本远高于现在这行代码的成本。

验证方式也简单,把四分支正则换成构造出来的可空正则跑一遍 highlightCode,没有 921 行时卡死、有 921 行时正常返回。

正则可零宽匹配时 exec 的 lastIndex 不前进,防御就一行:空匹配时手动 lastIndex++。这不是洁癖,是给未来改正则的人买的保险。

坑四:语言家族归并粒度——想按语言精确分表的冲动

坑四:第一版想给每种语言配独立关键字表,表越养越大,最后砍回 4 个家族。

这个坑的形态是「过度设计被真机使用数据打脸」。第一版我按语言精确分表:js 一张表、ts 一张表、go 一张表、rust 一张表……写到第五张的时候自己先烦了:rust 的 fn、go 的 func、dart 的 final,全是三五个词的差异,却要各养一张表、各走一条分支。

真正的转折是统计自己的使用数据:笔记里贴过的语言,ArkTS/JS/Python/shell/JSON 占九成以上,其余的偶尔一两段。这些主流语言在「注释写法 + 核心关键字」层面高度重叠——if、for、return、true/false/null 几乎全家族通用。为剩下的长尾语言精确建模,收益趋近于零。

于是砍成现在的 4 家族(890-895 行):c 家族一张 60 词的大表通吃 js/ts/ets/java/c/cpp/go/rust/swift/kotlin/dart 等 16 种,py 一张 30 词表通吃 py/sh/yaml 等 9 种,json 3 词,css 借用。砍完之后真机回测,肉眼差异只有:go 的 func 不显蓝了(KW_C 里没有)——可接受,它旁边的注释和字符串照样有色。

配套的降级也一起定了(911 行):!fam 时 return escapeHtml(src)。未登记的语言不炸、不高亮,排版照旧。这比「识别失败就报错」友好得多——用户贴个 ```toml,代码块还是干干净净的代码块。

归并粒度跟着使用数据走:一套粗规则覆盖九成场景,未登记语言退化为纯转义,比五张精确表更接近「对的方案」。

坑五:escapeHtml 之后,测试断言全失配

坑五:写单元测试时断言字符串里含 "hi",实际输出是 &quot;hi&quot;。

tokenizer 是纯函数,我按惯例给它配了单元测试。第一组断言很快翻车:

// 测试第一版(断言失配)
const out = highlightCode('const s = "hi"', 'js');
assert(out.includes('"hi"'));   // 失败!
// 实际 out 是:
// <span class="tok-kw">const</span> s = <span class="tok-string">&quot;hi&quot;</span>

排查只花了一分钟,但暴露的认知问题值钱:escapeHtml 把 " 转成了 &quot;(882-886 行的白名单里有 "),所以输出世界里不存在裸的双引号。我的断言还活在「转义前的世界」里。

修法不是绕开转义,是把断言按转义后的世界重写:

// 测试修正版(按转义后的世界断言)
const out = highlightCode('const s = "hi"', 'js');
assert(out.includes('&quot;hi&quot;'));                       // 字符串内容已转义
assert(out.includes('<span class="tok-kw">const</span>'));    // 关键字 span 正确
assert(!out.includes('<img'));                                 // 注入样本必须被转义成死文本

顺带把注入样本也补进了测试集:<script>、<img onerror>、"、' 混进代码的用例,断言全部是「输出里出现的是实体而不是标签」。这组测试后来成了安全模型的回归防线——谁改 escapeHtml 或 highlightCode,跑一遍就知道防线还在不在。

先转义后拼接的渲染器,测试断言要按「转义后的世界」来写;断言失配往往不是测试错了,是你对输出世界的想象错了。

7. 现在怎么用:从 Demo 到依赖

这套 tokenizer 没有依赖,接入就是把三样东西拷进渲染层:renderer.js 里那 50 行(escapeHtml、LANG_FAM、三个关键字常量、buildCodeRe、highlightCode),renderMarkdown 的围栏分支,style.css 的四条 .tok-* 规则。如果你的渲染器不是自写的,也能单独用 highlightCode:

// 最小用法:输入源码 + 语言后缀,输出可直接 innerHTML 的字符串
document.getElementById('out').innerHTML = highlightCode(src, 'ts');
// 未登记语言自动退化为 escapeHtml(src),无需调用方处理

构建与验证走的是 HAP 常规链路:DevEco Studio 里 hvigorw assembleHap 出包,真机安装 1.0.12(versionCode 1000012),预览开关切到 Markdown 预览,贴代码验证。测试方面,tokenizer 相关的单元测试目前 14 个用例,覆盖四家族命中、未登记语言降级、转义注入样本、空串输入、块注释跨行——全部跑在纯函数上,不需要真机和 Web 组件,CI 里几秒出结果。

免得读者踩到同一堵墙,硬限制清单:

  • 只识别双引号字符串:单引号、反引号字符串不上色(JS/Python 帖子里单引号很常见,这是已知的最明显缺口);
  • token 只有 4 类:没有函数名、属性名、类型名高亮,想要 IDE 级效果请直接用 highlight.js;
  • 家族共享关键字表:go 的 func、rust 的 fn 不在 KW_C 里,不会显蓝;
  • 未登记语言纯转义:不炸也不高亮,想要新语言就往 LANG_FAM 加一行映射;
  • 未闭合围栏会吃掉后续全文:这是 Markdown 标准行为,没有做自动闭合;
  • 仅浅色主题:四色是按浅灰代码底挑的,暗色模式未适配。

写到这里,我对「代码高亮」的理解已经和最初完全不同了。它表面是个语法问题,骨子里是个安全问题:高亮的本质是往 DOM 里注入富 HTML,而注入富 HTML 的每一条路都必须从安全模型里过。50 行 tokenizer 真正值钱的不是省了 50 KB 依赖,而是每一字节进 HTML 的文本,我都能指着源码说清它是怎么被转义、被谁控制的。如果这篇文章只能留一句话,我会留这句:轻量不是功能少,而是每一条输出路径都短到可以逐字审计。

8. 快问快答

Q:为什么不用 highlight.js?就 50 KB。
A:两个理由。一是安全模型:我的渲染器是「先转义后拼接」,所有进 HTML 的东西都过自己的 escapeHtml;highlight.js 自己生成富 HTML 注回 DOM,这条防线就被绕开了。二是体积配比:渲染层总共一千多行,为一个功能引一个比渲染器还大的库,维护心智不划算。

Q:单引号字符串什么时候补?
A:往 buildCodeRe 的字符串分支加一条 ('...') 交替即可,注意坑一的教训——所有 \b、\. 在字符串里都要双反斜杠。补完后 .tok-string 的 class 判定逻辑不变。目前没补是因为双引号覆盖了我笔记里九成以上的代码。

Q:性能怎么样?大代码块会卡吗?
A:单趟线性扫描,复杂度 O(n)。实际体验里,几百行的代码块预览切换无感;没有做精确的毫秒级基准,因为从未在任何真实笔记上感觉到它存在。真要卡了,瓶颈也会先出现在 innerHTML 的解析上而不是 tokenizer。

Q:怎么加一门新语言?
A:两步。LANG_FAM 加一行后缀映射(归到已有的 4 个家族之一,或新建家族);新建家族的话在 buildCodeRe 里加一条注释规则和一张关键字常量。改完跑一下那 14 个测试用例,再按坑五的口径补断言。

Q:\b 的坑有没有一劳永逸的躲法?
A:有,把拼接式正则改成字面量形式,或者干脆用 RegExp 时全部用模板字符串加双反斜杠。但我的正则必须按家族动态拼(注释规则和关键字表都是变量),字面量写不了,所以规矩只有一条:在字符串里造正则,每个 \ 都当成 \\ 写。

Q:和同系列其他场景什么关系?
A:同属 Electron-OH 鸿蒙实战系列,本文是第 04 篇。前几篇覆盖了窗口管理、文件系统桥接等场景,本文专门讲 Web 渲染层内的纯前端方案——不碰 ArkTS、不碰原生 API,全在 renderer.js 里解决。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐