YmTreeSelector 组件使用

YmTreeSelector 是一个基于 Vue 3 和 Element Plus 的树形选择器组件，支持多选和单选模式，适用于需要从树形结构数据（支持10W+数据）中进行选择的场景。

npm install ym-tree-selector

依赖库相关版本，确保项目的相关版本大于这个版本： element-plus: >=2.7.0 lodash: >=4.17.21

引入组件（推荐）

在你的项目中引入 YmTreeSelector 组件：

import { YmTreeSelector } from 'ym-tree-selector'

使用示例

<template>
  <main class="home">
    <div class="home-box">
      <div style="padding: 10px 0">多选</div>
      <ym-tree-selector v-model="selectedValue1" :data="sourceData" :show-select-all="true" :show-selected="true" @change="handleChange" />
      {{ selectedValue1 }}
      <div style="padding: 10px 0">受限多选</div>
      <ym-tree-selector v-model="selectedValue2" :data="sourceData" :maxSelectNum="3" :show-select-all="true" :show-selected="true" @change="handleChange" />
      {{ selectedValue2 }}
      <div style="padding: 10px 0">单选</div>
      <ym-tree-selector v-model="selectedValue3" :data="sourceData" :multiple="false" :show-selected="false" @change="handleChange" />
      {{ selectedValue3 }}
    </div>
  </main>
</template>

<script setup>
import { ref, watch } from 'vue'
import { getResData } from '../api'

const selectedValue1 = ref(['691543', '691545', '695983'])
const selectedValue2 = ref([])
const selectedValue3 = ref()
const sourceData = ref([])
setTimeout(() => {
  selectedValue1.value = ['691543', '691545']
}, 3000)

async function initData() {
  const res = await getResData()
  sourceData.value = res.data
  console.log('sourceData', sourceData.value)
}

setTimeout(() => {
  initData()
}, 1000)

function handleChange(val, valData, opts) {
  console.log('handleChange', val, valData, opts)
}
</script>

<style>
.home {
  width: 100%;
  height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
}
.home-box {
  width: 100%;
  height: 300px;
  padding: 20px;
}
</style>

属性说明

| 属性名 | 类型 | 默认值 | 描述 | | ------------------ | --------------------------- | -------------- | ---------------------------------------------- | | v-model | String \| Number \| Array | null | 默认值，多选要求为数组，单选要求为字符串或数字 | | data | Array<SourceDataItem> | [] | 树形结构的数据源(附录1) | | multiple | Boolean | true | 是否多选 | | maxTagNum | Number | 3 | 最大可视 tag 数量 | | attrProps | Object | defaultProps | 树节点属性配置(附录2) | | showSelectAll | Boolean | false | 是否显示全选按钮 | | maxSelectNum | Number | 0 | 最大可选数量，0 表示无限制 | | showSelected | Boolean | true | 是否显示已选下拉内容 | | showSearch | Boolean | true | 是否显示筛选框 | | popperTreeHeight | Number | 200 | 下拉树节点盒子高度，单位px | | clearable | Boolean | true | 支持清空 | | showLimitTip | Boolean | true | 是否显示限制提示 | | checkStrictly | Boolean | true | 是否支持父子互不联动 | | disabled | Boolean | false | 禁用状态 | | defaultExpandAll | Boolean | false | 展开第一层 |

事件说明

| 事件名 | 参数 | 描述 | | -------- | ----------------------------------------------------- | ---------------------- | | change | (value: string \| string[], data: SourceDataItem[]) | 当选择项发生变化时触发 |

方法说明

| 方法名 | 参数 | 返回值 | 描述 | | --------------------------------------------------------------------------------------------------------- | ------------------- | ------ | ------------------------ | | initData() | - | - | 初始化数据 | | handleSearchKey(keyword: string) | keyword | - | 处理搜索关键字 | | handleSelectAll() | - | - | 全选/取消全选 | | handleNodeClick(data: TreeNodeData, node: TreeNode, e: MouseEvent) | data, node, e | - | 节点点击事件处理 | | handleCheckChange(data: TreeNodeData, checked: boolean) | data, checked | - | 节点选中状态变化事件处理 | | handleCheck(data: TreeNodeData, info: { checkedKeys, checkedNodes, halfCheckedKeys, halfCheckedNodes }) | data, info | - | 节点选中事件处理 | | handleSelectChange(newData: string[]) | newData | - | 选择项变化事件处理 | | handleRemoveTag(removeValue: string) | removeValue | - | 移除标签事件处理 |

注意事项

1. 数据格式：sourceData 需要是一个符合特定格式的树形结构数组，每个节点对象应包含 value 和 label 和 children(如有) 属性。

示例项目结构

your-project/
├── src/
│   ├── package/
│   │   ├── index.ts
│   │   └── src/
│   │       └── index.vue
│           └──ymts-util.ts
│   ├── App.vue
│   └── main.js
└── package.json

附录1

SourceDataItem 属性说明

SourceDataItem 是 YmTreeSelector 组件中用于表示树形结构数据的接口。每个节点对象应符合此接口的定义，以便组件能够正确解析和渲染树形结构。

接口定义

export interface SourceDataItem {
  label: string;
  value: string;
  leaf?: boolean;
  parentId: string;
  children?: SourceDataItem[];
}

属性说明

| 属性名 | 类型 | 是否必填 | 描述 | | ---------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | label | string | 是 | 节点的显示文本 | | value | string | 是 | 节点的唯一标识符 | | leaf | boolean | 否 | 标识该节点是否为末级节点（叶子节点）。如果为 true，则该节点没有子节点。默认情况下，组件会根据 children 属性自动判断是否为叶子节点。 | | parentId | string | 否 | 父节点的标识符。根节点的 parentId 可以设置为空字符串或其他特殊值，表示没有父节点。 | | children | SourceDataItem[] | 否 | 子节点数组。如果节点有子节点，则该属性为一个 SourceDataItem 数组。 |

示例

以下是一个符合 SourceDataItem 接口的树形结构数据示例：

const sourceData: SourceDataItem[] = [
  {
    label: 'Node 1',
    value: '1',
    children: [
      {
        label: 'Child Node 1-1',
        value: '1-1',
        children: [
          {
            label: 'Grandchild Node 1-1-1',
            value: '1-1-1',
            leaf: true,
          },
        ],
      },
      {
        label: 'Child Node 1-2',
        value: '1-2',
        leaf: true,
      },
    ],
  },
  {
    label: 'Node 2',
    value: '2',
    children: [
      {
        label: 'Child Node 2-1',
        value: '2-1',
        leaf: true,
      },
    ],
  },
];

附录2

defaultProps默认示例

const defaultProps = {
  label: 'label',
  value: 'value',
  children: 'children',
  isLeaf: 'leaf',
}

注意事项

1. 唯一标识符：每个节点的 value 属性必须是唯一的，以确保组件能够正确识别和操作节点。
2. 叶子节点：虽然 leaf 属性是可选的，但为了提高性能和准确性，建议在末级节点上明确设置 leaf: true。