从 BibTeX 语法解析到引用格式生成——JabRef 鸿蒙PC文献管理器的数据模型、字段校验与文献库持久化
文献管理工具的核心,不只是把论文标题显示成一张表,而是把 BibTeX 文本、结构化字段、检索条件、引用格式和本地文件连接成一条可操作的数据链路。本文介绍鸿蒙 PC 上的 JabRef Electron 壳应用:以纯 JavaScript 实现 BibTeX 解析、字段校验、类型与关键词分组、疑似重复检测、四种引用样式和文献库读写,并围绕主进程、页面布局、文献引擎、编辑交互及 HAP 工程配置展开适配实践。
需要先说明版本范围:本文分析的是当前 ohos_JabRef_electron-main 工程中的 Electron 壳与 JavaScript 业务实现,不是将上游 Java JabRef 的全部代码迁移为 JavaScript,也不代表已实现上游项目的全部功能。下文代码依据本地源码,界面图片使用对应项目已有截图;构建与设备验证步骤是复现指引,不作为本次已经完成 HAP 构建或真机测试的记录。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_JabRef
一、技术架构分析
1.1 整体架构
本项目采用 Electron 业务层 + 鸿蒙 HAP 壳工程的分层结构。与需要持续上报抓取进度的工具不同,文献解析、搜索和引用格式化都是本地计算,当前实现将这些工作直接放在渲染进程中。
- 文献引擎:bib-engine.js 负责解析、序列化、检索、校验、引用格式化、重复候选检测、分组和统计,不调用 DOM,也不依赖 Node.js 模块。
- 渲染进程:renderer.js 直接加载文献引擎,维护条目数组、当前分组、选中条目、搜索词和修改标记,再将结果更新到页面。
- 主进程:main.js 创建窗口,通过 7 个请求响应 IPC 通道完成文件读取、保存和系统文件对话框操作。
- 鸿蒙壳工程:electron 是 entry 模块,依赖 web_engine HAR 模块;业务资源随工程打包,由随附的运行时承载。
数据流可以概括为:
用户库 / 外部 .bib / 内置样例
↓ 主进程读取,IPC 返回文本
renderer.js → bib-engine.js
↓ 解析为条目数组
分组 / 检索 / 校验 / 引用
↓ DOM 更新
条目表 + 四 Tab 详情
↓ 序列化或生成引用文本
IPC → 主进程 → 本地文件
这个边界让文献引擎可以脱离窗口独立验证,也让文件权限和活动文件路径集中在主进程管理。但“计算位于渲染层”不等于后台计算:当前搜索和统计都是同步执行,大规模文献库仍需要单独评估交互延迟。
1.2 技术方案
| 设计关注点 | 本工程采用的方案 | 对应收益与边界 |
|---|---|---|
| 项目定位 | 本地 BibTeX 文献库管理 | 聚焦打开、整理、编辑与导出工作流 |
| 业务语言 | HTML、CSS、Vanilla JavaScript | 业务层不需要 Java 运行环境 |
| 数据格式 | 字符扫描解析 + 条目对象序列化 | 便于结构化处理,但不保留全部原始语法 |
| 文献组织 | 类型分组、关键词分组、多词 AND 检索 | 筛选条件可组合,不依赖外部数据库 |
| 引用输出 | APA、IEEE、MLA、Plain 四套简化模板 | 直接生成文本,不引入完整引用样式引擎 |
| 文件操作 | Electron dialog + Node.js fs + IPC | 系统交互与文献计算分开 |
| 部署形态 | electron entry + web_engine HAR + HAP | 业务资源随鸿蒙壳工程打包 |
这里的“纯 JavaScript”描述的是业务引擎,不表示应用不需要 Electron 或鸿蒙原生运行时。仓库主页的 Java 适配介绍与本地 Electron 工程不是同一层面的说明,复现本文时应核对所用分支是否包含下文列出的业务文件。
1.3 核心功能清单
| 功能模块 | 当前能力 |
|---|---|
| BibTeX 解析 | 花括号形式条目、嵌套花括号、引号值、字符串连接、宏展开 |
| 指令处理 | 读取 @string、@comment、@preamble,预置 12 个月份宏 |
| 字段校验 | 19 种类型的必填字段配置,部分类型另有建议字段 |
| 检索过滤 | 空白分词、多词 AND、字段前缀,与分组范围叠加 |
| 自动分组 | 全部条目、无关键词条目、类型分组、关键词分组 |
| 重复提示 | 标题归一化、首位作者姓氏与年份两类候选规则 |
| 引用预览 | APA、IEEE、MLA、Plain 四种纯文本样式 |
| 条目编辑 | 新建、BibTeX 编辑后应用、重填编辑区、两步删除 |
| 库文件操作 | 打开、追加导入、保存、另存为、载入内置样例 |
| 文件导出 | BibTeX、纯文本参考文献、HTML 参考文献 |
| 界面交互 | 四 Tab 详情、可拖拽分隔条、自定义下拉、状态栏与关于弹层 |
“疑似重复”是候选组,不会自动删除文献;“字段校验”是本项目规则,不是完整 BibTeX 规范验证;“序列化”也不意味着原始文件可以无损往返。这些区别会直接影响日常使用方式。
二、环境准备
2.1 开发环境要求
| 项目 | 版本或配置依据 |
|---|---|
| 开发工具 | DevEco Studio,安装与工程匹配的 HarmonyOS SDK 和构建工具 |
| 桌面调试 | Node.js、npm,以及可运行本项目的 Electron 环境 |
| 核心框架 | Electron;业务层使用 CommonJS 模块与原生 DOM |
| 兼容 SDK 配置 | build-profile.json5 中为 5.0.5(17) |
| 运行系统配置 | runtimeOS 为 HarmonyOS |
| 声明设备类型 | 2in1、tablet |
| 随附原生库目录 | electron/libs/arm64-v8a |
| 构建产品与模块 | product 为 default,入口模块为 electron,target 为 default |
| 当前应用标识 | bundleName 仍为 com.huawei.ohos_electron |
| 当前应用级名称 | AppScope 中的 app_name 仍为 Electron |
兼容 SDK 字段是工程声明,不等于所有对应系统版本和设备均已测试通过。项目没有通过 package.json 固定 Electron 版本;桌面调试时选用的运行时,也不能自动代表鸿蒙随附运行时的版本与行为。
web_engine 的权限清单还保留了网络、文件目录访问、定位、麦克风、摄像头等模板声明。当前文献业务代码没有在线元数据检索或网络下载逻辑,但不能由此推断整个壳及运行时完全没有网络行为。正式发布前应逐项核对权限用途,不把模板权限直接解释为业务能力。
2.2 项目结构
ohos_JabRef_electron-main/
├── lib.unstripped/ # 未剥离符号的原生库目录
└── ohos_hap/
├── AppScope/ # 应用标识、名称及全局资源
├── electron/ # entry 模块与随附原生运行时
│ └── libs/arm64-v8a/
├── web_engine/ # HAR 模块
│ └── src/main/resources/resfile/resources/app/
│ ├── main.js # 窗口、活动文件、7 个文件 IPC
│ ├── bib-engine.js # 独立文献计算引擎
│ ├── renderer.js # 页面状态与交互调度
│ ├── index.html # 工具栏、分组、条目、详情、关于
│ ├── package.json # 入口与桌面启动脚本
│ ├── samples/
│ │ └── default-library.bib # 14 条内置样例
│ └── styles/
│ └── jabref.css # Catppuccin Mocha 深色主题
└── build-profile.json5 # 产品、模块和签名配置
后文出现的 main.js、bib-engine.js、renderer.js 等文件名,均指上述 app 目录内的文件。代码块为实际源码节选;位于某个函数内部的片段会注明上下文,不能脱离外层变量直接粘贴运行。
2.3 依赖说明
业务目录的 package.json 很精简:
{
"name": "jabref",
"version": "1.0.0",
"description": "JabRef - BibTeX 文献管理器(鸿蒙 PC 适配版)",
"main": "main.js",
"scripts": {
"start": "electron ."
}
}
| 依赖或模块 | 用途 |
|---|---|
| Electron | 窗口、应用生命周期、屏幕工作区、IPC 和文件对话框 |
| Node.js fs / path | 主进程读写文件、组合路径、创建保存目录 |
| bib-engine.js | 纯计算模块,没有 require 外部库 |
| 浏览器 DOM / CSS | 表格、详情、分组、下拉及主题样式 |
| web_engine | electron 模块通过 file:…/web_engine 引用的本地 HAR |
package.json 没有 dependencies 或 devDependencies,不能指望在这个目录执行 npm install 自动获得 Electron。这里的零第三方业务库依赖,减少了 npm 原生扩展的适配工作;HAP 壳本身的依赖、SDK 和原生库仍然需要正确配置。
三、核心适配流程
3.1 主进程实现(main.js)
主进程主要解决两件事:给本地业务页面创建窗口,以及管理文件的读取和落盘。
窗口尺寸采用主显示器的工作区,而不是直接使用整块屏幕尺寸。宽度取 92%,高度取 86%,再交给系统窗口管理器处理后续缩放。
以下是窗口函数的实际实现。源码中的防崩注释表示配置意图,不能替代对具体设备的稳定性验证:
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),
frame: true,
transparent: false,
resizable: true,
title: 'JabRef - 文献管理',
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
});
mainWindow.loadFile('index.html');
} catch (e) {
console.warn('[JabRef] 创建窗口失败:', e.message);
}
}
app.whenReady 后调用该函数;所有窗口关闭时调用 app.quit。文件相关操作统一使用以下 7 个请求响应通道,主进程没有文献业务的 webContents.send 推送:
| 通道 | 职责 | 是否影响活动文件 |
|---|---|---|
| lib:load | 读取用户库,失败时尝试样例,再回退空库 | 设置用户库路径或空值 |
| lib:loadSample | 读取样例并尝试覆盖默认用户库 | 切回默认用户库,写入失败时置空 |
| lib:save | 保存当前内存库生成的文本 | 保持目标,必要时回退默认用户库 |
| lib:saveAs | 选择新路径并写入 | 成功后切换到新文件 |
| lib:openExternal | 打开外部 bib/txt 文件 | 读取成功后切换到外部文件 |
| lib:importFile | 读取待导入文件 | 不改变活动文件 |
| lib:export | 写入已生成的 bib/txt/html 文本 | 不改变活动文件 |
用户库与样例库分开存放:
function canonicalLib() {
return path.join(app.getPath('userData'), 'JabRefLibrary.bib');
}
function samplesLib() {
return path.join(__dirname, 'samples', 'default-library.bib');
}
样例属于随包资源,用户修改写入 userData 或用户选择的文件。lib:load 先读取默认用户库;只要读取结果不是 null,即使内容为空,也按用户库处理。仅当读取失败时才尝试样例。
这个路径策略还有一个容易忽略的细节:打开外部库或另存为,只切换当前会话的 currentFile。代码没有持久化“最近打开的外部库路径”,重新启动仍先读取默认的 JabRefLibrary.bib。
3.2 页面布局实现(index.html)
页面采用顶部工具栏 + 左侧分组 + 中央条目表 + 底部详情的组合。文献条目始终是中心对象,其余区域分别提供操作入口、筛选条件和字段解释。
| 区域 | 页面内容 |
|---|---|
| 顶部工具栏 | 打开、导入、保存、另存为、载入示例、导出、新增、删除和搜索 |
| 文件行 | 当前文件名;存在已应用但未保存的变更时显示圆点标记 |
| 左侧分组 | 全部、未分组、类型、关键词及对应条目数 |
| 中央条目表 | 引用键、类型、首位作者、年份、标题 |
| 底部详情 | 信息、BibTeX、引用、校验四个 Tab |
| 状态栏 | 当前操作结果、错误提示和关于入口 |
四个 Tab 共享同一个选中条目,页面中的按钮结构如下:
<div id="detailTabs" class="detail-tabs">
<button class="detail-tab active" data-tab="info" aria-label="查看条目字段">信息</button>
<button class="detail-tab" data-tab="bib" aria-label="编辑 BibTeX">BibTeX</button>
<button class="detail-tab" data-tab="cite" aria-label="引用格式预览">引用</button>
<button class="detail-tab" data-tab="check" aria-label="字段校验结果">校验</button>
<span id="detailTitle" class="detail-title">未选中条目</span>
</div>
- 信息页按字段顺序展示可读文本。
- BibTeX 页使用 textarea,修改后需要点击“应用”。
- 引用页展示当前样式预览,并列出四种样式文本。
- 校验页展示字段问题及当前条目的疑似重复提示。
导出格式、新建类型和引用样式都采用自定义 div 下拉,通过 data-value 保存选择值,再用 selected 和 open 类控制视觉状态。当前新增菜单提供 8 种常用类型;引擎中的 19 种类型配置不能直接当作新增菜单的选项数量。
页面声明了本地资源策略:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'self' 'unsafe-inline'">
该策略约束页面资源加载,但不是 Node.js 权限隔离机制。应用依然应只加载受信任的本地页面,文献内容则作为数据展示。
3.3 BibTeX 文献引擎(bib-engine.js)
引擎将一份文献库转换为 entries、strings、comments、preamble 和 errors 组成的对象。普通条目再拆为引用键、类型、字段映射和字段顺序:
lib.entries.push({ key: key, type: typeRawLocal, fields: fields, order: order });
上面一行位于 parseBibtex 内部的 parseEntry 函数中。这个模型有意把用于检索的结构化数据与原始排版分开,后续搜索、分组和格式化都围绕条目对象展开。
1. 逐字符扫描,处理嵌套结构
BibTeX 的字段值可能出现嵌套花括号,不能简单按逗号或右花括号切开。例如内置样例中的标题保留了 BERT 的大小写保护:
title = {{BERT}: Pre-training of Deep Bidirectional Transformers for Language Understanding}
解析器先提取普通条目的外层正文,再由 parseEntry 中的局部扫描器处理字段。以下是字段花括号扫描函数原文:
function readBalLocal(open, close) {
var depth = 0, out = '';
while (p < m) {
var ch = body[p];
if (ch === '\\' && p + 1 < m) { out += ch + body[p + 1]; p += 2; continue; }
if (ch === open) { depth++; }
if (ch === close) { depth--; if (depth === 0) { out += ch; p++; return out; } }
out += ch; p++;
}
return out;
}
这个函数依赖外层的 body、p 和 m,深度归零才结束当前组;反斜杠与后一个字符一起消费,避免把转义字符误当作结构边界。花括号字段读取时再剥离最外层的一对括号,保留内部组。
2. 字符串宏和连接值
字段值既可以是花括号或引号包裹的文本,也可以是数字和宏名。多个值用 # 连接,连接逻辑仍位于 parseEntry 内部:
function readFieldVal() {
var parts = [];
var firstFlag = true;
while (p < m) {
if (!firstFlag) { if (body[p] === '#') { p++; wS(); } else break; }
firstFlag = false;
var seg = readFieldAtom();
if (seg === null) break;
parts.push(seg);
wS();
if (body[p] !== '#') break;
}
return parts.join('');
}
@string 声明写入 lib.strings,普通字段读到宏名时查表展开。样例库中的 acm 宏用于 publisher 字段,jan 至 dec 则在解析开始时预置。未知宏返回名称文本,而不是执行任何脚本。
@comment 和 @preamble 也有单独分支,但这不代表解析器覆盖全部 BibTeX 语法:普通条目目前识别花括号形式,不能据此宣称支持所有圆括号写法;preamble 分支只读取一个值原子;引号字段中的花括号子组会被局部扫描器剥去一层。解析错误也没有完整的行列号诊断,lib.errors 当前主要记录重复键改名。
3. 多词 AND 与字段限定检索
检索先处理分组范围,再把搜索词按空白切开,每个词都匹配才保留条目。引擎中的核心逻辑如下:
function searchEntries(entries, query, opts) {
opts = opts || {};
var q = String(query || '').trim();
var tokens = q ? q.split(/\s+/) : [];
return entries.filter(function (e) {
if (opts.type && opts.type !== 'all' && e.type !== opts.type) return false;
if (opts.keys && opts.keys.indexOf(e.key) < 0) return false;
if (opts.minYear && parseInt(getYear(e), 10) && parseInt(getYear(e), 10) < opts.minYear) return false;
if (opts.maxYear && parseInt(getYear(e), 10) && parseInt(getYear(e), 10) > opts.maxYear) return false;
if (!tokens.length) return true;
return tokens.every(function (tok) {
var m = /^([a-z]+):(.+)$/i.exec(tok);
if (m) {
var field = m[1].toLowerCase(), term = lower(m[2]);
var hay;
if (field === 'type') return lower(e.type).indexOf(term) >= 0;
if (field === 'key') return lower(e.key).indexOf(term) >= 0;
hay = lower(fieldValueForSearch(e, field));
return hay.indexOf(term) >= 0;
}
var t = lower(tok);
return lower(searchable(e)).indexOf(t) >= 0;
});
});
}
典型查询可以写成:
author:He year:2016
keyword:cv title:residual
type:article transformer
字段前缀是子串匹配,不是精确相等,也不是正则表达式。keyword 对应 keywords 字段,journal 优先读取 journal、缺失时读取 booktitle,url 优先读取 url、缺失时读取 howpublished。DOI 可用 doi: 前缀检索,但普通无前缀检索的字段集合并不包含所有字段。
当前 UI 只向检索器传入分组 keys;引擎虽然预留了 type、minYear、maxYear 选项,页面没有对应的独立年份范围控件,也没有引号短语或 OR 查询语法。
4. 必填项、建议项与库统计
REQUIRED_FIELDS 为 19 种类型定义必填项;RECOMMENDED_FIELDS 只为 article、inproceedings、book、techreport 定义建议项。validateEntry 内部据此生成不同等级的问题:
req.forEach(function (f) {
if (!getFieldValue(entry, f).trim()) problems.push({ level: 'error', field: f, msg: '缺少必填字段 ' + f });
});
rec.forEach(function (f) {
if (!getFieldValue(entry, f).trim()) problems.push({ level: 'warn', field: f, msg: '建议补充 ' + f });
});
除此之外,还会检查引用键字符、年份格式、页码分隔符、月份、摘要长度、crossref 目标和 URL 前缀。crossref 只检查目标条目是否存在,不会继承父条目的字段;也没有 DOI 在线核验。
工具栏“待完善”统计的是至少包含一个 error 的条目数量,而不是错误总数。样例中的 incomplete2021 同时缺少 author 和 year,仍只计为 1 条待完善。只有建议字段缺失的条目会显示警告标记,但不增加这一计数。
5. 类型分组、关键词分组与重复候选
buildGroups 自动构建四类分组:全部条目、没有关键词的“未分组”、按类型聚合的分组,以及按关键词聚合的分组。关键词使用逗号或分号拆分,一个条目可以同时进入多个关键词组,因此不能把各组数量相加当成全库数量。
findDuplicates 则使用两组规则:
- 标题经可读文本转换、转小写、去除部分非字母数字字符后相同。
- 首位作者姓氏与年份相同。
它返回候选组,供工具栏计数与校验页提示。相同作者同年发表不同论文很常见,第二条规则尤其需要人工判断。代码没有 DOI 主键去重、自动合并字段或批量删除逻辑。
6. 四种引用样式
formatCitation 按样式生成单条引用;formatBibliography 对数组排序后连接为多行文本。以下是后者的实际实现:
function formatBibliography(entries, style) {
var sorted = entries.slice().sort(function (x, y) {
var ax = (getAuthors(x)[0] || { last: '' }).last.toLowerCase();
var ay = (getAuthors(y)[0] || { last: '' }).last.toLowerCase();
if (ax !== ay) return ax < ay ? -1 : 1;
return (parseInt(getYear(x), 10) || 0) - (parseInt(getYear(y), 10) || 0);
});
return sorted.map(function (e, idx) {
var body = formatCitation(e, style);
if (style === 'ieee') return '[' + (idx + 1) + '] ' + body;
return body;
}).join('\n');
}
| 样式 | 当前实现特点 |
|---|---|
| APA | 姓氏与名字首字母、年份、标题、出版来源等文本拼接 |
| IEEE | 作者缩写、带引号标题、卷期页码;批量文本输出增加序号 |
| MLA | 作者、标题、来源、年份、页码组合 |
| Plain | 用分号连接作者,生成简单可读文本 |
这些是便于预览和导出的简化样式,不是完整 CSL 引擎。作者解析、LaTeX 转可读文本、机构作者、重音字符和标点规则都比较有限;IEEE 批量文本按作者姓氏和年份排序,并非正文引用顺序。投稿前仍应对照目标刊物的规范校订。
3.4 渲染进程交互与编辑回写(renderer.js)
渲染层直接加载引擎:
var electron = require('electron');
var ipcRenderer = electron.ipcRenderer;
var E = require('./bib-engine');
这使搜索、分组、字段校验和引用预览不需要额外的业务计算 IPC。页面只在打开、保存等文件动作发生时请求主进程。
派生数据与视图范围:
function refreshDerived() {
state.groups = E.buildGroups(state.entries);
state.stats = E.libraryStats(state.entries);
$('badgeEntries').textContent = state.stats.total;
$('badgeIncomplete').textContent = state.stats.incomplete;
$('badgeDup').textContent = state.stats.dupGroups;
}
refreshDerived 以整个 state.entries 为输入,所以工具栏的 14 / 1 / 1 是全库统计;表格底部的“5 条”或“3 条”才是当前视图数量。
分组和搜索组合后的结果由 filteredEntries 获取:
function filteredEntries() {
var keys = groupKeys(state.currentGroupId);
var opts = keys ? { keys: keys } : {};
return E.searchEntries(state.entries, state.query, opts);
}
表格渲染使用 createElement、textContent 和 createTextNode 写入文献数据,避免把标题、作者或摘要当成 HTML 执行。字段状态点先判断 error,再判断 warn,因此列表中的红黄标记表达的是问题等级,不是文献类型。
BibTeX 编辑采用“应用到内存,再保存到磁盘”:
用户在 textarea 中修改后,点击“应用”,渲染层重新调用 parseBibtex。如果没有解析到条目则提示失败;有结果时只使用第一条替换当前条目,随后更新选择、修改标记、分组、统计和详情。
以下节选自“应用”按钮回调末尾,ne 是前面取得的首个解析条目:
state.selectedKey = ne.key;
markDirty();
refreshDerived();
renderGroups();
renderTable();
renderDetail(ne.key);
setStatus('已应用并写回条目 ' + ne.key, 'ok');
这里的“写回”是写回内存条目,不是已经落盘。正确操作顺序是编辑 → 应用 → 保存。Ctrl/Cmd+S 只是触发保存按钮,不会先自动应用编辑区中的文本。
删除使用短时确认状态:
第一次点击删除,按钮变为“确认删除?”,状态栏提示目标,并启动 3000ms 定时器。第二次点击执行删除;超时则恢复普通按钮。这避免了在业务页面调用原生 confirm,但当前确认状态没有绑定首次点击时的固定条目,确认期间应避免切换选中项。
布局拖拽:
初始化时为左右和上下分隔条分别绑定范围:
makeResizable($('sidebarResize'), $('sidebar'), 'x', 150, 420);
makeResizable($('detailResize'), $('detailPanel'), 'y', 120, 640);
侧栏宽度限制为 150~420px,详情区高度为 120~640px。详情位于下方,因此向上拖拽时通过减去纵向位移增加高度。当前实现使用鼠标事件,没有单独实现触摸拖拽和尺寸持久化。
3.5 文献库保存、导入与多格式导出
文献工具最需要分清的是“改变当前库”“改变保存目标”和“生成一份导出副本”。这三件事在代码中并不是同一个动作。
1. 条目序列化
entryToBibtex 按保存的字段顺序输出,整数形式字段不加花括号,其余字段用花括号包裹:
function entryToBibtex(entry) {
var lines = [];
var type = entry.type || 'misc';
lines.push('@' + type + '{' + (entry.key || '') + ',');
var names = (entry.order && entry.order.length ? entry.order : Object.keys(entry.fields || {}));
names.forEach(function (f, idx) {
var v = entry.fields[f];
if (v == null) return;
var out;
if (needsQuotes(v)) out = String(v).trim();
else out = '{' + String(v).replace(/\n\s+/g, ' ').trim() + '}';
lines.push(' ' + f + ' = ' + out + (idx === names.length - 1 ? '' : ','));
});
lines.push('}');
return lines.join('\n');
}
entriesToBibtex 再加上生成器注释,将所有条目连接起来。它只接收 entries,不接收原始库对象,所以不会恢复原来的 @string、@comment 和 @preamble。宏已展开、部分空白已规范化,原始引号选择也不会保留;这是一种结构化导出,不是源码级无损保存。
2. 保存到当前活动文件
保存按钮把整个 state.entries 序列化,再发给 lib:save。以下为主进程处理器原文:
ipcMain.handle('lib:save', function (event, text) {
var target = currentFile || canonicalLib();
try {
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, String(text == null ? '' : text), 'utf-8');
currentFile = target;
return { success: true, file: target };
} catch (e) {
return { success: false, error: '保存失败' };
}
});
成功后渲染层更新文件名并清除修改标记。当前实现直接同步写目标文件,没有临时文件替换、自动备份或撤销恢复机制;处理重要文献库时,应先另存副本。
3. 打开与导入的区别
打开外部库会替换内存条目,并将 currentFile 切换到外部文件;导入只读取文本,由渲染层调用 mergeEntries 追加到现有数组,不改变保存目标。
mergeEntries 返回 added 和 merged,其中 merged 表示引用键冲突次数,不是成功合并字段的条目数。冲突时当前实现只追加 -imported 后缀,再把条目加入数组。因此“导入合并”应理解为追加导入,而不是按标题或 DOI 智能整合。
4. 按当前视图与选中状态导出
导出按钮回调先确定范围,再生成文本。以下为该回调中的范围和格式分支:
var fmt = selectValue('selExportFmt');
var scope = filteredEntries();
var list = state.selectedKey ? scope.filter(function (e) { return e.key === state.selectedKey; }) : scope;
if (!list.length) { setStatus('没有可导出的条目', 'warn'); return; }
var text;
if (fmt === 'html') text = buildBibliographyHtml(list, state.style);
else if (fmt === 'txt') text = E.formatBibliography(list, state.style);
else text = E.entriesToBibtex(list);
| 状态 | 实际导出范围 |
|---|---|
| 没有选中条目 | 当前分组与搜索共同筛选出的条目 |
| 已选中且仍在当前视图 | 只导出该条目 |
| 已选中但被当前分组或搜索排除 | 结果为空,提示“没有可导出的条目” |
因此,“导出”不总是全库导出。当前 UI 没有独立的导出范围选择器,切换分组也不会自动清除选中状态,操作前需要检查详情标题。
HTML 导出生成带 UTF-8 声明和有序列表的完整文档,对引用文本中的 &、<、>、双引号进行转义。它使用独立的作者姓氏排序,不包含纯文本导出的年份次级排序;两种输出在同姓作者的排列上可能不同。
主进程 lib:export 只接收已生成的文本并写盘,扩展名分支只认 txt 和 html,其余回退 bib。文件过滤器是选择提示,不应当作对任意传入路径或文件内容的完整验证。
3.6 Catppuccin Mocha 深色主题
主题由 jabref.css 的 23 个颜色变量统一管理,基础背景、表面层级、文字、强调色各有分工。变量表如下:
: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;
--green: #a6e3a1;
--red: #f38ba8;
--yellow: #f9e2af;
--peach: #fab387;
--mauve: #cba6f7;
--teal: #94e2d5;
--pink: #f5c2e7;
--sky: #89dceb;
--lavender: #b4befe;
--rosewater: #f5e0dc;
--flamingo: #f2cdcd;
}
正文布局主要使用 Flex:
- 工具栏允许换行,避免按钮完全依赖固定窗口宽度。
- 中央列设置 min-width: 0 和 min-height: 0,让表格在可用空间内滚动。
- 表头使用 sticky,条目较多时仍保留列名。
- 列表状态点、校验卡片与状态栏共享错误、警告和成功颜色。
- 侧栏初始宽度 210px,详情区初始高度 260px,再由拖拽交互调整。
统一色彩之外,更重要的是统一语义。红色表示字段错误,黄色表示建议或警告,绿色用于成功反馈;不能因为某条文献显示黄色,就把它从“待完善”计数中强行加一,两处使用的是不同统计口径。
四、鸿蒙稳定性适配
本章按照“问题现象—根因分析—解决方案”组织,说明当前代码采用的适配方式。涉及异常的描述属于排查场景与实现边界,不表示本次已在设备上复现这些故障。
4.1 禁用默认菜单栏
问题现象: 如果宿主保留默认应用菜单,File、Edit、View 等入口可能与已经存在的文献工具栏形成重复操作区域。
根因分析: Electron 应用菜单与页面内工具栏是两套机制。JabRef 的打开、保存、新增、删除和关于入口已放在页面中,无需再依赖默认菜单组织业务。
解决方案: main.js 在初始化阶段移除应用菜单,而不是等待用户打开文献后再处理:
Menu.setApplicationMenu(null);
这解决的是菜单配置问题,不是所有原生交互的替代方案。打开、另存为、导入和导出仍会调用 Electron 的文件对话框。
4.2 自定义关于弹窗与非阻塞反馈
问题现象: 关于信息和操作结果需要清晰展示,但没有必要为每次提示建立原生消息框;页面自身也需要保持统一的深色主题。
根因分析: 关于内容是静态说明,适合由当前页面承载。保存失败、字段应用结果和删除确认则属于工作流反馈,使用状态栏或按钮状态即可表达。
解决方案: HTML 预先放置关于层,JavaScript 只切换 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');
}
实际遮罩样式使用 fixed 覆盖页面:
#aboutDialogLayer.about-layer {
position: fixed;
top: 0; left: 0; right: 0; bottom: 0;
background: rgba(17, 17, 27, 0.72);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
#aboutDialogLayer.hidden { display: none; }
因此不能把源码顶部“无 position:fixed”的旧注释当作实际限制。当前关于弹层已有打开与关闭按钮,但没有完整的焦点锁定、关闭后焦点恢复和 Escape 处理,键盘可访问性仍有完善空间。
关于文案还提到了“外部 PDF 定位”。在本文核对的业务代码中,没有对应按钮、附件路径解析或 PDF 打开处理;lib:openExternal 实际是打开文献库,并不是打开外部 PDF。截图中的这段文字不计入当前功能清单。
弹层展示的 Apache-2.0 说明也只是界面声明,不能替代正式发布时对许可证文件、第三方组件许可和源码来源的逐项核对。
4.3 鸿蒙窗口配置与适用边界
当前窗口配置采用系统边框、不透明窗口和可缩放尺寸,同时在应用初始化阶段禁用硬件加速:
app.disableHardwareAcceleration();
| 配置项 | 当前值或实现 | 作用与边界 |
|---|---|---|
| disableHardwareAcceleration | 调用应用 API | 调整渲染路径,不等于所有白屏均可解决 |
| frame | true | 保留系统窗口边框和标题栏 |
| transparent | false | 使用不透明窗口 |
| resizable | true | 允许系统窗口缩放 |
| 初始尺寸 | 工作区宽 92%、高 86% | 使用工作区尺寸,不是截图中的固定像素 |
| 创建异常处理 | try/catch + console.warn | 捕获同步 JavaScript 异常,不捕获原生进程崩溃 |
| 页面加载 | loadFile(‘index.html’) | 当前为本地页面;加载 Promise 未单独处理失败 |
这些参数组成当前项目的兼容性基线,但不能描述为“加上三项配置就永不崩溃”。如果实际出现白屏,应分别检查页面加载、脚本异常、原生库、签名、设备日志及运行时版本,而不是仅凭窗口参数判断原因。
4.4 计算与文件 IPC 分层
问题现象: 如果解析、搜索、格式化与文件操作全部混在跨进程链路中,界面刷新和文件故障容易相互牵连,也难以单独验证文献算法。
根因分析: 文献计算需要的是文本和条目对象,文件选择需要的是系统对话框,文件落盘需要的是路径与权限。这三类职责不必采用同一种调用方式。
解决方案: 本工程将纯计算放在渲染层,将文件动作保留为一问一答的 IPC。状态栏统一承接结果:
function setStatus(msg, kind) {
var el = $('statusText');
el.textContent = msg;
el.className = kind || '';
}
本项目没有采用“渲染层 fs 直写”的 IPC 旁路,也没有代码或本次测试证据可以支持“同一通道第二次调用必定挂起”的结论。调试时应记录具体通道、请求参数和 Promise 完成情况,再判断故障位置。
现有 nodeIntegration: true、contextIsolation: false 让渲染层可以直接 require 引擎与 Electron 模块,但也扩大了页面权限。页面 CSP 与 textContent 渲染是有益措施,仍不能把这种配置当作安全沙箱。后续若增强安全隔离,需要同时调整引擎加载方式,并通过 preload 暴露最小化文件接口,不能只修改两个布尔值。
此外,当前主进程文件读写与渲染层计算都包含同步操作。本文没有大库性能基准,不据此宣称十万条文献也能保持流畅。
五、构建与部署

