EPubBuilder 源码解析:一款在线 EPUB 电子书编辑器的架构与实现指南

原创2026-10-15 15:58:301,402 阅读
文章标签:前端内容协同

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 是唯一的应用入口页面,页面加载顺序清晰地反映了依赖关系:

  1. 样式:bootstrap、font-awesome、common.css、main.css、umeditor.min.css;
  2. 基础库:jquery(jq1.9.js)、bootstrap.min.js、prefixfree、handlebars、underscore、backbone;
  3. 富文本编辑器:umeditor(config + min.js + 中文语言包);
  4. 项目代码:ui.js、util.js、i18n.js、config.js、jszip.min.js、FileSaver.js、IndexedDBStore.js;
  5. 最后由 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 的"约定"一节强调:电子书编辑器中的标题不能随便命名为"封面",名字为"封面"的标题只能出现一次。

从源码看,该约定贯穿导入与导出全流程,主要因为"封面"是一个具有特殊语义的保留名:

  1. 自动创建:新建书籍时左侧列表第一项自动命名为"封面"(TitleList.js 的 add() 方法);
  2. 不可编辑、不可删除:封面项的输入框只读、无复制/删除按钮(TitleList.js);
  3. 导出时特殊处理:在 EpubBuilder.js 中,章节标题 trim 后若等于"封面",则 isCoverPage: true——该章节会生成到 content.opf 的 spine 中,但 不会 出现在 toc.ncx 的 navMap 目录里(对应 toc.ncx 模板中的 {{#unless this.isCoverPage}} 判断);
  4. 导入时兜底:readEpub 解析目录时,如果 spine 的第一个章节在 toc 中找不到对应 navPoint,则默认命名为"封面"。

因此,若用户手动把任意章节改名为"封面",会导致封面判定逻辑失效或出现多个封面页,这就是该约定存在的原因。

九、导入与导出核心流程(EpubBuilder.js)

EpubBuilder.js 是整个项目的引擎,定义 EpubBuilder 构造器,其 init() 通过同步 $.ajax 加载第五节介绍的全部 EPUB 模板。结合 main.js(负责桥接 TitleView 与 ContentListView 的"桥接器",源码注释自述"作为 titleList 和 contentList 的桥接"),完整的编辑工作流如下:

9.1 导入流程

点击 #open 按钮 → importEpub(setData) → 弹出文件选择 Modal(本地文件 + 近期文件双栏布局):

  1. 用户选择 .epub 文件后,util.readArrayBuffer 用 FileReader 读取 ArrayBuffer;
  2. 用 JSZip(arrayBuffer) 解压,并同步把文件 Blob 存入 IndexedDB(近期文件功能);
  3. 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:

  1. main.js 的 getData() 收集左侧标题(tocArray)与各 umeditor 实例正文(contentArray),再合并 dublinCore.getDublinCore() 的表单数据;
  2. 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 模板目录是最值得精读的起点。

登录后查看全文
EPubBuilder