欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

配套工程源码(墨记 MoJi):https://atomgit.com/gcw_TvBBemqt/moji-electron-ohos

验证环境:HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26,aarch64(2in1),HongMeng Kernel 1.13.0。运行时 Electron 40.0.1-release / Chromium 144.0.7559.76 / Node 24.11.1。应用版本 v1.1.0,签名 HAP 219,923,910 B(209.74 MiB,v1.1.0 首次构建;现行构建 220,378,184 B),数据目录 /data/storage/el2/base/files/moji。

第 3 篇讲窗口,这一篇讲窗口里的内容写到哪。鸿蒙 PC 上的鸿蒙应用有两个容易混淆的目录:一个是 HAP 安装后的 el1/bundle,只读;一个是运行时的 el2/base/files,可写。墨记把 Markdown 正文、索引、设置、窗口状态、事件日志全部放在后者,资源页面留在前者。导入导出则要跨出沙箱,和系统文件选择器打交道。诊断页里那条 EPERM 就是这条边界上的一次真实失败。

这一篇的路径都取自鸿蒙 PC 的 el2/base/files,导入、导出和拖拽也在同一台机器上实测;开发、构建、装机、调试都没有离开这台机器,在鸿蒙 PC 上开发鸿蒙应用这条文件链路是通的。


1. 结论表

项目实测路径或结果说明
应用资源/data/storage/el1/bundle/electron/resources/resfile/resources/app随 HAP 安装,只读
userData/data/storage/el2/base/filesElectron 的 app.getPath('userData')
墨记数据根/data/storage/el2/base/files/mojiuserData/moji
笔记目录/data/storage/el2/base/files/moji/notes每篇一个 <id>.md
回收站/data/storage/el2/base/files/moji/trash删除后移动到这里
导出目录/data/storage/el2/base/files/moji/exports保存对话框失败时的回退位置
临时目录/data/storage/el2/base/files/moji/tmpPDF 导出用的中间 HTML
索引/data/storage/el2/base/files/moji/index.json元数据数组
设置/data/storage/el2/base/files/moji/settings.json主题、字号、视图、最后笔记
窗口状态/data/storage/el2/base/files/moji/window-state.json位置、尺寸、最大化
事件日志/data/storage/el2/base/files/moji/events.log最多 256 KB,超出保留最后 200 行
当前笔记数5 篇诊断页「笔记数」
收藏1 篇诊断页「收藏」
回收站0 篇诊断页「回收站」
导入入口系统文件选择器,多选openFile + multiSelections
拖拽入口窗口级 drop,只收文本走 File.text(),不碰路径
导出 Markdown保存对话框,失败回退 exports直接写目标文件
导出 HTML保存对话框,失败回退 exports主进程拼完整 HTML
导出 PDF不弹保存框,直接写 exportsprintToPDF,实测 530 KB / 2 页 / 776 ms
PDF 峰值 RSS386,146,304 B(368.3 MiB)导出当前笔记时采样
已知失败EPERM 写临时文件选择器只授权目标文件

这张表里最需要解释的是最后一行。EPERM 不是「没有存储权限」,也不是「磁盘满了」,而是「这个进程没有被允许打开这个具体路径」。同一个目录下的目标文件可以写,旁边的临时文件不能写,因为系统文件选择器授权的是用户选中的那个文件,不是整个目录。


2. 两个存储区

2.1 资源区:只读,不写数据

ohos-env.js 的 resourceRoot() 先按 __dirname 往上两级找 src/renderer,找不到再退回 process.resourcesPath。这次诊断页显示的应用资源是 /data/storage/el1/bundle/electron/resources/resfile/resources/app。这个目录是 HAP 的一部分。应用代码、index.html、style.css、markdown.js、app.js、preload、main 都在这里。它可以读,不能作为数据目录。第 1 篇的踩坑表里有一条「数据写完重启就没了」,原因就是写到了 resfile 下;这一版所有写操作都走 Store,Store 的根目录是 env.dataDir(),不是资源目录。

资源目录里有多少东西?app/ 下 19 个文件,合计 298,991 B(另有 src/main/test-assets/ 2 个测试素材 435,050 B,打在包里但运行时不读):