图 1:article 类型分组显示 5 条文献,工具栏仍为全库 14 条、待完善 1 条、疑似重复 1 组。incomplete2021 的作者和年份为空,列表以红色状态点提示字段问题。

图 2:cv 关键词分组包含 he2016resnet、krizhevsky2012alexnet 和 zhang2019resnetdup,共 3 条。这是关键词筛选结果,不是三条重复文献。两张分组图底部均保留了此前选中的 lecun1991thesis 详情,说明详情选择与分组列表并未自动同步清空。

图 3:页面内关于弹层覆盖在条目列表上,包含开源说明、免责声明和关闭按钮。三张截图用于展示已有界面状态,不作为保存、导出或全部交互已通过设备测试的证明。
5.1 本地调试
在业务 app 目录打开终端。若当前环境已提供 Electron,可使用 npm start;临时桌面验证也可执行:
npx electron .
npx 可能下载当前环境尚未安装的 Electron,团队开发时应明确并固定经过验证的版本。桌面端可启动,不等于鸿蒙端文件对话框、窗口和权限行为完全相同。
由于引擎不依赖 Electron,可以先在同一目录做轻量检查:
node --check main.js
node --check bib-engine.js
node --check renderer.js
也可以自己写一个一次性脚本,在 Node.js 里解析内置样例、查看统计:
var fs = require('fs');
var E = require('./bib-engine');
var lib = E.parseBibtex(fs.readFileSync('samples/default-library.bib', 'utf-8'));
console.log(E.libraryStats(lib.entries));
console.log(E.buildGroups(lib.entries));
console.log(E.findDuplicates(lib.entries).map(function (g) {
return g.map(function (entry) { return entry.key; });
}));
本文整理时执行了三个业务 JavaScript 文件的语法检查,并在 Node.js 下读取样例运行上述相关引擎函数。结果为:
| 检查项 | 实际结果 |
|---|---|
| JavaScript 语法 | main.js、bib-engine.js、renderer.js 均通过 |
| 样例条目总数 | 14 |
| 样例类型数 | 9 |
| article / book 数量 | 5 / 2 |
| cv 关键词分组 | 3 |
| 待完善条目数 | 1 |
| 疑似重复组数 | 1 |
| 重复候选键 | he2016resnet、zhang2019resnetdup |
| 有摘要 / 有 URL 或 DOI 的条目数 | 3 / 2 |
这些结果与图片中的关键数量一致,只验证当前样例和纯计算路径,不覆盖 UI 事件、系统文件对话框、任意 BibTeX 文件或真机表现。
5.2 部署到鸿蒙壳工程
本工程的业务代码直接维护在 web_engine 的资源目录中。修改后应确认以下文件作为整体参与打包:
- package.json 和 main.js:业务入口。
- index.html、renderer.js 和 styles/jabref.css:页面与交互。
- bib-engine.js:运行时直接加载的文献引擎。
- samples/default-library.bib:首启兜底与“载入示例”的数据来源。
如果团队另有开发目录,应完整同步这组业务资源,核对相对路径,避免只更新 renderer.js 却遗漏引擎或样例。业务同步不应覆盖签名材料、原生库或无关壳配置。
在 ohos_hap 目录安装工程依赖:
ohpm install
随后用 DevEco Studio 打开 ohos_hap,等待 Sync 完成,确认 electron 对 web_engine 的本地依赖被正确解析,再检查设备连接、SDK、构建产品和签名配置。
正式发布前,需要将模板 bundleName、应用名称、入口 Ability 名称资源和图标替换为实际发布信息,并让签名 Profile 与最终 bundleName 一致。签名应通过本机有效材料配置,不应照搬其他开发者的绝对路径、密码或证书。
5.3 构建 HAP 包
工程实际定义的是 default 产品与 electron 模块的 default target。优先在 DevEco Studio 中选择对应产品和模块,通过 Build Hap(s) 构建。
如果环境已经提供可调用的 hvigorw,可在 ohos_hap 目录使用与上述配置对应的命令:
hvigorw assembleHap --mode module -p product=default -p module=electron@default -p buildMode=debug
如果项目目录和环境中没有可用的 hvigorw,不要直接假定这一命令可以执行;应使用 DevEco Studio 的构建入口或该安装环境提供的 Hvigor 调用方式。
产物通常在 electron/build/default/outputs/default 下检查,具体文件名和签名状态以构建日志为准。使用 Run 安装到目标设备后,建议至少验证以下路径:
- 首次启动能加载样例;保存后重启能读取默认用户库。
- 打开外部库、追加导入、保存与另存为的目标文件符合预期。
- article 类型、cv 关键词和带字段前缀的搜索结果正确。
- BibTeX 编辑遵循“应用 → 保存”,保存后重新打开检查字段。
- bib、txt、html 三种导出文件实际存在,编码与导出范围正确。
- 删除确认、关于弹层、窗口缩放和分隔条拖拽可操作。
- 连续执行多次文件操作,核对取消、失败及成功反馈。
上述为设备验收建议;本次文章整理没有执行 HAP 构建、安装或这组真机验收。
六、常见问题与解决方案
Q1:窗口标题已经是 JabRef,为什么应用名称仍显示 Electron?
问题现象: 页面品牌和窗口标题使用 JabRef,但应用级名称仍可能沿用壳工程默认值。
根因分析: BrowserWindow.title、HTML title、AppScope 应用 label 和入口 Ability label 属于不同配置。当前 AppScope/app.json5 引用 app_name,其 base 资源值仍为 Electron;入口 Ability 还另行引用 EntryAbility_label。
解决: 发布配置时分别核对应用级资源、Ability 资源及对应的本地化覆盖,确保名称、图标和包名一致,再重新构建验证。本文没有修改这些工程资源。
教训: 修改页面文案不等于修改系统安装信息,名称应沿资源引用链检查。
Q2:保存之后,原来的宏声明、注释或排版为什么变了?
问题现象: 原文件中的 @string、@comment、@preamble 没有按原样保留,宏引用变成展开后的值,字段空白和包裹形式也发生变化。
根因分析: 解析结果虽然包含库级元数据,但 loadText 只把 lib.entries 放入页面状态;保存调用 entriesToBibtex,也只输出条目数组。序列化处理的是结构化数据,不是原始文本。
解决: 首次处理重要库时先另存副本;若业务要求无损编辑,应扩展库模型,保留宏、注释、前导指令及原始语法信息,再设计对应输出器。当前版本没有完成这项扩展。
教训: “能解析后再导出”与“源文件无损往返”是两个不同承诺。
Q3:month = jan 可以解析,为什么校验仍提示月份无法识别?
问题现象: 输入标准月份宏 jan,解析成功,但校验得到“无法识别的 month 值:january”。
根因分析: 解析器先把 jan 展开为 January;校验器转小写后只检查月份宏键 jan 至 dec 或一至两位数字,没有接受展开后的英文全称。本文用最小条目在 Node.js 下调用解析与校验函数,确认了这一结果。
解决: 若暂时使用当前版本,可在确认语义后将月份录为 1~12 的数字值;长期应统一解析与校验的月份表示,并补充范围校验。现有正则只检查数字位数,不能据此认为 00 或 99 是合法月份。
教训: 解析输出与校验输入必须采用同一套归一化约定,否则合法输入也会产生误报。
Q4:在 BibTeX 编辑区修改后按保存,为什么改动没有写进文件?
问题现象: textarea 中已改动标题或作者,点击保存或按 Ctrl/Cmd+S 后,重新打开仍是旧字段。
根因分析: 保存读取 state.entries,不读取编辑区。只有“应用”按钮才把编辑文本重新解析并更新内存;单纯输入也不会自动设置库的 dirty 标记。切换条目会重新填充编辑区,未应用的文本可能被覆盖。
解决: 先点击“应用”,确认详情和修改标记更新,再保存。一次编辑只放一条文献;当前处理器只取首个解析条目,多条输入应通过文件导入完成。
教训: 编辑草稿、已应用的内存条目、已落盘文件是三种状态,界面与操作说明都应区分。
Q5:点击“载入示例”会不会影响已有用户库?
问题现象: 载入示例后,当前页面变成样例条目,默认用户库文件也可能被替换。
根因分析: lib:loadSample 不是只读预览:它读取随包样例并写入 userData/JabRefLibrary.bib,再切换活动文件。渲染层也会替换内存条目、清除 dirty 状态;当前没有未保存变更确认。打开另一份库和关闭应用同样缺少完整的未保存保护。
解决: 使用示例前先备份默认用户库,并把当前重要库另存到明确的外部路径。“先保存到默认用户库再载入示例”并不能防止默认文件被覆盖。后续可将示例改为未命名内存库,或增加备份与覆盖确认。
教训: 初始化数据与用户数据应隔离;读取样例成功也不代表落盘成功,当前样例写入失败时仍可能返回 success: true 和 file: null。
Q6:表格里有文献,为什么导出提示“没有可导出的条目”?
问题现象: 切换到 article 或 cv 分组后列表非空,但导出仍提示无条目;底部详情可能显示不在当前列表中的旧文献。
根因分析: 分组与搜索变化只重绘表格,不清除 selectedKey。导出时先获取当前视图,再按旧 selectedKey 过滤;两者没有交集时便得到空数组。本文两张分组截图都保留了 lecun1991thesis 详情,正好展示了这种选择状态。
解决: 单条导出前重新点击当前列表中的目标条目。若要导出整个筛选结果,当前版本需要处于未选中状态;可先应用并保存,再重新打开库以重置选择,然后只做分组和搜索,不点击条目行。更直接的后续改进是增加“选中 / 当前视图 / 全库”范围选项。
教训: 列表筛选、详情选择和导出范围必须协同设计,不能仅凭表格看起来有数据判断导出目标。
Q7:已经做了重复检测和引用键改名,为什么还要人工检查?
问题现象: 同一作者同一年发表的不同论文可能被提示重复,重复导入后也可能出现相同后缀的引用键。
根因分析: 重复文献检测是启发式候选规则,而引用键处理是另一套逻辑。parseBibtex 对重复键追加 -N,却没有将生成的新键完整纳入后续冲突检查;编辑冲突只追加 _2;mergeEntries 冲突只追加 -imported。这些分支都不是统一的全局唯一键分配器。
解决: 删除候选前比对标题、作者、年份和原始来源;导入或改键后检查全库键唯一性及 crossref 引用。后续应统一键分配逻辑,循环检查候选键是否已存在,并明确引用关系如何同步更新。本文仅说明现状,没有修改引擎。
教训: “疑似同一篇文献”“相同引用键”“合并字段”是三个问题,不宜用一个去重标签概括。
七、总结
JabRef 鸿蒙 Electron 壳应用把文献管理拆成了三个清晰层次:纯 JavaScript 引擎处理文本与条目,渲染层组织分组和编辑体验,主进程承担文件与窗口能力。这个实现的价值,在于将常见文献工作流连接起来,并让核心算法可以离开 UI 单独验证。
| 关键特性 | 实现方式 | 需要保留的边界 |
|---|---|---|
| 文献解析 | 字符扫描、宏表、条目与字段模型 | 不是完整 BibTeX 解析器,保存不保证无损 |
| 检索与分组 | 多词 AND、字段限定、类型与关键词聚合 | 同步执行,没有大库性能结论 |
| 字段质量提示 | 按类型生成必填错误与建议警告 | 月份归一等规则仍需完善 |
| 疑似重复检测 | 标题、首位作者姓氏与年份 | 候选提示,不自动删除或合并 |
| 引用与导出 | 四种简化样式,bib/txt/html 文件 | 需核对格式规范及实际导出范围 |
| 本地持久化 | 活动文件 + 默认用户库 + 7 个 IPC | 无自动备份、原子保存和完整未保存保护 |
| 鸿蒙交互 | 页面工具栏、关于弹层、窗口配置 | 设备兼容性仍需逐项验收 |
回顾实现,三个经验最值得保留:
- 先建立独立的数据引擎,再连接页面。 解析、检索、校验和引用共享条目模型,样例统计可以直接在 Node.js 下核对,降低了定位问题时对设备环境的依赖。
- 明确每一次操作改变的是哪一层状态。 编辑文本、内存库、活动文件、默认用户库和导出副本有不同生命周期;把“应用”“保存”“导入”“载入示例”区分清楚,比增加更多按钮更重要。
- 让实现、截图和发布说明保持一致。 14 条样例、5 条 article、3 条 cv 分组是可核对的结果;PDF 文案、完整标准兼容和真机稳定性则不能仅凭界面或注释作出承诺。
沿着这条结构继续完善时,可以优先补齐库级元数据保留、统一引用键分配、未保存变更保护和明确的导出范围,再评估异步大库处理与更完整的引用样式支持。这样,后续能力扩展仍能沿用同一套分层,而不必把文件、解析和界面重新耦合在一起。
更多推荐



所有评论(0)