更新记录

0.1.0（2026-07-19）

首个版本：支持 uni-app x Web（Chrome）的树形渲染、展开收起、同层排序、跨层移动、非法放置校验、边缘自动滚动和自定义拖拽预览；Android 15/16 模拟器已完成验证，实体设备兼容性待确认。

平台兼容性

uni-app x(5.15)

DragTree X

DragTree X 是一个面向 uni-app x 的树形拖拽排序组件，提供无后端、无权限、无运行时第三方依赖的目录和分类编辑能力。

已验证范围

• HBuilderX 5.15.2026070915。
• uni-app x Web（Chrome/Edge 浏览器内核）。
• uni-app x Android：Pixel 5 x86_64 模拟器，Android API 35 和 API 36。
• Android 实体设备和 iOS、小程序、鸿蒙尚未在本版本声明支持。

快速开始

将插件导入项目后，使用 easycom 组件名 <dtx-drag-tree-x>：

<template>
  <dtx-drag-tree-x
    :data="tree"
    :default-expanded-keys="expandedKeys"
    :height="520"
    :long-press-delay="300"
    :validate-drop="validateDrop"
    @change="onChange"
    @drag-start="Start"
    @drag-end="End"
    @drop-rejected="Rejected"
  />
</template>

<script setup lang="uts">
type DragTreeNode = {
  id: string
  label: string
  children: DragTreeNode[]
  dragDisabled: boolean
  dropDisabled: boolean
}

const tree = ref<DragTreeNode[]>([
  {
    id: 'root',
    label: '目录',
    dragDisabled: false,
    dropDisabled: false,
    children: []
  }
])

const expandedKeys = ['root']

function onChange(change: any): void {
  tree.value = change.data
}

function validateDrop(source: DragTreeNode, target: DragTreeNode, position: string): boolean {
  return true
}
</script>

数据节点的 id 必须在整棵树中唯一；children 必须是数组；dragDisabled 用于禁止拖动，dropDisabled 用于禁止节点接收子节点。

Props

拖拽手柄只启动拖拽，不会拦截长按启动前的普通滚动。目标行的顶部 25% 为 before，中间 50% 为 inside，底部 25% 为 after。拖到容器边缘会自动滚动并重新计算目标。

Events

• drag-start(node)：开始拖拽。
• change({ data, sourceId, targetId, position })：放置成功，data 为新的树数据。
• drop-rejected(code)：放置被拒绝，常见错误码包括 SELF_DROP、DESCENDANT_DROP、DROP_DISABLED、DRAG_DISABLED、VALIDATOR_REJECTED。
• drag-end(sourceId)：拖拽流程结束，无论成功、拒绝或取消都会触发。

自定义拖拽预览

组件提供名为 drag-preview 的作用域插槽，插槽参数为当前节点：

<template #drag-preview="{ node }">
  <view class="my-preview">
    <text>{{ node == null ? '' : node.label }}</text>
  </view>
</template>

在 uni-app x 模板中，若 HBuilderX 提示作用域插槽参数类型为 Any，请在使用处显式转换为 DragTreeNode | null。

限制

本版本不包含搜索、异步加载、虚拟列表、多选、跨树拖拽、撤销重做和自定义字段映射；不声明旧版 uni-app Vue、小程序、iOS 或鸿蒙支持。建议在目标项目中先使用普通授权试用验证平台和交互。

授权与首次编译

普通授权版和试用版由 DCloud 自动加密组件中的 .uvue 和 .uts 文件。首次运行到目标平台时，HBuilderX 需要联网并登录具备试用或购买权限的 DCloud 账号，由平台单独编译加密插件；插件使用者项目中的其他代码不会随插件上传。首次编译成功后会使用本地缓存。

隐私与权限

组件无系统权限申请、无网络请求、无广告 SDK、无遥测和无数据采集。