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的默认插槽透传出来) - [ ] 搜索目前只按节点文字匹配,可以增加自定义过滤方法