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.
OrganizationChart 组织架构图
按树形数据画出部门、人员的上下级关系:上级在上,下级在下面横向排开,中间用线连起来。节点可以自定义内容、折叠、选中,也可以改成从左到右横着排。
引入
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
基础用法
data 传根节点,每个节点要有唯一的 id,label 是卡片上的文字,children 是下级。卡片默认是白底、细边框、顶上一条主题色,连线用 CSS 画。
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' },
{ id: 'qa', label: '测试组' }
]
},
{
id: 'mk',
label: '市场部',
children: [
{ id: 'east', label: '华东大区' },
{ id: 'south', label: '华南大区' }
]
},
{ id: 'hr', label: '人事部' }
]
}
</script>
<template>
<NsOrganizationChart :data="data" aria-label="星河科技组织架构" />
</template>
多个根节点
data 也可以是数组,几个根节点并排显示,各自是一棵独立的树。
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData[] = [
{
id: 'bj',
label: '北京分公司',
children: [
{ id: 'bj-sales', label: '销售部' },
{ id: 'bj-service', label: '客服部' }
]
},
{
id: 'sh',
label: '上海分公司',
children: [{ id: 'sh-sales', label: '销售部' }]
}
]
</script>
<template>
<NsOrganizationChart :data="data" />
</template>
自定义字段名
数据里的字段名不是 id、label、children、disabled 时,用 props 指定:key 是唯一标识,label 是文字,children 是下级,disabled 是禁用。
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
deptCode: 'HQ',
deptName: '集团总部',
subDepts: [
{ deptCode: 'FIN', deptName: '财务中心' },
{
deptCode: 'OPS',
deptName: '运营中心',
subDepts: [
{ deptCode: 'OPS-1', deptName: '客服部' },
{ deptCode: 'OPS-2', deptName: '物流部' }
]
}
]
}
const fieldNames = { key: 'deptCode', label: 'deptName', children: 'subDepts' }
</script>
<template>
<NsOrganizationChart :data="data" :props="fieldNames" />
</template>
自定义节点
默认插槽自定义卡片里的内容,参数有节点数据 node、层级 level(根节点是 0)、expanded、selected、disabled。卡片的边框、圆角、主题色和选中高亮还在,插槽只管里面放什么。下面每个节点放了头像、姓名和职位,有下属的再显示人数:
<script setup lang="ts">
import { NsAvatar, NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 1,
name: '王建国',
title: '总经理',
children: [
{
id: 2,
name: '李晓明',
title: '技术总监',
children: [
{ id: 4, name: '陈思', title: '前端负责人' },
{ id: 5, name: '赵磊', title: '后端负责人' }
]
},
{
id: 3,
name: '刘芳',
title: '市场总监',
children: [{ id: 6, name: '孙悦', title: '品牌经理' }]
}
]
}
const firstChar = (node: OrganizationChartNodeData) => String(node.name).slice(0, 1)
const count = (node: OrganizationChartNodeData) =>
Array.isArray(node.children) ? node.children.length : 0
</script>
<template>
<NsOrganizationChart :data="data">
<template #default="{ node, level }">
<div class="person">
<NsAvatar :label="firstChar(node)" :size="level === 0 ? 'default' : 'small'" />
<div class="person__text">
<div class="person__name">{{ node.name }}</div>
<div class="person__title">
{{ node.title }}<template v-if="count(node)"> · {{ count(node) }} 人</template>
</div>
</div>
</div>
</template>
</NsOrganizationChart>
</template>
<style scoped>
.person {
display: flex;
gap: var(--ns-spacing-2);
align-items: center;
text-align: left;
}
.person__name {
font-weight: var(--ns-font-weight-semibold);
}
.person__title {
font-size: var(--ns-font-size-sm);
color: var(--ns-text-color-secondary);
white-space: nowrap;
}
</style>
节点类名
node-class 给卡片加类名:传字符串时每个卡片都加,传函数时按节点返回,参数是节点数据和层级,返回值和模板里 class 的写法一样(字符串、数组、对象)。类名加在卡片 .ns-organization-chart__card 上。组件的样式带 scoped,自己的类要写在全局样式里,或者在 scoped 样式里用 :deep(),选择器前面再带一个类,比卡片自己的样式优先。
下面公司用主色底,部门顶上一条绿色,小组顶上一条橙色:
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
type: 'company',
children: [
{
id: 'rd',
label: '研发中心',
type: 'dept',
children: [
{ id: 'fe', label: '前端组', type: 'team' },
{ id: 'be', label: '后端组', type: 'team' }
]
},
{
id: 'mk',
label: '市场部',
type: 'dept',
children: [{ id: 'east', label: '华东大区', type: 'team' }]
}
]
}
const nodeClass = (node: OrganizationChartNodeData) => `org-card--${node.type}`
</script>
<template>
<NsOrganizationChart class="org-chart" :data="data" :node-class="nodeClass" />
</template>
<style scoped>
.org-chart :deep(.org-card--company) {
color: var(--ns-color-white);
background-color: var(--ns-color-primary);
}
.org-chart :deep(.org-card--dept) {
border-top-color: var(--ns-color-success);
}
.org-chart :deep(.org-card--team) {
border-top-color: var(--ns-color-warning);
}
</style>
可折叠
加上 collapsible 后,有下级的节点卡片下边多一个小圆钮,点它展开、收起下级(显示减号时是展开着的)。收起的那一支不渲染。不加 collapsible 时始终全部展开,没有按钮。
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
},
{
id: 'mk',
label: '市场部',
children: [
{ id: 'east', label: '华东大区' },
{ id: 'south', label: '华南大区' }
]
},
{ id: 'hr', label: '人事部' }
]
}
</script>
<template>
<NsOrganizationChart :data="data" collapsible />
</template>
默认展开层级
default-expand-level 是默认展开的层数,根节点算第 1 层:0 时全部收起,只显示根节点;1 时只展开根节点,能看到第 2 层;2 时展开到第 2 层,能看到第 3 层;不传时全部展开。它只决定一开始的状态,下面切换时用 key 让图重新创建。
<script setup lang="ts">
import { ref } from 'vue'
import { NsOrganizationChart, NsSegmented, NsSpace } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{
id: 'fe',
label: '前端组',
children: [
{ id: 'web', label: 'Web 小组' },
{ id: 'app', label: 'App 小组' }
]
},
{ id: 'be', label: '后端组' }
]
},
{
id: 'mk',
label: '市场部',
children: [{ id: 'east', label: '华东大区' }]
}
]
}
const level = ref<string | number>(1)
const options = [
{ label: '0', value: 0 },
{ label: '1', value: 1 },
{ label: '2', value: 2 },
{ label: '不传(全部展开)', value: 'all' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSegmented v-model="level" :options="options" />
<NsOrganizationChart
:key="level"
:data="data"
collapsible
:default-expand-level="level === 'all' ? undefined : Number(level)"
/>
</NsSpace>
</template>
默认展开指定节点
default-expanded-keys 指定一开始展开哪些节点,它们的上级也会跟着展开,其余收起。和 default-expand-level 同时传时,两者指定的节点都展开。下面只展开“前端组”,所以能看到它的两个小组,“市场部”是收起的:
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{
id: 'fe',
label: '前端组',
children: [
{ id: 'web', label: 'Web 小组' },
{ id: 'app', label: 'App 小组' }
]
},
{ id: 'be', label: '后端组' }
]
},
{
id: 'mk',
label: '市场部',
children: [{ id: 'east', label: '华东大区' }]
}
]
}
</script>
<template>
<NsOrganizationChart :data="data" collapsible :default-expanded-keys="['fe']" />
</template>
受控展开和方法
v-model:expanded-keys 双向绑定展开的节点,传了以后由它决定展开状态,default-expand-level、default-expanded-keys 不再起作用。也可以通过 ref 调用方法:expand(key) 展开节点和它的上级,collapse(key) 收起,expandAll()、collapseAll() 全部展开、收起,getExpandedKeys() 读取展开的节点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsOrganizationChart, NsSpace } from '@ns/ui'
import type {
OrganizationChartExpose,
OrganizationChartKey,
OrganizationChartNodeData
} from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
},
{
id: 'mk',
label: '市场部',
children: [
{ id: 'east', label: '华东大区' },
{ id: 'south', label: '华南大区' }
]
}
]
}
const chartRef = ref<OrganizationChartExpose>()
const expandedKeys = ref<OrganizationChartKey[]>(['co'])
const result = ref('')
const read = () => {
result.value = `getExpandedKeys():${JSON.stringify(chartRef.value?.getExpandedKeys())}`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton @click="chartRef?.expandAll()">全部展开</NsButton>
<NsButton @click="chartRef?.collapseAll()">全部收起</NsButton>
<NsButton @click="chartRef?.expand('east')">展开到华东大区</NsButton>
<NsButton @click="chartRef?.collapse('rd')">收起研发中心</NsButton>
<NsButton @click="expandedKeys = ['co', 'mk']">只展开市场部</NsButton>
<NsButton @click="read">读取展开的节点</NsButton>
</NsSpace>
<NsOrganizationChart
ref="chartRef"
v-model:expanded-keys="expandedKeys"
:data="data"
collapsible
/>
<p>v-model:{{ expandedKeys }}</p>
<p>{{ result || '点“读取展开的节点”试试' }}</p>
</NsSpace>
</template>
单选
selection-mode="single" 后点击卡片选中它,选中的卡片是主色边框、浅主色底;点别的节点换成选中别的,再点一次已选中的节点取消选中。用 v-model:selection 拿到选中节点的 key,没选中时是 null。
<script setup lang="ts">
import { ref } from 'vue'
import { NsOrganizationChart, NsSpace } from '@ns/ui'
import type { OrganizationChartNodeData, OrganizationChartSelection } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
},
{ id: 'mk', label: '市场部' },
{ id: 'hr', label: '人事部' }
]
}
const selection = ref<OrganizationChartSelection>('rd')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsOrganizationChart v-model:selection="selection" :data="data" selection-mode="single" />
<p>选中的 key:{{ selection ?? '无' }}</p>
</NsSpace>
</template>
多选
selection-mode="multiple" 后点击卡片在选中和不选中之间切换,可以选多个,v-model:selection 是 key 数组。节点数据里 disabled 为 true 的不能选中,点击也不触发 node-click。
<script setup lang="ts">
import { ref } from 'vue'
import { NsOrganizationChart, NsSpace } from '@ns/ui'
import type { OrganizationChartNodeData, OrganizationChartSelection } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' },
{ id: 'qa', label: '测试组' }
]
},
{ id: 'mk', label: '市场部' },
{ id: 'legal', label: '法务部(停用)', disabled: true }
]
}
const selection = ref<OrganizationChartSelection>(['fe', 'mk'])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsOrganizationChart v-model:selection="selection" :data="data" selection-mode="multiple" />
<p>选中的 key:{{ selection }}</p>
</NsSpace>
</template>
事件
点击、展开、收起、选中都会触发事件,参数里有节点数据 node 和它的 key。下面把最近的几次事件列出来:
node-click:点卡片、或者聚焦节点后按回车、空格时触发,参数还有层级level。点展开按钮、点禁用的节点不触发。node-expand、node-collapse:点按钮、按键展开或收起时触发。调用方法展开、收起时不触发。selection-change:选中的节点变了时触发,selection是操作后的值,nodes是选中的节点数据。
<script setup lang="ts">
import { ref } from 'vue'
import { NsOrganizationChart, NsSpace } from '@ns/ui'
import type {
OrganizationChartNodeClickPayload,
OrganizationChartNodeData,
OrganizationChartNodeTogglePayload,
OrganizationChartSelectionChangePayload
} from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
},
{
id: 'mk',
label: '市场部',
children: [{ id: 'east', label: '华东大区' }]
}
]
}
const events = ref<string[]>([])
const record = (text: string) => {
events.value = [text, ...events.value].slice(0, 6)
}
const onClick = ({ node, level }: OrganizationChartNodeClickPayload) =>
record(`node-click:${node.label}(第 ${level + 1} 层)`)
const onExpand = ({ node }: OrganizationChartNodeTogglePayload) =>
record(`node-expand:${node.label}`)
const onCollapse = ({ node }: OrganizationChartNodeTogglePayload) =>
record(`node-collapse:${node.label}`)
const onSelectionChange = ({ nodes }: OrganizationChartSelectionChangePayload) =>
record(`selection-change:选中 ${nodes.map((node) => node.label).join('、') || '无'}`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsOrganizationChart
:data="data"
collapsible
selection-mode="multiple"
@node-click="onClick"
@node-expand="onExpand"
@node-collapse="onCollapse"
@selection-change="onSelectionChange"
/>
<div>
<p v-if="events.length === 0">点卡片、点展开按钮试试</p>
<p v-for="(text, index) in events" :key="index" style="margin: 0 0 4px">{{ text }}</p>
</div>
</NsSpace>
</template>
横向
direction 是排列方向:vertical(默认)上级在上、下级在下面横向排开;horizontal 上级在左、下级在右边竖着排,适合层级多、每层节点少的结构。横向时展开按钮在卡片右边,键盘的方向也跟着转过来(见“键盘操作”)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsOrganizationChart, NsSegmented, NsSpace } from '@ns/ui'
import type { OrganizationChartDirection, OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' },
{ id: 'qa', label: '测试组' }
]
},
{
id: 'mk',
label: '市场部',
children: [
{ id: 'east', label: '华东大区' },
{ id: 'south', label: '华南大区' }
]
},
{ id: 'hr', label: '人事部' }
]
}
const direction = ref<OrganizationChartDirection>('horizontal')
const options = [
{ label: '竖向(vertical)', value: 'vertical' },
{ label: '横向(horizontal)', value: 'horizontal' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSegmented v-model="direction" :options="options" />
<NsOrganizationChart :data="data" :direction="direction" collapsible />
</NsSpace>
</template>
宽内容滚动
内容比外面宽时,组件里出现横向滚动条;给组件设了高度(或 max-height)时,内容更高也在组件里上下滚动。内容比外面窄时居中显示(横向时靠左)。
focus(key) 方法让节点获得焦点,并把它的卡片滚到能看见的位置;节点被收起看不到时先展开它的上级。下面一个总部带 12 个事业部,点按钮定位到某个事业部并选中它:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsOrganizationChart, NsSpace } from '@ns/ui'
import type {
OrganizationChartExpose,
OrganizationChartKey,
OrganizationChartNodeData,
OrganizationChartSelection
} from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'root',
label: '集团总部',
children: Array.from({ length: 12 }, (_, i) => ({
id: `d${i + 1}`,
label: `第 ${i + 1} 事业部`,
children: [
{ id: `d${i + 1}-product`, label: '产品组' },
{ id: `d${i + 1}-ops`, label: '运营组' }
]
}))
}
const chartRef = ref<OrganizationChartExpose>()
const selection = ref<OrganizationChartSelection>(null)
const locate = (key: OrganizationChartKey) => {
selection.value = key
chartRef.value?.focus(key)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton @click="locate('d1')">定位到第 1 事业部</NsButton>
<NsButton @click="locate('d7')">定位到第 7 事业部</NsButton>
<NsButton @click="locate('d12-ops')">定位到第 12 事业部运营组</NsButton>
</NsSpace>
<NsOrganizationChart
ref="chartRef"
v-model:selection="selection"
:data="data"
selection-mode="single"
collapsible
:default-expand-level="1"
style="max-height: 280px; border: 1px solid var(--ns-border-color-light)"
/>
</NsSpace>
</template>
间距和连线颜色
在组件上覆盖这几个 CSS 变量,调整上下级之间的距离、同一层相邻两支之间的距离和连线颜色:
| 变量 | 默认值 | 说明 |
|---|---|---|
--ns-organization-chart-level-gap | var(--ns-spacing-10) | 上下级卡片之间的距离(横向时是左右),40px |
--ns-organization-chart-node-gap | var(--ns-spacing-4) | 同一层相邻两支之间的距离(横向时是上下),16px |
--ns-organization-chart-line-color | var(--ns-border-color) | 连线和展开按钮边框的颜色 |
<script setup lang="ts">
import { NsOrganizationChart } from '@ns/ui'
import type { OrganizationChartNodeData } from '@ns/ui'
const data: OrganizationChartNodeData = {
id: 'co',
label: '星河科技',
children: [
{
id: 'rd',
label: '研发中心',
children: [
{ id: 'fe', label: '前端组' },
{ id: 'be', label: '后端组' }
]
},
{ id: 'mk', label: '市场部' }
]
}
</script>
<template>
<NsOrganizationChart
:data="data"
style="
--ns-organization-chart-level-gap: 64px;
--ns-organization-chart-node-gap: 40px;
--ns-organization-chart-line-color: var(--ns-color-primary);
"
/>
</template>
键盘操作
整张图只占一个 Tab 停留点:按 Tab 进来时,焦点落在上次聚焦过的节点上;第一次进来、或那个节点已经看不到时,落在第一个能看到的选中节点上,再没有就是第一个根节点。聚焦的卡片有主色焦点框,并会滚到能看见的位置。在图里用方向键移动焦点:
| 按键(竖向) | 按键(横向) | 作用 |
|---|---|---|
| ↑ | ← | 焦点回到上级 |
| ↓ | → | 节点收起着时先展开它;已经展开时焦点移到第一个下级 |
| ←、→ | ↑、↓ | 焦点移到同一层的前一个、后一个能看到的节点,可以跨到别的上级下面 |
| Home、End | Home、End | 焦点移到第一个根节点、最后一个能看到的节点 |
| Enter、空格 | Enter、空格 | 相当于点击卡片:开了 selection-mode 时选中或取消,触发 node-click |
| +、- | +、- | 展开、收起(开了 collapsible 时) |
带 Ctrl、Alt、Meta 的组合键不处理,留给浏览器。焦点在自定义内容里的按钮、输入框上时,按键也留给它们自己。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data | OrganizationChartNodeData | OrganizationChartNodeData[] | null | — | 数据:一个根节点,或者多个根节点组成的数组(并排显示)。null、undefined 时什么都不显示 |
| props | OrganizationChartFieldNames | {} | 自定义节点数据的字段名:key(默认 'id')、label、children、disabled |
| direction | 'vertical' | 'horizontal' | 'vertical' | 排列方向:竖向(上级在上)、横向(上级在左) |
| collapsible | boolean | false | 是否可以折叠。开了以后有下级的节点显示展开、收起按钮;不开时始终全部展开 |
| defaultExpandLevel | number | — | 默认展开的层数,根节点是第 1 层:0 只显示根节点,1 显示到第 2 层。不传(也没传 defaultExpandedKeys)时全部展开 |
| defaultExpandedKeys | OrganizationChartKey[] | — | 默认展开的节点,它们的上级也会展开。和 defaultExpandLevel 同时传时两者都展开 |
| expandedKeys | OrganizationChartKey[] | — | 展开的节点 key,支持 v-model:expanded-keys。传了以后由它决定展开状态 |
| selectionMode | 'single' | 'multiple' | — | 选择模式:单选、多选。不传时节点不能选中 |
| selection | OrganizationChartSelection | — | 选中的节点,支持 v-model:selection。单选时是一个 key 或 null,多选时是 key 数组 |
| nodeClass | OrganizationChartClassValue | ((node: OrganizationChartNodeData, level: number) => OrganizationChartClassValue) | — | 节点卡片的类名。传函数时按节点返回,level 根节点是 0 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| node-click | (data: { node: OrganizationChartNodeData; key: OrganizationChartKey; level: number }) | 点击卡片、按回车或空格时触发。点展开按钮、点禁用的节点不触发 |
| node-expand | (data: { node: OrganizationChartNodeData; key: OrganizationChartKey }) | 点按钮、按键展开节点时触发;调用方法时不触发 |
| node-collapse | (data: { node: OrganizationChartNodeData; key: OrganizationChartKey }) | 点按钮、按键收起节点时触发;调用方法时不触发 |
| selection-change | (data: { selection: OrganizationChartSelection; nodes: OrganizationChartNodeData[] }) | 点击、按键改变选中时触发。nodes 是选中的节点数据,顺序和 selection 一致 |
| update:selection | (value: OrganizationChartSelection) | 选中的值变化时触发,v-model:selection 用 |
| update:expandedKeys | (keys: OrganizationChartKey[]) | 展开的节点变化时触发(点按钮、按键、调用方法都会触发),v-model:expanded-keys 用 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | { node: OrganizationChartNodeData, level: number, expanded: boolean, selected: boolean, disabled: boolean } | 自定义卡片里的内容,不写时显示节点文字。level 根节点是 0 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| expand | (key: OrganizationChartKey) | void | 展开节点,它的上级也会展开 |
| collapse | (key: OrganizationChartKey) | void | 收起节点 |
| expandAll | — | void | 展开全部节点 |
| collapseAll | — | void | 收起全部节点,只显示根节点 |
| getExpandedKeys | — | OrganizationChartKey[] | 当前展开着的、有下级的节点 key。不开 collapsible 时是全部有下级的节点 |
| focus | (key?: OrganizationChartKey) | void | 让节点获得焦点,并把卡片滚到能看见的位置;被收起看不到时先展开它的上级。不传时聚焦 Tab 停留的节点 |
类型
import type {
OrganizationChartKey,
OrganizationChartDirection,
OrganizationChartSelectionMode,
OrganizationChartSelection,
OrganizationChartNodeData,
OrganizationChartFieldNames,
OrganizationChartClassValue,
OrganizationChartProps,
OrganizationChartSlotProps,
OrganizationChartNodeClickPayload,
OrganizationChartNodeTogglePayload,
OrganizationChartSelectionChangePayload,
OrganizationChartExpose
} from '@ns/ui'
type OrganizationChartKey = string | number
/** 单选时是一个 key(没选中时是 null),多选时是 key 数组 */
type OrganizationChartSelection = OrganizationChartKey | OrganizationChartKey[] | null
interface OrganizationChartNodeData {
id?: OrganizationChartKey
label?: string
children?: OrganizationChartNodeData[]
disabled?: boolean
/** 可以带任意其他字段,自定义节点内容时能用到 */
[key: string]: unknown
}
/** props 属性的结构:数据里对应的字段名 */
interface OrganizationChartFieldNames {
key?: string
label?: string
children?: string
disabled?: string
}
注意事项
- 每个节点的 key 在整张图里必须唯一。没有 key 的节点按它在数据里的位置生成 key,key 重复时后出现的节点也这样处理,控制台都会警告一次;数据换了位置以后,按位置生成的 key 会变,选中、展开就对不上了。
defaultExpandLevel、defaultExpandedKeys只在节点第一次出现下级时生效,之后改它们不会重新展开或收起;数据是后来才加载的也一样生效。要重新应用默认值时给组件换一个key。- 不开
collapsible时始终全部展开,defaultExpandLevel、defaultExpandedKeys、expandedKeys和展开收起的方法都看不出效果。 - 传了
expandedKeys(或selection)时完全由它决定展开(选中)状态;只监听update:expandedKeys(update:selection)而不更新它,界面不会变。 - 单选时再点一次已选中的节点会取消选中。单选传了数组时只取第一个,多选传了单个值时按只选了它处理,控制台会警告。
- 禁用(
disabled)只影响选中和点击,禁用的节点照样能展开、收起,也能用方向键聚焦。 - 展开、收起按钮不占 Tab 停留点,读屏软件也不读它;键盘用 ↓(横向时 →)和 +、- 展开收起,节点的展开状态通过
aria-expanded告诉读屏软件。 - 根元素是
role="tree"的滚动容器,写在组件上的class、style、aria-label都落在它上面。图里只有一棵树时,建议用aria-label给它起个名字。 - 节点的名称取卡片里的内容(
aria-labelledby),不会把下级的文字也读进来。自定义内容里只有图片时,记得给图片写alt。 - 卡片宽度跟着内容走,同一层的卡片不会自动等宽;要等宽时用
node-class给卡片设width。卡片文字默认不折行,内容很长时设一个宽度让它折行。 - 节点很多(上千个)时一次全部渲染会慢,可以开
collapsible并用default-expand-level只展开前几层。