家谱世系图这个需求乍一看很简单无非就是画一棵树。但真落到移动端、落到 uniapp、还得加一句“纯 CSS 实现”的时候事情就变得有意思了。我上一个项目正好接到类似需求要在 App 里展示一个家族从始祖到当前几代人的完整世系关系。当时第一反应是找现成的树形组件翻了一圈要么体积太大要么样式绑得太死要么在微信小程序端兼容性堪忧。最后决定自己写而且整条链路全部用 CSS 来实现层级和连线——就是标题里说的“纯 CSS 家谱世系图”。这篇文章就把我踩过的坑、验证过的方案和最终的完整代码一次讲清楚。不管是自己项目要用还是纯粹想研究 CSS 到底能把树形结构画到什么程度这篇应该都能给你省不少时间。1. 先聊清楚这个需求到底要做什么1.1 家谱世系图和普通树形图的差异很多人会把“家谱世系图”和“组织架构图”混为一谈其实两者的展示逻辑不完全一样。组织架构图强调的是职位层级上下级之间往往是“一个上级对应多个下级”而且每个节点通常就一个人名或一个职位。家谱世系图则更复杂一些它既要体现血脉的纵向传承又要保证同一辈分的人在视觉上尽量平齐还要兼顾配偶信息、出生去世年份、子嗣数量、过继关系等。简单说它是一棵带“横向辈分对齐”和“纵向血缘延续”双重语义的树。移动端尤其麻烦。屏幕宽度只有那么点一个节点卡片上可能同时要放姓名、配偶、生卒年如果按照网页端那种“横向铺开”的组织架构图画法一旦某个老祖宗生了五六个儿子这一层就会直接超出屏幕。所以移动端家谱图在设计时就必须做取舍卡片做紧凑、线条做合理、文字做省略。而纯 CSS 方案的优势在于它和组件模板天然绑定数据一变 DOM 自动更新不需要像 canvas 一样手动维护绘制状态。1.2 为什么我放弃了 canvas / svg / 第三方组件在做技术选型的时候我认真考虑过三条路最终都放弃了。第一条路是 canvas。canvas 在大屏图表场景确实强势但在移动端家谱这种“强交互、强滚动、强文本展示”的需求里问题很突出文本换行要自己算节点点击命中要自己判滚动和缩放要自己监听触摸事件数据一旦变化还得重绘全图。相当于把一个展示需求硬生生做成了一个绘图引擎项目。第二条路是 svg。svg 在 H5 端表现非常好但 uniapp 要同时兼容小程序端时动态生成 svg 海量节点会导致性能和解析上的各种奇怪问题。而且 svg 的路径计算、文本换行、点击事件绑定在小程序端的支持参差不齐做起来远没有想象中顺滑。第三条路是引入第三方树形组件。其实大部分第三方树形图库都是基于 DOM 的核心思路也是 CSS flex 布局加绝对定位连线本质上和我手写差不多。但问题在于组件库的样式是黑的白的粗细的想调成“族谱纸质感”需要覆盖大量样式改造成本有时候比从零写还高。纯 CSS 方案的真正价值不是“不用 JS”而是用最少量的模板结构把布局和连线交给 CSS 自己推导。你只需要给一个递归组件传嵌套数据剩下的层级、对齐、线条全自动生成。1.3 uniapp 环境对纯 CSS 方案的影响uniapp 的渲染链路比较特殊H5 端走的是普通浏览器渲染小程序端走的是小程序原生渲染。这两个环境对 CSS 的支持有一些细微差别尤其是伪元素、CSS 变量、后代选择器、position: absolute的定位基准在部分旧版本小程序基础库上会有兼容性差异。我最终实现的方案没有依赖 CSS 变量也没有使用任何冷门选择器主要用的就是flex、position和伪元素这几个东西在微信小程序、支付宝小程序、H5 上都能稳定工作。另外移动端要格外注意 rpx 单位。rpx 在 uniapp 里是响应式单位屏幕宽度固定 750rpx不同设备上会自动缩放。画 1 像素线时直接用2rpx比较合适但如果追求极致的清晰可以考虑在特定设备上用px配合transform: scaleY(0.5)来模拟 0.5px 线后面我把这个技巧也写出来。2. 设计思路数据、布局与选型拆解2.1 先把数据源设计成“递归无害”的样子任何树形结构的实现第一步永远是数据结构。家谱数据的自然形态是嵌套的一个节点代表一个人节点上有配偶信息有孩子数组。我在项目里用的数据模型大概是这样的const familyData { id: g1, name: 某氏始祖, spouse: 配李太君, birth: 约1680, death: 约1750, children: [ { id: g2-1, name: 二世长子, spouse: 配王太君, birth: 约1705, death: 约1772, children: [ { id: g3-1, name: 三世长孙, spouse: 配张太君, children: [] }, { id: g3-2, name: 三世次孙, spouse: 配刘太君, children: [] } ] }, { id: g2-2, name: 二世次子, spouse: 配赵太君, children: [] } ] }这个数据结构有几个关键设计点。第一每个节点必须有唯一id否则递归渲染做v-for时根本无法正确复用和 diff。第二children必须始终是数组没有子嗣就置空数组这样可以避免渲染前到处做空值判断。第三配偶不是单独的节点而是当前节点的一个属性字段这样家谱图中“夫妻合体”的展示逻辑就落到了卡片内部而不是另起一个兄弟节点。如果你要做更复杂的族谱比如存在“一夫多妻”“妻妾并列”“过继关系”建议在这个模型上再加一个spouses数组但核心递归结构不要动。树形递归组件最忌讳的就是数据结构频繁变卦。2.2 布线的核心逻辑一根线怎么画出来家谱图看起来神秘其实每一根线的本质就三类横线、竖线、横竖交接的转角。我这一版方案的连线全部由 CSS 伪元素完成没有额外增加用于画线的 DOM 节点。具体思路可以拆成三段理解第一段兄弟节点之间的水平线。每个子节点元素自己贡献“半截横线”两个相邻节点各出一半拼接起来视觉上就是一条贯穿整个兄弟组的横线。这里用::before和::after分别控制左右两半不需要 JavaScript 计算它的宽度。第二段从横线向下到达节点卡片的那根短竖线。这根竖线直接定位在节点卡片的上方从卡片顶边向上延伸到横线位置。第三段父节点向下连接到子级横线的竖线。当父节点有孩子时在这张卡片的底边画一根向下的竖线长度为子级容器预留的间距正好落到子级横线上。三段线各管一段组合在一起就成了完整的“父节点 → 竖线 → 横线 → 竖线 → 子节点”通路。而且因为所有线都写在递归组件的样式里不管嵌套多少层都能自动正确生成。2.3 移动端适配与视觉规范画家谱视觉上的“古旧感”和“纸质感”是加分的。我在项目里定了一个比较克制的配色线条用旧纸色#b49c6c卡片底色用米黄#fffdf5边框用同色系但稍微压暗的浅棕文字用深褐色。实际效果类似宣纸上用淡墨勾线不抢内容辈分层级一眼就能读出来。卡片尺寸也要专门调。移动端单卡片我控制在宽度 220rpx 左右能放下两个字段主姓名加配偶下面是生卒年份小字。如果名字较长超过 6 个字就做单行省略。晚辈的卡片可以稍微小一点但最好不要小于 180rpx否则手指点击命中率太低。辈分之间的垂直间距我用了 60rpx这个高度刚好容纳一截竖线又不会让整棵树过于松散。最终整体是纵向滚动的同一辈分尽量水平对齐用户通过上下滑动查看代际传承。3. 手把手实现递归组件 纯CSS连线3.1 递归组件的骨架在 uniapp 中实现递归组件最稳妥的方式是给组件设置name然后在模板中引用自身。我用 Vue3 的defineOptions给 SFC 命名这样在小程序端和 H5 端都能正确递归。组件接收node和isRoot两个 props分别表示当前节点数据和是否根节点。template view classtree-li :class{ is-root: isRoot } view classnode-card :class{ has-children: hasChildren } clickhandleTap view classcard-main text classname{{ node.name }}/text text v-ifnode.spouse classspouse{{ node.spouse }}/text /view view classcard-sub v-ifnode.birth || node.death text{{ node.birth || ? }} - {{ node.death || ? }}/text /view /view view v-ifhasChildren classtree-children FavoriteNode v-forchild in node.children :keychild.id :nodechild :is-rootfalse / /view /view /template script setup import { computed } from vue defineOptions({ name: FavoriteNode }) const props defineProps({ node: { type: Object, required: true }, isRoot: { type: Boolean, default: false } }) const emit defineEmits([nodeTap]) const hasChildren computed(() ( props.node.children props.node.children.length 0 )) function handleTap() { emit(nodeTap, props.node) } /script注意这里有个细节我故意给每个子节点传:is-rootfalse而不是像有些人写的那样“不传就默认 false”因为在递归场景下显式传参会规避小程序端某些组件属性继承的怪异行为。另外如果递归层数很深nodeTap事件会逐层冒泡建议在父页面统一处理不要在每层都拦截。3.2 三条核心 CSS 线接下来是重头戏画线的三段式 CSS。我把完整样式贴出来再逐段解释。style scoped .tree-li { position: relative; display: flex; flex-direction: column; align-items: center; padding: 60rpx 20rpx 0 20rpx; } /* 兄弟组横线每个节点贡献左半和右半 */ .tree-li::before, .tree-li::after { content: ; position: absolute; top: 0; right: 50%; width: 50%; border-top: 2rpx solid #b49c6c; } .tree-li::after { right: auto; left: 50%; } /* 节点卡片上方竖线从横线垂下到卡片 */ .node-card::before { content: ; position: absolute; top: -60rpx; left: 50%; width: 2rpx; height: 60rpx; background: #b49c6c; } /* 父节点到子级横线的竖线 */ .node-card.has-children::after { content: ; position: absolute; top: 100%; left: 50%; width: 2rpx; height: 60rpx; background: #b49c6c; } .tree-children { display: flex; justify-content: center; align-items: flex-start; padding-top: 60rpx; } /* 根节点单独处理 */ .tree-li.is-root { padding-top: 30rpx; } .tree-li.is-root::before, .tree-li.is-root::after { display: none; } .tree-li.is-root .node-card::before { display: none; } .node-card { position: relative; display: flex; flex-direction: column; align-items: center; width: 220rpx; padding: 20rpx 12rpx 14rpx; background: #fffdf5; border: 2rpx solid #b49c6c; border-radius: 12rpx; box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.06); } .card-main { display: flex; flex-direction: column; align-items: center; } .name { font-size: 28rpx; color: #4a3622; font-weight: 600; } .spouse { margin-top: 4rpx; font-size: 22rpx; color: #8a6d4b; } .card-sub { margin-top: 8rpx; font-size: 20rpx; color: #b08d66; } .tree-li:only-child::before, .tree-li:only-child::after { display: none; } .tree-li:only-child .node-card::before { top: -60rpx; height: 60rpx; } /style第一段::before和::after这两个伪元素一个从节点左边缘画到中心一个从中心画到右边缘。因为每个节点都占满自己在 flex 容器里的宽度左右相邻节点的半截线在边界处自然衔接视觉上就是一条完整横线。而且最左侧节点的线不会超出左边缘最右侧节点的线也不会超出右边缘因为每段线都是节点自身宽度的一半。第二段.node-card::before它是一根绝对定位的竖线从卡片顶边向上延伸 60rpx。为什么是 60rpx因为.tree-li的padding-top是 60rpx也就是说卡片在纵向布局中其实是从父节点的第 60rpx 处才开始排的这 60rpx 的空间就是留给竖线的。竖线从卡片顶边向上画 60rpx正好到横线的位置。第三段.node-card.has-children::after当节点有孩子时卡片底边往下延伸 60rpx。这 60rpx 对应.tree-children的padding-top: 60rpx。子级横线在 children 容器的内容区顶部也就是父卡片底部往下 60rpx 的位置父节点竖线也正好画到这个位置两边严丝合缝。这个三段式结构最难的地方不是写代码而是理解“每个元素贡献的间距必须和其他元素的定位尺寸完全一致”。想调间距的时候记得padding-top、::before高度、::after高度、tree-children的padding-top这四个值必须同步修改。3.3 根节点、叶子节点、单子节点的边界处理家谱图里最尴尬的永远是边界情况。根节点没有兄弟也没有向上的线所以.is-root会把伪元素横线和上竖线全部隐藏只留卡片和向下延伸的竖线。叶子节点没有孩子所以不会渲染.tree-children也就自然不会多出向下的竖线。单子节点是我在测试时特别留意的情况。一个儿子继承香火在族谱里是很常见的。在默认样式下单子节点也会画出横线看起来就是一个“T 形”连接在父节点和唯一儿子之间。视觉上虽然不丑但有点多余。上面代码里的.tree-li:only-child就是为了处理这个情况隐藏横线只保留上下贯通的竖线。:only-child在 H5 和小程序端的基础库上基本都支持但如果你要兼容特别老的小程序环境也可以改为在数据层判断“是否只有一个孩子”然后追加一个 class。3.4 交互增强节点点击与样式反馈家谱图肯定不能只是静态展示。实际项目里用户会点击某个节点查看详情、编辑成员、查看其后代。我在组件里通过handleTap把当前节点对象抛出去父页面接收后打开半屏弹窗展示完整资料。// 在父页面使用组件 const familyData ref(treeData) function onNodeTap(node) { memberPopup.value.open(node) }为了让点击反馈更明显我加了一个按下态样式当手指按住卡片时卡片轻微缩小并加一层半透明底色。这个效果在移动端非常重要它能第一时间告诉用户“我按到了”。实现方式也很简单给node-card加hover-class或者直接用 CSS 的active伪类。uniapp 的 H5 端:active支持良好小程序端建议用hover-class更为稳定。.node-card { transition: transform 0.15s ease; } .node-card:active { transform: scale(0.96); background: #f6ecd8; }需要注意如果卡片上绑定了点击事件同时内部又有子节点一定要避免事件冒泡导致误触。在递归组件里点击卡片时并不希望它触发祖先节点的卡片点击但事件默认会冒泡。我建议在handleTap里调用stopPropagation或者在模板上使用.stop修饰符。uniapp 小程序端对click.stop是支持的直接用就好。4. 踩坑实录与排查技巧4.1 伪元素在部分小程序端不生效的问题这是我遇到的第一个大坑。写完组件后在 H5 端一切正常拿到微信开发者工具里一看部分线条不见了。排查了半天发现是小程序对页面根组件容器的overflow和某些position上下文处理不一致。比如如果整个树的外层容器设置了overflow-x: hidden在某些安卓 WebView 里绝对定位伪元素的绘制会被意外截断。解决办法是把最外层的滚动容器和内部的树形渲染容器分开。外层只负责滚动内层专门做布局。不要在内层容器上设置任何overflow给伪元素一个干净的绘制环境。如果确实需要横向裁切尽量用padding挤出安全区而不是用overflow硬砍。另外一部分老版本小程序基础库对伪元素content: 里的空字符串要求很严格写成content: none或者漏掉引号都会导致伪元素不渲染。写 uniapp 跨端样式时建议统一使用content: 这种写法别图省事。4.2 节点文字过长挤爆布局家谱里最不缺的就是“长名字”。我自己测试时输入了一个八个字的满名整个卡片瞬间被撑宽兄弟节点都被排挤错位。后来我做了三件事第一卡片固定宽度不随内容无限增长第二姓名超出部分用省略号第三配偶信息同样做截断。.name { max-width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } .spouse { max-width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }要注意text标签在 uniapp 里默认是内联元素直接设置max-width和overflow: hidden可能无效最好给它一个display: block或者display: inline-block。文本过长的问题如果不处理会导致整棵树的兄弟组宽度不一致横线错位所以这一步不要省。如果想显示完整名字可以做一个“点击卡片弹出详情”的能力把省略的信息放到详情弹层里而不是强塞进卡片。4.3 线条粗细、颜色、间距的对齐强迫症新写的家谱图往往一眼看上去“连线有点歪”排查方法其实就一句话任何线段的起点和终点都必须是某个容器的边界或中心。如果歪了九成是绝对定位基准不同。比如我上面把父节点竖线定位在.node-card.has-children::after上它的基准是卡片底边也就是卡片盒子的 content 区域底边。但如果卡片有padding且box-sizing设置不同top: 100%的实际位置就会变化。我在项目里统一给包括卡片、容器在内的所有元素设置了box-sizing: border-box避免这种偏差。还有一个非常容易漏的细节position: absolute的left: 50%是相对于元素包含块的宽度而transform: translateX(-50%)才是让线条真正居中的手段。如果你只设置了left: 50%而没有位移2rpx 宽的竖线会偏向右侧 1rpx。在普通设备上看不出来但在高清屏上会显得线条中轴不居中。我的写法是直接用margin-left: -1rpx来做微调或者用transform: translateX(-1rpx)。注意 rpx 换算后-1rpx在很多设备上是 0.5px刚好补偿半像素偏移效果很细腻。4.4 递归层级过深的性能瓶颈纯 CSS 树形方案最大的软肋是节点数量。如果某代人特别多比如同辈有 20 个兄弟节点那么这一层的 flex 容器会同时渲染 20 个递归组件每个组件又包含自己的后代总节点数一旦超过几百个小程序端的渲染就会明显卡顿。我实际做的优化有几个。第一不一次性渲染全部世代而是默认只展开前几层点击“加载更多”再展开更深的后代。这样根节点下面的前两三代最多几十个节点页面压力很小。第二对同一层的多余兄弟数量做折叠比如“五子”只展示前三个剩余显示为“余 2 人”的合并节点点击后再展开。第三卡片内部的图片、装饰元素尽量少用凡是能用纯色和边框表达的就不要再加额外的 view 嵌套。如果你面对的数据量实在巨大几千人那种纯 DOM 方案无论如何都会到瓶颈。那时候再去评估 canvas 或分页加载不迟。但绝大多数移动端家谱场景几百人以内这个方案已经够稳。4.5 常见问题速查表问题现象可能原因解决方案横线缺失或断线伪元素 content 写法问题或被 overflow 裁剪检查 content 引号移除内层容器 overflow竖线不在节点中心left 50% 未做位移补偿加 margin-left 或 transform 微调子节点宽度不一致卡片 min-width 缺失或文字未截断固定卡片宽度文本省略根节点上方有多余横线is-root 类未作用或选择器被覆盖检查根组件 isRoot 传参确认样式优先级小程序端线条发虚2rpx 折算为 1px 但无物理像素对齐尝试 transform: scaleY(0.5) 模拟细线深层节点卡顿递归组件渲染过多分批展开、兄弟折叠、合并节点5. 扩展思路还能做成什么样5.1 从纵向世系图换成横向世系图我上面实现的是从始祖到后代依次向下的“纵向世系图”适合按代浏览。但移动端还有一个常见形态是“横向世系图”老祖宗在左后代往右展开。这种形态在需要展示“某一支的完整传承路径”时更好用尤其是每代人只有一个独苗的时候。横向世系图的 CSS 逻辑其实和纵向基本对称核心改动点是把.tree-li的方向变成row把孩子们的容器方向变成column竖线变横线横线变竖线。具体操作上父节点右侧的横线负责连接孩子列表每个孩子上方的纵线变成左侧的横线。如果你掌握了纵向版的三段式画线原理横向版只是把坐标系旋转一下。5.2 配偶合并展示与多偶场景家谱数据里配偶是个容易翻车的点。我的简单做法是把配偶作为文本放在卡片内。但真族谱里常有“继配”“侧室”一个人多条婚配记录。这时候卡片内部布局要改成两段式父节点在上配偶列表在下或者用“同框并排”的方式展示。核心数据结构建议这样调整{ id: g3-1, name: 三世长孙, spouses: [ { name: 配张太君, note: 元配 }, { name: 继配刘太君, note: 继配 } ], children: [] }视觉上可以做成“主卡片展示本人姓名下方小字按行列出多任配偶”。这样递归结构不用改只是卡片内部从单行文本变成了多行列表。孩子在族谱中的归属一般跟父亲多个配偶的孩子还是统一挂在当前节点下不影响树结构。5.3 大数据量下的分页与分代加载移动端家谱图永远面对一个现实问题数据量。我最后采用的分层加载策略是页面初始渲染前三代然后每个节点下方放一个“展开后代”按钮点击后才递归渲染它的子节点。这样即便总数据有一千人初始渲染可能只有几十个节点。实现方式是在数据结构里给每个节点加一个字段{ name: 四世某公, children: [], // 真实孩子 childrenLoaded: false }渲染时判断childrenLoaded为 false 就不渲染孩子而是显示一个按钮。点击后把childrenLoaded置为 true并重新赋值真实的children数组。这个方案比一次性渲染所有数据要稳妥得多。另外如果你希望整个家谱图可以缩放建议在外层套一个scroll-view加双指缩放的手势处理。不过要注意一旦做了缩放CSS 里 rpx 的等比换算和绝对定位线条就会变得敏感。我自己的经验是家谱图更适合“大屏分辈分浏览点进详情看个人”过度纠结在单屏内缩放反而是吃力不讨好。最后再分享一个小经验画树形连线时一定要先在草稿纸上把节点盒子的尺寸、间距、竖线高度、横线高度写清楚再来写 CSS。我第一版就是边写边调四个间距值各调各的结果越调越乱。后来固定为一套“60rpx 标准间距”所有位置计算全部围绕它展开样式一下就干净了。这种树形结构的 CSS本质上就是把几何关系想清楚后面的代码只是照着落笔而已。
家谱世系图这个需求乍一看很简单无非就是画一棵树。但真落到移动端、落到 uniapp、还得加一句“纯 CSS 实现”的时候事情就变得有意思了。我上一个项目正好接到类似需求要在 App 里展示一个家族从始祖到当前几代人的完整世系关系。当时第一反应是找现成的树形组件翻了一圈要么体积太大要么样式绑得太死要么在微信小程序端兼容性堪忧。最后决定自己写而且整条链路全部用 CSS 来实现层级和连线——就是标题里说的“纯 CSS 家谱世系图”。这篇文章就把我踩过的坑、验证过的方案和最终的完整代码一次讲清楚。不管是自己项目要用还是纯粹想研究 CSS 到底能把树形结构画到什么程度这篇应该都能给你省不少时间。1. 先聊清楚这个需求到底要做什么1.1 家谱世系图和普通树形图的差异很多人会把“家谱世系图”和“组织架构图”混为一谈其实两者的展示逻辑不完全一样。组织架构图强调的是职位层级上下级之间往往是“一个上级对应多个下级”而且每个节点通常就一个人名或一个职位。家谱世系图则更复杂一些它既要体现血脉的纵向传承又要保证同一辈分的人在视觉上尽量平齐还要兼顾配偶信息、出生去世年份、子嗣数量、过继关系等。简单说它是一棵带“横向辈分对齐”和“纵向血缘延续”双重语义的树。移动端尤其麻烦。屏幕宽度只有那么点一个节点卡片上可能同时要放姓名、配偶、生卒年如果按照网页端那种“横向铺开”的组织架构图画法一旦某个老祖宗生了五六个儿子这一层就会直接超出屏幕。所以移动端家谱图在设计时就必须做取舍卡片做紧凑、线条做合理、文字做省略。而纯 CSS 方案的优势在于它和组件模板天然绑定数据一变 DOM 自动更新不需要像 canvas 一样手动维护绘制状态。1.2 为什么我放弃了 canvas / svg / 第三方组件在做技术选型的时候我认真考虑过三条路最终都放弃了。第一条路是 canvas。canvas 在大屏图表场景确实强势但在移动端家谱这种“强交互、强滚动、强文本展示”的需求里问题很突出文本换行要自己算节点点击命中要自己判滚动和缩放要自己监听触摸事件数据一旦变化还得重绘全图。相当于把一个展示需求硬生生做成了一个绘图引擎项目。第二条路是 svg。svg 在 H5 端表现非常好但 uniapp 要同时兼容小程序端时动态生成 svg 海量节点会导致性能和解析上的各种奇怪问题。而且 svg 的路径计算、文本换行、点击事件绑定在小程序端的支持参差不齐做起来远没有想象中顺滑。第三条路是引入第三方树形组件。其实大部分第三方树形图库都是基于 DOM 的核心思路也是 CSS flex 布局加绝对定位连线本质上和我手写差不多。但问题在于组件库的样式是黑的白的粗细的想调成“族谱纸质感”需要覆盖大量样式改造成本有时候比从零写还高。纯 CSS 方案的真正价值不是“不用 JS”而是用最少量的模板结构把布局和连线交给 CSS 自己推导。你只需要给一个递归组件传嵌套数据剩下的层级、对齐、线条全自动生成。1.3 uniapp 环境对纯 CSS 方案的影响uniapp 的渲染链路比较特殊H5 端走的是普通浏览器渲染小程序端走的是小程序原生渲染。这两个环境对 CSS 的支持有一些细微差别尤其是伪元素、CSS 变量、后代选择器、position: absolute的定位基准在部分旧版本小程序基础库上会有兼容性差异。我最终实现的方案没有依赖 CSS 变量也没有使用任何冷门选择器主要用的就是flex、position和伪元素这几个东西在微信小程序、支付宝小程序、H5 上都能稳定工作。另外移动端要格外注意 rpx 单位。rpx 在 uniapp 里是响应式单位屏幕宽度固定 750rpx不同设备上会自动缩放。画 1 像素线时直接用2rpx比较合适但如果追求极致的清晰可以考虑在特定设备上用px配合transform: scaleY(0.5)来模拟 0.5px 线后面我把这个技巧也写出来。2. 设计思路数据、布局与选型拆解2.1 先把数据源设计成“递归无害”的样子任何树形结构的实现第一步永远是数据结构。家谱数据的自然形态是嵌套的一个节点代表一个人节点上有配偶信息有孩子数组。我在项目里用的数据模型大概是这样的const familyData { id: g1, name: 某氏始祖, spouse: 配李太君, birth: 约1680, death: 约1750, children: [ { id: g2-1, name: 二世长子, spouse: 配王太君, birth: 约1705, death: 约1772, children: [ { id: g3-1, name: 三世长孙, spouse: 配张太君, children: [] }, { id: g3-2, name: 三世次孙, spouse: 配刘太君, children: [] } ] }, { id: g2-2, name: 二世次子, spouse: 配赵太君, children: [] } ] }这个数据结构有几个关键设计点。第一每个节点必须有唯一id否则递归渲染做v-for时根本无法正确复用和 diff。第二children必须始终是数组没有子嗣就置空数组这样可以避免渲染前到处做空值判断。第三配偶不是单独的节点而是当前节点的一个属性字段这样家谱图中“夫妻合体”的展示逻辑就落到了卡片内部而不是另起一个兄弟节点。如果你要做更复杂的族谱比如存在“一夫多妻”“妻妾并列”“过继关系”建议在这个模型上再加一个spouses数组但核心递归结构不要动。树形递归组件最忌讳的就是数据结构频繁变卦。2.2 布线的核心逻辑一根线怎么画出来家谱图看起来神秘其实每一根线的本质就三类横线、竖线、横竖交接的转角。我这一版方案的连线全部由 CSS 伪元素完成没有额外增加用于画线的 DOM 节点。具体思路可以拆成三段理解第一段兄弟节点之间的水平线。每个子节点元素自己贡献“半截横线”两个相邻节点各出一半拼接起来视觉上就是一条贯穿整个兄弟组的横线。这里用::before和::after分别控制左右两半不需要 JavaScript 计算它的宽度。第二段从横线向下到达节点卡片的那根短竖线。这根竖线直接定位在节点卡片的上方从卡片顶边向上延伸到横线位置。第三段父节点向下连接到子级横线的竖线。当父节点有孩子时在这张卡片的底边画一根向下的竖线长度为子级容器预留的间距正好落到子级横线上。三段线各管一段组合在一起就成了完整的“父节点 → 竖线 → 横线 → 竖线 → 子节点”通路。而且因为所有线都写在递归组件的样式里不管嵌套多少层都能自动正确生成。2.3 移动端适配与视觉规范画家谱视觉上的“古旧感”和“纸质感”是加分的。我在项目里定了一个比较克制的配色线条用旧纸色#b49c6c卡片底色用米黄#fffdf5边框用同色系但稍微压暗的浅棕文字用深褐色。实际效果类似宣纸上用淡墨勾线不抢内容辈分层级一眼就能读出来。卡片尺寸也要专门调。移动端单卡片我控制在宽度 220rpx 左右能放下两个字段主姓名加配偶下面是生卒年份小字。如果名字较长超过 6 个字就做单行省略。晚辈的卡片可以稍微小一点但最好不要小于 180rpx否则手指点击命中率太低。辈分之间的垂直间距我用了 60rpx这个高度刚好容纳一截竖线又不会让整棵树过于松散。最终整体是纵向滚动的同一辈分尽量水平对齐用户通过上下滑动查看代际传承。3. 手把手实现递归组件 纯CSS连线3.1 递归组件的骨架在 uniapp 中实现递归组件最稳妥的方式是给组件设置name然后在模板中引用自身。我用 Vue3 的defineOptions给 SFC 命名这样在小程序端和 H5 端都能正确递归。组件接收node和isRoot两个 props分别表示当前节点数据和是否根节点。template view classtree-li :class{ is-root: isRoot } view classnode-card :class{ has-children: hasChildren } clickhandleTap view classcard-main text classname{{ node.name }}/text text v-ifnode.spouse classspouse{{ node.spouse }}/text /view view classcard-sub v-ifnode.birth || node.death text{{ node.birth || ? }} - {{ node.death || ? }}/text /view /view view v-ifhasChildren classtree-children FavoriteNode v-forchild in node.children :keychild.id :nodechild :is-rootfalse / /view /view /template script setup import { computed } from vue defineOptions({ name: FavoriteNode }) const props defineProps({ node: { type: Object, required: true }, isRoot: { type: Boolean, default: false } }) const emit defineEmits([nodeTap]) const hasChildren computed(() ( props.node.children props.node.children.length 0 )) function handleTap() { emit(nodeTap, props.node) } /script注意这里有个细节我故意给每个子节点传:is-rootfalse而不是像有些人写的那样“不传就默认 false”因为在递归场景下显式传参会规避小程序端某些组件属性继承的怪异行为。另外如果递归层数很深nodeTap事件会逐层冒泡建议在父页面统一处理不要在每层都拦截。3.2 三条核心 CSS 线接下来是重头戏画线的三段式 CSS。我把完整样式贴出来再逐段解释。style scoped .tree-li { position: relative; display: flex; flex-direction: column; align-items: center; padding: 60rpx 20rpx 0 20rpx; } /* 兄弟组横线每个节点贡献左半和右半 */ .tree-li::before, .tree-li::after { content: ; position: absolute; top: 0; right: 50%; width: 50%; border-top: 2rpx solid #b49c6c; } .tree-li::after { right: auto; left: 50%; } /* 节点卡片上方竖线从横线垂下到卡片 */ .node-card::before { content: ; position: absolute; top: -60rpx; left: 50%; width: 2rpx; height: 60rpx; background: #b49c6c; } /* 父节点到子级横线的竖线 */ .node-card.has-children::after { content: ; position: absolute; top: 100%; left: 50%; width: 2rpx; height: 60rpx; background: #b49c6c; } .tree-children { display: flex; justify-content: center; align-items: flex-start; padding-top: 60rpx; } /* 根节点单独处理 */ .tree-li.is-root { padding-top: 30rpx; } .tree-li.is-root::before, .tree-li.is-root::after { display: none; } .tree-li.is-root .node-card::before { display: none; } .node-card { position: relative; display: flex; flex-direction: column; align-items: center; width: 220rpx; padding: 20rpx 12rpx 14rpx; background: #fffdf5; border: 2rpx solid #b49c6c; border-radius: 12rpx; box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.06); } .card-main { display: flex; flex-direction: column; align-items: center; } .name { font-size: 28rpx; color: #4a3622; font-weight: 600; } .spouse { margin-top: 4rpx; font-size: 22rpx; color: #8a6d4b; } .card-sub { margin-top: 8rpx; font-size: 20rpx; color: #b08d66; } .tree-li:only-child::before, .tree-li:only-child::after { display: none; } .tree-li:only-child .node-card::before { top: -60rpx; height: 60rpx; } /style第一段::before和::after这两个伪元素一个从节点左边缘画到中心一个从中心画到右边缘。因为每个节点都占满自己在 flex 容器里的宽度左右相邻节点的半截线在边界处自然衔接视觉上就是一条完整横线。而且最左侧节点的线不会超出左边缘最右侧节点的线也不会超出右边缘因为每段线都是节点自身宽度的一半。第二段.node-card::before它是一根绝对定位的竖线从卡片顶边向上延伸 60rpx。为什么是 60rpx因为.tree-li的padding-top是 60rpx也就是说卡片在纵向布局中其实是从父节点的第 60rpx 处才开始排的这 60rpx 的空间就是留给竖线的。竖线从卡片顶边向上画 60rpx正好到横线的位置。第三段.node-card.has-children::after当节点有孩子时卡片底边往下延伸 60rpx。这 60rpx 对应.tree-children的padding-top: 60rpx。子级横线在 children 容器的内容区顶部也就是父卡片底部往下 60rpx 的位置父节点竖线也正好画到这个位置两边严丝合缝。这个三段式结构最难的地方不是写代码而是理解“每个元素贡献的间距必须和其他元素的定位尺寸完全一致”。想调间距的时候记得padding-top、::before高度、::after高度、tree-children的padding-top这四个值必须同步修改。3.3 根节点、叶子节点、单子节点的边界处理家谱图里最尴尬的永远是边界情况。根节点没有兄弟也没有向上的线所以.is-root会把伪元素横线和上竖线全部隐藏只留卡片和向下延伸的竖线。叶子节点没有孩子所以不会渲染.tree-children也就自然不会多出向下的竖线。单子节点是我在测试时特别留意的情况。一个儿子继承香火在族谱里是很常见的。在默认样式下单子节点也会画出横线看起来就是一个“T 形”连接在父节点和唯一儿子之间。视觉上虽然不丑但有点多余。上面代码里的.tree-li:only-child就是为了处理这个情况隐藏横线只保留上下贯通的竖线。:only-child在 H5 和小程序端的基础库上基本都支持但如果你要兼容特别老的小程序环境也可以改为在数据层判断“是否只有一个孩子”然后追加一个 class。3.4 交互增强节点点击与样式反馈家谱图肯定不能只是静态展示。实际项目里用户会点击某个节点查看详情、编辑成员、查看其后代。我在组件里通过handleTap把当前节点对象抛出去父页面接收后打开半屏弹窗展示完整资料。// 在父页面使用组件 const familyData ref(treeData) function onNodeTap(node) { memberPopup.value.open(node) }为了让点击反馈更明显我加了一个按下态样式当手指按住卡片时卡片轻微缩小并加一层半透明底色。这个效果在移动端非常重要它能第一时间告诉用户“我按到了”。实现方式也很简单给node-card加hover-class或者直接用 CSS 的active伪类。uniapp 的 H5 端:active支持良好小程序端建议用hover-class更为稳定。.node-card { transition: transform 0.15s ease; } .node-card:active { transform: scale(0.96); background: #f6ecd8; }需要注意如果卡片上绑定了点击事件同时内部又有子节点一定要避免事件冒泡导致误触。在递归组件里点击卡片时并不希望它触发祖先节点的卡片点击但事件默认会冒泡。我建议在handleTap里调用stopPropagation或者在模板上使用.stop修饰符。uniapp 小程序端对click.stop是支持的直接用就好。4. 踩坑实录与排查技巧4.1 伪元素在部分小程序端不生效的问题这是我遇到的第一个大坑。写完组件后在 H5 端一切正常拿到微信开发者工具里一看部分线条不见了。排查了半天发现是小程序对页面根组件容器的overflow和某些position上下文处理不一致。比如如果整个树的外层容器设置了overflow-x: hidden在某些安卓 WebView 里绝对定位伪元素的绘制会被意外截断。解决办法是把最外层的滚动容器和内部的树形渲染容器分开。外层只负责滚动内层专门做布局。不要在内层容器上设置任何overflow给伪元素一个干净的绘制环境。如果确实需要横向裁切尽量用padding挤出安全区而不是用overflow硬砍。另外一部分老版本小程序基础库对伪元素content: 里的空字符串要求很严格写成content: none或者漏掉引号都会导致伪元素不渲染。写 uniapp 跨端样式时建议统一使用content: 这种写法别图省事。4.2 节点文字过长挤爆布局家谱里最不缺的就是“长名字”。我自己测试时输入了一个八个字的满名整个卡片瞬间被撑宽兄弟节点都被排挤错位。后来我做了三件事第一卡片固定宽度不随内容无限增长第二姓名超出部分用省略号第三配偶信息同样做截断。.name { max-width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } .spouse { max-width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }要注意text标签在 uniapp 里默认是内联元素直接设置max-width和overflow: hidden可能无效最好给它一个display: block或者display: inline-block。文本过长的问题如果不处理会导致整棵树的兄弟组宽度不一致横线错位所以这一步不要省。如果想显示完整名字可以做一个“点击卡片弹出详情”的能力把省略的信息放到详情弹层里而不是强塞进卡片。4.3 线条粗细、颜色、间距的对齐强迫症新写的家谱图往往一眼看上去“连线有点歪”排查方法其实就一句话任何线段的起点和终点都必须是某个容器的边界或中心。如果歪了九成是绝对定位基准不同。比如我上面把父节点竖线定位在.node-card.has-children::after上它的基准是卡片底边也就是卡片盒子的 content 区域底边。但如果卡片有padding且box-sizing设置不同top: 100%的实际位置就会变化。我在项目里统一给包括卡片、容器在内的所有元素设置了box-sizing: border-box避免这种偏差。还有一个非常容易漏的细节position: absolute的left: 50%是相对于元素包含块的宽度而transform: translateX(-50%)才是让线条真正居中的手段。如果你只设置了left: 50%而没有位移2rpx 宽的竖线会偏向右侧 1rpx。在普通设备上看不出来但在高清屏上会显得线条中轴不居中。我的写法是直接用margin-left: -1rpx来做微调或者用transform: translateX(-1rpx)。注意 rpx 换算后-1rpx在很多设备上是 0.5px刚好补偿半像素偏移效果很细腻。4.4 递归层级过深的性能瓶颈纯 CSS 树形方案最大的软肋是节点数量。如果某代人特别多比如同辈有 20 个兄弟节点那么这一层的 flex 容器会同时渲染 20 个递归组件每个组件又包含自己的后代总节点数一旦超过几百个小程序端的渲染就会明显卡顿。我实际做的优化有几个。第一不一次性渲染全部世代而是默认只展开前几层点击“加载更多”再展开更深的后代。这样根节点下面的前两三代最多几十个节点页面压力很小。第二对同一层的多余兄弟数量做折叠比如“五子”只展示前三个剩余显示为“余 2 人”的合并节点点击后再展开。第三卡片内部的图片、装饰元素尽量少用凡是能用纯色和边框表达的就不要再加额外的 view 嵌套。如果你面对的数据量实在巨大几千人那种纯 DOM 方案无论如何都会到瓶颈。那时候再去评估 canvas 或分页加载不迟。但绝大多数移动端家谱场景几百人以内这个方案已经够稳。4.5 常见问题速查表问题现象可能原因解决方案横线缺失或断线伪元素 content 写法问题或被 overflow 裁剪检查 content 引号移除内层容器 overflow竖线不在节点中心left 50% 未做位移补偿加 margin-left 或 transform 微调子节点宽度不一致卡片 min-width 缺失或文字未截断固定卡片宽度文本省略根节点上方有多余横线is-root 类未作用或选择器被覆盖检查根组件 isRoot 传参确认样式优先级小程序端线条发虚2rpx 折算为 1px 但无物理像素对齐尝试 transform: scaleY(0.5) 模拟细线深层节点卡顿递归组件渲染过多分批展开、兄弟折叠、合并节点5. 扩展思路还能做成什么样5.1 从纵向世系图换成横向世系图我上面实现的是从始祖到后代依次向下的“纵向世系图”适合按代浏览。但移动端还有一个常见形态是“横向世系图”老祖宗在左后代往右展开。这种形态在需要展示“某一支的完整传承路径”时更好用尤其是每代人只有一个独苗的时候。横向世系图的 CSS 逻辑其实和纵向基本对称核心改动点是把.tree-li的方向变成row把孩子们的容器方向变成column竖线变横线横线变竖线。具体操作上父节点右侧的横线负责连接孩子列表每个孩子上方的纵线变成左侧的横线。如果你掌握了纵向版的三段式画线原理横向版只是把坐标系旋转一下。5.2 配偶合并展示与多偶场景家谱数据里配偶是个容易翻车的点。我的简单做法是把配偶作为文本放在卡片内。但真族谱里常有“继配”“侧室”一个人多条婚配记录。这时候卡片内部布局要改成两段式父节点在上配偶列表在下或者用“同框并排”的方式展示。核心数据结构建议这样调整{ id: g3-1, name: 三世长孙, spouses: [ { name: 配张太君, note: 元配 }, { name: 继配刘太君, note: 继配 } ], children: [] }视觉上可以做成“主卡片展示本人姓名下方小字按行列出多任配偶”。这样递归结构不用改只是卡片内部从单行文本变成了多行列表。孩子在族谱中的归属一般跟父亲多个配偶的孩子还是统一挂在当前节点下不影响树结构。5.3 大数据量下的分页与分代加载移动端家谱图永远面对一个现实问题数据量。我最后采用的分层加载策略是页面初始渲染前三代然后每个节点下方放一个“展开后代”按钮点击后才递归渲染它的子节点。这样即便总数据有一千人初始渲染可能只有几十个节点。实现方式是在数据结构里给每个节点加一个字段{ name: 四世某公, children: [], // 真实孩子 childrenLoaded: false }渲染时判断childrenLoaded为 false 就不渲染孩子而是显示一个按钮。点击后把childrenLoaded置为 true并重新赋值真实的children数组。这个方案比一次性渲染所有数据要稳妥得多。另外如果你希望整个家谱图可以缩放建议在外层套一个scroll-view加双指缩放的手势处理。不过要注意一旦做了缩放CSS 里 rpx 的等比换算和绝对定位线条就会变得敏感。我自己的经验是家谱图更适合“大屏分辈分浏览点进详情看个人”过度纠结在单屏内缩放反而是吃力不讨好。最后再分享一个小经验画树形连线时一定要先在草稿纸上把节点盒子的尺寸、间距、竖线高度、横线高度写清楚再来写 CSS。我第一版就是边写边调四个间距值各调各的结果越调越乱。后来固定为一套“60rpx 标准间距”所有位置计算全部围绕它展开样式一下就干净了。这种树形结构的 CSS本质上就是把几何关系想清楚后面的代码只是照着落笔而已。
