基础使用

基础用法

SunlightThree 是基于 Element Plus Tree 的增强型树形选择器组件，支持单选、多选、关键字过滤等功能。

树形选择器

全部

一级 1

二级 1-1

二级 1-2

一级 2

二级 2-1

二级 2-2

当前选择值：1-1

<script setup lang="ts">
import { ref } from "vue";
import { SunlightThree } from "sunlight-ui";

// 基础用法示例数据
const selectedValue = ref("1-1");
const treeData = ref([
  {
    id: '1',
    label: '一级 1',
    children: [
      { id: '1-1', label: '二级 1-1' },
      { id: '1-2', label: '二级 1-2' }
    ]
  },
  {
    id: '2',
    label: '一级 2',
    children: [
      { id: '2-1', label: '二级 2-1' },
      { id: '2-2', label: '二级 2-2' }
    ]
  }
]);

const handleChange = (value: string) => {
  console.log('选中值:', value);
  selectedValue.value = value;
};
</script>

<template>
  <div>
    <div style="margin-bottom: 20px;">
      <SunlightThree 
        :data="treeData"
        title="树形选择器"
        :defaultValue="selectedValue"
        @change="handleChange"
        :wrapperStyle="{
          borderColor: '#c0c4cc',
          focusBorderColor: '#409eff'
        }"
      />
    </div>
    <div style="margin-top: 20px;">
      <p>当前选择值：{{ selectedValue || '暂无选择' }}</p>
    </div>
  </div>
</template>

<style scoped>
</style>

隐藏源代码

多选模式

通过设置 multiple: true 开启多选模式，支持选择多个节点。

多选模式（multiple: true）

多选树形选择器

一级 1

二级 1-1

二级 1-2

一级 2

二级 2-1

二级 2-2

当前选择值：[ "1-1", "2-1" ]

<script setup lang="ts">
import { ref } from "vue";
import { SunlightThree } from "sunlight-ui";

// 多选模式示例数据
const selectedValue = ref(["1-1", "2-1"]);
const treeData = ref([
  {
    id: '1',
    label: '一级 1',
    children: [
      { id: '1-1', label: '二级 1-1' },
      { id: '1-2', label: '二级 1-2' }
    ]
  },
  {
    id: '2',
    label: '一级 2',
    children: [
      { id: '2-1', label: '二级 2-1' },
      { id: '2-2', label: '二级 2-2' }
    ]
  }
]);

const handleChange = (value: string[]) => {
  console.log('选中值:', value);
  selectedValue.value = value;
};
</script>

<template>
  <div>
    <div style="margin-bottom: 20px;">
      <p style="margin-bottom: 10px; font-weight: bold;">多选模式（multiple: true）</p>
      <SunlightThree 
        :data="treeData"
        title="多选树形选择器"
        multiple
        :defaultValue="selectedValue"
        @change="handleChange"
        :wrapperStyle="{
          borderColor: '#c0c4cc',
          focusBorderColor: '#409eff'
        }"
      />
    </div>
    <div style="margin-top: 20px;">
      <p>当前选择值：{{ selectedValue.length > 0 ? selectedValue : '暂无选择' }}</p>
    </div>
  </div>
</template>

<style scoped>
</style>

隐藏源代码

异步加载

通过设置 lazy: true 和 load 方法开启异步加载功能。

异步加载模式（lazy: true）

异步加载树形结构

一级节点 1

一级节点 2

当前选择值：暂无选择

<script setup lang="ts">
import { ref } from "vue";
import { SunlightThree } from "sunlight-ui";

// 异步加载示例数据
const selectedValue = ref("");
const treeData = ref([]);

