ARTICLE · 1378001
《史记》安卓APP:一款离线阅读器的技术与设计全解析


一款针对《史记》内容开发的安卓APP,《史记》全本一百三十篇、约 73 万字原文,还给 十二万余处人名地名做了彩色标注。📚
它不需要联网,不申请通讯录、定位、相册权限,双击本地网页也能打开。🔒
这是一款典型的「内容型工具」:把复杂的工程藏在背后,把极简的阅读留在眼前。 本文从技术栈、功能设计、UI 与页面设计三个维度,完整拆解这款史记阅读器的做法。🧩
🧱 一、技术栈:一个原生壳,加一套网页
🏗️ 整体架构:原生负责容器,网页负责一切
这款 APP 采用的是「WebView 壳 + 离线网页」的混合架构,思路非常清晰。✨
📦 原生层只有一个 Java 文件,二百八十余行代码,零第三方依赖,只干四件事:承载网页、映射本地资源、同步系统状态栏、处理返回键。
🖥️ 界面、交互、数据、主题,全部由 assets 目录下的
index.html、reader.css、reader.js和book-data.js提供。🔁 同一套网页文件,既能打包进 APP,也能用浏览器直接双击打开,一份代码两处复用。
这套架构最大的好处,是内容的更新与界面的迭代都发生在网页层,原生壳几乎不用改动。👏
🌐 虚拟域名拦截:让本地文件表现得像真实网站
APP 没有直接用 file:// 加载网页,而是虚拟了一个 https 域名 shiji.reader.local,再通过 shouldInterceptRequest 把每一个请求拦截下来,映射回 assets 里的真实文件。🧭
这个细节解决了三个关键问题。👇
💾
localStorage、hash 路由、跨域策略的表现,与在真实浏览器里完全一致,阅读进度和书签才能可靠保存。🧾 每一个资源都返回准确的 MIME 类型,JavaScript 和 CSS 才能被 WebView 正确执行与渲染。
🛡️ 设置了路径穿越防护与响应头,任何外链请求都会被拦截,全程不发起真实网络访问。
一旦主资源加载失败,还有一条 file:// 的降级路径自动兜底,避免出现白屏。🪄
🌉 JS 桥:只做一件极简的事
原生向网页注入了一个名为 ShijiNative 的对象,只暴露一个 setTheme 方法。🔧
当网页里切换纸白、护眼、墨夜三套主题时,网页调用这个方法,原生随即把状态栏、导航栏和容器底色同步成对应的颜色,并自动判断该用浅色图标还是深色图标。🎨
一个桥,一个方法,却让网页主题与系统界面浑然一体。🤝
📲 系统适配:把细节让给容器
针对 Android 15 之后「内容绘制到状态栏背后」的新特性,外层容器主动吃掉系统栏和刘海的 insets,WebView 只占据安全区,顶部标题和底部操作栏不会被引擎盖住。🧐
字体缩放被锁定为 100%,不受系统字号影响;系统的强制反色也被关闭,主题完全交给网页自己管理——这些处理,都是为了保证排版在每台手机上表现一致。📏
返回键的处理同样克制:优先回退网页内的篇目历史,没有历史时才用「双击退出」提示,避免误触退出。👆
🗃️ 数据管线:把标注文本编译成可离线读取的数据
真正的技术含量,藏在数据构建环节。⚙️
📝 源数据是 130 个带实体标记的文本文件,用一套符号系统标注人名、地名、官职、邦国、时间等类别。
🐍 一个 Python 构建脚本把这些标记解析成安全的 HTML,同时生成一份去掉标记的纯文本,专门供全文检索使用。
📦 产出物是一个约 10MB 的
book-data.js,以全局变量window.BOOK_DATA的形式直接赋值。
不使用 fetch 异步加载,是为了让网页在 file:// 协议下也能正常打开——这是「离线可用」这条设计原则在技术选型上的直接体现。✅
更讲究的是体积优化:脚本刻意不在每个词条上重复写入类别中文名,而是交给前端按 CSS class 推导。十几万处标注,靠推导省下的体积相当可观,手机首次解析也更快。⚡
🛠️ 构建与工程:自动同步,杜绝不一致
🧰 构建工具为 Gradle 9.6.0,搭配 Android Studio 内置的 JDK 25。
🎯 编译与目标 SDK 均为 37,最低支持到 Android 6.0(API 23)。
🔄 每次构建前,Gradle 任务自动从项目根目录同步最新的网页文件到 APP 资源目录。
也就是说,网页版改一个字,重新打包即可生效,APP 里的目录、正文、注释永远与网页版一致,不需要手工拷贝,也不会出现两个版本内容对不上的问题。👌
📖 二、功能设计:把一本古籍做成趁手的阅读器
🗂️ 五体目录,一眼看清全书结构
《史记》分为本纪十二篇、表十篇、书八篇、世家三十篇、列传七十篇。目录严格按这五体分组,并支持以下能力。👇
🔍 按体裁筛选,也可切换到「我的收藏」。
🔎 目录内二次搜索,篇名实时高亮匹配词。
📁 卷可折叠,折叠状态会自动保存。
🎯 当前篇目自动滚动到视野中央,重新打开时不迷路。
⚡ 全文检索,找一句话不超过一秒
检索功能覆盖了全部 130 篇的篇名与正文。🚀
⌨️ 输入即搜,160 毫秒防抖,避免频繁触发。
🧾 篇名匹配与正文匹配分开呈现,正文结果附带上下文摘要,并高亮关键词。
🌟 空关键词时给出「名篇速览」,直接列出项羽本纪、鸿门宴、货殖列传等热门篇目。
🧭 点击结果,直接跳转到对应篇目乃至对应段落。
🌈 二十二类实体标注,读古籍像读现代注释本
这是这款 APP 最有辨识度的功能。💡
全书 12.99 万处实体被分成二十二个类别,包括人名、地名、官职、身份、时间、氏族、邦国、名物、器物、天文历法、神话、生物、数量、典籍、礼仪、刑法、思想,以及军事、刑罚、政治、经济四类动词。📚
其中人名约 3.7 万处、邦国约 1.7 万处、身份约 1.37 万处、地名约 1.06 万处。📊
👆 点击任意彩色词条,底部图例会定位到对应类别,显示该类别在全篇的数量。
📈 每篇正文末尾附一张实体统计,读之前就能知道这一篇的人物与邦国密度。
⚪ 不想看标注时,一键切换到「素读」模式,所有颜色与装饰瞬间消失,只留干净正文。
🎛️ 阅读设置与记忆,越用越贴合个人习惯
🔠 字号、行距、页宽、主题、标注开关五项可调。
💾 收藏、已读、阅读进度、目录折叠状态全部保存在本机,下次打开自动续读。
📊 顶部一条极细的进度条,实时反映当前篇目的阅读位置。
⌨️ 键盘快捷键,桌面端的隐藏彩蛋
在电脑浏览器里使用时,一排快捷键让操作脱离鼠标。🖱️❌
/或Ctrl+K唤起搜索←→方向键切换篇目B键收藏,H键切换标注,M键打开目录Esc一键关闭所有浮层
移动端则把这一排操作,落成了底部固定的五按钮操作栏。📱
🎨 三、UI 与页面设计:用东方美学做一次「克制」的示范
🖼️ 启动图标:一枚可以握在手里的线装古籍
图标采用线装古籍封面的形制,几乎把中国传统书籍的视觉符号集齐了。🧵
📜 底色是带纤维纹理的宣纸,温润不刺眼。
📕 左侧是深色书脊与四枚订孔,还原线装书的装订结构。
🖋️ 中间是文武双线边框,稳住整体重心。
🔴 正中是朱红白文大印,刻小篆「史」字,是全图的视觉锚点。
🏷️ 右上是竖排「史記」题签,配浅色底和双线框,取法古籍的书签形制。
✍️ 左下是「寧靜致遠」墨书题跋,压一枚「製」字小朱印。
古意、辨识度、书卷气三者兼顾,放在桌面上极易辨认。👀
🏠 首页:数据、气质与入口,三件事一次说完
首页没有一张图片,全靠排版、线条和留白撑起气质。🪶
🔤 顶部一行英文眉题,用极小的字号铺陈「SHI JI · RECORDS OF THE GRAND HISTORIAN」,先立住气质。
🖌️ 大标题「史记全本」用书名号式的衬线字体,配一道朱砂短线,下面接司马迁那句「究天人之际,通古今之变,成一家之言」。
⭕ 右侧视觉核心是一组同心圆环,环心是巨大的数字「130」,压一枚「史記」朱印,旁注竖排小字「黄帝 — 汉武」,把时间跨度一眼说清。
🃏 下方五张体裁卡片,对应本纪、表、书、世家、列传,每张卡片以淡到几乎看不见的巨大汉字作底纹,悬停时卡片上浮、朱红边线浮现。
📌 页脚一句话点明立场:由项目内 130 篇标注文本构建,22 类实体高亮,全部内容可离线阅读。
🎨 视觉母题:朱红、宣纸、墨色,三色定调
整套界面围绕三个颜色展开。🌈
🔴 朱红
#a8352b作为强调色,贯穿印章、按钮、进度条、选中态和品牌标识。📜 宣纸米色作为背景与正文纸张,营造阅读的松弛感。
⚫ 墨色作为侧栏底色,与浅色正文形成鲜明对比,让导航区沉下去、阅读区浮上来。
字体也做了分工:界面用无衬线体保证清晰,正文用宋体/思源宋体一类的衬线体保留书卷味。✒️
🌙 三套主题:不只是换个背景色
纸白、护眼、墨夜三套主题,每一套都重新定义了整整一组 CSS 变量。🎛️
最见功力的是,连二十二类实体的颜色也逐套重新配色。夜间模式下,标注色统一换成低饱和的暖色系,长时间阅读不刺眼,也不会出现深色背景上的高亮色突兀跳脱。👁️
🔶 实体标注的视觉编码:颜色之外还有形状
为了照顾不同的阅读习惯,实体类别不止用颜色区分,还叠加了多重编码。🧩
📍 地名用双下划线,神话与成语用波浪下划线。
⏳ 时间与天文历法用斜体。
🏷️ 官职、名物、典籍、人名等用不同字重。
🎨 四类动词额外铺一层浅底色,与名词性实体区分开。
即便是对颜色不敏感的读者,也能靠下划线和字形分辨类别——这是无障碍设计里很见心思的一笔。♿
📄 阅读页与表格:古籍版式的现代转译
正文区是一张居中的「纸」,段落编号、引用、加粗各有样式。「太史公曰」这类史家评语用专门的围栏容器呈现,与正文拉开层次。📑
《史记》十篇表是按表格编排的,脚本把 Markdown 表格完整转成带表头的 HTML 表格,并用横向滚动容器承载,古籍的表格体例在手机上依然可读。📱
📲 移动端适配:让单手操作成为可能
👇 屏幕宽度小于 900 像素时,顶部工具栏整体移到底部,变成五枚大按钮,拇指可达。
📂 目录变为从左侧滑出的抽屉,点遮罩即可关闭。
🧷 所有浮层都避让刘海与底部手势区,设置了
safe-area-inset。🃏 体裁卡片从宽屏的五列,依次退化为两列、一列。
🌟 四、值得记取的四个设计要点
第一,职责分离带来复利。 🧩 原生只做原生该做的事,界面交给网页,一份代码同时服务网页版与 APP,维护成本被压到最低。
第二,离线优先是一种产品态度。 🔒 不联网、不索取多余权限、不追踪用户,换来的是极致的稳定与隐私友好,这在当下的应用环境里反而成了稀缺品质。
第三,内容工程化是内容型 APP 的护城河。 🏰 十二万处标注不是手工敲进 APP 的,而是一套「标注语言—构建脚本—数据文件」的流水线产物。内容可以持续沉淀、批量修正、自动校验。
第四,克制是最难的设计。 🪷 没有动效堆砌,没有多余按钮,没有信息轰炸。把复杂留在工程里,把简单交给读者——这款 APP 用 3.4MB 的体积证明,工具的价值在于让人专注内容,而不是迷恋功能。
🧭 结语
技术选型上,它是 WebView 壳与离线网页的经典组合;内容工程上,它把一部古籍拆解成可检索、可标注、可续读的结构化数据;设计上,它用朱红与宣纸完成了一次东方美学的现代表达。🎋
对内容创作者、独立开发者和传统文化爱好者来说,这款 APP 提供的不只是一个阅读工具,更是一份可复用的方法论:💡
一款好应用,未必需要庞大的团队和复杂的架构。想清楚为谁服务、守住一条设计原则、把一件事做到极致,就已经足够。 ✅















































































