添加树结构组件

2026-02-02 13:46:36 +08:00
parent 55ea9d72c5
commit fc089395c9
7 changed files with 976 additions and 5 deletions
--- a/Web/Vue/CubeLib/README.md
+++ b/Web/Vue/CubeLib/README.md
@@ -305,6 +305,196 @@ const handleStatusChanged = (newStatus) => {
 - [自动重连示例](examples/CubeWebSocket/AutoReconnectExample.vue)
 - [消息队列示例](examples/CubeWebSocket/MessageQueueExample.vue)

+### CubeTreeView
+
+树形视图组件，用于展示层级数据结构，支持展开/折叠、键盘导航、自定义样式等功能。
+
+#### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|---------|
+| data | 树形数据数组 | Array | [] |
+| selectedId | 当前选中的节点ID | String | '' |
+| config | 组件配置对象 | Object | 见下方配置说明 |
+| iconMap | 自定义图标映射 | Object | - |
+
+#### Config 配置对象
+
+| 配置项 | 说明 | 类型 | 默认值 |
+|--------|------|------|---------|
+| defaultExpandAll | 是否默认展开所有节点 | Boolean | false |
+| showExpandIcon | 是否显示展开/折叠图标 | Boolean | true |
+| indentSize | 缩进大小（像素） | Number | 16 |
+| expandable | 是否允许展开/折叠 | Boolean | true |
+| iconType | 图标类型：'custom'、'file'、'heading' | String | 'custom' |
+| showLevel | 是否显示层级前缀 | Boolean | false |
+| levelPrefix | 层级前缀文本 | String | 'H' |
+| levelKey | 层级字段名 | String | 'level' |
+| autoExpand | 选中节点时是否自动展开路径 | Boolean | false |
+| highlightPath | 是否高亮选中节点的路径 | Boolean | false |
+
+#### Events
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| node-click | 节点被点击 | item |
+| toggle-expand | 节点展开/折叠状态变化 | itemId |
+
+#### Methods
+
+| 方法名 | 说明 | 参数 | 返回值 |
+|--------|------|------|--------|
+| expandAll | 展开所有节点 | - | void |
+| collapseAll | 折叠所有节点 | - | void |
+| expandNode | 展开指定节点 | id | void |
+| collapseNode | 折叠指定节点 | id | void |
+| toggleNode | 切换节点展开/折叠状态 | id | void |
+| expandPath | 展开到指定节点的路径 | id | void |
+| collapsePath | 折叠到指定节点的路径 | id | void |
+| getNodeById | 根据ID获取节点 | id | Object |
+| getSelectedNode | 获取当前选中的节点 | - | Object |
+| selectNode | 选中指定节点 | id | void |
+
+#### Slots
+
+| 插槽名 | 说明 | 作用域参数 |
+|--------|------|-----------|
+| icon | 自定义节点图标 | { item } |
+| title | 自定义节点标题 | { item } |
+| prefix | 自定义节点前缀 | { item } |
+| suffix | 自定义节点后缀 | { item } |
+
+#### 使用示例
+
+```vue
+<template>
+  <div class="tree-container">
+    <CubeTreeView
+      ref="treeViewRef"
+      :data="treeData"
+      :selected-id="selectedId"
+      :config="treeConfig"
+      @node-click="handleNodeClick"
+      @toggle-expand="handleToggleExpand"
+    >
+      <template #icon="{ item }">
+        <span class="custom-icon">{{ item.icon }}</span>
+      </template>
+      <template #title="{ item }">
+        <span class="custom-title">{{ item.title }}</span>
+      </template>
+    </CubeTreeView>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { CubeTreeView } from 'joyd.web.vue.cubelib'
+
+const treeViewRef = ref(null)
+const selectedId = ref('')
+
+const treeData = ref([
+  {
+    id: '1',
+    title: '根节点1',
+    level: 1,
+    children: [
+      {
+        id: '1-1',
+        title: '子节点1-1',
+        level: 2,
+        children: [
+          { id: '1-1-1', title: '叶子节点1-1-1', level: 3 },
+          { id: '1-1-2', title: '叶子节点1-1-2', level: 3 }
+        ]
+      },
+      {
+        id: '1-2',
+        title: '子节点1-2',
+        level: 2,
+        children: [
+          { id: '1-2-1', title: '叶子节点1-2-1', level: 3 }
+        ]
+      }
+    ]
+  },
+  {
+    id: '2',
+    title: '根节点2',
+    level: 1,
+    children: [
+      { id: '2-1', title: '子节点2-1', level: 2 }
+    ]
+  }
+])
+
+const treeConfig = {
+  defaultExpandAll: false,
+  showExpandIcon: true,
+  indentSize: 16,
+  expandable: true,
+  iconType: 'custom',
+  showLevel: false,
+  autoExpand: true,
+  highlightPath: true
+}
+
+const handleNodeClick = (item) => {
+  console.log('节点被点击:', item)
+  selectedId.value = item.id
+}
+
+const handleToggleExpand = (itemId) => {
+  console.log('节点展开/折叠:', itemId)
+}
+</script>
+
+<style scoped>
+.tree-container {
+  width: 300px;
+  padding: 16px;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+}
+
+.custom-icon {
+  margin-right: 8px;
+  font-size: 16px;
+}
+
+.custom-title {
+  font-size: 14px;
+}
+</style>
+```
+
+#### 键盘导航
+
+CubeTreeView 支持以下键盘操作：
+
+- `↑` - 向上移动选择
+- `↓` - 向下移动选择
+- `←` - 折叠当前节点或选择父节点
+- `→` - 展开当前节点或选择第一个子节点
+- `Enter` / `Space` - 触发节点点击事件
+
+#### CSS 变量
+
+CubeTreeView 组件支持通过 CSS 变量进行定制：
+
+```css
+:root {
+  --cube-tree-item-hover-bg: rgba(0, 0, 0, 0.05);
+  --cube-tree-item-selected-bg: #1890ff;
+  --cube-tree-item-selected-color: #ffffff;
+  --cube-tree-item-path-bg: rgba(24, 144, 255, 0.1);
+  --cube-tree-item-icon-color: rgba(0, 0, 0, 0.45);
+  --cube-tree-item-level-color: rgba(0, 0, 0, 0.45);
+  --cube-tree-item-title-color: inherit;
+}
+```
+
 ## 常见问题解答

 ### Q: 如何保存分隔条的位置？