夜雨聆风学习资料网

ARTICLE · 1380443

第 06 篇(谱书·上):先用 PDF 模板走死一条路,再用一份 2208 行调研笔记定方向

第 06 篇(谱书·上):先用 PDF 模板走死一条路,再用一份 2208 行调研笔记定方向
谱书是这个平台最容易被打动、也最难做的一项功能:把族谱数据自动排成一本可以拿去印刷的书。

传统谱书的结构是:封面(书名、堂号、卷数、编者)、扉页、目录、谱文(谱序、姓氏源流、家规祖训、传记)、世系谱(吊线图 + 行传)、人名检索表、封底。中式线装书还有一条硬规矩——双页开本,奇偶页版心不同:一页留左边距、下一页留右边距,装订线在中间。

先看这条线的提交密度,就知道它有多难缠:

2025-07-07  add 谱文                 2025-07-14  add 谱书制作2025-07-16  update 谱书编辑           2025-08-01  update 生成PDF调整2025-10-11  add PDF加入水印           2025-10-16  update 谱书下载功能2025-10-22  add PDF生成头像、向山/背山照片2025-10-27  add pdf生成加入目录页      2025-10-29  update 目录页调整,年号日期调整

7 月立项,10 月还在调目录页。这三个月做出来的版本,后来被我整体重做了一遍。这一篇把两段讲完:v1 怎么走死,以及重做之前那件最值钱的事。

v1 的做法:一张 PDF 底图 + 表单字段填充

思路很自然:既然排版难,那我干脆不排版——让设计把版面做成 PDF 模板,在 Acrobat 里给每个位置埋好 AcroForm 表单域,后端只负责把数据填进对应的域。

好处来得很快:版面可控,设计师画成什么样就是什么样;中文字体、边框、版心这些最麻烦的东西一次性在设计稿里解决。工程侧只有一个类:PdfExportUtil),按 PdfTemplateProperties选模板、灌字段、输出成品。水印、下载、头像与墓地照片、目录页这些能力也都是这个版本做完的,到 2025 年 11 月已经能交付。

三堵墙

用了两个多月,我撞到三堵墙。

一、页数是事先不知道的。目录要写"某某支,第 37 页",可目录本身也占页,插进目录后正文页码又往后推。AcroForm 是"固定版面 + 填格子",天生不适合这种内容长度决定版面、版面又反过来决定内容的循环。而中式线装还要求前置页凑成偶数页(makeEvenNumber()),一补空白页,页码全变。

二、世系谱是变长的。一个人可能有一支后裔,也可能有六支;吊线图要按代际横向铺开,节点数完全不可预测。模板里预置的格子要么放不下,要么留大片空白。这条是压死 v1 的主因。

三、改一个字要重做一版模板。家族方常问的是"我们这个堂号的谱,标题能不能换个位置",而在 v1 里这不是配置项,是回到设计稿重画 PDF、重新埋域、重新映射。族谱偏偏是最讲究"我们家跟别人不一样"的场景:不同房支、不同体例、不同翻页方向。到后期我手上堆了十来份底模板。

三堵墙的共同点是一句自我诊断:PDF 模板路线把"排版"外包给了设计稿,而排版本身才是这个业务的核心难度。我越是加水印、照片、检索表,越是往这条路里沉没。

v1 留下的两样好东西

推倒重来不是全扔。有两样活到今天:

其一,静态资源与印刷预设。老谱扫描件(平台支持家族把老谱扫成 PDF 上传)、字体(resources/fonts/simsun.ttf)、A4 印刷尺寸预设(PlayWrightUtils.ViewportPreset.PRINT_A4_PORTRAIT)——它们与排版方式无关,v2 直接复用。

其二,页型这套分类语言。封面 / 扉页 / 目录 / 检索 / 前文 / 世系谱 / 后文 / 封底,这套 PageTypeEnum 是我在 v1 时期就抽出来的,v2 整个版面编排算法就是按这八类依次生成再统一算页码。在业务还没做对的时候,先把业务的"名词"定下来,是回报很高的一次抽象。

两个具体坑顺手记下来:iText7 必须带 font-asian(或直接嵌 ttf),否则中文变方块——我用 itext7-core 7.2.5 + font-asian,字体走 classpath 嵌入,避免"本地好使、线上乱码";页数与文字量我用 PDFBox 的 getTextPositions 从内容流解析字形数组来统计,这两个数(pdfPageCount / pdfTextCount)是要写进谱书申请记录的业务字段,不是技术指标。

2026 年 4 月重做:动手之前先把别人扒了一遍

写第一行代码之前,我花了不少时间做一件事:把市面上做得成熟的族谱产品,从接口层扒了一遍。不是抄,是搞清楚在这个业务里"排版"到底要暴露哪些可配置项,才能同时满足几十个各不相同的家族。工作区留着这份底稿:修谱功能/谱书编写功能开发.md,2208 行,标题就叫"族谱网接口列表分析"。

按功能分组,一个电子谱书产品至少要这几类接口:

