--- title: Tree subtitle: 树形 group: 数据展示 version: 1.6+ --- ## 介绍用于显示层次结构数据，可展开或折叠。 ## 引入 ```js import Tree from 'sard-uniapp/components/tree/tree.vue' ``` ## 代码演示 ### 基础使用通过 `data` 属性设置数据，通过 `node-keys` 属性告知如何从传入的数据中获取每个节点的数据。 <<< @demo/tree/demo/Basic.vue ### 手风琴对于同一级的节点，每次只能展开一个。 <<< @demo/tree/demo/Accordion.vue ### 可选择的设置 `selectable` 属性可以显示复选框让用户选择节点，还可以禁用节点的选择。节点的 `key` 属性是非常重要的（可以自定义 `key` 的键名），必须保证节点的 `key` 在所有节点中的唯一性。如果没有设置 `key`，则由程序生成一个全局唯一的标识作为 `key`。 <<< @demo/tree/demo/Selectable.vue ### 严格选择在显示复选框的情况下，设置 `check-strictly` 属性来严格遵循父子不互相关联规则。 <<< @demo/tree/demo/CheckStrictly.vue ### 默认展开以及默认选中树节点可以在初始化阶段被设置为展开和选中。 <<< @demo/tree/demo/DefaultExpandedAndChecked.vue ### 单一选择设置 `single-selectable` 属性即可实现单选，选择后会触发 `select` 事件，可使用 `current` 属性设置当前选择的节点。 <<< @demo/tree/demo/Single.vue ### 仅选择叶子节点设置 `leaf-only` 属性让其仅能选择叶子节点。 <<< @demo/tree/demo/LeafOnly.vue ### 可拖拽的设置 `draggable` 属性使节点可拖拽，短按拖拽按钮便可进入拖拽状态；单击拖拽按钮，还可以设置节点的层级。 <<< @demo/tree/demo/Draggable.vue ### 可编辑的设置 `editable` 属性使节点可编辑（增删改），配合 `draggable` 属性便可以随意编辑树形数据。 <<< @demo/tree/demo/Editable.vue ### 异步编辑与拖拽 ^1.26+ 使用 `before-drop` 和 `before-edit` 属性可在节点拖拽或编辑时与远程服务器通信，在接口请求失败时会取消拖拽和编辑。这两属性也可用于同步阻止拖拽或编辑。 <<< @demo/tree/demo/Async.vue ### 树节点过滤树节点是可以被过滤的。调用 `filter` 方法来过滤树节点。方法的参数就是过滤关键字。通过设置 `filter-method` 属性还可以实现自定义的过滤。 <<< @demo/tree/demo/Filter.vue ### 严格的树节点过滤默认的过滤是宽松的，即匹配到一个节点后便停止后代节点的匹配，其后代节点都会被显示出来。设置 `filter-mode="strict"` 进入严格模式，即所有节点都要进行匹配，只有匹配成功的节点才会显示出来。 <<< @demo/tree/demo/StrictFilter.vue ### 懒加载 ^1.24.7+ 设置 `lazy` 属性标识为懒加载，设置 `load` 属性用于获取数据，会在点击节点时调用，当获取的数据为空时，会将点击的节点标识为叶子节点，并隐藏箭头按钮。当然，你也可以提前设置节点是否为叶子节点，以避免为叶子节点时渲染箭头按钮。 <<< @demo/tree/demo/Lazy.vue ## API ### TreeProps | 属性 | 描述 | 类型 | 默认值 | | ---------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------- | | root-class | 组件根元素类名 | string | - | | root-style | 组件根元素样式 | StyleValue | - | | data | 树形数据 | TreeNode[] | - | | node-keys | 节点对象的键名 | TreeNodeKeys | defaultNodeKeys | | default-expand-all | 是否默认展开所有节点 | boolean | false | | default-expanded-keys | 默认展开的节点的 key | `(string \| number)[]` | - | | accordion | 是否每次只展示一个同级树节点 | boolean | false | | selectable | 节点是否可被选择（复选） | boolean | false | | check-strictly | 可选时是否严格遵循父子不关联的做法（复选） | boolean | false | | default-checked-keys | 默认勾选的节点的 key 的数组（复选） | `(string \| number)[]` | - | | single-selectable ^1.17+ | 节点是否可被选择（单选） | boolean | false | | leaf-only ^1.17+ | 是否只能选择叶子节点（单选） | boolean | false | | current (v-model) ^1.17+ | 当前选择的节点的 key（单选） | string \| number | - | | draggable | 是否可以拖拽节点 | boolean | false | | editable | 是否可编辑节点（增删改） | boolean | false | | filter-mode | 节点过滤模式 | 'lenient' \| 'strict' | 'lenient' | | filter-method | 自定义过滤方法 | `(value: string, node: TreeStateNode) => boolean` | - | | lazy ^1.24.7+ | 是否懒加载子节点，需与 load 方法结合使用 | boolean | false | | load ^1.24.7+ | 加载子树数据的方法，仅当 lazy 属性为true 时生效 | `(node?: TreeStateNode) => Promise \| TreeNode[]` | - | | auto-height ^1.25.9+ | 默认只可展示一行文字，设置此属性可让节点高度跟随内容变化，只可用在非拖拽模式 | boolean | false | | allow-drag ^1.26+ | 判断节点能否被拖拽，返回 false 不允许拖拽 | `(node: TreeStateNode) => boolean` | - | | before-drop ^1.26+ | 拖拽完放置前回调，返回 `false` 或 `Promise{}` 可阻止放置 | `(draggingNode: TreeStateNode, dropNode: TreeStateNode, type: TreeDropType) => any \| Promise\` | - | | before-edit ^1.26+ | 节点编辑前回调，返回 `false` 或 `Promise{}` 可阻止编辑 | `(node: TreeStateNode, title: string, type: TreeEditType) => any \| Promise \` | - | | edit-options ^1.26+ | 自定义编辑菜单选项 | TreeEditOption[] | - | ### TreeEmits | 事件 | 描述 | 类型 | | ------------------------------- | ---------------------- | ---------------------------------------------------------- | | update:current ^1.17+ | 选择节点后触发（单选） | `(key: string \| number, node: TreeStateNode) => void` | | select ^1.17+ | 选择节点后触发（单选） | `(key: string \| number, node: TreeStateNode) => void` | | check ^1.24+ | 点击树节点复选框时触发 | `(event: {checked: boolean; node: TreeStateNode}) => void` | | node-click ^1.24.1+ | 点击树节点时触发 | `(event: {event: any; node: TreeStateNode}) => void` | ### TreeExpose | 属性 | 描述 | 类型 | | ------------------ | ---------------------- | ---------------------------------------------------- | | getCheckedKeys | 获取所有选中节点的 key | `() => (string \| number)[]` | | getHalfCheckedKeys | 获取所有半选节点的 key | `() => (string \| number)[]` | | setCheckedKeys | 设置指定节点为选中状态 | `(keys: (string \| number)[]) => void` | | setChecked | 设置节点是否选中 | `(key: string \| number, checked: boolean) => void` | | setExpandedKeys | 设置指定节点为展开状态 | `(keys: (string \| number)[]) => void` | | setExpanded | 设置节点是否展开 | `(key: string \| number, expanded: boolean) => void` | | toggleExpanded | 切换节点展开状态 | `(key: string \| number) => void` | | addRootNode | 添加根节点 | `() => void` | | getCleanTreeData | 获取干净的当前树形数据 | `() => TreeCleanNode[]` | | filter | 过滤树节点 | `(searchString: string) => void` | ### TreeDropType ```ts type TreeDropType = 'before' | 'after' | 'prepend' | 'append' ``` ### TreeEditType ```ts type TreeEditType = 'addSibling' | 'addChild' | 'addRoot' | 'edit' | 'delete' ``` ### TreeEditOption ```ts interface TreeEditOption { type: TreeEditType icon?: string text?: string } ``` ### TreeNode ```ts interface TreeNode { title?: string | number key?: any children?: TreeNode[] disabled?: boolean isLeaf?: boolean [prop: string]: any } ``` ### TreeCleanNode ```ts interface TreeCleanNode { title: string | number key: string | number children?: TreeCleanNode[] } ``` ### TreeStateNode ```ts export interface TreeStateNode { title: string | number key: string | number expanded: boolean checked: boolean children?: TreeStateNode[] parent: TreeStateNode | null indeterminate: boolean level: number offsetLevel: number visible: boolean disabled: boolean isLeaf: boolean loadStatus: 'idle' | 'loading' | 'loaded' depth: number } ``` ### TreeNodeKeys ```ts interface TreeNodeKeys { title?: string key?: string children?: string isLeaf?: string } ``` ### defaultNodeKeys ::: code-group ```ts [ts] const defaultNodeKeys = { title: 'title', key: 'key', children: 'children', isLeaf: 'isLeaf', } ``` ```js [js] const defaultNodeKeys = { title: 'title', key: 'key', children: 'children', isLeaf: 'isLeaf', } ``` ::: ## 主题定制 ### CSS 变量 <<< @comp/tree/variables.scss#variables