鸿蒙 PC × Electron:沙箱目录、选择器 URI 与拖拽导入
欢迎加入开源鸿蒙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/files | Electron 的 app.getPath('userData') |
| 墨记数据根 | /data/storage/el2/base/files/moji | userData/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/tmp | PDF 导出用的中间 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 | 不弹保存框,直接写 exports | printToPDF,实测 530 KB / 2 页 / 776 ms |
| PDF 峰值 RSS | 386,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.json | 771 | 入口、版本、构建配置 |
src/main/index.js | 70,302 | 主进程、窗口、IPC、导出 |
src/main/ohos-env.js | 2,774 | 平台判断、路径、窗口参数 |
src/main/store.js | 14,140 | 索引、正文、设置、原子写 |
src/main/seed.js | 5,759 | 5 篇示例笔记 |
src/main/docx.js | 6,029 | docx 最小 ZIP/XML 解析 |
src/main/limits.js | 2,309 | 2 MB / 10 MB / 100 KB / 5 MB 限额与限流 |
src/main/native-kit.js | 1,637 | ArkTS 桥调用 |
src/main/search-index.js | 3,309 | 倒排索引构建与查询 |
src/main/search-service.js | 4,054 | worker 生命周期与超时 |
src/main/search-worker.js | 2,578 | worker 线程入口 |
src/preload/bridge.js | 7,287 | 白名单桥、限额与限流 |
src/preload/index.js | 43 | 普通 preload 入口 |
src/preload/frameless.js | 42 | 自绘标题栏实验入口 |
src/renderer/index.html | 17,239 | 三栏结构、弹层、菜单 |
src/renderer/app.js | 111,692 | 交互、保存、诊断、拖拽 |
src/renderer/markdown.js | 9,246 | 纯函数 Markdown 渲染 |
src/renderer/ocr-ui.js | 3,359 | OCR 面板与取字按钮 |
src/renderer/style.css | 36,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/files | Electron 约定的用户数据根 |
| 墨记数据 | /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 日.md | sanitizeFileName() 处理后的标题 |
| PID | 39793 | 当时的应用主进程 |
| 时间戳 | 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。
| 阶段 | 目标 | 失败后的动作 | 结果 |
|---|---|---|---|
| 保存对话框 | 用户选的路径 | 对话框异常 → exports | fallback: true |
| 写 Markdown | 用户选的 .md | 写失败 → exports/<名字>.md | 返回新路径 |
| 写 HTML | 用户选的 .html | 写失败 → exports/<名字>.html | 返回新路径 |
| 写 PDF | exports/<名字>.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() |
| 输入形态 | 绝对路径 | 文件内容 |
| 多选 | multiSelections | dataTransfer.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 | 有 | 用户选的 .md | exports/<名字>.md | 未校验字节 |
| HTML | 有 | 用户选的 .html | exports/<名字>.html | 未校验字节 |
| 无 | exports/<名字>.pdf | 不回退,直接报错 | 530 KB / 2 页 / 776 ms | |
| 复制正文 | 无 | 剪贴板 | {ok:false} | 未测 |
6.4 文件名的边界
sanitizeFileName() 处理的是「用户标题 → 文件名」,规则是:
| 输入 | 输出 | 原因 |
|---|---|---|
周会纪要 · 11 月 14 日 | 原样 | 中文、空格、间隔号都合法 |
a/b:c*d?e"f<g>h|i | a_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 |
| 3 | PDF 保存框卡主进程 | 平台对话框行为 | 不弹框,直接写 exports |
| 4 | 导出文件写一半 | 放弃原子写换权限 | 接受,笔记正文仍原子写 |
| 5 | 索引损坏后示例重写 | readJson 失败当首次启动 | 已知,未做备份 |
| 6 | 选择器返回 URI | 代码只处理路径 | 未覆盖,未测 |
| 7 | 大文件导入 | 分块读 1 MB/块,10 MB 上限在主进程 | 超出返回 LIMIT,10 MB 档导入耗时未测 |
| 8 | 拖拽导入顺序 | 逐篇 unshift | 列表最后导入在最上 |
| 9 | 拖拽非文件 | drop 无条件 preventDefault | 防止页面被 file:// 替换 |
| 10 | 回收站 30 天 | 只有文案,没有定时器 | 手动清理 |
| 11 | resfile 写不进去 | 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 从「已导出」变成「导出文件为空」,用户少一次困惑。这三件事都不大,但都能把「文件边界」从能跑变成可诊断,出问题时也少猜几次。
下一篇换到键盘和焦点:快捷键到底绑了哪些、右键菜单有没有、中文输入法在搜索框和编辑器里的差别、单实例到底是不是单实例。
参考
- 框架仓库:https://atomgit.com/CPF-Electron/Electron
- 预编译包:https://atomgit.com/CPF-Electron/Electron/releases/tag/v40.0.1
- 第 1 篇:从 367MB 预编译包到第一个能开窗的 HAP
- 第 2 篇:首启排障的四个检查层
- 第 3 篇:自由窗口、DPI、多屏与自绘标题栏
- 开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
更多推荐


所有评论(0)