更新记录

1.0.0（2026-01-29） 下载此版本

组织树组件

平台兼容性

uni-app(4.17)

ft-org-tree

OrgTree 组织树形结构组件 API 文档

# OrgTree 组织树形结构组件

一个功能完整的树形结构组件，支持单选/多选、默认展开层级、默认选中、搜索过滤等功能。

## 基础用法

```vue
<template>
  <org-tree
    :data="treeData"
    mode="single"
    :default-expand-level="2"
    @change="handleChange"
  />
</template>

<script>
import OrgTree from '@/components/org-tree/org-tree.vue'

export default {
  components: { OrgTree },
  data() {
    return {
      treeData: [
        {
          id: '1',
          name: '总公司',
          children: [
            { id: '1-1', name: '技术部' },
            { id: '1-2', name: '产品部' }
          ]
        }
      ]
    }
  },
  methods: {
    handleChange(nodes) {
      console.log('选中的节点:', nodes)
    }
  }
}
</script>

数据结构

TreeNode 节点数据结构

示例：

const treeData = [
  {
    id: '1',
    name: '总公司',
    children: [
      {
        id: '1-1',
        name: '技术部',
        children: [
          { id: '1-1-1', name: '前端组' },
          { id: '1-1-2', name: '后端组' },
          { id: '1-1-3', name: '测试组', disabled: true }
        ]
      },
      {
        id: '1-2',
        name: '产品部',
        isLeaf: true  // 标记为叶子节点
      }
    ]
  }
]

Props 属性

基础属性

展开控制

defaultExpandLevel 取值说明：

选中控制

checkStrictly 说明：

• false（默认）：父子关联，选中父节点会自动选中所有子节点，子节点全选时父节点自动选中
• true：父子不关联，父节点和子节点的选中状态互不影响

外观配置

功能开关

Events 事件

change

选中状态变化时触发（推荐使用）

<org-tree @change="handleChange" />

handleChange(selectedNodes) {
  // selectedNodes: Array<TreeNode> - 当前选中的所有节点数组
  console.log('选中的节点:', selectedNodes)
}

select

单选模式下选中节点时触发

<org-tree mode="single" @select="handleSelect" />

handleSelect({ node, nodeId, selected, selectedNodes }) {
  // node: TreeNode - 当前操作的节点
  // nodeId: string | number - 节点ID
  // selected: boolean - 是否选中
  // selectedNodes: Array<TreeNode> - 当前选中的所有节点
}

check

多选模式下勾选节点时触发

<org-tree mode="multiple" :show-checkbox="true" @check="handleCheck" />

handleCheck({ node, nodeId, checked, checkedNodes }) {
  // node: TreeNode - 当前操作的节点
  // nodeId: string | number - 节点ID
  // checked: boolean - 是否勾选
  // checkedNodes: Array<TreeNode> - 当前勾选的所有节点
}

expand

展开或折叠节点时触发

<org-tree @expand="handleExpand" />

handleExpand({ nodeId, expanded, expandedKeys }) {
  // nodeId: string | number - 节点ID
  // expanded: boolean - 是否展开
  // expandedKeys: Array<string | number> - 当前展开的所有节点ID
}

Methods 方法

通过 ref 调用组件方法：

<template>
  <org-tree ref="treeRef" :data="treeData" />
  <button @click="handleGetSelected">获取选中</button>
</template>

<script>
export default {
  methods: {
    handleGetSelected() {
      const nodes = this.$refs.treeRef.getSelectedNodes()
      console.log(nodes)
    }
  }
}
</script>

获取数据

设置数据

展开控制

其他

使用示例

示例1：单选模式

<template>
  <org-tree
    :data="treeData"
    mode="single"
    :default-expand-level="2"
    :default-selected-ids="['1-1']"
    :searchable="true"
    @change="handleChange"
  />
</template>

<script>
export default {
  methods: {
    handleChange(nodes) {
      if (nodes.length > 0) {
        console.log('选中:', nodes[0].name)
      }
    }
  }
}
</script>

示例2：多选模式（父子关联）

<template>
  <org-tree
    :data="treeData"
    mode="multiple"
    :show-checkbox="true"
    :check-strictly="false"
    :default-selected-ids="['1-1-1', '1-1-2']"
    :show-selected="true"
    :show-toolbar="true"
    @change="handleChange"
  />
</template>

<script>
export default {
  methods: {
    handleChange(nodes) {
      console.log('选中数量:', nodes.length)
      console.log('选中节点:', nodes.map(n => n.name))
    }
  }
}
</script>

示例3：多选模式（父子不关联）

<template>
  <org-tree
    :data="treeData"
    mode="multiple"
    :show-checkbox="true"
    :check-strictly="true"
    :default-expand-level="-1"
    @change="handleChange"
  />
</template>

示例4：只选择叶子节点

<template>
  <org-tree
    :data="treeData"
    mode="multiple"
    :show-checkbox="true"
    :only-leaf="true"
    @change="handleChange"
  />
</template>

示例5：自定义字段名

<template>
  <org-tree
    :data="customData"
    node-key="orgId"
    label-key="orgName"
    children-key="subOrgs"
    @change="handleChange"
  />
</template>

<script>
export default {
  data() {
    return {
      customData: [
        {
          orgId: '1',
          orgName: '总公司',
          subOrgs: [
            { orgId: '1-1', orgName: '技术部' }
          ]
        }
      ]
    }
  }
}
</script>

示例6：通过 ref 控制组件

<template>
  <org-tree ref="treeRef" :data="treeData" mode="multiple" :show-checkbox="true" />

  <view class="actions">
    <button @click="getSelected">获取选中</button>
    <button @click="setSelected">设置选中</button>
    <button @click="expandAll">展开全部</button>
    <button @click="collapseAll">折叠全部</button>
  </view>
</template>

<script>
export default {
  methods: {
    getSelected() {
      const nodes = this.$refs.treeRef.getSelectedNodes()
      const keys = this.$refs.treeRef.getSelectedKeys()
      console.log('选中节点:', nodes)
      console.log('选中ID:', keys)
    },

    setSelected() {
      this.$refs.treeRef.setSelectedKeys(['1-1', '1-2'])
    },

    expandAll() {
      this.$refs.treeRef.expandAll()
    },

    collapseAll() {
      this.$refs.treeRef.collapseAll()
    }
  }
}
</script>

插槽 Slots

暂不支持自定义插槽，如需自定义节点内容，请修改 org-tree-node.vue 组件。

注意事项

1. 节点ID唯一性：确保每个节点的 id（或自定义 nodeKey）在整棵树中唯一

2. 禁用节点：设置 disabled: true 的节点不可选中，但可以展开/折叠

3. 性能考虑：数据量较大时（>1000节点），建议：

   • 设置合理的 defaultExpandLevel，避免初始全部展开
   • 关闭 showCount，减少计算开销

4. 多选模式：建议同时设置 showCheckbox: true，提供更好的交互体验

5. 搜索功能：搜索时会自动展开匹配节点的父级路径，并高亮第一个匹配项

更新日志

v1.0.0

• 🎉 初始版本发布
• ✨ 支持单选/多选模式
• ✨ 支持默认展开层级配置
• ✨ 支持默认选中节点
• ✨ 支持父子节点关联/不关联
• ✨ 支持搜索过滤
• ✨ 支持只选择叶子节点
• ✨ 支持工具栏和已选中项展示

文件下载

将上述内容保存为 org-tree-api.md 文件即可。