文件字节数作用
package.json771入口、版本、构建配置
src/main/index.js70,302主进程、窗口、IPC、导出
src/main/ohos-env.js2,774平台判断、路径、窗口参数
src/main/store.js14,140索引、正文、设置、原子写
src/main/seed.js5,7595 篇示例笔记
src/main/docx.js6,029docx 最小 ZIP/XML 解析
src/main/limits.js2,3092 MB / 10 MB / 100 KB / 5 MB 限额与限流
src/main/native-kit.js1,637ArkTS 桥调用
src/main/search-index.js3,309倒排索引构建与查询
src/main/search-service.js4,054worker 生命周期与超时
src/main/search-worker.js2,578worker 线程入口
src/preload/bridge.js7,287白名单桥、限额与限流
src/preload/index.js43普通 preload 入口
src/preload/frameless.js42自绘标题栏实验入口
src/renderer/index.html17,239三栏结构、弹层、菜单
src/renderer/app.js111,692交互、保存、诊断、拖拽
src/renderer/markdown.js9,246纯函数 Markdown 渲染
src/renderer/ocr-ui.js3,359OCR 面板与取字按钮
src/renderer/style.css36,421浅色/深色、布局

这 19 个文件是只读资源,升级 HAP 时整体替换。用户数据不在这里,所以覆盖安装不会丢笔记。反过来说,不要指望在资源目录里改一个 JSON 来保存设置,重启或升级就没了。

2.2 数据区:userData/moji

dataDir() 只有一行:

return path.join(app.getPath('userData'), 'moji');

这次 userData 是 /data/storage/el2/base/files,所以数据根是 /data/storage/el2/base/files/moji。Store.init() 会一次性建七个目录:

