更新记录

1.0.0（2025-05-05）

首次上传插件

平台兼容性

zp-tree 组件文档

简介

zp-tree 是一个用于展示家族树结构的 Vue 组件，支持多种平台，包括 App、H5、小程序等。该组件具备可移动、缩放的视图，支持节点的点击交互，能动态显示节点的亲属关系，还可进行添加、删除、查看详情等操作。

安装与使用

安装

该组件以 uni_modules 形式发布，可直接将其复制到项目的 uni_modules 目录下。

使用

在需要使用 zp-tree 组件的 Vue 文件中引入并使用：

<template>
  <view>
    <zp-tree :data="treeData" :useFullLabel="true" @click="handleTreeClick" />
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue';
// 统一引入路径
import { nodeData } from '../../uni_modules/zp-tree/components/zp-tree';

const treeData = ref<nodeData[]>([
  // 节点数据示例
  {
    name: '始祖',
    gender: '1',
    generation: 1,
    birth_order: null,
    is_alive: '1',
    avatar_url: '',
    spouse: false,
    id: 1,
    spouses: [],
    children: [],
    fold: false,
    father_id: null,
    mother_id: null
  }
]);

const handleTreeClick = (event) => {
  console.log('点击事件:', event);
};
</script>

组件属性

data

• 类型：nodeData[]
• 必填：是
• 描述：当前节点数据数组，每个节点包含成员的基本信息和亲属关系。

useFullLabel

• 类型：boolean
• 默认值：false
• 描述：是否显示完整标签，完整标签包含世代、关系和生存状态信息。

组件事件

click

• 参数：RelationClickEvent
• 描述：关系操作点击事件，当用户点击节点或模态框中的操作按钮时触发。

数据结构

nodeData

// 可通过统一路径引入
import { nodeData, Gender, IsAlive } from '../../uni_modules/zp-tree/components/zp-tree';

/**
 * 性别枚举
 * 使用数字字符串标识符，适用于需要与数值型数据库存储兼容的场景
 */
export enum Gender {
  /** 男性 (通常对应数据库存储值'1') */
  Male = '1',
  /** 女性 (通常对应数据库存储值'0') */
  Female = '0',
  /** 未知性别 (通常对应数据库存储值'2') */
  Unknown = '2'
}

/**
 * 生存状态枚举
 * 使用数字字符串标识存活状态，适用于二值状态存储
 */
export enum IsAlive {
  /** 在世 (通常对应数据库存储值'1') */
  Yes = '1',
  /** 已故 (通常对应数据库存储值'0') */
  No = '0'
}

/**
 * 家庭成员核心数据结构
 * 描述家族树中的个体基本信息及关系
 */
export interface nodeData<T = unknown> {
  /** 成员姓名 */
  name: string;

  /**
   * 性别标识
   * @see Gender 枚举映射关系
   */
  gender: Gender;

  /**
   * 所属世代
   * - null 表示世代信息未知
   * - 数字越大表示辈分越小（如：1=第一代长辈）
   */
  generation: number | null;

  /**
   * 出生顺序
   * - null 表示顺序未知或不适用（如独生子女）
   * - 1=长子/长女，2=次子/次女，依此类推
   */
  birth_order: number | null;

  /** 生存状态标识 */
  is_alive: IsAlive;

  /** 头像图片URL地址（空字符串表示无头像） */
  avatar_url: string;

  /** 是否为配偶（true表示是配偶） */
  spouse?: boolean;

  /** 节点ID */
  id: number;

  /** 配偶节点列表 */
  spouses: nodeData<T>[];

  /** 子节点列表 */
  children: nodeData<T>[];

  /** 是否折叠 */
  fold?: boolean;

  /** 父亲ID */
  father_id: number | null;

  /** 母亲ID */
  mother_id: number | null;

  /** 扩展字段 */
  [key: string]: any;
}

RelationClickEvent

import { RelationClickEvent, RelationType } from '../../uni_modules/zp-tree/components/zp-tree';

export interface RelationClickEvent {
  type: RelationType;
  node: nodeData;
}

export type RelationType = 'father' | 'mother' | 'spouse' | 'brother' | 'sister' | 'son' | 'daughter' | 'delete' | 'close' | 'detail';

工具函数

useTreeState

• 描述：核心状态管理函数，返回树的初始数据。

  import { useTreeState, nodeData } from '../../uni_modules/zp-tree/components/zp-tree';
  import { ref } from 'vue';
  const initialData = ref<nodeData[]>([]);
  const treeState = useTreeState(initialData);

usenodeDataFinder

• 描述：优化的节点查询工具，提供 findNode 方法用于深度优先搜索查找节点及其所在数组。

  import { usenodeDataFinder, nodeData } from '../../uni_modules/zp-tree/components/zp-tree';
  const { findNode } = usenodeDataFinder();
  const treeData: nodeData[] = []; // 假设的树数据
  const targetId = 1;
  const result = findNode(treeData, targetId);

useTreeActions

• 描述：增强的节点操作工具，提供添加、删除、更新节点等方法。

  import { useTreeActions, nodeData } from '../../uni_modules/zp-tree/components/zp-tree';
  import { ref } from 'vue';
  const treeData = ref<nodeData[]>([]);
  const { addNode, deleteNode, updateNode } = useTreeActions(treeData);
  addNode(1, { name: '新节点', gender: '1', generation: 1, /* 其他属性 */ }, 'child');
  deleteNode(2);
  updateNode(3, { name: '更新后的姓名' });