鸿蒙PC多文档编辑器的行模型设计:Kate 跨行词法分析、折叠区间映射与文件编解码实现
Kate 是 KDE 生态中的高级文本编辑器。本项目并不是将 KDE Kate 的原生程序直接编译到鸿蒙,而是参考其多文档、语法高亮、代码折叠、搜索替换和 Vi 编辑等使用习惯,在鸿蒙 Electron 壳工程中实现一套独立的 JavaScript 文本编辑应用。本文围绕完整行模型与可见行映射、textarea 与高亮层叠加、跨行词法状态、折叠区间生成、文件编解码和会话持久化展开,结合实际源码与应用截图说明实现方式,也明确当前折叠编辑、矩形写回和文件保存链路中仍需完善的边界。
文章按七章推进:先交代壳工程的分层、开发环境与能力边界,再围绕主进程、叠层编辑界面、高亮与折叠引擎、多文档调度、文件编解码、会话持久化和深色主题展开,随后说明源码中的稳定性处理、构建部署要求与已知编辑限制,最后以功能对照表和三条可复用的经验收尾。构建、安装和真机验收部分仅提供后续核对指引,不作为本文已完成的验证成果。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_Kate
一、技术架构分析
1.1 整体架构
本项目采用“鸿蒙 HAP 壳工程 + Electron 主进程 + Web 编辑界面 + JavaScript 引擎”的分层结构:
- 鸿蒙壳层:electron 为入口模块,依赖 web_engine 共享模块,承载应用资源和平台桥接。
- Electron 主进程:管理窗口、文件对话框、目录工作范围、文件字节读写、编码转换、偏好、会话和剪贴板。
- Web 渲染层:管理多文档状态、标签切换、编辑选区、工具面板、快捷键和页面刷新。
- JavaScript 引擎层:分别处理行模型、高亮、折叠、搜索、文本工具与 Vi 命令,不将这些计算放入系统文件处理器。
关键的数据链路可以概括为:文件字节进入主进程,解码后形成文档行数组;渲染层根据折叠状态建立可见行映射,将可见文本交给 textarea,将词法结果交给高亮层;保存时再将模型文本和编码、行尾选项交回主进程。
这样的拆分便于独立核对算法,但并不意味着所有层完全脱离运行环境:引擎可以在 Node.js 中直接调用,页面仍依赖 DOM 和 Electron IPC,HAP 还依赖配套的鸿蒙运行时与原生桥接。
1.2 技术方案
| 对比项 | KDE Kate 原生应用 | 当前鸿蒙 Electron 壳应用 |
|---|---|---|
| 实现基础 | KDE/Qt 原生编辑器体系 | HTML、CSS 与独立 JavaScript 引擎 |
| 编辑表面 | 原生编辑组件 | textarea 输入层与 HTML 高亮层叠加 |
| 文档结构 | 原生编辑器内部模型 | 行数组、可见行映射、光标和历史快照 |
| 语法能力 | 上游语法定义与编辑器功能体系 | 19 种方案、16 种 token 样式、部分语言的正则大纲 |
| 折叠机制 | 上游编辑组件提供 | 括号、缩进、Markdown 标题与显式标记 |
| 扩展能力 | 上游插件与集成体系 | 当前工程内置面板、17 项文本工具与 Vi 常用子集 |
| 文件操作 | 原生平台文件接口 | 主进程 Node.js fs 与请求响应 IPC |
| 部署形态 | 对应桌面平台的软件包 | 鸿蒙 electron 入口模块与 web_engine 资源 |
这里的“19 种方案”包含纯文本,并不代表实现了 19 个完整语言解析器。项目没有建立 AST、类型系统或 LSP 服务,也没有复刻 KDE Kate 的完整插件体系。
1.3 核心功能清单
| 功能模块 | 当前实现 |
|---|---|
| 多文档编辑 | 标签、完整行模型、光标选区、书签、文本修改标记 |
| 高亮与大纲 | 跨行词法状态、16 种 token 样式、按语言规则提取符号 |
| 代码折叠 | 模型行区间、开合状态、可见行映射与隐藏行统计 |
| 搜索替换 | 普通文本与正则查找、捕获组替换、文档与目录文件搜索 |
| 文本工具 | 排序去重、空白缩进、大小写、行合并与注释,共 17 项 |
| 单词补全 | 从当前文档词表中按前缀和词频产生候选 |
| Vi 模式 | Normal、Insert、Visual 等状态及常用操作子集 |
| 文件编解码 | UTF-8、UTF-8 BOM、UTF-16 LE/BE、Latin-1,三种行尾 |
| 偏好与会话 | 配置持久化、标签文本及部分编辑状态恢复 |
| 页面交互 | 七个功能面板、自研下拉、DOM 关于弹层、状态栏反馈 |
上述清单表示源码中存在的实现入口,不等于全部功能已经完成设备验收。涉及覆盖写入的操作,尤其是截断文件、折叠状态下编辑和矩形变换,应先阅读第六章的限制说明。
二、环境准备
2.1 开发环境要求
| 项目 | 配置或要求 |
|---|---|
| 开发系统 | Windows 开发环境,终端命令以 PowerShell 为例 |
| 开发工具 | DevEco Studio 与匹配的 HarmonyOS SDK |
| 工程兼容 SDK | 根 build-profile.json5 配置为 5.0.5(17) |
| 工程运行系统 | runtimeOS 为 HarmonyOS |
| 产品与入口目标 | 产品 default,electron 模块目标 default |
| 目标设备类型 | 模块声明 2in1、tablet |
| 桌面调试 | Node.js 与可用的桌面 Electron 运行环境 |
| 业务技术栈 | HTML、CSS、Vanilla JavaScript、Node.js 内置模块 |
| 目标 ABI | 需与项目配套的鸿蒙 Electron 运行时及原生库一致 |
兼容 SDK 配置、桌面 Electron 版本和鸿蒙运行时版本属于不同层次,不能只依据 package.json 推导出一个通用版本组合。当前业务包也没有锁定 Electron 的依赖版本。
2.2 项目结构
ohos_Kate_electron-main/
└── ohos_hap/
├── AppScope/ 应用级名称、版本与包配置
├── electron/ HAP 入口模块
├── web_engine/ 共享模块与运行时资源
│ └── src/main/resources/resfile/resources/app/
│ ├── package.json Electron 业务入口声明
│ ├── main.js 窗口、文件、编码、IPC
│ ├── renderer.js 文档状态、编辑事件与面板调度
│ ├── index.html 编辑器与七个功能面板
│ ├── engines/
│ │ ├── kate-core.js 行模型、映射、历史与会话
│ │ ├── highlight-engine.js 词法高亮、方案识别与大纲
│ │ ├── fold-engine.js 折叠区间生成
│ │ ├── search-engine.js 搜索、替换与文档词表
│ │ ├── text-tools.js 文本工具与统计
│ │ └── vi-engine.js Vi 命令状态机
│ ├── styles/kate.css 主题与编辑叠层布局
│ └── samples/ 内置文本样例及清单
└── build-profile.json5 产品、SDK 与模块配置
后文提到 main.js、renderer.js、engines 和 styles 时,均以这一级 app 目录为业务根目录。当前业务代码已经位于壳工程的资源目录,不需要假设另有一个必须同步的开发目录。
2.3 依赖说明
业务 package.json 内容如下:
{
"name": "kate",
"version": "1.0.0",
"description": "Kate 高级文本编辑器 - 鸿蒙 PC Electron 壳应用(自研高亮/折叠/搜索/Vi 引擎)",
"main": "main.js",
"author": "wei",
"license": "Apache-2.0"
}
该文件没有 dependencies,也没有 scripts。这里的“无第三方业务库依赖”指编辑、高亮、折叠等逻辑没有引入 Monaco、CodeMirror 等编辑器库,并不是应用不需要 Electron 或鸿蒙运行时。
| 依赖层 | 用途 |
|---|---|
| Electron | BrowserWindow、screen、dialog、IPC、clipboard 与 shell |
| Node.js fs/path/Buffer | 文件读写、路径处理、字节编解码 |
| 六个本地引擎 | 文档、词法、折叠、搜索、工具与 Vi 计算 |
| DOM/CSS | 编辑叠层、导航、面板、下拉与关于弹层 |
| electron → web_engine | 入口模块通过本地模块依赖接入共享运行资源 |
本文代码块为当前源码中的完整函数或连续节选。节选依赖的模块别名、常量和相邻辅助函数仍由原文件提供,不能将每个片段都当作可单独运行的应用。
三、核心适配流程
3.1 主进程实现(main.js)
主进程不处理高亮或编辑选区,重点是统一系统能力入口。窗口根据主屏工作区计算初始尺寸,并设置最小宽高:
function createWindow() {
try {
var display = screen.getPrimaryDisplay();
var width = display.workAreaSize.width;
var height = display.workAreaSize.height;
// 防 XComponent 崩溃:frame: true + transparent: false + resizable: true
mainWindow = new BrowserWindow({
width: Math.floor(width * 0.92),
height: Math.floor(height * 0.86),
minWidth: 900,
minHeight: 600,
frame: true,
transparent: false,
resizable: true,
title: 'Kate 高级文本编辑器',
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
});
mainWindow.loadFile('index.html');
mainWindow.on('closed', function () { mainWindow = null; });
} catch (e) {
console.warn('[Kate] 创建窗口失败:', String(e && e.message));
}
}
代码中的 BrowserWindow、screen 和 mainWindow 来自主进程上下文。原有注释表达了配置目的,但不能据此推导“不会发生 XComponent 崩溃”的保证;try/catch 也只覆盖此处同步 JavaScript 异常。
主进程共注册 16 个请求响应通道:
| 分类 | 通道 | 职责 |
|---|---|---|
| 运行信息 | app:info | 返回运行时版本、目录、读取限额等 |
| 目录范围 | dir:choose、dir:trust | 选择目录或显式使用已知目录 |
| 文件系统 | fs:scan、fs:readText、fs:readMany、fs:writeText | 扫描、单文件读取、批量读取与写入 |
| 文件对话框 | files:choose、file:saveText | 选文件与另存为 |
| 系统交互 | shell:reveal、clip:write | 文件定位与剪贴板写入 |
| 偏好 | prefs:get、prefs:set | 读取和保存页面配置 |
| 会话 | session:save、session:load | 写入和读取会话快照 |
| 样例 | samples:list | 枚举资源目录中的样例文件 |
这里没有单独的业务推送事件流。页面发起请求后,根据返回对象中的 success、error 和数据字段更新状态栏或面板。
目录范围由 allowedRoots 管理,路径判断使用以下实现:
function isUnder(target, root) {
var t = fwd(target), r = fwd(root);
if (!t || !r) return false;
if (t === r) return true;
var sep = r.charAt(r.length - 1) === '/' ? r : r + '/';
return t.indexOf(sep) === 0;
}
function guard(p) {
var t = fwd(p);
if (!t) return false;
for (var i = 0; i < allowedRoots.length; i++) if (isUnder(t, allowedRoots[i])) return true;
return false;
}
其中 fwd 只统一斜杠。这个机制适合解释“当前工作目录范围”,不能称为安全沙箱:代码没有在此完成真实路径规范化、符号链接校验等处理,而且渲染层开启了 Node 集成。当前方案应限于受信任的本地应用页面。
3.2 编辑界面:textarea 与高亮层同格叠加
页面由顶部工具栏、左侧七面板导航、中央文档标签和编辑区、符号大纲、右侧功能坞及底部状态栏组成。编辑区没有把彩色 span 设置为可编辑,而是将输入和展示拆成两层。
index.html 中的实际结构如下:
<div id="editorStack" class="editor-stack">
<div id="hlLayer" class="highlight-layer" aria-hidden="true"><div id="hlContent"></div></div>
<textarea id="editor" class="input-layer" spellcheck="false" wrap="off"
aria-label="文本编辑区:可直接输入,Ctrl+T 折叠、Ctrl+M 书签、Ctrl+Shift+C 注释切换,Vi 模式开启后由状态机接管按键"></textarea>
<div id="completeBox" class="complete-box hidden" aria-label="单词补全候选列表"></div>
</div>
- textarea 接收文本输入、光标移动和浏览器选区。
- hlContent 展示按 token 分类后的文字。
- completeBox 展示当前文档词表产生的补全候选。
- 行号列独立存在,显示模型行号而不是简单的可见行序号。
两层占用同一个 Grid 单元,必须共享排版参数。styles/kate.css 中的共同规则为:
.highlight-layer,
.input-layer {
grid-area: 1 / 1;
font-family: var(--font-mono);
font-size: var(--editor-font-size);
line-height: var(--editor-line-height);
padding: 8px 12px;
tab-size: var(--tab-width);
-moz-tab-size: var(--tab-width);
white-space: pre;
border: none;
margin: 0;
}
输入层本身保持透明文字,但保留可见光标:
.input-layer {
overflow: auto;
background: transparent;
color: transparent;
caret-color: var(--text);
outline: none;
resize: none;
width: 100%;
height: 100%;
}
这样,高亮渲染不需要维护复杂的 contenteditable 节点选区。不过,视觉重叠正确依赖字体、字号、行高、padding、Tab 宽度和换行规则共同一致,仅统一颜色是不够的。
renderer.js 还同步编辑层与高亮层的滚动;开启动态换行后,依据高亮行的实际高度调整行号列。纯光标移动主要切换当前行样式,避免每次移动都重建全部高亮 DOM。
这套方案保留了 textarea 的输入入口,但不能由此宣称鸿蒙输入法组合输入、触摸选择和所有 Unicode 编辑边界均已验证。
3.3 语法高亮、符号大纲与折叠引擎
高亮:跨行状态与逐行 token 扫描。
highlight-engine.js 提供 C、C++、Java、JavaScript、TypeScript、Python、Bash、CMake、Makefile、SQL、JSON、YAML、INI、HTML、XML、CSS、Markdown、Diff 和纯文本共 19 种方案。
每个 token 记录类型 t、起始位置 from 和长度 len。整篇扫描共享一个状态对象,用来承接跨行注释或字符串状态:
function highlight(langId, lines) {
var st = newState(), rows = [];
for (var i = 0; i < lines.length; i++) {
var r = tokenizeLine(langId, st, lines[i]);
rows.push(r.tokens);
}
return rows;
}
这里的 newState 和 tokenizeLine 均位于同一引擎中。页面通过方案名称和文档修订号缓存扫描结果:
function tokenRows(d) {
d.hlSkip = d.lines.length > HL_MAX_LINES;
if (d.hlSkip) return null;
if (d.tokRev === d.rev && d.tokLang === d.lang) return d.tokRows;
d.tokRows = Hl.highlight(d.lang, d.lines);
d.tokRev = d.rev;
d.tokLang = d.lang;
return d.tokRows;
}
HL_MAX_LINES 为 6000。超过这一行数时,编辑显示退化为纯文本。这是高亮渲染层的降级条件,不是完整的大文件处理方案:文档创建和折叠分析仍可能执行扫描,编辑 DOM 也不是虚拟列表,超长单行并不受该行数阈值限制。
统计:归类长度不是 token 数量。
语法面板的统计直接累加 token.len:
function tokenStats(rows) {
var by = {}, total = 0;
for (var i = 0; i < rows.length; i++) {
for (var j = 0; j < rows[i].length; j++) {
var t = rows[i][j].t;
by[t] = (by[t] || 0) + rows[i][j].len;
total += rows[i][j].len;
}
}
var list = Object.keys(by).map(function (k) { return { type: k, chars: by[k] }; });
list.sort(function (a, b) { return b.chars - a.chars; });
return { byType: list, total: total };
}
因此,截图中的 584 和 411 是相应样例被归类的字符串长度,不是 584 个或 411 个 token,也不是文件字节数。JavaScript 字符串索引按 UTF-16 码元计算,部分空白不进入 token,统计值不能直接等同于完整文本长度。
折叠:复用词法结果,避免把字符串里的括号当作代码结构。
fold-engine.js 的括号深度计算如下:
function braceDepth(tokens, text) {
var net = 0, i, t;
for (i = 0; i < tokens.length; i++) {
t = tokens[i];
if (t.t === 'comment' || t.t === 'string') continue;
var seg = text.substr(t.from, t.len);
for (var k = 0; k < seg.length; k++) {
if (seg.charAt(k) === '{') net++;
else if (seg.charAt(k) === '}') net--;
}
}
return net;
}
引擎再根据深度变化构造模型行区间,并与其他类型的折叠规则组合:
| 来源 | 实现方式 | 适用边界 |
|---|---|---|
| 括号结构 | 复用 token,忽略 comment/string,累计花括号深度 | 不等于完整语法解析或编译检查 |
| 缩进结构 | 识别简单块头,向后寻找更深缩进 | 各语言只覆盖当前规则中的形式 |
| Markdown 标题 | 根据标题级别确定章节范围 | 按标题结构处理,不是完整 Markdown AST |
| 显式标记 | 识别 region 或花括号标记形式 | 当前实现不是通用嵌套标记解析器 |
折叠结果包含 start、end、kind、open 和 title。引擎负责“哪些模型行属于一个区间”,文档内核负责“哪些行现在可见”,两者职责不同。
符号大纲则使用逐行正则,按语言提取函数或类型候选。它没有覆盖每一种高亮方案的全部符号语法;例如当前 Java 类规则的捕获组取值会显示 class 而不是实际类名,这一点也能在配图中看到。大纲项数量可以核对,但不能把数量正确等同于语义完全正确。
3.4 多文档模型、编辑回写与命令调度
完整模型与可见文本分开保存。
每个文档有自己的 lines、saved、encoding、eol、lang、folds、bookmarks、caret、sel、hist 和 Vi 状态;高亮缓存另用 rev、tokRev、tokLang 等字段管理。切换标签只改变活动文档索引,再刷新编辑视图和面板。
kate-core.js 根据闭合折叠构造可见行映射:
function buildVisible(lines, folds) {
var hidden = {}, list = folds || [];
for (var i = 0; i < list.length; i++) {
var f = list[i];
if (f.open) continue;
for (var l = f.start + 1; l <= f.end; l++) hidden[l] = true;
}
var map = [];
for (var n = 0; n < lines.length; n++) if (!hidden[n]) map.push(n);
return { map: map, hidden: hidden, hiddenCount: lines.length - map.length };
}
function visibleText(lines, map) {
var out = [];
for (var i = 0; i < map.length; i++) out.push(lines[map[i]]);
return out.join('\n');
}
折叠起始行保留,后续至 end 的行隐藏。hidden 按模型行去重,因此实际隐藏行数不会因为嵌套区间而重复累计。
编辑过程中需要区分三类坐标:
| 坐标 | 含义 | 用途 |
|---|---|---|
| 模型行列 | 完整文档中的位置 | 书签、折叠、保存、大纲跳转 |
| 可见行列 | 折叠过滤后的显示位置 | 编辑层、高亮层与行号对齐 |
| textarea 偏移 | 可见文本中的字符串索引 | selectionStart、selectionEnd |
普通输入与面板操作分别接入模型。
普通输入经 syncModel 比较输入前后的可见文本,找到共同前后缀,再把差异映射回模型区间。面板操作主要通过 renderer.js 的 setModel 写回:
function setModel(lines, opt) {
var d = cur();
if (!d) return false;
opt = opt || {};
var before = d.lines.join('\n');
d.lines = lines;
if (opt.folds) d.folds = copyFolds(opt.folds);
else d.folds = normalizeFolds(d.folds, d.lines);
if (opt.caret) d.caret = opt.caret;
if (opt.sel !== undefined) d.sel = opt.sel;
clampCaret(d);
touchDoc(d);
if (opt.history !== false && d.lines.join('\n') !== before) histPush(d, snapEntry(d, opt.merge));
if (!opt.keepFolds) refreshFoldRegions();
renderEditor();
refreshPanels();
if (opt.note) status(opt.note, 'okk');
return true;
}
该函数依赖当前文档、历史和渲染辅助函数,集中处理光标约束、修订号、历史与刷新。源码中的统一入口是一个重要设计方向,但调用方若提前原地修改了文档,仍可能影响“修改前后”的比较,因此不能仅凭入口存在就保证所有操作都可完整撤销。
历史快照包含文本、光标和折叠。栈容量最多 250 条,连续输入的合并窗口为 450ms;新编辑会丢弃重做分支。250 是快照容量,不是无条件可撤销 250 次任意操作的保证。
这里还有一个必须明确的当前限制:syncModel 将可见差异转换为连续模型区间,编辑闭合折叠的起始行时,可能连同隐藏行一起替换。这个问题已用最小内存案例确认,具体见 Q3,当前不宜在闭合折叠上直接执行修改。
文本工具、补全与 Vi 的接入。
text-tools.js 注册了 17 个工具,分为排序去重、空白缩进、大小写、行与注释四组。多数工具返回新行数组和说明;添加、移除注释则需要注入当前语言的注释规则。
补全来自当前文档词表,renderer.js 实际按最小长度 2 生成词表,最多请求 12 个候选。它是词频和前缀补全,不提供类型推导或跨文件符号解析。
vi-engine.js 通过 feed 接收按键、文档上下文和状态,返回文本、光标、选区、模式或待执行动作。Insert 模式的普通输入仍交给 textarea;保存、关闭、撤销等动作由渲染层执行。
快捷键表有 44 条绑定,映射到 43 个唯一命令;其中 Ctrl+1~7 切换面板,Ctrl+PageUp/PageDown 切换文档。Vi 仅实现常用子集,控制键还受外层快捷键分发影响,不能将参考表当作完整 Vim 兼容性证明。保存后关闭等命令也需要单独验证异步完成顺序。
3.5 文件编解码、搜索替换与会话持久化
文件编码与行尾是两个独立维度。
主进程识别五种编码 ID,并支持 LF、CRLF、CR 三种行尾。自动探测首先检查 BOM,再使用零字节比例和 UTF-8 替换字符做启发式判断:
function detectEncoding(buf) {
if (buf.length >= 3 && buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF) return 'utf8bom';
if (buf.length >= 2 && buf[0] === 0xFF && buf[1] === 0xFE) return 'utf16le';
if (buf.length >= 2 && buf[0] === 0xFE && buf[1] === 0xFF) return 'utf16be';
if (buf.length >= 8) {
var nul = 0, half = Math.min(buf.length, 2048);
for (var i = 0; i < half; i++) if (buf[i] === 0) nul++;
if (nul > half * 0.2) return (buf.length % 2 === 0) ? 'utf16le' : 'latin1';
}
return buf.toString('utf8').indexOf('\uFFFD') >= 0 ? 'latin1' : 'utf8';
}
这不是通用字符集识别器,不能可靠识别 GBK 或所有无 BOM 编码。UTF-16 BE 的字节处理通过交换字节对完成,内部模型统一保存 JavaScript 字符串。
写出时再应用编码和行尾:
function encodeBuf(text, enc, eol) {
var s = String(text == null ? '' : text);
var eolKey = EOL[eol] ? eol : 'lf';
s = s.split(/\r\n|\n|\r/).join(EOL[eolKey]);
if (s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
var buf, lossy = 0;
if (enc === 'latin1') {
for (var i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0xFF) lossy++;
buf = Buffer.from(s, 'latin1');
} else if (enc === 'utf8bom') buf = Buffer.concat([Buffer.from([0xEF, 0xBB, 0xBF]), Buffer.from(s, 'utf8')]);
else if (enc === 'utf16le') buf = Buffer.concat([Buffer.from([0xFF, 0xFE]), Buffer.from(s, 'utf16le')]);
else if (enc === 'utf16be') buf = Buffer.concat([Buffer.from([0xFE, 0xFF]), swapPairs(Buffer.from(s, 'utf16le'))]);
else buf = Buffer.from(s, 'utf8');
return { buf: buf, lossy: lossy, eol: eolKey, encoding: ENC_IDS.indexOf(enc) >= 0 ? enc : 'utf8' };
}
该函数依赖 EOL、ENC_IDS 和 swapPairs。混合行尾会被统一,BOM 会按目标编码重建,因此这条链路不是原文件字节无损往返。Latin-1 的 lossy 记录超出单字节范围的码元数,写入入口必须认真处理这类信息,不能把写后警告当作保存前保护。
搜索和替换使用同一组模型坐标。
文档搜索逐行运行 JavaScript RegExp,普通文本模式先转义模式串;匹配结果保存行号、起点、长度和捕获组。替换计划先按行聚合,再对同一行从右向左操作,避免前方替换改变后方坐标。
以下为 search-engine.js 中 replacePlan 内的连续节选,依赖外层 lines、byLine 和 replacement:
var text = String(lines[ln] == null ? '' : lines[ln]);
var list = byLine[ln].slice().sort(function (a, b) { return b.from - a.from; });
var acc = text;
list.forEach(function (mm) {
acc = acc.slice(0, mm.from) + expand(replacement, mm) + acc.slice(mm.from + mm.len);
});
替换文本支持数字捕获组引用、换行和 Tab 展开,但不是完整 JavaScript replace 模板语义。搜索逐行执行,不支持跨行匹配;匹配上限也不能限制某一次正则灾难性回溯的耗时。
| 限制位置 | 当前值或行为 |
|---|---|
| 当前文档匹配 | 最多 20000 条,面板最多显示 300 条 |
| 跨文件匹配 | 最多 4000 条,结果表最多显示 600 条 |
| 目录扫描 | 最多 4000 个条目,递归深度参数限制为 0~4 |
| 单文件读取 | 默认截取 2MiB,参数上限 8MiB |
| 批量读取 | 每个文件默认截取 1MiB,文件数上限 600 |
| 批量累计量 | 以 24MiB 阈值检查累计读取字节 |
读取实现先调用 readFileSync 获得完整 Buffer,再截取允许的部分,因此这些值不是进程内存占用的硬上限。批量替换还有编码、截断和冲突处理上的限制,见 Q7。
会话快照与文档保存分离。
偏好写入 userData 下的 KatePrefs.json,会话写入 KateSession.json。内容修改后会安排一次 4 秒静默保存:
function queueSessionSave() {
if (saveTimer) clearTimeout(saveTimer);
saveTimer = setTimeout(function () { saveTimer = null; if (app.docs.length) sessionSave(false); }, 4000);
}
saveTimer、app 和 sessionSave 来自渲染层。此处保存的是会话快照,不是将每个打开文档自动写回原路径。
会话包含文本、文件路径、书签、光标、滚动位置和折叠区间等信息,主进程拒绝超过 8MiB 的会话写入。当前序列化却将编码固定为 utf8,也没有保存撤销历史和原始 saved 基线。因此,“恢复了标签和文本”不能解释成“恢复了文件的所有编辑状态”,更不能替代可靠备份。
3.6 Catppuccin Mocha 深色主题
主题沿用 Catppuccin Mocha 的底色和强调色,通过 CSS 变量覆盖工具栏、编辑器、面板卡片、表格、下拉与状态信息。以下是 styles/kate.css 中完整的根变量规则:
:root {
--base: #1e1e2e;
--mantle: #181825;
--crust: #11111b;
--surface0: #313244;
--surface1: #45475a;
--surface2: #585b70;
--overlay0: #6c7086;
--overlay1: #7f849c;
--text: #cdd6f4;
--subtext0: #a6adc8;
--subtext1: #bac2de;
--blue: #89b4fa;
--lavender: #b4befe;
--sky: #89dceb;
--teal: #94e2d5;
--green: #a6e3a1;
--yellow: #f9e2af;
--peach: #fab387;
--rosewater: #f5e0dc;
--flamingo: #f2cdcd;
--pink: #f5c2e7;
--mauve: #cba6f7;
--red: #f38ba8;
/* 语义混色(由上面调色板两两混合得到,界面只引用语义名) */
--sel-bg: #2a3b5c;
--sel-bd: #3a5c8c;
--primary-hover: #33486f;
--danger-bg: #3d2731;
--danger-bd: #5c3a48;
--danger-hover: #4d3140;
--mark-bg: #4a4a2a;
--mark-cur-bg: #5c5320;
--ok-bg: #26382c;
--ok-bd: #375040;
--warn-bg: #3b3524;
--warn-bd: #55503a;
--row-bg: #26314b;
--font-mono: "Cascadia Mono", Consolas, "Courier New", monospace;
/* 编辑器排版三要素:字号由配置面板写入,行高必须与之成比例,否则高亮层与 textarea 会错位 */
--editor-font-size: 14px;
--editor-line-height: 21px;
--tab-width: 4;
/* 面板坞是主体第三列(与编辑面并列),只占宽不抢高;收起时 renderer 把它写成 0px */
--dock-w: 400px;
--outline-w: 204px;
}
主题变量除了颜色,还承载编辑排版参数。renderer.js 运行时调整字号、行高、Tab 宽度和功能坞宽度,使输入层和高亮层共同变化;大纲宽度则在当前 CSS 中单独定义。
这种组织方式的重点是“同一语义使用同一变量”:选区、危险操作、成功提示和当前行都有独立令牌。对于叠层编辑器,视觉一致性还直接关系到光标与文字是否重合,并非仅仅是外观修饰。
四、鸿蒙稳定性适配
本章依据当前工程的实现组织,不将其他项目的故障经历套用为 Kate 的实测结论。窗口配置、DOM 控件和异常包装可以减少部分平台交互复杂度,但不能替代目标设备上的回归测试。
4.1 禁用默认菜单栏
问题现象: 当应用已经提供完整的页面工具栏时,额外的 Electron 默认菜单会形成重复入口,也可能让用户误以为菜单项与页面命令共享相同实现。
根因分析: 系统菜单和 Web 工具栏属于两套交互入口,需要明确哪些能力由当前应用接管。不能只完成页面布局而忽略主进程菜单状态。
解决方案: main.js 初始化阶段清除应用菜单,页面通过自己的工具栏和快捷键分发命令:
Menu.setApplicationMenu(null);
这说明当前工程采取了统一入口策略,不表示本次曾在设备上复现菜单重叠。清除菜单后,仍要逐项检查页面快捷键、焦点和剪贴板行为。
4.2 自定义关于弹层与下拉控件
问题现象: 编辑器需要关于信息、语言方案和编码选项等交互。如果这些入口分别采用不同的窗口或控件机制,主题、焦点与关闭行为就需要跨层协调。
根因分析: 页面中的普通信息展示并不需要新建原生窗口;原生控件和 DOM 控件也不共享同一套 CSS。当前工程选择将这些交互保留在页面内。
解决方案: 关于弹层预先定义在 index.html 中,通过 hidden 类控制显示:
function openAboutDialog() {
var l = document.getElementById('aboutDialogLayer');
if (l) l.classList.remove('hidden');
}
function closeAboutDialog() {
var l = document.getElementById('aboutDialogLayer');
if (l) l.classList.add('hidden');
}
关于页包含开源说明、免责声明与 Apache-2.0 文案,包配置也声明了 Apache-2.0;这不等于本文已经完成整套依赖的许可证合规审计。
语言、编码等选择器使用 .custom-select,由 data-value 保存选项值,再由统一点击委托更新选中样式与显示文字。使用 DOM 控件之后,应用自己承担状态同步责任,Q2 展示了一个实际的同步遗漏。
需要注意,当前关于层确实使用 position: fixed,不能仅凭 CSS 文件头的约束注释声称工程完全没有 fixed 布局。文件打开、保存对话框仍由 Electron 主进程提供,也不能将“关于弹层使用 DOM”扩大为“所有原生对话框均已移除”。
4.3 窗口配置与渲染负载控制
| 配置或机制 | 当前实现 | 准确作用与边界 |
|---|---|---|
| disableHardwareAcceleration | 启动时调用 | 禁用硬件加速,不能保证所有白屏原因都被排除 |
| frame | true | 保留系统窗口框架 |
| transparent | false | 使用非透明窗口 |
| resizable | true | 允许窗口缩放 |
| 初始尺寸 | 工作区宽 92%、高 86% | 基于主屏工作区计算 |
| 最小尺寸 | 900 × 600 | 为编辑区和功能坞保留基本空间 |
| createWindow 异常处理 | try/catch | 记录同步 JavaScript 创建异常,不覆盖所有原生故障 |
| 高亮缓存 | 文档修订号与语言方案 | 未变化时复用 token 行结果 |
| 高亮降级 | 超过 6000 行返回纯文本 | 不等于跳过全部折叠或 DOM 工作 |
| 面板刷新 | 260ms 延迟调度 | 合并输入后的部分面板更新,不是全应用渲染防抖 |
这些机制分别作用于窗口、计算缓存和界面刷新,不能用一个“稳定性配置”标签替代各自的作用范围。长行、复杂正则、同步文件读写和大量 DOM 仍需要有针对性的性能测试。
4.4 混合模块加载与 IPC 错误反馈
问题现象: 在开启 Node 集成的 Electron 页面中,DOM 全局对象与 CommonJS 的 module.exports 可能同时存在。如果只用后者判断加载环境,脚本可能进入不适合当前页面的依赖分支。
根因分析: 本工程的引擎通过 script 标签顺序加载,但也保留 CommonJS 导出供 Node 调用。折叠引擎又依赖高亮引擎,必须先判断同页依赖是否已经就绪,不能把“存在 module”直接等同于“正在独立模块测试”。
解决方案: index.html 先加载高亮,再加载折叠,最后才加载 renderer.js。六个引擎的实际顺序如下:
<script src="engines/kate-core.js"></script>
<script src="engines/highlight-engine.js"></script>
<script src="engines/fold-engine.js"></script>
<script src="engines/search-engine.js"></script>
<script src="engines/text-tools.js"></script>
<script src="engines/vi-engine.js"></script>
fold-engine.js 在包装器内优先使用 root.KateHl,只有同页依赖不存在且满足 CommonJS 条件时才调用相对 require;构造后同时提供页面全局和 CommonJS 导出。这使页面加载和独立引擎核对可以共享实现,而不是维护两套算法。
系统调用则统一经过 renderer.js 的 invoke 包装:
function invoke(ch, req) {
return ipcRenderer.invoke(ch, req).catch(function (e) {
return { success: false, error: '通道 ' + ch + ' 调用失败:' + errText(e) };
});
}
errText 负责整理异常消息,调用方据 success 更新界面。这个包装能够处理 Promise 拒绝,但没有超时机制,不能处理一直不结束的请求,也不能覆盖所有后续回调异常。
当前 Kate 文件读写走主进程 IPC,没有采用渲染层 fs 旁路。本文没有在该工程中复现“第二次 invoke 挂起”,因此不把其他应用的绕行方案写成这里已经发生或已经修复的事实。
五、构建与部署

图一为 demo.cpp:33 行、3 个折叠区、4 个大纲项,已归类字符长度为 584。截图中的 C++ 徽标与语法详情来自文档实际方案;下拉框仍显示 None,属于控件状态同步问题,而不是当前按纯文本计算。

图二为 main.java:26 行、5 个折叠区、4 个大纲项,已归类字符长度为 411。大纲中的 class 项反映了当前 Java 捕获组取值问题,不应将其描述为正确显示了类名。

图三展示 DOM 关于弹层。三张图片来自项目对应的应用截图,不使用图标素材。它们能够说明相应页面的展示状态,不能据此推导保存、编码转换、矩形操作或批量替换均已完成设备验收。
5.1 本地调试
业务入口位于以下目录:
ohos_hap/web_engine/src/main/resources/resfile/resources/app/
在已经准备好合适桌面 Electron 的环境中,可以在该目录执行:
npx --no-install electron .
该命令是读者本地调试指引,本次未执行;若本地没有可用 Electron,需要先准备运行环境。package.json 没有 npm start 脚本,不能直接假定 npm start 可用。桌面启动成功也不代表鸿蒙窗口、文件选择和输入交互已经通过验证。
无需启动 UI 的语法检查可以在业务目录执行:
$files = @(
'main.js',
'renderer.js',
'engines/kate-core.js',
'engines/highlight-engine.js',
'engines/fold-engine.js',
'engines/search-engine.js',
'engines/text-tools.js',
'engines/vi-engine.js'
)
foreach ($file in $files) {
node --check $file
if ($LASTEXITCODE -ne 0) { throw "语法检查失败:$file" }
}
本次资料核对实际完成了上述 8 个 JavaScript 文件的语法检查,并直接调用引擎重算两份截图样例:
| 样例 | 行数 | 折叠区 | 大纲项 | 已归类字符长度 |
|---|---|---|---|---|
| demo.cpp | 33 | 3 | 4 | 584 |
| main.java | 26 | 5 | 4 | 411 |
同时核对了 19 种方案、16 种样式、44 条快捷键绑定、43 个唯一命令,以及 17 项工具、4 个分组。顶栏“示例”是 14 步循环,不等于 samples 目录只包含 14 个文件。
这些结果来自实际文本与引擎计算,不是 UI 中预写的演示数字。demo.cpp 在当前样例中还缺少末尾 main 函数的闭合花括号,因此上述核对不包含 C++ 编译通过的结论。
5.2 部署到鸿蒙壳工程
当前仓库已经将 main.js、renderer.js、index.html、engines、styles 和 samples 放在 web_engine 的实际资源目录中。开发时应首先确认修改的是这一份资源,不能凭目录名称另建一份副本后假定构建会自动取用。
建议按以下顺序核对部署输入:
- 确认业务 package.json 的 main 仍指向 main.js。
- 确认 index.html 中六个引擎的顺序与 renderer.js 的依赖一致。
- 保留 styles 与 samples 的相对路径,避免界面存在但样例读取失败。
- 确认 electron 模块仍依赖 file:…/web_engine。
- 如确有外部开发副本,仅同步本次业务资源,并核对源文件与部署文件哈希;不要清空整个运行时目录。
renderer.js 的 BUILD_BANNER 当前为 renderer 示例直达 v3,启动状态栏和诊断面板会显示该信息,可作为判断资源版本的辅助线索。版本标记不能代替文件内容或哈希比对。
5.3 构建 HAP 包
在 DevEco Studio 中打开 ohos_hap,使用工程声明的 default 产品和 electron 的 default 目标,准备匹配的 SDK、模块依赖与有效签名,再执行 IDE 提供的 HAP 构建操作。
当前配置中需要区分的几项信息如下:
| 配置位置 | 当前内容 | 构建与发布时的关注点 |
|---|---|---|
| 根 build-profile.json5 | compatibleSdkVersion 为 5.0.5(17),runtimeOS 为 HarmonyOS | SDK 与实际工具链保持匹配 |
| electron/src/main/module.json5 | entry 模块,设备类型为 2in1、tablet | 核对入口和目标设备 |
| web_engine/src/main/module.json5 | har 模块 | 核对桥接资源与实际权限用途 |
| AppScope/app.json5 | bundleName 为 com.huawei.ohos_electron | 当前仍是模板式标识,发布前需统一确认 |
| AppScope 字符串资源 | app_name 为 Electron | Web 页面标题不等于桌面应用名称 |
web_engine 中仍包含网络、文件、剪贴板、位置、摄像头、麦克风等模板权限声明。不能因为模板中存在就认定 Kate 文本编辑业务需要全部权限;发布前应逐项核对运行时与业务用途,不照搬其他应用的权限数量或删减列表。
本次仅新增技术文章和配图,没有修改业务代码、签名、包名、权限或原生库,也没有执行 HAP 构建、安装、真机测试或上架。后续设备验收应优先覆盖输入法、窗口缩放、连续打开保存、异常路径、编码往返与本章列出的编辑边界。
六、常见问题与解决方案
以下区分“当前已有机制”和“建议后续修正”。涉及尚未修复的问题,不将规避办法表述为已经落地的代码修复。
Q1:页面已经显示 Kate,为什么应用级资源仍叫 Electron?
问题现象: 主进程窗口标题和 Web 页面展示 Kate,但 AppScope 中的 app_name 仍为 Electron,应用包名也保留 com.huawei.ohos_electron。这是当前配置可以直接确认的差异,不是本次设备安装后的复现记录。
根因分析: 页面标题、BrowserWindow 标题、应用级 label 和入口 Ability 的 label 分属不同配置层。修改一个层次不会自动改动其他层次。
解决: 发布前统一核对 AppScope 的应用名、入口 Ability 的资源引用、各语言目录同名资源以及应用标识。本次只记录差异,未修改名称、包名或签名配置。
教训: “页面品牌正确”和“安装包身份正确”需要分别验收,不能以页面截图代替应用资源检查。
Q2:语法详情是 C++ 或 Java,为什么语言下拉仍显示 None?
问题现象: 两张样例截图中,语法详情和徽标已经显示实际语言,下拉控件却停留在 None。
根因分析: newDoc 根据文件名和文本设置 d.lang,高亮和语法详情读取该字段;下拉显示则由 data-value 和 selSet 独立维护。当前普通打开与标签切换路径没有统一回填语言下拉,因此两套状态可能不同步。
解决: 当前判断实际方案应以文档语言字段及对应计算结果为准。后续应在活动文档刷新流程中统一同步语言控件,而不只在手动切换语言或重新解码时更新;同步过程也应避免再次触发不必要的文档修改。
教训: 自研下拉解决了控件外观控制问题,同时把状态同步责任交回应用,不能只更新模型而忽略控件投影。
Q3:编辑闭合折叠的起始行,会不会影响隐藏内容?
问题现象: 本次直接调用文档内核,用三行 head、hidden、tail 构造闭合折叠区间 0~1。可见文本为 head 和 tail;将 head 改成 HEAD 后,syncModel 返回的模型只剩 HEAD、tail,隐藏行未保留。
根因分析: syncModel 以可见行共同前后缀定位差异,再将差异换算为连续模型区间。该案例中,下一条可见行对应模型第 2 行,替换范围就包含了隐藏的第 1 行。renderer.js 的普通输入路径没有先展开这一闭合区域。
解决: 当前应先展开折叠再编辑,避免在闭合区域起始行或跨隐藏区间直接修改。后续需要采用能够保留隐藏片段的编辑映射,或在输入前展开受影响区域,并增加折叠头编辑、跨区删除、粘贴和撤销的回归用例;本次未实施修复。
教训: “隐藏行仍在模型中”只说明显示时没有删除,不能保证后续编辑映射不会把它们纳入替换范围。
Q4:矩形区域转换后,为什么右侧文字可能消失?
问题现象: 本次调用 rectReplace,将 abcdef 的第 1~3 列区间转换为大写,结果为 aBC,而不是保留右侧后缀的 aBCdef。
根因分析: 当前行拼接使用以下表达式:
next[ln] = s.slice(0, r.c1) + pad + cell + s.slice(Math.max(r.c2, s.length));
Math.max 使后缀起点至少等于整行长度,因而原矩形右侧内容被丢弃。渲染层的矩形插入、编号、大小写等写回动作均调用这一内核函数。
解决: 当前不要在重要原文档上使用矩形写回,应先保留独立副本。后续应修正后缀截取位置,并覆盖短行补齐、零宽矩形、多行区间和撤销;本次没有修改这段业务代码。
教训: 矩形编辑必须明确左右边界和后缀保留规则。这里的列还是字符串索引,不是 Tab 展开后的视觉列,也不是 Unicode 字素簇位置。
Q5:文件已截断载入,或者只改编码和行尾,保存链路有哪些限制?
问题现象: 打开超过限额的文件时,页面提示只载入部分内容,但文档没有自动变为只读;另外,仅修改编码或行尾设置后,“全部保存”未必会选中该文档。
根因分析: openFile 只把 truncated 转成 doc.note,保存入口没有据此拒绝覆盖。docModified 比较的是文本行数组,不包含编码、行尾变化;saveAllDocuments 又按该文本修改状态筛选。读取还采用先全量 readFileSync 后截取的方式,并统一调用 UTF-8 截断边界函数,不能认为所有编码都得到同样的边界保护。
解决: 当前不要把截断内容保存覆盖回原文件;重要文件应使用独立副本核对完整性。仅转换编码或行尾时,应显式保存当前文档并核对输出字节,不依赖“全部保存”自动发现设置变化。后续应把截断状态保留为只读约束,将编码与行尾纳入修改状态,并完善按编码截断、保存前可编码性检查、备份和原子写入。
教训: 提示文字不等于写入保护,内存文本正确也不代表磁盘编码正确。当前直接 writeFileSync 的写入方式还没有原子替换或磁盘冲突检查。
Q6:恢复会话后,为什么不能认定原文件已经保存且编码不变?
问题现象: 会话可以恢复标签文本、光标和折叠,但本次内存调用 serializeSession 时,即使输入文档 encoding 为 utf16le,输出仍为 utf8。
根因分析: 序列化函数将 encoding 写死为 utf8,渲染层没有再补回原编码;lang 和撤销历史也未完整保存。恢复时 newDoc 又把恢复文本作为 saved 基线,并没有读取磁盘做内容比较。因此界面上的未修改状态只反映内存基线,不能证明当前磁盘文件一致。
解决: 会话恢复后先确认内容、编码和原路径,不将自动会话保存当成原文档保存。后续应保留真实编码、语言、修改基线及必要版本信息,恢复时检查磁盘冲突;文件路径的恢复也不能替代目录授权流程。
教训: 会话、偏好、撤销历史和原文档是不同的数据对象。保存了其中一个,不代表其他对象也已经持久化。
Q7:跨文件替换有预览和写入开关,是否就能安全覆盖原文件?
问题现象: 文件搜索面板可以生成替换计划,并要求启用写入选项后执行,但当前流程不能保证保留所有原编码、拒绝截断输入或回滚部分成功的写入。
根因分析: search-engine.js 的 replaceInFiles 输出 file、name、before、after 和 count,没有携带原文件 encoding 等元数据;renderer.js 的 fsPlan 因而回退到全局编码设置。计划来源还是上次读取的文本,没有在写前重新核对磁盘版本,也没有拒绝截断内容或自动创建备份。逐文件写入不是事务,成功后还会同步已打开文档并重置其历史。
解决: 当前仅在已备份、确认读取完整且编码明确的副本目录中使用,修改范围或掩码后先重新搜索,不在仍有未保存编辑的工作文档上直接批量覆盖。后续需要贯穿读取、计划、写入保留编码和截断标志,加入内容版本检查、未保存文档冲突处理、备份及失败恢复;本次未执行批量磁盘写入测试,也未修复该链路。
教训: 替换计划正确只解决文本计算问题。落盘还需要文件身份、编码、完整性、并发修改与恢复机制,不能将 Ctrl+Z 当作批量文件写入的通用回滚。
七、总结
当前 Kate 鸿蒙 Electron 壳应用展示了如何将多文档文本编辑拆成独立的行模型、词法扫描、折叠映射、搜索替换和系统文件接口。它的技术重点不是复刻原生 KDE 编辑器的全部能力,而是在可检查的 JavaScript 模块中建立编辑流程,并清楚区分已实现功能与尚未解决的边界。
| 特性 | 实现方案 | 当前边界 |
|---|---|---|
| 多文档模型 | 行数组、保存基线、光标选区、标签状态 | 修改标记未覆盖全部元数据 |
| 叠层编辑 | textarea 输入与 HTML 高亮同格叠加 | 排版、滚动与输入法仍需设备回归 |
| 语法高亮 | 19 种方案、16 种样式、跨行词法状态 | 不是 AST 或语言服务 |
| 大纲与折叠 | 正则符号提取、四类折叠机制 | 部分符号规则和闭合折叠编辑有已知问题 |
| 搜索与工具 | 逐行正则、反向替换、17 项文本工具 | 非跨行搜索,矩形写回需修正 |
| Vi 子集 | 状态机返回编辑结果或动作 | 不等同完整 Vim,需核对外层按键分发 |
| 编码读写 | 五种编码、三种行尾、主进程 IPC | 探测启发式、截断保护和安全写入待完善 |
| 会话恢复 | 文本与部分视图状态序列化 | 原编码、保存基线和撤销历史不完整 |
| 鸿蒙壳接入 | electron 入口与 web_engine 资源 | 本次未执行 HAP 构建或真机验收 |
这套实现最值得保留的三个经验是:
- 先明确坐标体系,再设计编辑操作。 模型行、可见行和 textarea 偏移不能混用;折叠不仅是显示问题,还会影响回写范围和内容完整性。
- 让词法结果被复用,让计算指标可以核对。 高亮 token 同时服务折叠与统计,样例数字可以从原始文本重算;同时必须说明统计单位和算法能力边界。
- 将文本计算与安全落盘分开验收。 编码、截断、未保存编辑、会话基线和磁盘版本都可能影响保存结果,预览正确或截图正常不能替代这些检查。
本文依据当前源码、工程配置和三张应用截图撰写,完成了 JavaScript 语法、样例统计与三个内核边界案例的核对。现有问题以实际结果和静态调用链为依据记录,未将建议修正写成已经完成的适配成果。
更多推荐




所有评论(0)