// 模拟异步加载方法
const loadNode = (node: any, resolve: (data: any[]) => void) => {
  // 根节点，加载一级数据
  if (node.level === 0) {
    return resolve([
      { id: "1", label: "一级节点 1", hasChildren: true },
      { id: "2", label: "一级节点 2", hasChildren: true }
    ]);
  }
  // 一级节点，加载二级数据
  if (node.level === 1) {
    setTimeout(() => {
      resolve([
        { id: `${node.data.id}-1`, label: `二级节点 ${node.data.id}-1`, hasChildren: true },
        { id: `${node.data.id}-2`, label: `二级节点 ${node.data.id}-2` }
      ]);
    }, 500);
    return;
  }
  // 二级节点，加载三级数据
  if (node.level === 2) {
    setTimeout(() => {
      resolve([
        { id: `${node.data.id}-1`, label: `三级节点 ${node.data.id}-1` },
        { id: `${node.data.id}-2`, label: `三级节点 ${node.data.id}-2` }
      ]);
    }, 500);
    return;
  }
  resolve([]);
};

const handleChange = (value: string) => {
  console.log('选中值:', value);
  selectedValue.value = value;
};
</script>

<template>
  <div>
    <div style="margin-bottom: 20px;">
      <p style="margin-bottom: 10px; font-weight: bold;">异步加载模式（lazy: true）</p>
      <SunlightThree 
        :data="treeData"
        title="异步加载树形结构"
        lazy
        :load="loadNode"
        @change="handleChange"
        :wrapperStyle="{
          borderColor: '#c0c4cc',
          focusBorderColor: '#409eff'
        }"
      />
    </div>
    <div style="margin-top: 20px;">
      <p>当前选择值：{{ selectedValue || '暂无选择' }}</p>
    </div>
  </div>
</template>

<style scoped>
</style>

隐藏源代码

文档说明

SunlightThree Props 配置项

属性名	说明	类型	默认值
data	树形数据，必传	array	[]
title	组件标题	string	-
id	节点唯一标识字段名	string	'id'
label	节点显示文本字段名	string	'label'
multiple	是否启用多选模式	boolean	false
defaultValue	默认选中节点，单选为字符串，多选为数组	string array	-
lazy	是否启用异步加载	boolean	false
load	异步加载子节点的方法	function	-
wrapperStyle	边框和样式配置对象	object	{}

wrapperStyle 配置对象

属性名	说明	类型	默认值
borderColor	树形选择器边框颜色	string	'#c0c4cc'
borderRadius	树形选择器圆角大小	string	'4px'
backgroundColor	树形选择器背景色	string	'#fff'
boxShadow	树形选择器阴影效果	string	-
focusBorderColor	聚焦时边框颜色	string	'#409eff'
focusBoxShadow	聚焦时阴影效果	string	-
selectedBgColor	选中节点背景色	string	'#409eff'
selectedTextColor	选中节点文字颜色	string	'#ffffff'

事件说明

事件名	说明	参数类型
change	选中节点变化时触发	单选：选中节点 id 多选：选中节点 id 数组

插槽说明

插槽名	说明	作用域参数
default	自定义树节点内容	{ row }，其中 row.node 是当前节点数据

数据结构

树形数据应为对象数组，每个对象包含以下字段：

字段名	说明	类型	必填
id	节点唯一标识	string number	是
label	节点显示文本	string	是
children	子节点数组	array	否

最佳实践

1. 基础选择：使用默认配置实现简单树形选择功能
2. 多选模式：设置 multiple: true 开启多选
3. 关键字过滤：组件内置搜索框，支持关键字过滤
4. 异步加载：通过 lazy 和 load 实现异步加载
5. 自定义节点：通过默认插槽自定义节点显示内容

注意事项

• data 为必传属性，且应为数组格式
• 单选模式下 defaultValue 应为字符串，多选模式下应为数组
• 异步加载时，根节点数据应通过 data 传入
• 多选模式下，组件会自动添加"全部"节点（id 为空字符串）

常见问题

1. 问题：节点不显示 解决：检查 data 是否为数组，以及数据结构是否正确

2. 问题：选中值不正确 解决：确保 defaultValue 类型与模式匹配（单选为字符串，多选为数组）

3. 问题：异步加载不生效 解决：确保 lazy: true 且 load 方法正确实现

相关链接

• Element Plus Tree 文档