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 或鸿蒙运行时。

依赖层用途
ElectronBrowserWindow、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启动时调用禁用硬件加速,不能保证所有白屏原因都被排除
frametrue保留系统窗口框架
transparentfalse使用非透明窗口
resizabletrue允许窗口缩放
初始尺寸工作区宽 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.cpp3334584
main.java2654411

同时核对了 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 的实际资源目录中。开发时应首先确认修改的是这一份资源,不能凭目录名称另建一份副本后假定构建会自动取用。

建议按以下顺序核对部署输入:

  1. 确认业务 package.json 的 main 仍指向 main.js。
  2. 确认 index.html 中六个引擎的顺序与 renderer.js 的依赖一致。
  3. 保留 styles 与 samples 的相对路径,避免界面存在但样例读取失败。
  4. 确认 electron 模块仍依赖 file:…/web_engine。
  5. 如确有外部开发副本,仅同步本次业务资源,并核对源文件与部署文件哈希;不要清空整个运行时目录。

renderer.js 的 BUILD_BANNER 当前为 renderer 示例直达 v3,启动状态栏和诊断面板会显示该信息,可作为判断资源版本的辅助线索。版本标记不能代替文件内容或哈希比对。

5.3 构建 HAP 包

在 DevEco Studio 中打开 ohos_hap,使用工程声明的 default 产品和 electron 的 default 目标,准备匹配的 SDK、模块依赖与有效签名,再执行 IDE 提供的 HAP 构建操作。

当前配置中需要区分的几项信息如下:

配置位置当前内容构建与发布时的关注点
根 build-profile.json5compatibleSdkVersion 为 5.0.5(17),runtimeOS 为 HarmonyOSSDK 与实际工具链保持匹配
electron/src/main/module.json5entry 模块,设备类型为 2in1、tablet核对入口和目标设备
web_engine/src/main/module.json5har 模块核对桥接资源与实际权限用途
AppScope/app.json5bundleName 为 com.huawei.ohos_electron当前仍是模板式标识,发布前需统一确认
AppScope 字符串资源app_name 为 ElectronWeb 页面标题不等于桌面应用名称

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 构建或真机验收

这套实现最值得保留的三个经验是:

  1. 先明确坐标体系,再设计编辑操作。 模型行、可见行和 textarea 偏移不能混用;折叠不仅是显示问题,还会影响回写范围和内容完整性。
  2. 让词法结果被复用,让计算指标可以核对。 高亮 token 同时服务折叠与统计,样例数字可以从原始文本重算;同时必须说明统计单位和算法能力边界。
  3. 将文本计算与安全落盘分开验收。 编码、截断、未保存编辑、会话基线和磁盘版本都可能影响保存结果,预览正确或截图正常不能替代这些检查。

本文依据当前源码、工程配置和三张应用截图撰写,完成了 JavaScript 语法、样例统计与三个内核边界案例的核对。现有问题以实际结果和静态调用链为依据记录,未将建议修正写成已经完成的适配成果。

Logo

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

更多推荐