moji/
├── index.json
├── settings.json
├── window-state.json
├── events.log
├── notes/        5 个 .md
├── trash/        空
├── exports/      导出回退
├── tmp/          PDF 临时 HTML
├── attachments/  粘贴的图片(moji-attachment:// 从这里读)
└── watch/        fs.watch 监听目录,新 .md 自动导入

init() 里的循环是 [this.base, this.notesDir, this.trashDir, this.tmpDir, this.exportDir, this.attachmentsDir, this.watchDir],mkdirSync(..., { recursive: true }) 对已存在目录不报错。index.json 不存在时才写 5 篇示例;存在但解析失败时 readJson() 返回 null,seeded 变成 true,会重新 seed。这个行为要小心:索引文件损坏会被当成首次启动,示例笔记会重新写入。正文文件不会删,但索引会被覆盖成 5 条新记录。这一版没有做索引备份或修复,属于已知边界。

数据目录可写这一项由 Store.probe() 实际验证:写 .write-probe、读回、删除,三步都成功才返回 writable: true。诊断页「数据目录:可写」就是这次探针的结果,不是把路径存在当成可写。

2.3 三个相似路径不要混

诊断页会同时显示「应用资源」「userData」「墨记数据」三行:

标签实际路径用途
应用资源/data/storage/el1/bundle/electron/resources/resfile/resources/app页面、脚本、样式
userData/data/storage/el2/base/filesElectron 约定的用户数据根
墨记数据/data/storage/el2/base/files/moji笔记、索引、设置、导出

「userData」是 Electron 的通用概念,「墨记数据」是应用自己加的一层。两者不是重复:鸿蒙 PC 上的别的 Electron 应用也可能用同一个 userData 根,墨记把自己所有的文件收在 moji/ 子目录里,卸载或清数据时不会和别的应用混在一起。报告问题时要给「墨记数据」这一行,不要只给 userData,否则还要再拼一次 /moji。

设置面板里显示的路径也是「墨记数据」,不是 userData。截图里的数据段有一行路径和两个按钮:

在这里插入图片描述

这张图证明设置页读的是 state.paths.dataDir 或 state.dataPaths.base,不是硬编码字符串。点「复制数据路径」复制的是同一行;点「打开数据目录」调用 shell.openPath(store.base),由系统决定用哪个文件管理器打开。

2.4 清理数据的后果

清空应用数据会把 el2/base/files/moji 整个删掉。下次启动时 Store.init() 发现 index.json 不存在,会重新写 5 篇示例。这个行为在开发时很方便,在排查时容易误判:用户说「笔记没了」,可能不是保存失败,而是清数据后重新 seed 了。

诊断页的「笔记数 5 / 收藏 1 / 回收站 0」是当前交付状态。如果清过数据,收藏会回到 0,因为 seed 的 5 篇里 favorite 全是 false;当前这 1 篇收藏是后来手动点的。这个差异可以用来判断数据目录有没有被重置。反过来,如果用户只删了 notes/ 下的文件而保留索引,启动后列表还在、正文为空,这才是真正的「笔记文件缺失」,诊断页会在事件里记 warn。


3. 一次写入的原子性

3.1 临时文件 + rename

Store.atomicWrite() 的做法是:在目标目录下生成一个点开头的临时文件,写入,renameSync() 覆盖目标,失败时删临时文件再抛错。

atomicWrite(file, data) {
  const dir = path.dirname(file);
  fs.mkdirSync(dir, { recursive: true });
  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
  try {
    fs.writeFileSync(tmp, data, 'utf8');
    fs.renameSync(tmp, file);
  } catch (err) {
    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch (cleanupErr) {}
    throw err;
  }
}

临时文件名包含四个部分:目标文件名、进程 PID、毫秒时间戳、自增序号。目的是避免并发写同一个文件时互相覆盖临时文件。renameSync 在同一个文件系统内是原子的,读者要么看到旧文件,要么看到新文件,不会看到半个 JSON。

这套逻辑对 index.json、settings.json、window-state.json、笔记正文都适用。notes/<id>.md 的原子写是「临时文件 + rename」;trash 的移动是 renameSync,失败时退化为 copyFileSync + unlinkSync。跨目录 rename 在同一个 el2/base/files 下应该成立,但代码仍然留了 copy 的退路。

3.2 EPERM 的临时文件就是从这来的

诊断页「最近事件」里有一条原文:

14:56:49 导出失败:EPERM: operation not permitted, open ‘/storage/Users/currentUser/Documents/周会纪要 · 11 月 14 日.md.39793.1794668209950.15.tmp’

把文件名拆开看:

片段值含义
目录/storage/Users/currentUser/Documents用户在保存对话框里选的目录
目标名周会纪要 · 11 月 14 日.mdsanitizeFileName() 处理后的标题
PID39793当时的应用主进程
时间戳1794668209950毫秒时间
序号15本次进程内第 15 个临时文件
后缀.tmp原子写的临时文件

这条错误说明当时导出走的是「在目标目录写临时文件,再 rename」的路径。系统文件选择器授权的是 周会纪要 · 11 月 14 日.md 这个目标文件,不是 Documents 整个目录;临时文件是兄弟文件,不在授权范围内,所以 open 被拒绝。

这不是鸿蒙 PC 特有的「沙箱目录不可写」,而是「选择器 URI 的授权粒度是文件级」。桌面端 Electron 的 showSaveDialog 返回路径后,通常可以在这个目录里创建临时文件;鸿蒙这套实现把授权收得更紧,才会出现「目标能写、临时不能写」的组合。

3.3 修法:直接写目标,失败回退

v1.0 的 export:note 对 Markdown 和 HTML 改成直接写目标文件,不再在目标目录做原子写。v1.1 把写入换成 writeFileChunked(),仍然直接写目标、不做临时文件,但改成 1 MB 一块流式写,并往渲染层发 export:progress:

const writeTo = async (target) => {
  if (extension === 'md') {
    return writeFileChunked(target, String(payload.content || ''), {
      onProgress: (p) => sendProgress(event.sender, 'export:progress', { format: extension, name: path.basename(target), ...p }),
    });
  }
  if (extension === 'html') {
    return writeFileChunked(target, buildHtmlDocument(title, String(payload.html || '')), {
      onProgress: (p) => sendProgress(event.sender, 'export:progress', { format: extension, name: path.basename(target), ...p }),
    });
  }
  const data = await win.webContents.printToPDF({ printBackground: true, pageSize: 'A4', preferCSSPageSize: true });
  fs.writeFileSync(target, data);
};

代价是导出文件没有原子性:写到一半失败,目标位置可能留下半个文件。收益是能写进选择器授权的位置。对于「用户主动导出一次」这个场景,可用性优先于原子性;笔记正文仍然走原子写,因为那是持续写入。分块写还顺手解决了大正文一次性 writeFileSync 的内存峰值问题,导出过程能看到百分比进度。

如果保存对话框本身不可用,askSavePath() 返回 store.exportDir/defaultName 并标记 fallback: true;如果目标写入失败,export:note 再回退到 exports 重写一次。两条回退路径最终都落在 /data/storage/el2/base/files/moji/exports。

阶段目标失败后的动作结果
保存对话框用户选的路径对话框异常 → exportsfallback: true
写 Markdown用户选的 .md写失败 → exports/<名字>.md返回新路径
写 HTML用户选的 .html写失败 → exports/<名字>.html返回新路径
写 PDFexports/<名字>.pdf直接报错不弹保存框
复制正文剪贴板返回 {ok:false,error}不落盘

3.4 事件日志是这条链路唯一的黑匣子

导出失败不会让应用崩溃,也不会弹系统错误框,只会往 events.log 追加一条。日志格式是每行一个 JSON:

{"t":"2026-11-14T14:56:49.000Z","level":"error","message":"导出失败:EPERM: operation not permitted, open ..."}

logEvent() 把消息截到 400 字符,级别只认 info/warn/error,其它一律当 info。文件超过 256 KB 时读全文、取最后 200 行、原子写回,避免日志无限增长。诊断页「最近事件」取最后 8 条显示,完整文件在数据目录里。

这条日志记的是「导出失败」,不是「笔记保存失败」。两者的区别很重要:保存失败会让状态栏变红并弹 toast,导出失败只弹 toast,正文仍在。排查时先看状态栏,再看事件日志,不要把所有红色提示都当成数据丢失。

在这里插入图片描述

这张图是 v1.0.0 历史采样:把路径、启动四段、窗口、内存和最近事件放在同一屏,事件区第一条就是 14:56:49 的 EPERM。它只用于证明当次失败被 logEvent 记录下来了、以及当时的路径布局;图左上角「应用版本 1.0.0」不能当作 1.1.0 的证据,事件区里的 EPERM 也不能当作当前版本的实时日志。

在这里插入图片描述

这张是修复后的 v1.1.0 真机诊断页:应用版本 1.1.0、平台区「数据目录:可写」、路径区的应用资源 / userData / 墨记数据三行、底部最近事件都在。它证明当前版本仍把这些信息放在同一屏;本轮事件不是 14:56 的 EPERM,所以 EPERM 原文仍以 v1.0 图和 events.log 为准。

事件日志的边界是:它只记应用主动调用 logEvent 的地方,不记每次 IPC、不记每个文件读写、不记用户点击。想靠它还原完整操作序列不够,想定位「哪一步失败了」够用。日志里的时间戳是 UTC,界面显示的是本地时间,对照时差 8 小时。诊断页只截取时分秒,不显示日期,跨天排查要回看原始文件,不能只看诊断页,这一点很关键。


4. 导入:选择器给的是路径

4.1 对话框参数

import:md 用 dialog.showOpenDialog(),properties 是 ['openFile', 'multiSelections'],过滤器是 Markdown(md、markdown、txt)和所有文件。取消时返回 {ok:false, canceled:true};选中文件后逐个交给 importMarkdownFile():先 statSync 拿文件大小,交给 limits.checkImportSize() 判断 10 MB 上限,再 readFileChunked() 按 1 MB 一块读完,最后 store.createNote({ content, tags: [] })。

const result = win ? await dialog.showOpenDialog(win, options) : await dialog.showOpenDialog(options);
if (result.canceled || !result.filePaths || !result.filePaths.length) return { ok: false, canceled: true };
for (const filePath of result.filePaths) {
  const imported = await importMarkdownFile(filePath, event.sender, 'import:md');
  if (imported.ok) created.push({ ...imported.meta, content: imported.content, stats: imported.stats });
}
// importMarkdownFile 内部:
const stat = fs.statSync(filePath);
const sizeCheck = limits.checkImportSize(stat.size);   // 10 MB
const read = await readFileChunked(filePath, { limit: limits.LIMITS.importFile, kind: 'import', onProgress });
const note = store.createNote({ content: read.content, tags: [] });

这里有两个边界。

第一,没有处理 URI。代码假设 result.filePaths 是可以直接给 fs.statSync / createReadStream 的本地路径。这次诊断页的 EPERM 显示,保存对话框返回的是 /storage/Users/currentUser/Documents/... 这样的真实路径,不是 content:// 或 file://。所以本机这条路径成立。但如果某个运行时版本把选择器结果换成 URI,第一步 statSync 就会失败。这一版没有 fileURLToPath 或 URI 解析,属于未覆盖的分支。

第二,文件大小上限在主进程,不在 preload。v1.1 的单文件导入上限是 10,485,760 B(10 MB),判断发生在主进程 importMarkdownFile() 的第一行——statSync 拿到字节数,checkImportSize() 比较,超了直接返回 { ok:false, error:'LIMIT', kind:'import', actual, limit },同时往事件日志和 import:progress 里各写一条。preload 的 importMarkdown() 只管发 invoke('import:md'),不做大小检查,所以「在 preload 拦截 10 MB」这个说法不成立。另有一条 2,097,152 B(2 MB)的正文限制在 preload 的 saveNote / createNote 里,作用于编辑器保存和拖拽导入,不拦选择器导入:5 MB / 10 MB 文件能导进来,一旦在编辑器里保存就会触发 2 MB 限制。

导入是分块读的,不是整体读入。readFileChunked() 每块 1 MB,读完返回 { total, read, chunks, ms, peakRss },这组数字写进 import:progress 的最后一条事件,也在 v11-metrics.json 的 lastImport 里。实测一次 155 B 的 .md 走同一个函数:13 ms / 1 块。10 MB 档的导入没有单独测过,只有分块读写基准里的 48 ms(10 MB 读),两者不能混为一谈。

4.2 导入后的数据形态

导入不是「引用原文件」,是「复制一份到 notes/<id>.md」。原文件之后怎么改,笔记里都不会变;笔记里怎么改,原文件也不会变。标题取正文第一条非空行的 # ,没有就用「未命名笔记」;标签为空;收藏为 false;创建时间是导入时刻。文件名用新生成的 n_YYYYMMDD_xxxxxx.md,不用原标题,避免重名和非法字符。

导入多篇时,created 数组按选择顺序排列,每篇都 unshift 到索引头部,所以列表顺序是最后导入的在最上面。渲染层导入完成后执行 selectNote(result.created[0].id),选的是选择顺序的第一篇,不是列表最上面那篇。小文件无所谓,大量导入时这个选择行为会让人以为「选中的不是刚导入的」,这是一个可以改进的点。

场景行为结果
选 1 篇 .md读文本 → 新建笔记列表 +1,选中该篇
选 3 篇逐篇读、逐篇建列表 +3,选中第一选择
选 .txt过滤器允许按纯文本导入
选 .pdf过滤器不允许,但「所有文件」可选读成乱码或失败
取消返回 canceled无变化,不弹错误
文件读失败记录事件,跳过其它文件继续
文件超过 10 MB主进程 checkImportSize 返回 LIMIT拒绝导入,写事件日志与 import:progress

4.3 数据落在哪

导入后的正文在 notes/,元数据在 index.json。左侧列表的 5 篇示例就是 seed 写入的同一套结构,所以导入笔记和示例笔记在界面上没有区别。截图里的三栏主界面显示 5 篇、收藏 0、回收站 0:

在这里插入图片描述

这张图证明的是数据层只有一种笔记形态,不区分「示例」和「导入」。列表里的摘要、更新时间、标签都来自 index.json 和 notes/*.md,没有单独的导入表。导入完成后标题、字数、更新时间会立即参与排序,和手动新建的笔记走同一套 saveIndex()。


5. 拖拽:不碰路径的导入

5.1 事件链

拖拽导入完全在渲染层完成。dragenter 时检查 dataTransfer.types 是否包含 Files,有就显示遮罩;dragover 阻止默认行为;drop 时取 dataTransfer.files,过滤扩展名,逐个 await file.text(),再 api.createNote({ content, tags: [] })。

async function importFiles(fileList) {
  const files = Array.from(fileList).filter((file) => /\.(md|markdown|txt)$/i.test(file.name));
  if (!files.length) { showToast('只支持 .md / .markdown / .txt'); return; }
  for (const file of files) {
    const content = await file.text();
    const res = await api.createNote({ content, tags: [] });
    state.index.unshift(res.meta);
    state.contents[res.meta.id] = res.content;
  }
}

这条链路里,渲染层拿到的是 File 对象,File.text() 读的是浏览器已经授权的文件内容。没有路径,没有 URI,也没有 fs。主进程只收到一个字符串,然后按普通新建笔记处理。所以拖拽导入不受「选择器只授权目标文件」的限制,也不需要额外的文件系统权限。代价是正文要走一次 IPC,于是撞上 preload 里那条 2 MB 的正文限制:createNote 会先用 Buffer.byteLength 量一遍内容,超了直接返回 { ok:false, error:'LIMIT', kind:'body', actual, limit },不会进主进程。拖一个 2 MB 以上的 Markdown 进来,importFiles() 拿不到 res.meta,会走进 catch 分支,界面上看到的是 toast「导入 xxx.md 失败」,而不是「超过 2 MB」。这个提示不精确,属于这一版的已知边界。

5.2 和选择器导入的差别

维度选择器导入拖拽导入
触发点导入按钮文件拖进窗口
读取位置主进程 fs.readFileSync渲染层 File.text()
输入形态绝对路径文件内容
多选multiSelectionsdataTransfer.files 多文件
扩展名过滤对话框过滤器正则过滤
大小限制10 MB(主进程 checkImportSize)2 MB(preload 的 createNote 正文限制)
权限依赖选择器授权浏览器文件授权
失败表现返回 {ok:false,error}toast「导入失败」

拖拽还有一个细节:drop 事件无条件 preventDefault(),即使拖的不是文件。这样做是为了防止把文件拖进窗口时 Chromium 直接导航到 file:// 地址,把整个应用页面替换成文件内容。will-navigate 里也挡了非 file:// 的导航,但 file:// 是放行的,所以 drop 的 preventDefault() 是必要的第二道。

拖出(把笔记拖到文件管理器)没有实现。draggable 没有设,dragstart 没有监听,导出仍然走菜单里的保存对话框。这一条留给第 25 篇。

5.3 遮罩、离开与失败

拖拽的视觉反馈只有一层遮罩:dragenter 时 state.dragDepth += 1,显示「松开导入 Markdown」;dragleave 时减一,减到 0 才隐藏。用计数器而不是布尔值,是因为拖过子元素时会连续触发 enter/leave,布尔值会闪。drop 时把计数清零并隐藏遮罩,不管导入成功还是失败。

失败分两种。扩展名不对时,importFiles() 直接 toast「只支持 .md / .markdown / .txt」,不进入循环;单个文件读失败时,toast 里带文件名,循环继续处理下一个。两种都不会写事件日志,所以拖拽失败只存在于当前界面的 toast 里,关掉就没了。这是和选择器导入的一个差别:选择器导入的失败会走 logEvent,拖拽的不会。

拖拽还有一个隐式限制:File.text() 按 UTF-8 解码,遇到 GB18030 或 UTF-16 的旧文件很可能得到乱码。选择器导入用 fs.readFileSync(filePath, 'utf8'),同样只认 UTF-8。这一版没有编码探测,也没有 BOM 处理。中文 Windows 上常见的 GBK 文件拖进来大概率会乱码,这是已知边界,未做自动转码。


6. 导出:三条路径

6.1 Markdown 与 HTML

export:note 先按 payload.format 归一化,只认 md、html、pdf,其它值一律当 md。标题用 sanitizeFileName():把 \ / : * ? " < > | 和换行替换成下划线,连续空白压成一个空格,trim,截到 80 个字符,空字符串回退「未命名笔记」。扩展名由格式决定,不信任调用方传的文件名。

Markdown 写 payload.content,HTML 写 buildHtmlDocument(title, payload.html)。HTML 文档带一段内联 CSS,正文最大宽度 760 px,A4 页边距 18 mm,打印时去掉外边距。payload.html 是渲染层 el.preview.innerHTML 的结果,已经过 markdown.js 的转义和白名单过滤。

6.2 PDF 为什么不弹保存框

代码里有一条注释:

// 鸿蒙 PC 上 PDF 保存对话框会卡住主进程,改为直接写入应用数据目录的 exports
target = path.join(store.exportDir, `${safeName}.pdf`);

所以 PDF 不调用 askSavePath(),直接写 moji/exports/<标题>.pdf。生成过程在 v1.1 里是直接对当前窗口调 webContents.printToPDF({ printBackground: true, pageSize: 'A4', preferCSSPageSize: true }),把 Buffer 写到目标文件——不再新建隐藏窗口。隐藏窗口那条路径还在,但只在打印失败回退时用:exportPdfFile() 新建一个 900×1200、javascript: false、sandbox: true 的 BrowserWindow,加载临时 HTML,等 150 ms 再 printToPDF,最后销毁窗口、删临时 HTML。

v1.1 补上了产物测量:导出「未命名笔记」得到 543,193 B(530 KB)、2 页、776 ms,峰值 RSS 386,146,304 B(368.3 MiB),文件落在 /data/storage/el2/base/files/moji/exports/未命名笔记.pdf。页数由 PDF 文本里的 /Type /Page 计数得到,不是按 Markdown 长度估算;耗时取 printToPDF 前后打点,RSS 是主进程整体峰值,含 Electron 基线。

在这里插入图片描述

这张图是性能面板全貌,PDF 指标卡片停在「未导出」——截图拍在导出动作之前,所以图上没有 530 KB、2 页、776 ms、368.3 MiB 这四个数字;四个数字来自 v11-metrics.json。图的作用是交代面板结构,数值另由 metrics 文件复核,两者不互相冒充。

6.3 菜单里的入口

「更多操作」菜单有九项:在新窗口打开、导出 Markdown、导出 HTML、导出 PDF、复制正文、打印 (Ctrl+P)、模拟 Ctrl+滚轮、性能面板 v1.1、移到回收站。其中导出三项走同一个 export:note,只是 format 不同:

在这里插入图片描述

这张图是 v1.1.0 的真机截图,九项都在,导出入口在应用内菜单里,不在系统右键菜单里。菜单的定位是相对「⋯」按钮算的,宽度 200 px,高度取 offsetHeight 或 230,超出视口就翻到按钮上方;截图里两条分隔线把「打开/导出」「复制」「打印/性能面板/回收站」分成三组,和 #moreMenu 的结构一致。

格式保存对话框写入位置失败回退实测产物
Markdown有用户选的 .mdexports/<名字>.md未校验字节
HTML有用户选的 .htmlexports/<名字>.html未校验字节
PDF无exports/<名字>.pdf不回退,直接报错530 KB / 2 页 / 776 ms
复制正文无剪贴板{ok:false}未测

6.4 文件名的边界

sanitizeFileName() 处理的是「用户标题 → 文件名」,规则是:

输入输出原因
周会纪要 · 11 月 14 日原样中文、空格、间隔号都合法
a/b:c*d?e"f<g>h|ia_b_c_d_e_f_g_h_i替换 9 个保留字符
连续多个空格压成一个避免文件名过长
前后空白trim避免首尾空格
超过 80 字符截断避免超出文件系统限制
空字符串未命名笔记兜底

这个函数只用于导出文件名,不用于笔记的 id。笔记文件用的是 n_YYYYMMDD_xxxxxx.md,由 makeId() 生成,和时间、随机字节有关,不含标题。标题改了,文件名不变;导出时才按当前标题生成新文件名。这个分离让「改标题」不会触发文件 rename,减少了失败点。

导出同名文件时,保存对话框的 showOverwriteConfirmation 会弹确认;回退到 exports 时直接覆盖同名文件,没有额外确认。这一点在批量导出同名笔记时会踩到:两篇都叫「未命名笔记」,第二次会覆盖第一次。这一版没有做自动加序号。


7. 回收站与目录移动

trashNote() 把 notes/<id>.md 移到 trash/<id>.md,索引里的 trashed 置 true,trashedAt 记时间。restoreNote() 反向移动。deleteNote() 删文件并从索引移除。emptyTrash() 遍历所有 trashed 项,删文件,过滤索引。

移动用 fs.renameSync,失败时 copyFileSync + unlinkSync。同一个 el2/base/files 下 rename 应该成立,copy 是退路。回收站的截图拍摄时是 1 篇:

在这里插入图片描述

这张图证明回收站是独立目录加索引标记,不是把正文改成空文件。左侧「全部笔记 4、回收站 1」,右侧显示「这篇笔记在回收站中」,正文只读,底部有恢复和彻底删除。

本次交付状态是回收站 0 篇。示例笔记里写着「默认保留 30 天」,但代码里没有定时清理,也没有按 trashedAt 过滤的过期逻辑。30 天只是文案,不是行为。要清空只能手动点「清空」或逐篇彻底删除。这一条在写产品文档时容易说错,代码为准。

7.1 移动失败会怎样

moveNoteFile() 先试 renameSync,失败再 copyFileSync + unlinkSync。如果 copy 也失败,trashNote() 会抛错,索引不会改成 trashed,界面上的操作会失败。这个顺序是对的:先移动文件,再改索引。反过来先改索引再移动,文件移动失败会留下「索引说在回收站、文件还在 notes」的不一致状态。

彻底删除是先删文件、再从索引移除。删文件失败只记 warn,索引仍然移除。结果是「文件成了孤儿,但列表里看不到」。这在正常权限下不会发生,在文件被外部程序占用时可能发生。孤儿文件不会被 loadAllContents() 读到,因为索引里没有它;但它会一直占磁盘,直到手动清理。这一版没有孤儿扫描。

清空回收站遍历所有 trashed 项,逐个删文件,最后一次性过滤索引。中间失败会跳过该文件并记 warn,其它继续。返回值是「原本有多少条 trashed」,不是「成功删了多少个文件」。界面 toast 写「回收站已清空」,即使有个别文件没删掉。这是一个口径差,不影响大多数场景。


8. 边界与踩坑

#现象原因当前处理
1导出报 EPERM选择器只授权目标文件,临时文件是兄弟文件直接写目标,失败回退 exports
2保存对话框不可用对话框异常或平台不支持回退 exports,返回 fallback:true
3PDF 保存框卡主进程平台对话框行为不弹框,直接写 exports
4导出文件写一半放弃原子写换权限接受,笔记正文仍原子写
5索引损坏后示例重写readJson 失败当首次启动已知,未做备份
6选择器返回 URI代码只处理路径未覆盖,未测
7大文件导入分块读 1 MB/块,10 MB 上限在主进程超出返回 LIMIT,10 MB 档导入耗时未测
8拖拽导入顺序逐篇 unshift列表最后导入在最上
9拖拽非文件drop 无条件 preventDefault防止页面被 file:// 替换
10回收站 30 天只有文案,没有定时器手动清理
11resfile 写不进去el1/bundle 只读所有写走 userData
12资源目录升级被覆盖HAP 整体替换数据不放在资源目录
13拖入超过 2 MB 的文件preload 返回 LIMIT,渲染层按异常处理只提示「导入失败」,且 state.index.unshift(undefined) 已在抛错前执行,未修

这一版没做的事:没有处理选择器 URI,没有拖出,没有索引备份,没有回收站过期清理;Markdown/HTML 导出有 export:progress 进度事件,PDF 导出只有结束后的指标、没有过程进度;导入上限 10 MB 在主进程,选择器路径的文件头识别仍未做。它们不影响「5 篇笔记能导入导出」这条主线,但会影响大文件和异常场景的可用性。

如果只补一件事,应该补「导入前的文件头识别」。v1.1 已经有主进程的 10 MB 上限和 LIMIT 返回,但选择器仍然只看扩展名;一个改了后缀的 docx 或二进制文件仍会被当 UTF-8 读成乱码。读前 4 个字节识别 PK / OLE 头,比继续调大小阈值更直接。URI 兼容是平台差异,文件头是内容保护,后者更容易在真实用户身上发生。

第二件应该补的是索引备份。index.json 损坏会触发重新 seed,虽然正文文件还在,但用户看到的是「列表变成 5 篇示例」。在 saveIndex() 前留一份 index.json.bak,启动时解析失败就回退,成本很低。

第三件是导出结果回读。现在 export:note 写完就返回路径,没有 stat 一下文件是否存在、字节数是否大于 0。选择器授权、磁盘满、路径被占用,三种失败都可能在 writeFileSync 返回后才暴露。加一次 fs.statSync(target) 并比对 content.length > 0,不解决权限问题,但能让 toast 从「已导出」变成「导出文件为空」,用户少一次困惑。这三件事都不大,但都能把「文件边界」从能跑变成可诊断,出问题时也少猜几次。

下一篇换到键盘和焦点:快捷键到底绑了哪些、右键菜单有没有、中文输入法在搜索框和编辑器里的差别、单实例到底是不是单实例。


参考

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