EPubBuilder 源码解析:一款在线 EPUB 电子书编辑器的架构与实现指南
EPubBuilder 源码解析:一款在线 EPUB 电子书编辑器的架构与实现指南
EPubBuilder 是一个完全在浏览器端运行的 EPUB 电子书编辑器,用户无需安装任何桌面软件即可完成书籍的导入、章节编辑、元数据填写与 EPUB 格式导出。本文以仓库根目录 README.md 为主线,结合 src/ 目录下的真实源码与模板文件,系统讲解它的目录架构、依赖组成、EPUB 模板体系、核心构造器设计、语言配置、导入导出流程与本地运行方式,帮助读者从源码层面完整理解这个纯前端 EPUB 编辑器的实现原理。
一、项目定位与浏览器支持
EPubBuilder 的核心目标是在线完成 EPUB 书籍的编辑。根据 README.md 的说明,它是一款"在线的 epub 格式书籍编辑器",方便在线进行 epub 书籍的编辑,即从浏览器中选择本地 .epub 文件解压解析,在富文本编辑器中逐章节修改内容,再重新压缩导出为标准的 .epub 文件。
浏览器支持情况(源自 README.md 与 doc/README.MD):
| 浏览器 | 支持情况 |
|---|---|
| Chrome | ✅ 支持 |
| Firefox | ✅ 支持 |
| IE9+ | ✅ 支持(含 IE9 及以上版本) |
由于整个编辑与打包过程都依赖浏览器的本地能力(FileReader、Blob、IndexedDB、canvas 等),因此没有服务器端打包依赖,符合"在线编辑器"的定位。
二、整体架构与 src 目录结构
README.md 明确指出:src 目录是源代码目录,包含所有的 JS 和 CSS 文件。实际目录结构如下(节选自仓库 src/):
src/
├── index.html # 应用入口页面
├── css/ # common.css、main.css
├── images/ # 界面图标(block-on/off、icon-on/off)
├── epub/ # EPUB 打包所需模板文件
│ ├── mimetype
│ ├── META-INF/container.xml
│ └── OPS/
│ ├── css/main.css
│ ├── content.opf
│ ├── coverpage.html
│ ├── page.html
│ └── toc.ncx
├── js/
│ ├── Construct/ # 核心构造函数(6 个模块)
│ ├── tpl/tpl.js # 基础模板
│ ├── EpubBuilder.js # EPUB 导入/导出核心逻辑
│ ├── IndexedDBStore.js # 近期文件本地存储
│ ├── app.js / main.js # 入口与桥接逻辑
│ ├── config.js # 全局配置(语言)
│ ├── ui.js / util.js # 组件与工具方法
│ └── FileSaver.js / jszip.min.js
├── lang/i18n.js # 中英文国际化文案
└── third/ # 第三方库(bootstrap、umeditor、font-awesome 等)
其中 src/index.html 是唯一的应用入口页面,页面加载顺序清晰地反映了依赖关系:
- 样式:bootstrap、font-awesome、common.css、main.css、umeditor.min.css;
- 基础库:jquery(jq1.9.js)、bootstrap.min.js、prefixfree、handlebars、underscore、backbone;
- 富文本编辑器:umeditor(config + min.js + 中文语言包);
- 项目代码:ui.js、util.js、i18n.js、config.js、jszip.min.js、FileSaver.js、IndexedDBStore.js;
- 最后由 require1.08.js 以
data-main="js/app"加载 app.js 启动应用。
可以看到页面同时引入了 Backbone(数据模型)、Handlebars(模板渲染)与 require(AMD 模块管理),它们在后面的构造器与导出逻辑中各自承担职责。
三、Builder 依赖组件
README.md 用表格列出了 Builder 的四大依赖,结合 src/third/ 目录与 src/index.html 的引入方式,可整理为下表:
| 依赖 | 作用 | 仓库中的实际位置 |
|---|---|---|
| bootstrap | 界面布局、按钮、Modal 弹窗 | src/third/bootstrap-4.0.0-alpha |
| umeditor 编辑器 | 提供章节内容富文本编辑能力 | src/third/umeditor |
| require | AMD 模块加载器,组织模块化代码 | src/third/require1.08.js |
| jszip | 对 epub 压缩包进行解压与重新打包 | src/js/jszip.min.js |
- bootstrap 承担了全部界面组件职责:
#open、#download、#help按钮,.export-div导出弹窗,.modal文件选择弹窗等,均在 src/index.html 中声明; - umeditor(百度 UEditor 的迷你版)在 ContentList.js 中通过
UM.getEditor(divId)为每个章节创建一个独立富文本编辑实例; - require 负责按 AMD 规范加载
Construct/*模块与EpubBuilder; - jszip 是 EPUB 导入/导出的关键技术底座(见下文第六、七节)。
此外页面还通过 handlebars.js(模板编译)、underscore.js 与 backbone.js(数据模型与视图)协同工作。
四、EPUB 模板文件体系(src/epub)
README.md 指出:src/epub 文件夹包含了 EPUB 文件需要的模板文件,包括 mimetype、container.xml、content.opf、toc.ncx、coverpage.html 等。这些模板在导出时由 EpubBuilder.js 通过 $.ajax 同步加载(见 init() 方法),再用 Handlebars 编译后写入新的 zip 包。
4.1 mimetype(EPUB 文件类型标识)
EPUB 规范要求 mimetype 必须位于 zip 包首位且不压缩。仓库中的 mimetype 内容为:
application/epub+zip
对应导出代码(EpubBuilder.js):
zip.file("mimetype", this.mimetype, { compression: "STORE" });
STORE 即不压缩存储,这正是 EPUB 规范对 mimetype 的强制要求。
4.2 META-INF/container.xml(包定位文件)
container.xml 声明 EPUB 的真正包文件位置:
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile full-path="OPS/content.opf" media-type="application/oebps-package+xml"/>
</rootfiles>
</container>
它告诉阅读器"内容清单在 OPS/content.opf"。导入时,readEpub 也正是先读取这个文件,解析出 rootfile 的 full-path 属性,从而定位 content.opf。
4.3 OPS/content.opf(包清单 + 元数据)
content.opf 是 EPUB 的核心清单文件,包含元数据(metadata)、资源清单(manifest)、阅读顺序(spine)与导航(guide)。仓库中的模板大量使用 Handlebars 语法注入动态数据,例如:
<metadata ...>
<dc:title>{{options.title}}</dc:title>
<dc:language>zh</dc:language>
<dc:publisher ...>{{options.publisher}}</dc:publisher>
<dc:description ...>{{options.description}}</dc:description>
<dc:creator opf:role="aut" ...>{{options.author}}</dc:creator>
<dc:date ...>{{options.date}}</dc:date>
<dc:contributor opf:role="bkp" ...>{{options.contributor}}</dc:contributor>
<dc:identifier opf:scheme="UUID" id="uuid_id" ...>urn:uuid:{{options.ISBN}}</dc:identifier>
{{#if options.coverImage}}
<meta name="cover" content="cover"/>
{{/if}}
</metadata>
<manifest>
<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
<item id="css" href="css/main.css" media-type="text/css" />
<item id="cover" href="{{options.coverImage}}" media-type="{{options._coverImageMediaType}}"/>
{{#each tocItem}}
<item id="{{href}}" href="Text/{{href}}" media-type="application/xhtml+xml"/>
{{/each}}
</manifest>
<spine toc="ncx">
{{#each tocItem}}
<itemref idref="{{href}}" linear="yes" />
{{/each}}
</spine>
<guide></guide>
其中 dc: 前缀的 Dublin Core 元数据(标题、语言、出版者、作者、日期、贡献者、ISBN)与 DublinCore.js 构造器一一对应。导出时 EpubBuilder.js 还会在 </manifest> 前动态注入章节内图片的 <item> 条目,并在 </guide> 前注入目录页的 <reference type="toc"> 导航引用。
4.4 OPS/toc.ncx(导航目录)
toc.ncx 定义 EPUB 2.0 的导航结构,模板按 playOrder 顺序输出每个 navPoint,并对封面页做了特殊处理(封面不出现在目录中):
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
<head><meta charset="UTF-8"/></head>
<docTitle><text>{{title}}</text></docTitle>
<docAuthor><text>{{author}}</text></docAuthor>
<navMap>
{{#each tocItem}}
<navPoint class="{{href}}" id="{{href}}" playOrder="{{playOrder}}">
{{#unless this.isCoverPage}}
<navLabel><text>{{name}}</text></navLabel>
<content src="Text/{{href}}" />
{{#if this.children}}
<navPoint ...>
{{#each this.children}}
<navPoint ...><navLabel><text>{{name}}</text></navLabel>
<content src="Text/{{../href}}#{{anchor}}" /></navPoint>
{{/each}}
</navPoint>
{{/if}}
{{/unless}}
</navPoint>
{{/each}}
</navMap>
</ncx>
模板中的 children 是导出时从章节正文里解析出的 h2/h3 子标题(带 id 锚点),它们会生成为二级 navPoint,实现"章下分节"的目录结构。
4.5 OPS/page.html 与 coverpage.html(章节页模板)
page.html 是每个章节页的 XHTML 模板,正文通过 {{{body}}} 三花括号原样注入(不做 HTML 转义),{{href}} 用于注入章节文件名:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title></title></head>
<body id="{{href}}">
{{{body}}}
</body>
</html>
coverpage.html 为书籍封面页,仅在用户选择了封面图片时生成(见 EpubBuilder.js 与 content.opf 中 {{#if options.coverImage}} 的判断)。
五、核心构造器(src/js/Construct)
README.md 说明:src/js/Construct 文件夹包含了构造函数。该目录下实际有 6 个 AMD 模块:ContentList.js、DublinCore.js、Lang.js、LocalFileSystem.js、Preview.js、TitleList.js。
5.1 TitleList.js —— 左侧目录导航
TitleList.js 定义 TitleView(Backbone.View 子类),负责左侧章节列表的增删改复制与点击切换:
events绑定了.addli(新建)、.fa-trash(删除)、.fa-clone(复制)、li(点击)、input(重命名)五类交互;- 通过 Backbone Model/Collection 维护标题数据(
TitleModel默认title: ""); - 关键的封面约定在这里实现:当列表为空时,自动插入标题为"封面"的第一项(
add()方法中this.items.length === 0时强制{ title: "封面" });且封面项不可编辑、不可删除(绑定focus时this.blur(),移除a链接按钮)。
5.2 ContentList.js —— 右侧章节编辑器
ContentList.js 定义 ContentListView,与 TitleView 一一对应:create(html, index) 通过 UM.getEditor(divId) 为每个章节创建一个 umeditor 富文本实例;clone 读取现有编辑器内容后新建;remove 删除对应章节。源码注释明确指出"内容编辑器的区域并不适合 mvc",因此该视图直接操作 DOM。
5.3 DublinCore.js —— 元数据读写
DublinCore.js 实现 Toc 构造器:
getDublinCore():将导出弹窗(.export-div form)中所有表单字段序列化为对象,并对封面图片做特殊处理;setDublinCore(xmlElement):导入时把 content.opf 的<metadata>子节点(dc:title、dc:author等)回填到导出表单;setCover(base64):把封面图片以 base64 数据存入input[name=coverImage]。
5.4 Preview.js —— 编辑/预览切换
Preview.js 实现顶部 ON/OFF 切换开关:setEnabled() 让所有 umeditor 实例可编辑并显示左侧操作按钮;setDisabled() 则禁用编辑器、隐藏按钮并让标题输入框 readonly,进入只读预览态。状态文本通过 Lang.js 的 setState(flag) 同步为"编辑/预览"。
5.5 Lang.js —— 国际化
Lang.js 是全局语言模块,依赖 config.js 中的 EBConfig.lang:init() 遍历 nono.I18N[lang] 字典,将文案写入 id="lang-*" 的元素;getProperty(prop) 供其他模块获取文案。
5.6 LocalFileSystem.js
LocalFileSystem.js 是最简模块,仅提供 clear() 清空 localStorage,由 app.js 在启动时调用一次(源码中该调用当前处于注释与启用两种状态,可视为历史遗留的调试代码)。
六、基础模板(src/js/tpl)
README.md 提到 src/js/tpl 文件夹包含基础模板,即 tpl.js,定义了三段用于渲染左侧列表与内容区的 HTML 模板:
var template = {
"coverTpl" : '<li><input value="封面" readonly="true"></li>',
"leftTpl" : '<li>' +
'<a href="###" class="clone"><i class="fa fa-clone"></i></a>' +
'<a href="###" class="trash"><i class="fa fa-trash"></i></a>' +
'<input value="{{this}}"></li>',
"contentTpl" : '<li><div></div></li>'
};
coverTpl:只读的"封面"输入项;leftTpl:普通章节条目,含复制/删除按钮与可编辑标题输入框,{{this}}由 Handlebars 注入标题文本;contentTpl:每个章节对应的容器<div>,后续由UM.getEditor挂载富文本编辑器。
七、语言配置与切换方式
doc/README.MD 对语言配置做了补充说明:src/js/config.js 是项目语言的配置目录,目前提供英语和中文两种语言。仓库实际文件 config.js 内容为:
var EBConfig = {
"lang" : "en"
//lang : "zh-cn"
};
- 使用中文时改为
"lang" : "zh-cn"; - 使用英文时保持
"lang" : "en"。
对应语言包位于 lang/i18n.js,分别定义了 nono.I18N['zh-cn'] 与 nono.I18N['en'] 两套字典,覆盖打开、下载、新建、柏林核心(Dublin Core)、编辑/预览状态、近期文件、清除历史等全部界面文案。
此外,src/index.html 还实现了 URL 参数覆盖:页面加载时解析 ?lang=zh-cn 或 ?lang=en,将 window.__HERMES_LANG_PARAM__ 写入,随后在引入 config.js 之后覆盖 EBConfig.lang,实现无需改代码即可按 URL 切换语言,便于演示与测试。
八、"封面"命名约定(关键约定)
doc/README.MD 的"约定"一节强调:电子书编辑器中的标题不能随便命名为"封面",名字为"封面"的标题只能出现一次。
从源码看,该约定贯穿导入与导出全流程,主要因为"封面"是一个具有特殊语义的保留名:
- 自动创建:新建书籍时左侧列表第一项自动命名为"封面"(TitleList.js 的
add()方法); - 不可编辑、不可删除:封面项的输入框只读、无复制/删除按钮(TitleList.js);
- 导出时特殊处理:在 EpubBuilder.js 中,章节标题 trim 后若等于"封面",则
isCoverPage: true——该章节会生成到 content.opf 的 spine 中,但 不会 出现在 toc.ncx 的 navMap 目录里(对应 toc.ncx 模板中的{{#unless this.isCoverPage}}判断); - 导入时兜底:readEpub 解析目录时,如果 spine 的第一个章节在 toc 中找不到对应 navPoint,则默认命名为"封面"。
因此,若用户手动把任意章节改名为"封面",会导致封面判定逻辑失效或出现多个封面页,这就是该约定存在的原因。
九、导入与导出核心流程(EpubBuilder.js)
EpubBuilder.js 是整个项目的引擎,定义 EpubBuilder 构造器,其 init() 通过同步 $.ajax 加载第五节介绍的全部 EPUB 模板。结合 main.js(负责桥接 TitleView 与 ContentListView 的"桥接器",源码注释自述"作为 titleList 和 contentList 的桥接"),完整的编辑工作流如下:
9.1 导入流程
点击 #open 按钮 → importEpub(setData) → 弹出文件选择 Modal(本地文件 + 近期文件双栏布局):
- 用户选择
.epub文件后,util.readArrayBuffer用 FileReader 读取 ArrayBuffer; - 用
JSZip(arrayBuffer)解压,并同步把文件 Blob 存入 IndexedDB(近期文件功能); readEpub(unzip, setData)执行解析:- 读取
META-INF/container.xml,用DOMParser解析出rootfile的full-path(对当当网等非标准 EPUB 会先清理<files>与encrypt属性,源码注释明确写了该兼容处理); - 定位并解析
content.opf,取出<spine>中的itemref顺序(idref→href),逐个读取章节 HTML 文件; - 兼容性处理 toc.ncx 文件名不固定的情况(先尝试
章节名.ncx,失败则回退toc.ncx); - 章节内的图片通过
FileReader.readAsDataURL转成 base64 内联(SVG 中的<image>会同时改写xlink:href),并用$.Deferred串行化异步处理保证顺序; - 封面图片按
meta[name*=cover]→<item id*=cover名>的链路查找并 base64 化,通过dublinCore.setCover写入表单; - 最终
setData(navArray, contentArray)把目录与内容灌入左侧 TitleView 与右侧 ContentListView。
- 读取
9.2 导出流程
用户填写导出弹窗(src/index.html)中的 publisher、coverImage、description、language、author、title、date、contributor、ISBN、fileName 后点击 #build:
- main.js 的
getData()收集左侧标题(tocArray)与各 umeditor 实例正文(contentArray),再合并dublinCore.getDublinCore()的表单数据; exportToEpub(options)执行(EpubBuilder.js):- 用
JSZip创建OPS/、OPS/images/、OPS/Text/、META-INF/标准目录结构; - ISBN 为空时自动生成 UUID,避免
dc:identifier空白; - 对标题/作者/出版者等做 XML 特殊字符转义(
&、<、>),并对 Handlebars 分隔符{{/}}插入零宽字符防止破坏模板(源码注释说明了这一步的必要性); base64toImage(content, imagesFolder):把章节内 base64 图片经 canvas 压缩(MAX_W=800、MAX_H=800、QUALITY=0.8,PNG 保持 PNG、其余输出 JPEG)后写入 images 目录,并将<img>的 src 改写为相对路径../images/uuid.ext;- 从正文中解析带
id的<h2>/<h3>生成二级目录(children); - 对章节 HTML 做规范化:剥离
<html>/<head>/<body>、XML 声明与<link>,自闭合标签补全<br/>(避免苹果 Books 等解析器报 "Opening and ending tag mismatch" 错误),绝对 URL 章节链接改写为相对路径,删除空白 h2/h3; - 用 Handlebars 编译 page.html 生成
Text/chapterN.html(首个章节为coverpage.html); - 写入
container.xml、不压缩的mimetype,动态注入图片 manifest 条目后编译 content.opf,编译 toc.ncx 生成导航; - 最终
zip.generate({type:"blob"})生成 Blob,由 FileSaver.js 的saveAs触发浏览器下载fileName.epub。
- 用
9.3 IndexedDB 近期文件存储
IndexedDBStore.js 负责近期文件能力:数据库名为 EPubBuilderDB(版本 1),包含 epubs(以 name 为 keyPath 存储 EPUB Blob 与 size、lastOpened 元数据)与 settings(存储 recentList)两个对象仓库。saveEpub 每次写入都会把文件名插到列表头部并截断到最多 10 条(MAX_RECENT = 10),导入弹窗的"近期文件"栏由此而来;deleteEpub、clearAll 分别支持单删与清空历史。所有存储均在浏览器本地完成,无需后端。
十、test 测试目录
README.md 指出 test 目录是测试用例文件夹,包含一些小 demo。仓库中 test/ 实际提供:
| 文件 | 内容 |
|---|---|
| EpubBuilderTest.html | EpubBuilder 相关功能测试页 |
| XMLNameSpace.html | XML 命名空间处理测试 |
| jsziptest.html | JSZip 压缩/解压能力测试 |
| test.html / testHex.html | 基础功能与十六进制数据处理测试 |
| umeditor.html | umeditor 编辑器集成测试 |
| uploadDemo.html | 上传功能演示 |
这些页面可用于验证解压、XML 解析、命名空间等关键技术点,是理解本项目边界行为(尤其是非标准 EPUB 兼容处理)的补充素材。
十一、本地运行方式
仓库根目录提供了 server.js 与 package.json,可通过 Node.js 本地起服务访问:
npm install
npm start
npm start 实际执行 node server.js。从 server.js 源码看,服务端使用 Express 静态托管仓库根目录(app.use(express.static(__dirname))),并额外配置了七牛云上传的 /uptoken 接口与 EJS 视图渲染(对应 config/ 目录下的 config.js 中的 Port、Bucket_Name、ACCESS_KEY 等配置)。注意:server.js 中引用的 qiniu、ejs 依赖来自 package.json,其中声明的 express 版本为 ~3.4.7,与 app.use(express.static(...)) 的 Express 4.x 写法存在差异(src/index.html 的"帮助"弹窗中注明已做过"Express 4.x 兼容修复"),实际运行时请以当前仓库代码为准。
如果不需要七牛上传等后端能力,也可以直接用任意静态文件服务器托管仓库根目录后访问 src/index.html,前端核心编辑功能即可在浏览器中完整运行。
十二、小结
EPubBuilder 用一套"前端模板 + 构造器 + JSZip 打包"的轻量架构,实现了完整闭环的在线 EPUB 编辑:src/epub 提供符合规范的模板骨架,src/js/Construct 中的 TitleList/ContentList 完成章节组织与富文本编辑,DublinCore 处理元数据,EpubBuilder.js 以 readEpub/exportToEpub 两个核心方法打通解压解析与压缩导出,IndexedDBStore 提供近期文件体验。对于想了解纯浏览器端 EPUB 工具链(尤其是不标准 EPUB 的容错处理、图片 base64 化与压缩、Handlebars 驱动模板生成)的开发者,src/js/EpubBuilder.js 与 src/epub 模板目录是最值得精读的起点。