开发预览更新于 2026-05-10

TreeView 树形列表

嵌套树形展示，支持单选 / 复选框（带级联）、展开 / 折叠、自定义图标。

基础用法

nodes 是一棵树（每个节点可有 children）。selectedKey + update:selectedKey 控制单选高亮；defaultExpandedKeys 设置初始展开的节点 key。disabled 节点不响应点击。

src
- components
  - Home.vue
  - About.vue
  - Contact.vue
- main.ts
- styles.css
README.md

<script setup lang="ts">
import { ref } from 'vue';
import { CfTreeView, type TreeNode } from '@chufix-design/vue';

const selected = ref<string | null>('home');

const nodes: TreeNode[] = [
{
  key: 'src',
  label: 'src',
  children: [
    {
      key: 'components',
      label: 'components',
      children: [
        { key: 'home', label: 'Home.vue' },
        { key: 'about', label: 'About.vue' },
        { key: 'contact', label: 'Contact.vue', disabled: true },
      ],
    },
    { key: 'main', label: 'main.ts' },
    { key: 'styles', label: 'styles.css' },
  ],
},
{ key: 'readme', label: 'README.md' },
];
</script>

<template>
<CfTreeView
  :nodes="nodes"
  :selected-key="selected"
  :default-expanded-keys="['src', 'components']"
  @update:selected-key="selected = $event"
/>
</template>

import { useState } from 'react';
import { CfTreeView, type TreeNode } from '@chufix-design/react';

const nodes: TreeNode[] = [/* ... */];

export default function Demo() {
const [selected, setSelected] = useState<string | null>('home');
return (
  <CfTreeView
    nodes={nodes}
    selectedKey={selected}
    defaultExpandedKeys={['src', 'components']}
    onSelectedKeyChange={setSelected}
  />
);
}

复选框 + 级联

checkable 在每个节点前加复选框，配合 v-model (Vue) / value + onChange (React) 绑定 string[]。cascade=true（默认）让父子勾选互相联动 — 勾父勾全部子节点，勾全部子节点反过来勾父；半选状态自动算 indeterminate。

cascade=false 时各节点独立，常用于按行业 / 标签多选场景。

<CfTreeView v-model="checked" :nodes="nodes" checkable />

<!-- 关闭级联 -->
<CfTreeView v-model="checked" :nodes="nodes" checkable :cascade="false" />

<CfTreeView nodes={nodes} value={checked} onChange={setChecked} checkable />

{/* 关闭级联 */}
<CfTreeView nodes={nodes} value={checked} onChange={setChecked} checkable cascade={false} />

三档尺寸

size 控制节点行高与字号 — sm 紧凑（侧栏文件树常用）/ md 默认 / lg 大号触摸友好。

size = sm

src
- main.ts
- App.vue
package.json

size = md

src
- main.ts
- App.vue
package.json

size = lg

src
- main.ts
- App.vue
package.json

<CfTreeView size="sm" :nodes="nodes" />
<CfTreeView size="md" :nodes="nodes" />
<CfTreeView size="lg" :nodes="nodes" />

<CfTreeView size="sm" nodes={nodes} />
<CfTreeView size="md" nodes={nodes} />
<CfTreeView size="lg" nodes={nodes} />

隐藏连接线

showLine={false} 关掉父子之间的虚线 — 视觉更干净，常配合自定义 icon 使用。

src
- components
  - Home.vue
  - About.vue
- main.ts

<CfTreeView :nodes="nodes" :show-line="false" />

<CfTreeView nodes={nodes} showLine={false} />

API

Prop	类型	默认值	说明
`nodes`	`TreeNode[]`	`[]`	树形数据
`modelValue` (Vue) / `value` (React)	`string[]`	`[]`	已勾选的 key（仅 checkable）
`expandedKeys` / `defaultExpandedKeys`	`string[]`	`—`	受控 / 非受控的展开列表
`selectedKey`	`string \| null`	`null`	当前单选的 key
`checkable`	`boolean`	`false`	显示复选框
`cascade`	`boolean`	`true`	父子勾选联动
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	字号 + 内距
`showLine`	`boolean`	`true`	显示嵌套连接线
`emptyText`	`string \| ReactNode`	`'暂无数据'`	空状态文案

TreeNode：

interface TreeNode {
  key: string;
  label: string;
  icon?: VNode | ReactNode;
  children?: TreeNode[];
  disabled?: boolean;
  selectable?: boolean;
  isLeaf?: boolean;
}

事件：update:modelValue / update:expandedKeys / update:selectedKey / select / expand / check（React 端：onChange / onExpandedKeysChange / onSelectedKeyChange / onSelect / onExpand / onCheck）。