# infogo-tree [在线 demo](https://ui.infogo.tech/ctree/) ## 安装 ### yarn 安装方式 ```bash yarn add infogo-tree ``` ### npm 安装方式 ```bash npm install infogo-tree ``` ### 样式引入 直接引入 css ```less @import 'infogo-tree/dist/ctree.css'; ``` 引入 less 以便于变量覆盖 ```less @import 'infogo-tree/src/styles/index.less'; ``` ## CTree API ### CTree Props | 属性 | 说明 | 类型 | 默认值 | | :---------------------- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- | :-------------------- | | value | 选中的值，可用 v-model ；单选为字符串或数字，多选为 `separator` 分隔的字符串或数组，优先多选 | `string \| number \| Array` | 无 | | data | 传入的树数据。数据量大时，不建议通过 props 传入数据，建议用 `setData` 方法代替 | `object[]` | [] | | unloadDataList | 供未加载且选中节点查询 title 字段值用的列表，格式与 `data` 一致即可 | `object[]` | [] | | showUnloadCheckedNodes | 过滤已选时是否在列表后面展示未加载的已选节点 | `boolean` | true | | emptyText | 数据为空时显示的文本 | `string` | '暂无数据' | | titleField | 节点标题字段 | `string` | 'title' | | keyField | 节点唯一标识字段 | `string` | 'id' | | childStr | 子数据标识字段 | `string` | 'children' | | disabledFn | 禁用拓展方法 | `string` | (node): boolean => {} | | separator | 多选模式下 value 分隔符 | `string` | ',' | | replenishSelect | 是否需要补全未渲染节点(初始化时，常用于补全子节点) | `boolean` | false | | checkable | 是否可多选 | `boolean` | false | | selectable | 是否可单选 | `boolean` | false | | filteredNodeCheckable | 是否可勾选被过滤节点 | `boolean` | false | | cascade | 父子节点是否关联 | `boolean` | true | | enableLeafOnly | 是否只启用子节点，当 `多选且父子不关联` 或 `单选` 时有效 | `boolean` | false | | cascadeLoose | 不严格的父子关联，父选中，子全选，子全选，父不选中，当 `多选且父子关联`时有效 | `boolean` | false | | disableAll | 是否禁用所有节点 | `boolean` | false | | defaultExpandAll | 是否默认展开所有节点 | `boolean` | false | | [] | | expandedKeys | 展开的节点 key ，组件内部将会响应此 Prop 的变化 | `Array` | [] | | draggable | 是否可拖拽 | `boolean` | false | | droppable | 是否可放置 | `boolean` | false | | beforeDropMethod | 在放置节点之前执行的方法，返回 true 允许放置， false 可阻止放置 | `(dragKey: string \| number, dropKey: string \| number, hoverPart: 'before' \| 'body' \| 'after') => boolean` | `() => true` | | ignoreMode | 忽略模式，指定 `getCheckedNodes`, `getCheckedKeys` 与 `v-model` 默认要忽略的部分 | `'none' \| 'parents' \| 'children'` | 'none' | | autoLoad | 异步加载初始化时是否自动加载根节点 | `boolean` | true | | load | 异步加载方法 | `(node: null \| TreeNode, resolve: Function, reject: Function) => any` | 无 | | render | 节点渲染 render 函数 | `(h: CreateElement, node: TreeNode) => VNode` | 无 | | filterMethod | 节点过滤方法 | `(keyword: string, node: TreeNode) => boolean` | 无 | | expandOnFilter `2.1.0` | 过滤时是否展开所有可见节点 | `boolean` | true | | unselectOnClick `2.1.0` | 点击已选中节点是否取消选中 | `boolean` | true | | loading | 是否显示 loading 图标 | `boolean` | false | | nodeClassName | 节点根元素的 class ，传入函数以对每个节点定制 class | `string \| object \| Array \| (node: TreeNode) => string \| object \| Array` | 无 | | nodeMinHeight | 根据节点最小高度计算数据总高度 | `number` | 30 | | nodeIndent | 子节点缩进 | `number` | 20 | | renderNodeAmount | 渲染节点数量，可见节点数大于此值且高度超过(容器可视高度能容纳节点数 + bufferNodeAmount)则不会渲染所有可见节点 | `number` | 100 | | bufferNodeAmount | 当滚动到视野外的节点个数大于此值时刷新渲染节点 | `number` | 20 | ### CTree Events 注：从 `2.0.8` 起，事件中返回的节点信息都是包括 `_parent` 与 `children` 的完整节点信息（拖拽事件的 `dataTransfer` 除外）。 | 事件名 | 说明 | 返回值 | | :--------------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------ | | input | 选中节点改变时触发 | 选中的节点 | | expand | 展开/折叠时触发 | 节点信息 | | check | 勾选时触发（多选） | 被勾选的节点信息 | | uncheck | 取消勾选时触发（多选） | 被取消勾选的节点信息 | | checked-change | 勾选/取消勾选时触发（多选） | 所有被勾选节点（数组） | | select | 选中时触发（单选） | 被选中的节点信息 | | unselect | 取消选中时触发（单选） | 被取消选中的节点信息 | | selected-change | 选中/取消选中时触发（单选） | 被选中节点 | | click | 点击节点时触发 | 节点信息 | | node-dblclick | 双击节点时触发 | 节点信息 | | node-right-click | 右击节点时触发 | 节点信息 | | node-dragstart | 开始拖拽节点时触发 | 节点信息, 拖拽事件对象 | | node-dragenter | dragenter 时触发 | 节点信息 , 拖拽事件对象, 事件触发的节点部位 `'before' \| 'body' \| 'after'` | | node-dragover | dragover 时触发 | 节点信息 , 拖拽事件对象, 事件触发的节点部位 `'before' \| 'body' \| 'after'` | | node-dragleave | dragleave 时触发 | 节点信息 , 拖拽事件对象, 事件触发的节点部位 `'before' \| 'body' \| 'after'` | | node-drop | 放置节点时触发 | 结束拖拽时最后进入的节点信息 , 拖拽事件对象, 被拖拽节点的放置位置 `'before' \| 'body' \| 'after'`, 被拖拽节点的信息 | ### CTree Methods | 方法 | 说明 | 参数 | 返回值 | | :--------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- | | setData | 使用此方法重置树数据，可避免大量数据被 vue 监听 | `data: object[]`: 同 data Prop | `void` | | setChecked | 设置多选选中/取消选中 | `key: string \| number`: 节点 key
`value: boolean`: 是否选中 | `void` | | setCheckedKeys | 批量设置选中/取消选中 | `keys: Array`: 节点 key
`value: boolean`: 是否选中 | `void` | | checkAll | 设置所有数据全选 | 无 | `void` | | clearChecked | 清空选中 | 无 | `void` | | setSelected | 设置单选选中/取消选中 | `key: string \| number`: 节点 key
`value: boolean`: 是否选中 | `void` | | setExpand | 设置展开/折叠 | `key: string \| number`: 节点 key
`value: boolean`: 是否展开
`expandParent: boolean = true`: 如果是展开是否同时展开父节点 `2.0.6` | `void` | | setExpandKeys | 批量展开/折叠 | `keys: Array`: 节点 key
`value: boolean`: 是否展开 | `void` | | setExpandAll | 设置全部展开/折叠 | `value: boolean`: 是否展开 | `void` | | getCheckedNodes | 获取多选选中节点 | `ignoreMode: 'none' \| 'parents' \| 'children'`: 需要忽略的部分，默认为 ignoreMode Prop | `TreeNode[]` | | getCheckedKeys | 获取多选选中节点 key | `ignoreMode: 'none' \| 'parents' \| 'children'`: 需要忽略的部分，默认为 ignoreMode Prop | `Array` | | getIndeterminateNodes | 获取半选状态的节点 | 无 | `TreeNode[]` | | getSelectedNode | 获取单选选中节点 | 无 | `TreeNode \| null` | | getSelectedKey | 获取单选选中节点 key | 无 | `TreeNode \| null` | | getExpandNodes | 获取展开的节点 | 无 | `TreeNode[]` | | getExpandKeys | 获取展开的节点 key | 无 | `TreeNode[]` | | getCurrentVisibleNodes | 获取当前可见的节点 | 无 | `TreeNode[]` | | getNode | 根据 key 获取节点 | `key: string \| number`: 节点 key | `TreeNode \| null` | | getTreeData | 获取树形结构的节点数据 | 无 | `TreeNode[]` | | getFlatData | 获取扁平化后的节点数据 | 无 | `TreeNode[]` | | getNodesCount | 获取节点总数量 | 无 | `number` | | insertBefore | 在参照节点前插入一个节点 | `insertedNode`: 节点 key 或者单个节点数据
`referenceKey: string \| number`: 参照节点 key | `TreeNode \| null` 返回插入的节点 | | insertAfter | 在参照节点后插入一个节点 | `insertedNode`: 节点 key 或者单个节点数据
`referenceKey: string \| number`: 参照节点 key | `TreeNode \| null` 返回插入的节点 | | append | 在父节点第一层子节点的末尾插入一个节点 | `insertedNode`: 节点 key 或者单个节点数据
`parentKey: string \| number`: 父节点 key | `TreeNode \| null` 返回插入的节点 | | prepend | 在父节点第一层子节点的开头插入一个节点 | `insertedNode`: 节点 key 或者单个节点数据
`parentKey: string \| number`: 父节点 key | `TreeNode \| null` 返回插入的节点 | | remove | 删除节点 | `removedKey: string \| number`: 要删除的节点 key | `TreeNode \| null` 返回删除的节点 | | filter | 过滤节点 | `keyword: string`: 过滤关键词
`filterMethod: (keyword: string, node: TreeNode) => boolean`: 过滤方法，默认为 filterMethod Prop ，如果没有传 filterMethod Prop 则为搜索 title 字段的一个内置方法 | `void` | | showCheckedNodes | 展示已选节点 | `showUnloadCheckedNodes: boolean`: 是否显示未加载的选中节点，默认为 Prop 传入的值 | `void` | | loadRootNodes | 从远程加载根节点 | 无 | `Promise` | | scrollTo | 滚动到指定节点位置 | `key: string \| number`: 节点 key
`verticalPosition: 'top' \| 'center' \| 'bottom' \| number`: 滚动的垂直位置 | `void` | ### CTree Slots | 名称 | 说明 | | :------ | :--------------- | | empty | 暂无数据 | | loading | 加载中显示的图标 | ### CTree Data Fields 注：以 '`_`' 开头的字段最好不要覆盖，以免影响内部处理逻辑 | 字段 | 说明 | | :-------------- | :------------------------------------------------------------------------------ | | id | 默认以 'id' 作为 key 字段，也可以通过 `keyField` Prop 指定其他字段作为 key 字段 | | title | 默认显示的名称，可通过 `titleField` Prop 指定其他字段作为 title 字段 | | checked | 多选模式下是否勾选 | | selected | 单选模式下是否选中 | | indeterminate | 多选模式下是否半选状态 | | disabled | 是否禁用 | | expand | 父节点有效，节点展开状态 | | visible | 是否可见 | | \_filterVisible | 过滤后是否可见，如果为 false 则在其他可见情况下也是不可见的 | | \_parent | 父节点 | | children | 子节点数组 | | isLeaf | 标记节点是否为叶子节点 | | \_level | 节点层级，默认从 0 开始 | | \_loading | 节点是否正在加载 | | \_loaded | 节点是否已经加载过，异步加载下有效 | ## CTreeSearch API ### CTreeSearch Props 注：可在 `CTreeSearch` 上直接使用 `CTree` 的所有 Props | 属性 | 说明 | 类型 | 默认值 | | :------------------- | :--------------------------------------------------------------------------------- | :------------------------------------------- | :------------------------------------------------ | | searchPlaceholder | 搜索输入框的 placeholder | `string` | '搜索关键字' | | diyText | 自定义文字 | `object` | {selectAll: '全选', selected: '已选', num: '个',} | | showCheckAll | 是否显示全选复选框 | `boolean` | true | | isTree | 数据是否是树形 | `boolean` | true | | showCheckedButton | 是否显示已选按钮 | `boolean` | true | | checkedButtonText | 已选按钮文字 | `string` | '已选' | | showFooter | 是否显示底部信息 | `boolean` | true | | searchMethod `2.0.2` | 如果传入此 Prop ，触发 `search` 事件后将会执行此方法，否则会执行组件内置的搜索方法 | `(keyword: string) => void \| Promise` | 无 | | searchLength | 触发搜索的字符长度 | `number` | 1 | | searchDisabled | 禁用搜索功能 | `boolean` | false | | searchRemote | 是否远程搜索，传入 `searchMethod` 时无效 | `boolean` | false | | searchDebounceTime | 搜索防抖时间，单位为毫秒 | `number` | 300 | ### CTreeSearch Events 注：可在 `CTreeSearch` 上直接监听 `CTree` 的所有 Events | 事件名 | 说明 | 返回值 | | :----- | :----------------- | :----------- | | search | 执行搜索操作时触发 | 搜索的关键字 | ### CTreeSearch Methods 注：可在 `CTreeSearch` 上直接调用 `CTree` 的所有 Methods | 方法 | 说明 | 参数 | 返回值 | | :----------- | :------------- | :------------------------------------------------------- | :-------------- | | clearKeyword | 清空关键字 | 无 | `void` | | getKeyword | 获取搜索关键字 | 无 | `string` | | search | 执行搜索 | `keyword: string`: 搜索的关键字，默认为内部 this.keyword | `Promise` | ### CTreeSearch Slots 注：可在 `CTreeSearch` 上直接传入 `CTree` 的所有 Slots | 名称 | 说明 | | :----------- | :------------------------------------------------- | | search-input | 搜索输入框，可通过此 slot 自行封装树搜索组件的行为 | | actions | 操作按钮，可在搜索输入框后加入更多操作按钮 | | footer | 底部信息 | ## CTreeDrop API ### CTreeDrop Props 注：可在 `CTreeDrop` 上直接使用 `CTree` 和 `CTreeSearch` 的所有 Props | 属性 | 说明 | 类型 | 默认值 | | :------------------------- | :------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :------------- | | dropHeight | 下拉内容高度 | `number` | 300 | | dropPlaceholder | 展示输入框 placeholder | `string` | 无 | | selectShowField | 输入框 展示选中的文本字段 不传默认为 title | `string` | 无 | | dropDisabled | 是否禁用 | `boolean` | false | | isTree | 数据是否是树形 | `boolean` | true | | clearable | 允许清空 | `boolean` | false | | collapseTags | 多选标签是否合并 | `boolean` | true | | showTagClose | 多选标签是否可以删除 | `boolean` | false | | placement | 下拉弹出框位置，注意！！不支持自动识别方向 | `'bottom-start' \| 'bottom-end' \| 'bottom' \| 'top-start' \| 'top-end' \| 'top'` | 'bottom-start' | | transfer | 将下拉 DOM 转移到 body 中 | `boolean` | false | | dropdownClassName | 在下拉框容器上额外添加的 class | `string \| string[]` | 无 | | dropdownMinWidth `2.0.1` | 下拉框容器最小宽度，未指定则默认为展示输入框宽度。 适合 transfer 为 false 时使用 | `number` | 无 | | dropdownWidthFixed `2.0.5` | 固定下拉框容器宽度，当内容超出最小宽度不会伸长，而是出现横向滚动条 | `boolean` | false | ### CTreeDrop Events 注：可在 `CTreeDrop` 上直接监听 `CTree` 和 `CTreeSearch` 的所有 Events | 事件名 | 说明 | 返回值 | | :---------------------- | :--------------------- | :------------- | | dropdown-visible-change | 下拉框出现或消失时触发 | 下拉框是否可见 | | clear | 点击清空按钮时触发 | 无 | ### CTreeDrop Methods 注：可在 `CTreeDrop` 上直接调用 `CTree` 和 `CTreeSearch` 的所有 Methods ### CTreeDrop Slots 注：可在 `CTreeDrop` 上直接传入 `CTree` 和 `CTreeSearch` 的所有 Slots | 名称 | 说明 | | :------ | :--------------------------------------------------- | | 默认 | 展示输入框 | | display | 展示输入框的展示文字，如果有默认 slot 则此 slot 无效 | | clear | 替换清空图标，如果有默认 slot 则此 slot 无效 | 默认 slot 与 display slot 的 Slot Props `2.3.0` ： ```typescript /** 展示 slot 的 props */ slotProps: { /** 多选选中的节点 */ checkedNodes: [] as TreeNode[], /** 多选选中的节点 key */ checkedKeys: [] as Array, /** 单选选中的节点 */ selectedNode: null as TreeNode | null, /** 单选选中的节点 key */ selectedKey: null as string | number | null, }, ``` **注意**： `checkedNodes` 与 `selectedNode` 只包含已加载的节点，如果设置了选中的值（比如设置了 `value` Prop），但没有设置树的数据，则这两个字段内容将为空；而 `checkedKeys` 与 `selectedKey` 则会包含未加载的选中节点 key 。