xtf-tree

组件说明

xtf-tree 用于展示、筛选、选择和维护层级数据，适合组织、分类和目录。支持复选级联、懒加载、编辑、增删、同级拖拽及节点插槽。

---

基础用法

1. 节点选择

<template><xtf-tree v-model="selected" :data="data" @node-click="click" /></template>
<script>
export default {
  data() {
    return {
      selected: [],
      data: [{ id: 'a', label: '商品', children: [{ id: 'b', label: '数码' }] }]
    }
  },
  methods: {
    click(node) {
      console.log(node)
    }
  }
}
</script>

2. 复选与搜索

<template>
  <xtf-tree
    v-model="selected"
    :data="data"
    checkbox
    multiple
    filterable
    default-expand-all
    @check-change="check"
  />
</template>
<script>
export default {
  data() {
    return { selected: [], data: [{ id: 1, label: '华东', children: [{ id: 2, label: '上海' }] }] }
  },
  methods: {
    check(payload) {
      console.log(payload.selectedKeys)
    }
  }
}
</script>

3. 自定义节点插槽

<template>
  <xtf-tree :data="data" show-line>
    <template #default="{ node, level }">
      <view>
        <xtf-icon name="folder" size="sm" /><text>{{ level + 1 }} 级：{{ node.label }}</text></view>
</template>

  </xtf-tree>
</template>
<script>
export default {
  data() {
    return { data: [{ id: 'root', label: '仓库' }] }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
data / modelValue / selectedKeys	Array	[] / undefined / []	节点数据与选中 key	数据、双向绑定
childrenKey / labelKey / valueKey / disabledKey	String	'children'/'label'/'id'/'disabled'	节点字段映射	非标准数据
selectable / onlyLeafSelectable / maxSelectable	Boolean/Boolean/String | Number	true/false/0	选择能力、仅叶子、上限	选择控制
multiple / checkbox / checkStrictly	Boolean	false/false/false	多选、复选、父子不关联	复选树
expandAll / defaultExpandAll	Boolean	false/false	全量或初始展开	展开控制
defaultExpandedKeys / expandedKeys	Array	[]	默认/受控展开 key	展开控制
draggable / accordion / showLine	Boolean	false/false/false	同级拖拽、手风琴、连线	行为样式
childrenClass / childrenStyle / contentClass / contentStyle / checkboxClass / checkboxStyle / lineClass / lineStyle	String | Array | Object | Function	''	节点局部样式；函数签名 (state) => value	逐节点定制
filterable / filterMethod	Boolean/Function	false/null	搜索及 (node) => Boolean 过滤	搜索
lazy / loadData	Boolean/Function	false/null	懒加载及 (node) => Promise	异步节点
editable / creatable / removable	Boolean	false/false/false	重命名、新增、删除	维护树
maxHeight / indent	String | Number	''/'64'	最大高度与层级缩进	布局
searchPlaceholder / emptyText	String	''	搜索和空态文案	文案
expandIcon / collapseIcon / toggleIconSize / toggleIconTheme	String | Number	'arrow-right-s'/''/'xs'/'secondary'	展开图标配置	图标
itemGap / toggleGap	String | Number	6/8	节点、开关间距	密度
nodeClass / nodeStyle / toggleClass / toggleStyle	String | Array | Object | Function	''	节点和开关样式	样式定制
variant / showActiveBar / density	String/Boolean/String	'default'/false/'default'	default/outline/plain/branch、活动条、compact/loose	视觉变体
customClass / customStyle	String/String | Object	''	根样式	样式覆盖

节点数据结构

字段	类型	默认值	说明
id	String | Number	-	默认节点 key
label	String	''	默认节点文案
children	Array	[]	子节点，结构递归
disabled / lazy	Boolean	false	禁用或标记懒加载

---

事件

事件名称	回调参数	说明
update:selectedKeys / update:modelValue / update:expandedKeys	(keys: Array)	选中或展开 key 状态同步。
node-click / node-expand / node-collapse / load	(node)	节点点击、展开、收起或触发懒加载时触发。
check-change	({ node, checked, selectedKeys })	复选状态改变。
search	(keyword: String)	搜索词输入或清空时触发。
node-edit	({ key, label, node, data })	重命名确认后触发。
node-add / node-remove	变更详情	新增或删除节点后触发。
node-drop	({ sourceKey, targetKey, parentKey, data })	同级拖拽排序完成后触发。
update:data	(data: Array)	编辑、新增、删除或拖拽后返回完整数据快照。

事件使用示例

<template>
  <xtf-tree
    v-model="keys"
    :data="data"
    checkbox
    @check-change="onCheck"
    @update:data="data = $event"
  />
</template>
<script>
export default {
  data() {
    return { keys: [], data: [{ id: 1, label: '部门' }] }
  },
  methods: {
    onCheck(p) {
      console.log(p.node, p.selectedKeys)
    }
  }
}
</script>

---

插槽

插槽名	作用域参数	说明
默认插槽	node、level、expanded、selected、checked	替换节点内容区域。
icon	node、expanded	替换有子节点时的展开图标。
checkbox	node、checked、indeterminate	替换 checkbox 为真时的复选框。

默认插槽示例

<template>
  <xtf-tree v-model="selected" :data="data" checkbox @check-change="onCheck">
    <template #default="{ node, level, selected: isSelected }">
      <view class="tree-node-content">
        <text>{{ level + 1 }} 级 {{ node.label }}</text>
        <text>{{ isSelected ? '已选' : '未选' }}</text>
      </view>
    </template>
  </xtf-tree>
</template>
<script>
export default {
  data() {
    return { selected: [], data: [{ id: 'root', label: '仓库' }] }
  },
  methods: {
    onCheck(payload) {
      console.log('checked', payload.selectedKeys)
    }
  }
}
</script>

图标与复选框插槽示例

<template>
  <xtf-tree :data="data" checkbox>
    <template #icon="{ expanded }">
      <xtf-icon :name="expanded ? 'folder_open' : 'folder'" size="sm" />
    </template>
    <template #checkbox="{ checked, indeterminate }">
      <xtf-tag
        size="xs"
        :theme="checked ? 'success' : 'secondary'"
        :label="indeterminate ? '部分' : checked ? '已选' : '未选'"
      />
    </template>
  </xtf-tree>
</template>
<script>
export default {
  data() {
    return { data: [{ id: 'root', label: '仓库', children: [{ id: 'stock', label: '库存' }] }] }
  }
}
</script>

---

主题说明

• 选择和复选使用 var(--xtf-color-primary)，文字使用 --xtf-color-text。
• 节点间距由 --xtf-tree-node-gap，连线由 --xtf-tree-rail-color 控制。
• 在 xtf-config-provider 或主题配置覆盖这些变量即可全局定制。