Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
TreeSelect 树选择器
在下拉层里用一棵树来选择,适合选项有层级关系、层级比较深的场景,例如选部门、选分类。下拉层里的树就是 NsTree,展开、勾选、禁用的规则和它一样。
引入
import { NsTreeSelect } from '@ns/ui'
基础用法
data 传树形数据,v-model 绑定选中节点的 key(默认取节点的 id 字段)。单选时默认只能选最后一级的节点,点父节点只是展开或收起。没有选中时值是 undefined,显示 placeholder(默认“请选择”)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const other = ref<string | number>()
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsTreeSelect v-model="value" :data="treeData" style="width: 240px" />
<NsTreeSelect
v-model="other"
:data="treeData"
placeholder="请选择所属分类"
style="width: 240px"
/>
</NsSpace>
<span>选中的值:{{ value ?? 'undefined' }}</span>
</NsSpace>
</template>
可选任意一级
加上 check-strictly 后,单选时父节点也可以选。这时点父节点的文字是选中,要展开它请点前面的箭头,所以一般同时设置 :expand-on-click-node="false"。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsTreeSelect
v-model="value"
:data="treeData"
check-strictly
:expand-on-click-node="false"
default-expand-all
/>
</template>
多选
加上 multiple 后每个节点前面有复选框,绑定值是 key 数组,选中的节点显示成标签。点最后一级节点的文字也能勾选;点父节点的文字只展开,勾选父节点要点它的复选框。
默认父子关联:勾选父节点会同时勾选它下面所有没禁用的节点,绑定值里父节点和子节点的 key 都有。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<(string | number)[]>([21])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsTreeSelect v-model="value" :data="treeData" multiple clearable style="width: 400px" />
</template>
同时加上 check-strictly 时父子不关联,每个节点单独勾选。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<(string | number)[]>([])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsTreeSelect v-model="value" :data="treeData" multiple check-strictly />
</template>
可清空
加上 clearable 后,有值时右侧显示清除按钮(没值或禁用时不显示)。点击后单选的值变成 undefined,多选的值变成 []。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number | undefined>(111)
const values = ref<(string | number)[]>([21, 22])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect v-model="value" :data="treeData" clearable style="width: 240px" />
<NsTreeSelect v-model="values" :data="treeData" multiple clearable style="width: 320px" />
</NsSpace>
<p style="margin-top: 12px">
单选:{{ value ?? 'undefined' }};多选:{{ JSON.stringify(values) }}
</p>
</template>
可搜索
加上 filterable 后,展开时输入框可以打字,按节点文字过滤(不区分大小写)。文字包含关键词的节点、它的各级父节点和它下面的节点会显示,父节点自动展开;没有匹配的节点时显示“暂无数据”。已有值时,搜索框的占位文字是“搜索”。
左边单选,右边多选,可以输入“1-1”或“2-2”试试:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const values = ref<(string | number)[]>([])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect
v-model="value"
:data="treeData"
filterable
placeholder="输入关键字搜索"
style="width: 240px"
/>
<NsTreeSelect
v-model="values"
:data="treeData"
filterable
multiple
placeholder="输入关键字搜索"
style="width: 320px"
/>
</NsSpace>
</template>
禁用
disabled 禁用整个选择器:不能展开,有值时也不显示清除按钮,多选的标签上没有叉。节点数据里的 disabled: true 禁用这个节点:不能选、不能勾选,也不能展开或收起;多选时勾选父节点也不会勾上它。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const empty = ref<string | number>()
const single = ref<string | number>(11)
const multi = ref<(string | number)[]>([11, 13])
const value = ref<string | number>()
const values = ref<(string | number)[]>([])
const data: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{ id: 11, label: '二级 1-1' },
{ id: 12, label: '二级 1-2(禁用)', disabled: true },
{ id: 13, label: '二级 1-3' }
]
}
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">整体禁用</span>
<NsTreeSelect v-model="empty" :data="data" disabled style="width: 200px" />
<NsTreeSelect v-model="single" :data="data" disabled clearable style="width: 200px" />
<NsTreeSelect v-model="multi" :data="data" multiple disabled style="width: 260px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">节点禁用</span>
<NsTreeSelect v-model="value" :data="data" default-expand-all style="width: 200px" />
<NsTreeSelect
v-model="values"
:data="data"
multiple
default-expand-all
style="width: 260px"
/>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
尺寸
size 有 large、default、small 三种,和同尺寸的 NsInput、NsButton 一致:高度 40 / 32 / 24px,字号 16 / 14 / 12px,圆角 8 / 6 / 4px。下拉面板里的树也跟着变,节点行高 40 / 32 / 28px,字号 16 / 14 / 12px;多选时节点前面的复选框也跟着 TreeSelect 的尺寸(方框 18 / 16 / 14px),不跟着外面的 Form。不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。
每一行是一种尺寸,依次是单选(可清空)、多选、同尺寸的按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>(111)
const values = ref<(string | number)[]>([21, 22])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsTreeSelect v-model="value" :data="treeData" size="large" clearable style="width: 200px" />
<NsTreeSelect v-model="values" :data="treeData" size="large" multiple style="width: 280px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsTreeSelect v-model="value" :data="treeData" clearable style="width: 200px" />
<NsTreeSelect v-model="values" :data="treeData" multiple style="width: 280px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsTreeSelect v-model="value" :data="treeData" size="small" clearable style="width: 200px" />
<NsTreeSelect v-model="values" :data="treeData" size="small" multiple style="width: 280px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
展开方式
default-expand-all 让下拉层里的树一开始就全部展开;accordion 让同一层每次只展开一个节点。expand-on-click-node 默认是 true,点有子节点的节点文字时展开或收起;设成 false 后只有点箭头才展开,多选时点父节点的文字就是勾选它。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const values = ref<(string | number)[]>([])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTreeSelect
v-model="value"
:data="treeData"
default-expand-all
placeholder="全部展开(default-expand-all)"
/>
<NsTreeSelect
v-model="value"
:data="treeData"
accordion
placeholder="同一层只展开一个(accordion)"
/>
<NsTreeSelect
v-model="values"
:data="treeData"
multiple
:expand-on-click-node="false"
placeholder="点父节点文字就勾选(expand-on-click-node 为 false)"
/>
</NsSpace>
</template>
自定义字段名
数据里的字段名不是 id、label、children、disabled 时,用 props 指定对应的字段名。只需要改 key 的字段名时也可以用 node-key。
左边用 props 改了 key、文字、子节点、禁用四个字段名;右边的数据只有 key 叫 code,用 node-key="code" 就够了:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
const value = ref<string | number>()
const code = ref<string | number>()
const departments = [
{
code: 'dev',
name: '研发部',
items: [
{ code: 'fe', name: '前端组' },
{ code: 'be', name: '后端组' },
{ code: 'qa', name: '测试组(停用)', locked: true }
]
},
{ code: 'ops', name: '运维部' }
]
const fieldNames = { id: 'code', label: 'name', children: 'items', disabled: 'locked' }
const regions = [
{
code: 'east',
label: '华东',
children: [
{ code: 'shanghai', label: '上海' },
{ code: 'hangzhou', label: '杭州' }
]
}
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect
v-model="value"
:data="departments"
:props="fieldNames"
default-expand-all
style="width: 240px"
/>
<NsTreeSelect
v-model="code"
:data="regions"
node-key="code"
default-expand-all
style="width: 240px"
/>
</NsSpace>
<p style="margin-top: 12px">左边:{{ value ?? 'undefined' }};右边:{{ code ?? 'undefined' }}</p>
</template>
下拉层最大高度
下拉层默认最高 300px,超出后滚动。max-height 传数字时单位是 px,也可以传带单位的字符串。下面左边是 :max-height="120",右边是 max-height="10em",展开后看滚动条:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{
id: 11,
label: '二级 1-1',
children: [
{ id: 111, label: '三级 1-1-1' },
{ id: 112, label: '三级 1-1-2' }
]
}
]
},
{
id: 2,
label: '一级 2',
children: [
{ id: 21, label: '二级 2-1' },
{ id: 22, label: '二级 2-2' }
]
}
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect
v-model="value"
:data="treeData"
:max-height="120"
default-expand-all
style="width: 240px"
/>
<NsTreeSelect
v-model="value"
:data="treeData"
max-height="10em"
default-expand-all
style="width: 240px"
/>
</NsSpace>
</template>
空数据提示
data 为空,或者搜索后没有匹配的节点时,下拉层显示“暂无数据”。用 empty 插槽可以换成别的内容。左边是没有数据,右边可以搜一个不存在的词看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const dept = ref<string | number>()
const data: TreeNodeData[] = [
{
id: 'dev',
label: '研发部',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
}
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect v-model="value" :data="[]" style="width: 240px">
<template #empty>没有可选的部门</template>
</NsTreeSelect>
<NsTreeSelect
v-model="dept"
:data="data"
filterable
placeholder="输入“财务”试试"
style="width: 240px"
>
<template #empty>没有找到这个部门</template>
</NsTreeSelect>
</NsSpace>
</template>
事件
node-click 在点击树节点时触发,不管这个节点能不能选;check 在多选时勾选、取消勾选节点时触发;change 只在用户操作导致值变化时触发;visible-change 在下拉层展开、收起时触发;clear 在点清除按钮时触发。左边单选、右边多选,最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const value = ref<string | number>()
const values = ref<(string | number)[]>([])
const logs = ref<string[]>([])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{ id: 11, label: '二级 1-1' },
{ id: 12, label: '二级 1-2' }
]
},
{ id: 2, label: '一级 2' }
]
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (val: unknown) => log(`change:${JSON.stringify(val)}`)
const onVisibleChange = (visible: boolean) => log(`visible-change:${visible}`)
const onNodeClick = (data: { node: TreeNodeData; key: string | number }) =>
log(`node-click:${data.node.label}`)
const onCheck = (data: { checkedKeys: (string | number)[]; key: string | number }) =>
log(`check:${data.key},勾选后是 ${JSON.stringify(data.checkedKeys)}`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsTreeSelect
v-model="value"
:data="treeData"
clearable
style="width: 200px"
@change="onChange"
@visible-change="onVisibleChange"
@node-click="onNodeClick"
@clear="log('clear')"
/>
<NsTreeSelect
v-model="values"
:data="treeData"
multiple
clearable
style="width: 280px"
@change="onChange"
@check="onCheck"
@clear="log('clear')"
/>
</NsSpace>
<div class="logs">
<div v-if="logs.length === 0">还没有触发事件</div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
调用方法
通过 ref 调用 focus()、blur()。ref 上的 selectedNodes 是当前选中项的列表,每项是 { key, label, node }:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTreeSelect } from '@ns/ui'
import type { TreeNodeData } from '@ns/ui'
const treeSelectRef = ref<InstanceType<typeof NsTreeSelect>>()
const values = ref<(string | number)[]>([11])
const treeData: TreeNodeData[] = [
{
id: 1,
label: '一级 1',
children: [
{ id: 11, label: '二级 1-1' },
{ id: 12, label: '二级 1-2' }
]
},
{ id: 2, label: '一级 2' }
]
</script>
<template>
<NsSpace wrap>
<NsTreeSelect
ref="treeSelectRef"
v-model="values"
:data="treeData"
multiple
style="width: 280px"
/>
<NsButton @click="treeSelectRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="treeSelectRef?.blur()">失焦(blur)</NsButton>
</NsSpace>
<p style="margin-top: 12px">
selectedNodes:{{ treeSelectRef?.selectedNodes.map((item) => item.label).join('、') }}
</p>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,收起下拉层触发 blur 规则;不写 size、disabled 时跟随表单。下面的部门展开后不选直接收起,就会提示必填:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsMessage, NsSpace, NsTreeSelect } from '@ns/ui'
import type { FormRule, TreeNodeData } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive<{ dept?: string | number; members: (string | number)[] }>({
dept: undefined,
members: []
})
const rules: Record<string, FormRule[]> = {
dept: [{ required: true, message: '请选择部门', trigger: ['change', 'blur'] }],
members: [{ required: true, message: '至少选一个成员', trigger: 'change' }]
}
const depts: TreeNodeData[] = [
{
id: 'dev',
label: '研发部',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
}
]
const members: TreeNodeData[] = [
{
id: 'fe',
label: '前端组',
children: [
{ id: 'zhangsan', label: '张三' },
{ id: 'lisi', label: '李四' }
]
}
]
const submit = async () => {
const result = await formRef.value?.validate()
if (result?.valid) NsMessage.success('校验通过')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px" style="max-width: 420px">
<NsFormItem label="部门" prop="dept">
<NsTreeSelect v-model="model.dept" :data="depts" clearable />
</NsFormItem>
<NsFormItem label="成员" prop="members">
<NsTreeSelect v-model="model.members" :data="members" multiple clearable />
</NsFormItem>
<NsFormItem>
<NsSpace>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
键盘操作
选择器可以用 Tab 聚焦,聚焦后:
| 按键 | 作用 |
|---|---|
| Enter、空格 | 展开或收起下拉层(焦点在搜索框里时不起作用) |
| ↓ | 没展开时展开;已展开时焦点进入下拉层,停到第一个节点上 |
| Esc | 收起下拉层,焦点回到选择器 |
| Tab | 收起下拉层 |
焦点进入下拉层之后的按键由树处理:↑、↓ 在节点之间移动,→ 展开,← 收起或回到父节点,Enter 相当于点击节点(单选时选中),多选时空格勾选或取消勾选。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | (string | number)[] | - | 绑定值,支持 v-model。单选是节点的 key,多选是 key 数组 |
| data | TreeNodeData[] | - | 树形数据,必填 |
| multiple | boolean | false | 是否多选 |
| checkStrictly | boolean | false | 单选时是否可以选父节点;多选时父子是否不关联 |
| disabled | boolean | false | 是否禁用 |
| clearable | boolean | false | 有值时是否显示清除按钮 |
| filterable | boolean | false | 是否可搜索,按节点文字过滤 |
| placeholder | string | '请选择' | 占位文本 |
| size | 'small' | 'default' | 'large' | 'default' | 尺寸 |
| props | FieldNames | {} | 自定义节点数据的字段名 |
| nodeKey | string | 'id' | 节点唯一标识的字段名。props.id 也传了时以 props.id 为准 |
| defaultExpandAll | boolean | false | 是否默认展开所有节点 |
| expandOnClickNode | boolean | true | 点节点时是否展开或收起,false 时只有点箭头才展开 |
| accordion | boolean | false | 手风琴模式:同一层每次只展开一个节点 |
| maxHeight | number | string | 300 | 下拉层的最大高度,数字的单位是 px |
| validateEvent | boolean | true | 值变化和收起下拉层时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number | (string | number)[] | undefined) | 值变化时触发,v-model 用 |
| change | (value: string | number | (string | number)[] | undefined) | 用户操作导致值变化时触发(选中、勾选、移除标签、清空) |
| clear | - | 点清除按钮时触发 |
| visibleChange | (visible: boolean) | 下拉层展开或收起时触发 |
| nodeClick | (data: { node: TreeNodeData; key: string | number }) | 点击树节点时触发,不管这个节点能不能选 |
| check | (data: { checkedKeys: (string | number)[]; node: TreeNodeData; key: string | number }) | 多选时勾选或取消勾选节点时触发,checkedKeys 是操作之后的全部 key |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| empty | - | 没有数据或搜索没有结果时的提示,默认是“暂无数据” |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让选择器获得焦点;可搜索并且已展开时聚焦到搜索框 |
| blur | - | void | 让选择器失去焦点 |
ref 上还有一个只读属性 selectedNodes,是当前选中项的列表,每项是 { key, label, node }(node 是数据里对应的节点,找不到时是 null)。
类型
import type { TreeNodeData, FieldNames, TreeSelectSize } from '@ns/ui'
interface TreeNodeData {
id?: string | number
label?: string
children?: TreeNodeData[]
disabled?: boolean
[key: string]: unknown
}
/** props 属性的结构:数据里对应的字段名 */
interface FieldNames {
label?: string
children?: string
disabled?: string
id?: string
}
type TreeSelectSize = 'small' | 'default' | 'large'
注意事项
- 每个节点的 key 在整棵树里必须唯一。
- 单选并且没加
check-strictly时只能选最后一级的节点。绑定值如果是父节点的 key,仍然会显示它的文字,只是用户没法通过点击选到它。 - 多选并且父子关联时,绑定值里父节点和它下面节点的 key 都在,每个 key 显示一个标签。只想要最后一级的话需要自己过滤,或者加
check-strictly让每个节点单独勾选。 - 绑定值里的 key 在
data里找不到时,直接显示这个 key 本身。 - 没有选中项时请用
undefined(多选用[])。 - 选择器默认宽度是 100%,占满父容器。需要固定宽度时用
style或class设置。 - 下拉层通过
Teleport渲染到body下,位置跟随选择器;下方放不下时改为向上弹出。 - 数据需要一次全部传入,不支持展开节点时再加载子节点。
优化点
- [ ] 支持懒加载
- [ ] 支持虚拟滚动
- [ ] 支持拖拽节点
- [ ] 多选时支持折叠标签(像
NsSelect的collapseTags) - [ ] 多选父子关联时支持只返回最后一级(或只返回父节点)的 key
- [ ] 支持自定义节点内容(把
NsTree的默认插槽透传出来) - [ ] 搜索目前只按节点文字匹配,可以增加自定义过滤方法