夜雨聆风学习资料网

ARTICLE · 1378001

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

《史记》安卓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 提供的不只是一个阅读工具,更是一份可复用的方法论:💡

一款好应用,未必需要庞大的团队和复杂的架构。想清楚为谁服务、守住一条设计原则、把一件事做到极致,就已经足够。 ✅

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料