/search/myBook                       族谱列表(volume 卷、pagesCount、individualCount、state)/api/genealogyTreeBranch/list/{id}   谱系分支列表(fatherId / individualId / sortValue)/api/zupu/subBook/list               电子谱书列表(slug / name / sortNum / pageCount)/api/config/queryBookConfigDetail    书本通用配置详细信息

调研翻成自己的表之后,得到三个结论。

结论一:可配置项比想象的多一个数量级。这是我调研完给自己设计的 ps_book_v2_config(谱书总配置)字段清单:

turn_direction   翻页方向:1 传统(从右往左)2 现代(从左往右)page_type        页码规则:1 单面 2 双面format_type      排版规则:1 单面 2 双面stroke_color     中柱及线框样式(描边颜色)middle_type      中柱样式(样式1 / 样式2)middle_width     中柱宽度:双面=页面中间中柱宽(默认70)                 单面=两个中柱宽 + 中缝宽(默认160,间隔20)title_font / _size                   主标题与堂号字体/字号(默认宋体/42)subtitle_font / _size / _weight      副标题字体/字号/加粗rollNum_font / _size                 卷号字体/字号offset_top / _buttom / _left         上/下/左右边距(102 / 56 / 91)suffix                               世系后缀(默认”世”)

"中柱"是中式谱表中间那根竖线,把一页分成左右两半,世系按代际从中柱往两侧排。它的宽度、样式、中缝间距在不同房支、不同体例里做法都不一样。这份清单告诉我一件事:谱书不是"一个模板 + 数据",而是"一组排版参数 + 数据"。v1 走死就是因为我把排版当模板问题,其实它是参数问题。suffix 这种细节最能说明问题——有的家族写"××世",有的写"××代",有的两边都写;不调研根本想不到,想不到就会在做完之后被一句"能不能改一下"打回来。

结论二:封面、扉页、目录、谱文、世系谱各自一张配置表。

ps_book                      谱书主体(书名、卷数、堂号、编者、封面)ps_book_v2_config            总配置(翻页方向、中柱、边距、字体)ps_book_cover_config         封面(6 种封面类型,每元素独立显隐 + 二维码开关)ps_book_flyleaf_config       扉页(主修/校对…多行 title-value + 显隐)ps_book_catalog_config/_item 目录配置与目录条目ps_book_puwen_config / ps_puwen_block  谱文(前文/后文)配置与内容块ps_book_genealogy_config(+_Biography/_Blank/_Ignore)  行传规则/空白页/排除人员

每个元素都配一对 xxx + xxx_show_flag:族谱名称/显示族谱名称、卷号/显示卷号、堂号/显示堂号、修谱人/显示修谱人。看着啰嗦,实际非常关键:家族用户的诉求是"我不想显示这个",而不是"我想改这个的位置"。显隐开关是性价比很高的可配置项,它把 80% 的定制需求变成勾选框。

结论三:一定要有"页面内容表"。

ps_genealogy_pages            一页一条:页型、物理页号、内容 JSONps_genealogy_pedigree_nodes   世系谱页面内的节点坐落(谁落在这页哪个位置)

这两张表是 v2 全部设计的承重墙,翻译过来是一句话:把"版面"本身当成数据存下来,而不是每次生成时临时算。版面一旦落库,v1 无解的问题全变成普通工程问题:页码可以先算完再回填目录,跨页子表可以接续,空白页可以显式插入,某人要排除就记在 _Ignore 里,重新生成只重算受影响的页。

中间还试过一条 SVG 的路

全面转向 HTML 之前,我先用 SVG 做封面。笔记 修谱功能/SVGToPNG.txt 里留着当时三行代码(SvgCoverConverter.convertToSvg → SvgPngConverter.convertToPng → 写回 cover_svg),依赖是 Apache XMLGraphics 的 batik-rasterizer / batik-codec 1.16;工作区 修谱功能/images/ 里那 6 张 bookCover1.png ~ bookCover6.png 就是这条路线的产物,正好对应封面配置表的 cover_type(1~6)。

结论是:SVG 能覆盖封面的静态装饰,覆盖不了内容有长度变化的场景。一段谱序写三十行还是三百行,SVG 里没有"自动回流"这个概念,你得自己算每行几个字、要不要换页。这条路只保住了封面。

方向定了:版面交给浏览器

调研做完方案自然浮出来:既然 CSS 已经解决了几百年的排版问题,为什么要自己实现一遍?用 Freemarker 把数据渲染成 HTML,让浏览器排版,截图成图片,图片合成 PDF。浏览器是免费的排版引擎,而且是全世界测试最充分的排版引擎。

下一篇(第 07 篇《谱书·下》)讲这条流水线怎么落地:三段式渲染、12 步版面编排、脏检查与异步生成,以及最难的世系图(吊线图)跨页算法——那部分我从第 05 篇的"数据树"接过来,整整做了五天。

 官网链接:https://rfc1iaug6m5k.meoo.fun

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

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

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

相关学习资料