文献管理工具的核心,不只是把论文标题显示成一张表,而是把 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_engineelectron 模块通过 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调整渲染路径,不等于所有白屏均可解决
frametrue保留系统窗口边框和标题栏
transparentfalse使用不透明窗口
resizabletrue允许系统窗口缩放
初始尺寸工作区宽 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 安装到目标设备后,建议至少验证以下路径:

  1. 首次启动能加载样例;保存后重启能读取默认用户库。
  2. 打开外部库、追加导入、保存与另存为的目标文件符合预期。
  3. article 类型、cv 关键词和带字段前缀的搜索结果正确。
  4. BibTeX 编辑遵循“应用 → 保存”,保存后重新打开检查字段。
  5. bib、txt、html 三种导出文件实际存在,编码与导出范围正确。
  6. 删除确认、关于弹层、窗口缩放和分隔条拖拽可操作。
  7. 连续执行多次文件操作,核对取消、失败及成功反馈。

上述为设备验收建议;本次文章整理没有执行 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无自动备份、原子保存和完整未保存保护
鸿蒙交互页面工具栏、关于弹层、窗口配置设备兼容性仍需逐项验收

回顾实现,三个经验最值得保留:

  1. 先建立独立的数据引擎,再连接页面。 解析、检索、校验和引用共享条目模型,样例统计可以直接在 Node.js 下核对,降低了定位问题时对设备环境的依赖。
  2. 明确每一次操作改变的是哪一层状态。 编辑文本、内存库、活动文件、默认用户库和导出副本有不同生命周期;把“应用”“保存”“导入”“载入示例”区分清楚,比增加更多按钮更重要。
  3. 让实现、截图和发布说明保持一致。 14 条样例、5 条 article、3 条 cv 分组是可核对的结果;PDF 文案、完整标准兼容和真机稳定性则不能仅凭界面或注释作出承诺。

沿着这条结构继续完善时,可以优先补齐库级元数据保留、统一引用键分配、未保存变更保护和明确的导出范围,再评估异步大库处理与更完整的引用样式支持。这样,后续能力扩展仍能沿用同一套分层,而不必把文件、解析和界面重新耦合在一起。

Logo

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

更多推荐