vue-family-tree-chart

vue-family-tree-chart

面向家谱场景的「宝塔吊线图」Vue 3 组件：基于 WebWorker 布局计算 + SVG 视口虚拟渲染，支持万级节点流畅交互、拖拽缩放、节点折叠、悬停分支高亮。

特性

• ⚡ 高性能：WebWorker 异步布局 + 视口二分虚拟渲染，仅渲染可见节点/连线；文字自动降级。
• 🖱️ 丰富交互：拖拽平移、滚轮以鼠标为中心缩放、节点点击折叠/展开、悬停高亮祖先链整条分支。
• 🎨 强定制：--ftc-* CSS 变量主题、主/辅文字样式、排版方向（ltr/rtl）、世系标尺。
• 📦 TypeScript 友好：完整类型导出，数据校验、受控属性、命令式 API 齐备。

安装

npm install vue-family-tree-chart

快速开始

<script setup lang="ts">
import { ref } from 'vue'
import { FamilyTreeChart } from 'vue-family-tree-chart'
import 'vue-family-tree-chart/style.css'
import type { FamilyNode } from 'vue-family-tree-chart'

const data = ref<FamilyNode>({
  id: 'root',
  name: '始',
  gender: 'm',
  children: [
    { id: 'a', name: '长', gender: 'm' },
    { id: 'b', name: '次', gender: 'f', spouse: ['某氏'] }
  ]
})
const collapsed = ref<string[]>([])
</script>

<template>
  <FamilyTreeChart :data="data" v-model:collapsed="collapsed" />
</template>

数据 children 的顺序即长幼顺序；spouse 为配偶名数组。

Props

Emits

命令式方法（expose）

<script setup>
const chart = ref()
onMounted(() => chart.value.fitView())
</script>
<template>
  <FamilyTreeChart ref="chart" :data="data" />
</template>

Slots

主题（CSS 变量）

.vue-family-tree-chart-container {
  --ftc-bg: #FCF7EC;          /* 背景 */
  --ftc-text-color: #4A3222;  /* 正文/节点文字 */
  --ftc-edge-color: #A97F4F;  /* 连线 */
  --ftc-edge-hl-color: #C0392B; /* 高亮连线 */
  --ftc-hint-color: #9A7D5C;  /* 提示文字 */
}

类型

interface FamilyNode {
  id: string
  name: string
  gender: 'm' | 'f'
  spouse?: string[]
  inherit?: '承继' | '过继' | '兼祧'
  children?: FamilyNode[]
}

interface ViewBox { x: number; y: number; w: number; h: number }
interface TextStyle { size: number; color: string; font: string }

浏览器支持

现代浏览器（Chromium / Firefox / Safari）。依赖 WebWorker、PointerEvent、setPointerCapture、SVG。

• Worker 不可用时自动降级为主线程布局。
• 如应用中禁用 Worker（内联环境），设 :use-worker="false"。

开发与测试

npm install
npm run dev        # 运行 demo
npm test           # 单元测试（Vitest）
npm run typecheck  # vue-tsc 类型检查
npm run build      # 打包库（ESM + UMD + 类型 + 样式）

License

MIT