1. 先聊聊“rea”这个名字是怎么来的这年头起项目名是个玄学。我见过有人用宠物名字命名核心服务的也有人拿常用字典随机翻页挑一个顺眼的。这个代号“rea”来源其实特别朴素——它是“read”和“annotate”两个词各取前几个字母拼起来的正好三个字符读起来也顺口。早期原型阶段当时桌面文件夹就叫“rea-demo”叫着叫着就懒得改了于是一个本来只打算存在两周的原型代号硬生生变成了正式项目名。很多项目都是这样名字并不重要重要的是它承担的职责。简单说这个项目解决的是这样一个痛点日常阅读 PDF、EPUB、网页长文时我习惯随手划线、写批注、摘录片段但这些动作分散在不同工具里有的存在某个阅读器的数据库里有的只能导出成“带批注的副本”还有的干脆只存在于截图里。等到真正要写总结、做知识管理、或者回头找某一段原文时根本无从下手。所以“rea”想做的就是一个专注本地优先、支持多种文档格式、带全文检索和轻量离线同步的批注阅读工具。这个项目不是给所有人用的它更适合三拨人一是像我这样每天要读大量技术文档、论文、行业报告并且强烈依赖“划线摘录-回顾整理”这条工作流的知识工作者二是对数据隐私有执念不想把全部阅读记录和批注都交给云端的人三是本身就喜欢折腾工具、愿意自己动手改代码的开发者。如果你只是偶尔读读小说那手机自带阅读器完全够用没必要看这篇文章。2. 技术选型的底层逻辑为什么不是原生也不是纯 Web2.1 三个方案摆在一起比过再选项目立项前我花了差不多一周时间把主流的技术路线全部过了一遍大概有三个候选方向方案优点缺点适合场景纯原生双端开发性能最优系统和手势深度集成两套代码库维护成本翻倍团队有充足人力用户量大跨平台框架React Native / Flutter单代码库UI 一致性好热更新方便部分底层能力仍需桥接原生独立开发者、小团队Web 应用 PWA开发最快迭代灵活离线能力弱原生阅读体验受限内网工具、快速验证原型最终选了跨平台框架主要原因有两个。第一这个工具的核心交互是“选中文字→划线→写批注”这一套手势逻辑如果在原生端要写两遍光是文本选取的差异处理就够喝一壶的。跨平台框架至少保证 UI 层和交互层的代码完全一致出问题只修一遍。第二我的开发节奏是典型的小步快跑可能某一个周末想到一个新交互下一周就要出包试效果跨平台的迭代速度最匹配这种节奏。2.2 本地优先为什么数据必须待在本地在设计数据存储时我做过一次简单的需求分析用户最频繁的操作场景是什么是在地铁上打开一篇长文做标注、是坐在电脑前对照批注写总结、还是多设备之间实时切换阅读进度对大多数知识工作者来说后面这个场景发生的频率其实很低撑死算个锦上添花。反而“随手记的批注必须立刻落盘、绝不能丢失”才是刚需。所以“rea”采用了典型的本地优先架构所有文档解析、标注数据、摘录片段都先写入本地数据库云同步只是一个可选的增值模块而不是核心依赖。这么做有一个副产品——应用在弱网甚至无网环境下依然能完整工作打开文档、翻页、标注、检索全链路都不需要网络参与。我用生活里的例子来类比本地方案就像学生时代把笔记写在纸质笔记本上永远不必担心“云端服务器出故障导致笔记丢失”这种事情而云同步方案则像是把笔记写在共享文档里随时随地能打开但一旦服务方出问题笔记也像被别人攥在手里一样不由自己掌控。两者之间的取舍很清楚而阅读这种隐私性偏强的数据我更倾向放在自己手里。2.3 为什么把核心解析层单独抽出来这个决定是在开发到第三周时逼出来的。最初我的想法很简单PDF 渲染用内置 WebView 加载 PDF.jsEPUB 解析直接用现成库浏览器阅读用扩展脚本搞定。结果第一版原型能跑通后我发现这三个入口分别依赖三套不同的解析方案但最终都需要把“用户选中了哪段文字、标注是什么颜色、批注内容是什么”这套数据统一起来。如果每个入口各写一套数据模型最后维护起来就是三套平行的逻辑改一个标注的存储格式要动三处代码。后来我干脆做了重构把文档解析、文本抽取、批注锚点计算全部抽到一个独立的解析核心层对外只提供统一的 API 接口。不管输入的是 PDF 里的一段文字还是 EPUB 里的一个章节解析层都输出一份结构化的节点数据标注层再基于这些节点做锚定。这样一来后续无论增加什么文档格式只需新写一个格式适配器接入解析层上层的标注、检索、导出逻辑一行都不用改。3. 核心设计的“牛鼻子”批注锚点与数据模型3.1 一个批注到底应该存什么如果只是做一个阅读器那文档本身是主角但在“rea”里文档只是背景批注才是核心资产。所以第一个要厘清的问题就是一条批注的数据结构到底长什么样。我最初的版本比较简单就是记录“页码文字片段颜色批注内容”。但真用到复杂排版的双栏 PDF 时问题立刻暴露同一个物理行的文字视觉上分布在两栏里简单按顺序拼接的文本片段和实际文字顺序对不上后续做摘录导出时乱序严重。最终的数据模型是这样设计的每条批注由四个部分构成——锚点定位信息、可视化信息、用户内容、元数据。锚点定位信息包含页码、页面内矩形坐标、字符级偏移范围和锚点文本快照可视化信息包含颜色、划线样式、创建时间用户内容就是批注正文和标签元数据则记录设备 ID、修改时间戳、冲突解决状态。之所以坚持存“字符级偏移范围”而不是只存“页码文字”是因为文档后续可能重新排版页码会变但字符偏移在一定范围内是相对稳定的。3.2 文字选取的深层坑跨平台框架里做“选中一段文字然后加批注”看似简单实际上坑很深。在移动端系统级的文本选择器受限于原生组件不同平台的行为差异很大尤其是 PDF 这种按坐标渲染的内容文本选取要自己实现命中检测。我前后试了两种方案方案 A 是用系统原生文本选择控件在 WebView 里选中文字后通过桥接把选中范围传回逻辑层方案 B 是自己实现屏幕坐标到文档字符偏移的换算。方案 A 的优势是手势体验好毕竟是系统级的但它的致命缺点是 H5 里的文本选取结果和原生 PDF 渲染层的坐标体系经常对不上。方案 B 则需要自己做命中检测把当前页面的文本节点提前构造成一个“块级索引”每个块记录它所在的矩形区域和字符偏移用户手指点中屏幕某个位置时通过逆坐标变换找到最接近的文本块再根据点击位置计算到字符级。这块我大概调了一周核心思路就是把每个可见文本行拆成若干个“候选块”块内再做字符级插值。最终选型还是方案 B因为只有自己控制选取逻辑才能实现“长按选词→拖动调整选段→弹出批注菜单”这条完整链路。3.3 全文检索用 FTS5 而不是 LIKE 查询阅读类工具如果只能一页一页翻着找之前划过的重点那它的价值直接砍半。所以“rea”从第一版就要求支持全文检索而且检索范围必须同时覆盖文档原文和批注内容。最初我用的是 SQLite 的 LIKE 查询凑合数据量小的时候感觉不到问题一旦本地积累了上百份文档、几万条批注检索速度会从毫秒级恶化为秒级这在阅读场景里是完全不可接受的。后来把检索层迁移到 SQLite 自带的 FTS5 全文检索扩展情况立刻不一样了。FTS5 做两件事一是对文本做分词并建立倒排索引二是提供 BM25 排序算法。这里需要注意一点FTS5 默认的分词器是按空格和标点切分的对中文支持不好。我在实验中发现如果直接用默认分词器搜“跨平台”能匹配但搜“平台”匹配不到因为“跨平台”被当成了一整个 token。解决方式是为内容表单独建一个使用 trigram 分词器的虚拟表配合一个内容同步触发器在批注写入时自动把文本同步到虚拟表里。抽查下来几十万的文本量级下检索耗时可控制在几十毫秒内体验可以接受。4. 实战从零搭建“rea”的核心主流程4.1 初始化工程与依赖选型如果你也想照着这个思路自己搭一遍我直接给出一份可以用的配置参考。开发环境方面我用的是跨平台框架官方脚手架创建的空项目然后按需加依赖。核心依赖大概有这几类文档渲染用的 PDF 渲染库和 EPUB 解析库、状态管理用的轻量级方案、本地数据库用的 SQLite 封装库、全文检索用的 FTS5 扩展、文件读写用的系统文件访问库。你不需要一次性全部装完我建议按下面这个顺序逐步加# 创建项目 npx create-app rea --template default # 进入目录后安装核心依赖 npm install pdf-render-lib epub-parser-lib npm install sqlite-storage-lib npm install state-manager-lib这里有两个选择上的心得状态管理不要选太重型的方案阅读类工具的状态流很简单无非是“当前打开哪个文档→当前页是第几页→当前正在展示哪个批注”用轻量方案完全够用重型方案反而会带来不必要的概念负担。SQLite 封装库我选的是支持原生模块自动链接的版本因为 FTS5 扩展在某些平台默认不是开启状态选一个维护积极的库能省去自己编译扩展的麻烦。4.2 文档渲染管线的搭法打开文档到看到内容的完整链路可以分为四个阶段读取原始文件、解析文档结构、渲染可视页面、叠加批注图层。PDF 的解析和渲染我在工程里用的是 WebView 里加载 PDF.js 的方案。为什么不用原生渲染因为原生 PDF 渲染虽然能拿到页面位图但无法拿到文本选择事件而“rea”最重要的交互恰好就是文本选择。PDF.js 的优点是它能同时提供渲染位图和文本层文本层的每个字符都带坐标信息这正好是批注锚点计算需要的数据。EPUB 的解析就简单一些本质上它是 zip 压缩包里的 XHTML 文件集合解析库会帮你把目录结构、章节内容和内部样式解出来然后统一渲染成一个可滚动的网页视图。在这个视图里做文本选取比 PDF 还要顺畅因为它本来就是标准的 HTML 页面系统级的文本选择可以直接复用。4.3 批注交互的全流程实现思路批注交互是全项目最核心的路径长按唤醒选区→拖动调整范围→弹出操作条→点击“加批注”→填写内容→保存落库。我逐步拆一下每个环节的实现要点。长按唤醒选区这一步在 PDF 页面里是自己监听触摸事件按一定阈值判定为长按后调用逆坐标变换定位文本块在 EPUB 页面里则直接监听 HTML 的 selectionchange 事件。这里容易踩的坑是PDF 里选中文本后需要把选中范围暂存到全局状态里因为弹出菜单是一个悬浮层悬停时原页面的 selection 可能会被系统清空提前存起来才能保证后面取锚点的时候数据不丢。拖动调整范围的问题更隐蔽。用户在选中一段文字后发现手抖选多了需要拖动两端的把手微调。在原生系统里这通常由系统控件完成但跨平台框架没有直接暴露这种把手能力只能自己模拟选区两端额外画两个小圆点触摸圆点时进入“调整模式”移动时实时重算锚点。这里要特别处理好“选区边界回弹”的逻辑不能让用户把手拖出页面边界。弹出操作条的最佳位置不是选区的正中间因为手指往往挡在那里。我实测下来把操作条放在选区上方约 40 像素处且靠右对齐误触率最低。如果距页面顶部不足操作条高度就自动翻到选区下方。这个细节看似无关紧要实际体验差别很大。保存落库时除批注的常规字段外务必把“锚点文本快照”一并存下来。快照的作用有两个一是文档重新排版后可以通过快照重新定位二是在全文检索结果里展示命中片段时不需要再回到原文里去取文本。4.4 数据同步模块的保守做法同步模块是“rea”里唯一联网的功能我把它放到了最后做而且是刻意做成可插拔的。同步的思路很简单每次批注变更时本地记录一条变更日志格式为“实体 ID 操作类型 修改时间戳 字段增量”。同步时设备把自己的变更日志推上去同时拉取其他设备的变更日志按时间戳做合并。这里最核心的取舍是不处理复杂的合并冲突只做最简单的“后写覆盖先写”策略。因为批注这个场景的并发冲突率极低——同一个用户不太可能同时在两台设备上编辑同一条批注。为了对抗这种小概率事件去做复杂的 OT/CRDT 合并算法在整个项目里属于过度设计。我看过太多独立开发者的项目最后就是死在过度设计上。如果同步时真的遇到同一条批注的两个版本我在界面上会亮一个“内容冲突请选择保留哪个版本”的提示让用户做最终决定。到现在为止这个提示在真实使用中我只见过一次。5. 踩坑实录三个真正的“拦路虎”5.1 滚动性能与批注图层不同步第一版实现里批注图层和 PDF 页面是分开渲染的底层是 PDF 渲染结果显示在 WebView 里批注则是通过添加原生标记绘制在 WebView 上层的原生视图上。一开始相安无事但页面滚动时原生涂层的更新频率跟不上 WebView 的滚动帧率于是批注出现明显“漂移”——划线的位置和文字错开半个身位特别影响阅读感受。我最终的解决办法是把批注直接画进 PDF.js 的 Canvas 之上让它作为页面 DOM 的一部分跟随滚动。这样批注的坐标天然和文本层锚定滚动时浏览器负责重绘不再存在两个图层不同步的问题。付出的代价是批注的样式不再有原生那么圆润而且渲染需要等 PDF 页面自身渲染完成后才能开始。这个取舍我觉得非常值得毕竟阅读场景里“准”远比“花哨”重要。5.2 文档重排后批注定位失效有个经常遇的情况用户一个月前在某个 PDF 上画了一批批注今天重新打开同一个文件发现页码变了——可能是 PDF 编辑工具修改过文件也可能是打印时设置不同导致重排。纯靠“页码字符偏移”的锚点在重排后几乎必然失效。我的应对策略分了三级第一级是快照匹配取锚点文本快照在新文档中做字符串查找找到即重定位第二级是相似度匹配如果精确匹配不到就提取快照前几个字符和后几个字符做模糊查找取得分最高的位置第三级是人工定位前两级都失效时在批注列表里给一个“原文已变动”的标记用户手动重新指定位置。这个方案不是绝对可靠但能在大多数场景下保住批注不丢算是对现实世界妥协的合理设计。5.3 中英文混排的检索分词问题FTS5 的 trigram 分词器对中文友好但它有一个副作用它会把任何三个连续字符都当作文档项这意味着检索“跨平台开发”时命中的文档可能是“跨平台开发”也可能是“跨平台开发与设计”这类包含连续子串的任意文档。在中文场景里这问题还不大但中英混排时会出现一些莫名其妙的命中比如搜“React”会命中包含“reactive”的段落。实际使用中我的处理方式是把检索分为两级先用 trigram 分词做粗筛再用 BM25 打分要求命中项里至少要有一个完整单词等于查询词否则降权。这一轮过滤后检索结果的准确率明显提升。如果你也要做类似功能建议是在虚拟表里额外存一个“原始片段”字段利用它做精确匹配校验不要只用分词结果来判断。下面把遇到的高频问题和解决办法整理成一张速查表方便你直接对照问题现象排查方向解决办法批注漂移滚动后划线错位检查批注是否和渲染层同源批注作为 DOM 元素嵌入渲染层而非独立原生图层选中文字后菜单闪烁弹出菜单定位不稳定检查是否是选区内 selection 被清空选中后立即将选区文本快照存入全局状态大 PDF 滚动卡顿翻页时帧率下降检查是否是逐页常驻内存使用“当前页前后两页”三级缓存释放远端页面检索中文失效搜“平台”匹配不到“跨平台”检查是否使用的默认分词器改用 trigram 分词器并对结果做二次精确过滤同步后批注消失另一设备删除导致覆盖检查时间戳比较逻辑增加删除类型变更日志保留最近删除的 tombstone 记录批量导入后卡死上百个文档同时解析检查是否有队列限制解析任务放入线程池最大并发数设为 3UI 层只读完成态6. 再聊几句大实话工具到底要不要“全平台制霸”在这方面我吃过大亏。项目做到中期时曾有一段时间特别焦虑觉得不做 Windows 客户端就对不起“跨平台”三个字。后来冷静下来做了个需求场景测试发现自己实际的使用时间分布大概是通勤和外出时用平板端阅读和批注占六成晚上在家用桌面端做整理和写长文摘录占三成剩下的一成才是临时拿手机快速查一条旧批注。手机端的作用更多是“应急查阅”而不是主力创作场景。于是我把桌面端定位成“整理与导出中心”移动端定位成“阅读与捕获前哨”这正好对应它们各自的硬件优势。桌面端有完整的键盘和鼠标适合做批量标签管理、导出 Markdown、生成阅读报告移动端有触摸屏和便携优势适合随手划线、语音输入批注。如果一开始就想着要六个平台 UI 全部统一大概还在第一版的设计稿里出不来。所以如果你也在做自己的工具我最大的建议就是先想清楚核心用户一天里哪几个小时会用到你的产品然后集中火力把那几个场景打磨到极致。工具类产品最怕的不是功能少而是功能的优先级稀碎。还有一个小技巧值得分享批注数据的导出格式我很早就定成了纯 Markdown而不是私有格式或复杂 HTML。因为 Markdown 是“最小公分母”——任何笔记软件都能导入任何编辑器都能打开甚至可以直接复制粘贴到邮件或文档里而不出现格式错乱。这个决定让我在后来迁移到其他知识管理工具时几乎没有付出任何数据搬迁成本。数据能自由进出工具才真正为你服务而不是把你锁死在里面。实战中这几条经验比任何一个具体代码技巧都更值钱。工具是人的延伸但它也必须允许你随时离开。
1. 先聊聊“rea”这个名字是怎么来的这年头起项目名是个玄学。我见过有人用宠物名字命名核心服务的也有人拿常用字典随机翻页挑一个顺眼的。这个代号“rea”来源其实特别朴素——它是“read”和“annotate”两个词各取前几个字母拼起来的正好三个字符读起来也顺口。早期原型阶段当时桌面文件夹就叫“rea-demo”叫着叫着就懒得改了于是一个本来只打算存在两周的原型代号硬生生变成了正式项目名。很多项目都是这样名字并不重要重要的是它承担的职责。简单说这个项目解决的是这样一个痛点日常阅读 PDF、EPUB、网页长文时我习惯随手划线、写批注、摘录片段但这些动作分散在不同工具里有的存在某个阅读器的数据库里有的只能导出成“带批注的副本”还有的干脆只存在于截图里。等到真正要写总结、做知识管理、或者回头找某一段原文时根本无从下手。所以“rea”想做的就是一个专注本地优先、支持多种文档格式、带全文检索和轻量离线同步的批注阅读工具。这个项目不是给所有人用的它更适合三拨人一是像我这样每天要读大量技术文档、论文、行业报告并且强烈依赖“划线摘录-回顾整理”这条工作流的知识工作者二是对数据隐私有执念不想把全部阅读记录和批注都交给云端的人三是本身就喜欢折腾工具、愿意自己动手改代码的开发者。如果你只是偶尔读读小说那手机自带阅读器完全够用没必要看这篇文章。2. 技术选型的底层逻辑为什么不是原生也不是纯 Web2.1 三个方案摆在一起比过再选项目立项前我花了差不多一周时间把主流的技术路线全部过了一遍大概有三个候选方向方案优点缺点适合场景纯原生双端开发性能最优系统和手势深度集成两套代码库维护成本翻倍团队有充足人力用户量大跨平台框架React Native / Flutter单代码库UI 一致性好热更新方便部分底层能力仍需桥接原生独立开发者、小团队Web 应用 PWA开发最快迭代灵活离线能力弱原生阅读体验受限内网工具、快速验证原型最终选了跨平台框架主要原因有两个。第一这个工具的核心交互是“选中文字→划线→写批注”这一套手势逻辑如果在原生端要写两遍光是文本选取的差异处理就够喝一壶的。跨平台框架至少保证 UI 层和交互层的代码完全一致出问题只修一遍。第二我的开发节奏是典型的小步快跑可能某一个周末想到一个新交互下一周就要出包试效果跨平台的迭代速度最匹配这种节奏。2.2 本地优先为什么数据必须待在本地在设计数据存储时我做过一次简单的需求分析用户最频繁的操作场景是什么是在地铁上打开一篇长文做标注、是坐在电脑前对照批注写总结、还是多设备之间实时切换阅读进度对大多数知识工作者来说后面这个场景发生的频率其实很低撑死算个锦上添花。反而“随手记的批注必须立刻落盘、绝不能丢失”才是刚需。所以“rea”采用了典型的本地优先架构所有文档解析、标注数据、摘录片段都先写入本地数据库云同步只是一个可选的增值模块而不是核心依赖。这么做有一个副产品——应用在弱网甚至无网环境下依然能完整工作打开文档、翻页、标注、检索全链路都不需要网络参与。我用生活里的例子来类比本地方案就像学生时代把笔记写在纸质笔记本上永远不必担心“云端服务器出故障导致笔记丢失”这种事情而云同步方案则像是把笔记写在共享文档里随时随地能打开但一旦服务方出问题笔记也像被别人攥在手里一样不由自己掌控。两者之间的取舍很清楚而阅读这种隐私性偏强的数据我更倾向放在自己手里。2.3 为什么把核心解析层单独抽出来这个决定是在开发到第三周时逼出来的。最初我的想法很简单PDF 渲染用内置 WebView 加载 PDF.jsEPUB 解析直接用现成库浏览器阅读用扩展脚本搞定。结果第一版原型能跑通后我发现这三个入口分别依赖三套不同的解析方案但最终都需要把“用户选中了哪段文字、标注是什么颜色、批注内容是什么”这套数据统一起来。如果每个入口各写一套数据模型最后维护起来就是三套平行的逻辑改一个标注的存储格式要动三处代码。后来我干脆做了重构把文档解析、文本抽取、批注锚点计算全部抽到一个独立的解析核心层对外只提供统一的 API 接口。不管输入的是 PDF 里的一段文字还是 EPUB 里的一个章节解析层都输出一份结构化的节点数据标注层再基于这些节点做锚定。这样一来后续无论增加什么文档格式只需新写一个格式适配器接入解析层上层的标注、检索、导出逻辑一行都不用改。3. 核心设计的“牛鼻子”批注锚点与数据模型3.1 一个批注到底应该存什么如果只是做一个阅读器那文档本身是主角但在“rea”里文档只是背景批注才是核心资产。所以第一个要厘清的问题就是一条批注的数据结构到底长什么样。我最初的版本比较简单就是记录“页码文字片段颜色批注内容”。但真用到复杂排版的双栏 PDF 时问题立刻暴露同一个物理行的文字视觉上分布在两栏里简单按顺序拼接的文本片段和实际文字顺序对不上后续做摘录导出时乱序严重。最终的数据模型是这样设计的每条批注由四个部分构成——锚点定位信息、可视化信息、用户内容、元数据。锚点定位信息包含页码、页面内矩形坐标、字符级偏移范围和锚点文本快照可视化信息包含颜色、划线样式、创建时间用户内容就是批注正文和标签元数据则记录设备 ID、修改时间戳、冲突解决状态。之所以坚持存“字符级偏移范围”而不是只存“页码文字”是因为文档后续可能重新排版页码会变但字符偏移在一定范围内是相对稳定的。3.2 文字选取的深层坑跨平台框架里做“选中一段文字然后加批注”看似简单实际上坑很深。在移动端系统级的文本选择器受限于原生组件不同平台的行为差异很大尤其是 PDF 这种按坐标渲染的内容文本选取要自己实现命中检测。我前后试了两种方案方案 A 是用系统原生文本选择控件在 WebView 里选中文字后通过桥接把选中范围传回逻辑层方案 B 是自己实现屏幕坐标到文档字符偏移的换算。方案 A 的优势是手势体验好毕竟是系统级的但它的致命缺点是 H5 里的文本选取结果和原生 PDF 渲染层的坐标体系经常对不上。方案 B 则需要自己做命中检测把当前页面的文本节点提前构造成一个“块级索引”每个块记录它所在的矩形区域和字符偏移用户手指点中屏幕某个位置时通过逆坐标变换找到最接近的文本块再根据点击位置计算到字符级。这块我大概调了一周核心思路就是把每个可见文本行拆成若干个“候选块”块内再做字符级插值。最终选型还是方案 B因为只有自己控制选取逻辑才能实现“长按选词→拖动调整选段→弹出批注菜单”这条完整链路。3.3 全文检索用 FTS5 而不是 LIKE 查询阅读类工具如果只能一页一页翻着找之前划过的重点那它的价值直接砍半。所以“rea”从第一版就要求支持全文检索而且检索范围必须同时覆盖文档原文和批注内容。最初我用的是 SQLite 的 LIKE 查询凑合数据量小的时候感觉不到问题一旦本地积累了上百份文档、几万条批注检索速度会从毫秒级恶化为秒级这在阅读场景里是完全不可接受的。后来把检索层迁移到 SQLite 自带的 FTS5 全文检索扩展情况立刻不一样了。FTS5 做两件事一是对文本做分词并建立倒排索引二是提供 BM25 排序算法。这里需要注意一点FTS5 默认的分词器是按空格和标点切分的对中文支持不好。我在实验中发现如果直接用默认分词器搜“跨平台”能匹配但搜“平台”匹配不到因为“跨平台”被当成了一整个 token。解决方式是为内容表单独建一个使用 trigram 分词器的虚拟表配合一个内容同步触发器在批注写入时自动把文本同步到虚拟表里。抽查下来几十万的文本量级下检索耗时可控制在几十毫秒内体验可以接受。4. 实战从零搭建“rea”的核心主流程4.1 初始化工程与依赖选型如果你也想照着这个思路自己搭一遍我直接给出一份可以用的配置参考。开发环境方面我用的是跨平台框架官方脚手架创建的空项目然后按需加依赖。核心依赖大概有这几类文档渲染用的 PDF 渲染库和 EPUB 解析库、状态管理用的轻量级方案、本地数据库用的 SQLite 封装库、全文检索用的 FTS5 扩展、文件读写用的系统文件访问库。你不需要一次性全部装完我建议按下面这个顺序逐步加# 创建项目 npx create-app rea --template default # 进入目录后安装核心依赖 npm install pdf-render-lib epub-parser-lib npm install sqlite-storage-lib npm install state-manager-lib这里有两个选择上的心得状态管理不要选太重型的方案阅读类工具的状态流很简单无非是“当前打开哪个文档→当前页是第几页→当前正在展示哪个批注”用轻量方案完全够用重型方案反而会带来不必要的概念负担。SQLite 封装库我选的是支持原生模块自动链接的版本因为 FTS5 扩展在某些平台默认不是开启状态选一个维护积极的库能省去自己编译扩展的麻烦。4.2 文档渲染管线的搭法打开文档到看到内容的完整链路可以分为四个阶段读取原始文件、解析文档结构、渲染可视页面、叠加批注图层。PDF 的解析和渲染我在工程里用的是 WebView 里加载 PDF.js 的方案。为什么不用原生渲染因为原生 PDF 渲染虽然能拿到页面位图但无法拿到文本选择事件而“rea”最重要的交互恰好就是文本选择。PDF.js 的优点是它能同时提供渲染位图和文本层文本层的每个字符都带坐标信息这正好是批注锚点计算需要的数据。EPUB 的解析就简单一些本质上它是 zip 压缩包里的 XHTML 文件集合解析库会帮你把目录结构、章节内容和内部样式解出来然后统一渲染成一个可滚动的网页视图。在这个视图里做文本选取比 PDF 还要顺畅因为它本来就是标准的 HTML 页面系统级的文本选择可以直接复用。4.3 批注交互的全流程实现思路批注交互是全项目最核心的路径长按唤醒选区→拖动调整范围→弹出操作条→点击“加批注”→填写内容→保存落库。我逐步拆一下每个环节的实现要点。长按唤醒选区这一步在 PDF 页面里是自己监听触摸事件按一定阈值判定为长按后调用逆坐标变换定位文本块在 EPUB 页面里则直接监听 HTML 的 selectionchange 事件。这里容易踩的坑是PDF 里选中文本后需要把选中范围暂存到全局状态里因为弹出菜单是一个悬浮层悬停时原页面的 selection 可能会被系统清空提前存起来才能保证后面取锚点的时候数据不丢。拖动调整范围的问题更隐蔽。用户在选中一段文字后发现手抖选多了需要拖动两端的把手微调。在原生系统里这通常由系统控件完成但跨平台框架没有直接暴露这种把手能力只能自己模拟选区两端额外画两个小圆点触摸圆点时进入“调整模式”移动时实时重算锚点。这里要特别处理好“选区边界回弹”的逻辑不能让用户把手拖出页面边界。弹出操作条的最佳位置不是选区的正中间因为手指往往挡在那里。我实测下来把操作条放在选区上方约 40 像素处且靠右对齐误触率最低。如果距页面顶部不足操作条高度就自动翻到选区下方。这个细节看似无关紧要实际体验差别很大。保存落库时除批注的常规字段外务必把“锚点文本快照”一并存下来。快照的作用有两个一是文档重新排版后可以通过快照重新定位二是在全文检索结果里展示命中片段时不需要再回到原文里去取文本。4.4 数据同步模块的保守做法同步模块是“rea”里唯一联网的功能我把它放到了最后做而且是刻意做成可插拔的。同步的思路很简单每次批注变更时本地记录一条变更日志格式为“实体 ID 操作类型 修改时间戳 字段增量”。同步时设备把自己的变更日志推上去同时拉取其他设备的变更日志按时间戳做合并。这里最核心的取舍是不处理复杂的合并冲突只做最简单的“后写覆盖先写”策略。因为批注这个场景的并发冲突率极低——同一个用户不太可能同时在两台设备上编辑同一条批注。为了对抗这种小概率事件去做复杂的 OT/CRDT 合并算法在整个项目里属于过度设计。我看过太多独立开发者的项目最后就是死在过度设计上。如果同步时真的遇到同一条批注的两个版本我在界面上会亮一个“内容冲突请选择保留哪个版本”的提示让用户做最终决定。到现在为止这个提示在真实使用中我只见过一次。5. 踩坑实录三个真正的“拦路虎”5.1 滚动性能与批注图层不同步第一版实现里批注图层和 PDF 页面是分开渲染的底层是 PDF 渲染结果显示在 WebView 里批注则是通过添加原生标记绘制在 WebView 上层的原生视图上。一开始相安无事但页面滚动时原生涂层的更新频率跟不上 WebView 的滚动帧率于是批注出现明显“漂移”——划线的位置和文字错开半个身位特别影响阅读感受。我最终的解决办法是把批注直接画进 PDF.js 的 Canvas 之上让它作为页面 DOM 的一部分跟随滚动。这样批注的坐标天然和文本层锚定滚动时浏览器负责重绘不再存在两个图层不同步的问题。付出的代价是批注的样式不再有原生那么圆润而且渲染需要等 PDF 页面自身渲染完成后才能开始。这个取舍我觉得非常值得毕竟阅读场景里“准”远比“花哨”重要。5.2 文档重排后批注定位失效有个经常遇的情况用户一个月前在某个 PDF 上画了一批批注今天重新打开同一个文件发现页码变了——可能是 PDF 编辑工具修改过文件也可能是打印时设置不同导致重排。纯靠“页码字符偏移”的锚点在重排后几乎必然失效。我的应对策略分了三级第一级是快照匹配取锚点文本快照在新文档中做字符串查找找到即重定位第二级是相似度匹配如果精确匹配不到就提取快照前几个字符和后几个字符做模糊查找取得分最高的位置第三级是人工定位前两级都失效时在批注列表里给一个“原文已变动”的标记用户手动重新指定位置。这个方案不是绝对可靠但能在大多数场景下保住批注不丢算是对现实世界妥协的合理设计。5.3 中英文混排的检索分词问题FTS5 的 trigram 分词器对中文友好但它有一个副作用它会把任何三个连续字符都当作文档项这意味着检索“跨平台开发”时命中的文档可能是“跨平台开发”也可能是“跨平台开发与设计”这类包含连续子串的任意文档。在中文场景里这问题还不大但中英混排时会出现一些莫名其妙的命中比如搜“React”会命中包含“reactive”的段落。实际使用中我的处理方式是把检索分为两级先用 trigram 分词做粗筛再用 BM25 打分要求命中项里至少要有一个完整单词等于查询词否则降权。这一轮过滤后检索结果的准确率明显提升。如果你也要做类似功能建议是在虚拟表里额外存一个“原始片段”字段利用它做精确匹配校验不要只用分词结果来判断。下面把遇到的高频问题和解决办法整理成一张速查表方便你直接对照问题现象排查方向解决办法批注漂移滚动后划线错位检查批注是否和渲染层同源批注作为 DOM 元素嵌入渲染层而非独立原生图层选中文字后菜单闪烁弹出菜单定位不稳定检查是否是选区内 selection 被清空选中后立即将选区文本快照存入全局状态大 PDF 滚动卡顿翻页时帧率下降检查是否是逐页常驻内存使用“当前页前后两页”三级缓存释放远端页面检索中文失效搜“平台”匹配不到“跨平台”检查是否使用的默认分词器改用 trigram 分词器并对结果做二次精确过滤同步后批注消失另一设备删除导致覆盖检查时间戳比较逻辑增加删除类型变更日志保留最近删除的 tombstone 记录批量导入后卡死上百个文档同时解析检查是否有队列限制解析任务放入线程池最大并发数设为 3UI 层只读完成态6. 再聊几句大实话工具到底要不要“全平台制霸”在这方面我吃过大亏。项目做到中期时曾有一段时间特别焦虑觉得不做 Windows 客户端就对不起“跨平台”三个字。后来冷静下来做了个需求场景测试发现自己实际的使用时间分布大概是通勤和外出时用平板端阅读和批注占六成晚上在家用桌面端做整理和写长文摘录占三成剩下的一成才是临时拿手机快速查一条旧批注。手机端的作用更多是“应急查阅”而不是主力创作场景。于是我把桌面端定位成“整理与导出中心”移动端定位成“阅读与捕获前哨”这正好对应它们各自的硬件优势。桌面端有完整的键盘和鼠标适合做批量标签管理、导出 Markdown、生成阅读报告移动端有触摸屏和便携优势适合随手划线、语音输入批注。如果一开始就想着要六个平台 UI 全部统一大概还在第一版的设计稿里出不来。所以如果你也在做自己的工具我最大的建议就是先想清楚核心用户一天里哪几个小时会用到你的产品然后集中火力把那几个场景打磨到极致。工具类产品最怕的不是功能少而是功能的优先级稀碎。还有一个小技巧值得分享批注数据的导出格式我很早就定成了纯 Markdown而不是私有格式或复杂 HTML。因为 Markdown 是“最小公分母”——任何笔记软件都能导入任何编辑器都能打开甚至可以直接复制粘贴到邮件或文档里而不出现格式错乱。这个决定让我在后来迁移到其他知识管理工具时几乎没有付出任何数据搬迁成本。数据能自由进出工具才真正为你服务而不是把你锁死在里面。实战中这几条经验比任何一个具体代码技巧都更值钱。工具是人的延伸但它也必须允许你随时离开。
