@splicetree/plugin-dnd 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @splicetree/plugin-dnd
 
+## 1.0.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 多节点拖拽增强：
+  - 当拖拽源节点属于当前选择集合时，启用“组拖拽”，保持被选节点的相对顺序。
+  - 悬停与释放阶段同时校验整组节点的 draggable / nestable / sortable 规则；任一节点不满足则整组操作禁用。
+  - 防止将节点拖入自身或其后代，确保结构合法性。
+  - 在 AFTER 场景按逆序处理，被选节点相对顺序保持正确。
+
+  影响与迁移：
+  - 若需要为部分节点放开“入内/前后排序”，请在 v-bind 拖拽行为中设置 nestable / sortable。
+
 ## 0.2.0
 
 ## 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @splicetree/plugin-dnd
 
-为树节点提供拖拽移动能力，支持插入到目标之前、之后或作为子节点。
+为树节点提供拖拽移动能力，支持插入到目标之前、之后或作为子节点。新增工程化的规则引擎，可精细控制「谁可以拖」「拖到哪里」「允许的落点（前/内/后）」。
 
 [![version](https://img.shields.io/npm/v/@splicetree/plugin-dnd.svg?label=version)](https://www.npmjs.com/package/@splicetree/plugin-dnd)
 [![downloads](https://img.shields.io/npm/dm/@splicetree/plugin-dnd.svg)](https://npmcharts.com/compare/%40splicetree%2Fplugin-dnd?minimal=true)
@@ -16,10 +16,31 @@
 
 ```ts
 import { createSpliceTree } from '@splicetree/core'
-import dnd from '@splicetree/plugin-dnd'
+import dnd, { DropPosition } from '@splicetree/plugin-dnd'
 
 const tree = createSpliceTree(data, {
   plugins: [dnd],
+  configuration: {
+    dnd: {
+      // 控制可拖拽
+      disabledDrag: (n) => n.level === 2, // 例如：禁用所有 2 级节点的拖拽
+      // 控制可放置
+      levelMatrix: {
+        // 例如：3 级可以放到 2 级「内」，但 2 级不能放到 1 级「内」
+        3: { 2: { inside: true } },
+        2: { 1: { inside: false } },
+      },
+      // 显式禁止某些 ID 对的放置
+      denyDropPairs: [
+        { fromId: 'a', toId: 'b', positions: [DropPosition.INSIDE] },
+      ],
+      // 完全自定义：覆盖所有规则（高优先级）
+      canDrop: (src, tgt, pos) => {
+        if (src.id === 'a' && tgt.id === 'b') return false
+        return true
+      },
+    },
+  },
 })
 ```
 
@@ -27,10 +48,16 @@ const tree = createSpliceTree(data, {
 
 ### Options
 
-| 选项               | 类型      | 默认值 | 说明                                                      |
-| ------------------ | --------- | ------ | --------------------------------------------------------- |
-| `autoUpdateParent` | `boolean` | `true` | 拖拽后自动更新源节点的父字段；为 `false` 时不写回且不移动 |
-| `autoExpandOnDrop` | `boolean` | `true` | 拖入后自动展开目标节点                                    |
+| 选项               | 类型                                                         | 默认值 | 说明                                                                 |
+| ------------------ | ------------------------------------------------------------ | ------ | -------------------------------------------------------------------- |
+| `autoUpdateParent` | `boolean`                                                    | `true` | 拖拽后自动更新源节点的父字段；为 `false` 时不写回且不移动           |
+| `autoExpandOnDrop` | `boolean`                                                    | `true` | 拖入后自动展开目标节点                                              |
+| `readonly`         | `boolean`                                                    | `false`| 只读模式，禁用拖拽与放置                                            |
+| `reorderOnly`      | `boolean`                                                    | `false`| 仅允许同层级排序（禁用 `INSIDE` 放入子级）                          |
+| `disabledDrag`     | `boolean \| string[] \| (node: DndNode) => boolean`          | `无`   | 禁用拖拽：布尔、ID 列表或方法                                       |
+| `levelMatrix`      | `Record<level, Record<level, { before?: boolean; inside?: boolean; after?: boolean }>>` | `无`   | 基于层级的允许矩阵。未显式配置的组合默认允许                        |
+| `denyDropPairs`    | `{ fromId: string; toId: string; positions?: DropPosition[] }[]` | `无`   | 显式禁止某些源-目标的放置；未指定 `positions` 时，禁止所有落点      |
+| `canDrop`          | `(src: DndNode, tgt: DndNode, position: DropPosition) => boolean` | `无`   | 自定义总规则（高优先级，返回 `true/false` 覆盖其它规则）            |
 
 ### Events
 
@@ -40,16 +67,16 @@ const tree = createSpliceTree(data, {
 
 ### 实例方法
 
-| 名称             | 参数                                                      | 说明                     |
-| ---------------- | --------------------------------------------------------- | ------------------------ |
-| `drop`           | `srcId: string; targetId: string; position: DropPosition` | 执行移动                 |
-| `onDragStart`    | `id: string`                                              | 标记拖拽源               |
-| `onDragOver`     | `id: string; el: HTMLElement; e: DragEvent \| MouseEvent` | 更新目标悬停位置         |
-| `onDragLeave`    | `id: string`                                              | 清理悬停位置             |
-| `onDrop`         | `targetId: string`                                        | 根据当前悬停位置执行移动 |
-| `hoverPositions` | `无`                                                      | 目标悬停位置缓存         |
-| `draggingId`     | `无`                                                      | 当前正在拖拽的节点 id    |
-| `dragProps`      | `无`                                                      | DOM 事件绑定集合         |
+| 名称             | 参数                                                      | 说明                       |
+| ---------------- | --------------------------------------------------------- | -------------------------- |
+| `drop`           | `srcId: string; targetId: string; position: DropPosition` | 执行移动                   |
+| `onDragStart`    | `id: string`                                              | 标记拖拽源                 |
+| `onDragOver`     | `id: string; el: HTMLElement; e: DragEvent \| MouseEvent` | 更新目标悬停位置           |
+| `onDragLeave`    | `id: string`                                              | 清理悬停位置               |
+| `onDrop`         | `targetId: string`                                        | 根据当前悬停位置执行移动   |
+| `hoverPositions` | `无`                                                      | 目标悬停位置缓存           |
+| `draggingId`     | `无`                                                      | 当前正在拖拽的节点 id      |
+| `dragProps`      | `id: string`                                              | DOM 事件绑定集合（逐节点） |
 
 ### 节点方法
 
@@ -57,3 +84,11 @@ const tree = createSpliceTree(data, {
 | ------------------- | ---- | -------------------- |
 | `getDropPosition()` | `无` | 当前节点的悬停位置   |
 | `isDragging()`      | `无` | 当前节点是否为拖拽源 |
+| `isDisabled()`      | `无` | 当前节点是否禁用拖拽 |
+
+## 规则优先级
+- `readonly` → 全面禁止
+- `canDrop` → 优先级最高，返回值直接决定是否允许
+- `denyDropPairs` → 其次，命中即禁止
+- `levelMatrix` → 再次，根据层级组合与落点决策
+- 默认允许（除去基础非法场景：拖到自己或到父级）

package/dist/index.d.ts

@@ -1,24 +1,36 @@
 import { SpliceTreePlugin } from "@splicetree/core";
 
-//#region src/index.d.ts
-
-/**
- * 拖拽落点位置
- * - BEFORE: 目标之前插入
- * - INSIDE: 作为目标的子节点插入
- * - AFTER:  目标之后插入
- */
+//#region src/types.d.ts
+/** dnd types */
+interface DndNode {
+  id: string;
+  level: number;
+  parentId?: string;
+  root?: boolean;
+}
+interface DragBehavior {
+  draggable?: boolean;
+  sortable?: boolean;
+  nestable?: boolean;
+}
 declare enum DropPosition {
   BEFORE = -1,
   INSIDE = 0,
   AFTER = 1,
 }
+interface DndOptions {
+  /** 执行拖拽后是否自动写回父字段并同步树结构 */
+  autoUpdateParent?: boolean;
+  /** 拖入为子节点后是否自动展开目标节点 */
+  autoExpandOnDrop?: boolean;
+  /** 全局只读，禁用所有拖拽与排序 */
+  readonly?: boolean;
+}
+//#endregion
+//#region src/index.d.ts
 declare module '@splicetree/core' {
   interface SpliceTreeConfiguration {
-    dnd?: {
-      autoUpdateParent?: boolean;
-      autoExpandOnDrop?: boolean;
-    };
+    dnd?: DndOptions;
   }
   interface SpliceTreeEventPayloadMap {
     /**
@@ -43,70 +55,49 @@ declare module '@splicetree/core' {
      * @param position 落点位置（前/内/后）
      */
     drop: (srcId: string, targetId: string, position: DropPosition) => void;
-    /**
-     * 当前拖拽源节点 id
-     */
+    /** 当前拖拽源节点 id */
     draggingId?: string;
-    /**
-     * 目标节点的悬停位置映射
-     */
+    /** 目标节点的悬停位置映射 */
     hoverPositions: Map<string, DropPosition>;
-    /**
-     * DOM 事件：开始拖拽
-     */
+    /** DOM 事件：开始拖拽 */
     onDragStart: (id: string) => void;
-    /**
-     * DOM 事件：悬停计算并更新位置
-     */
+    /** DOM 事件：悬停计算并更新位置 */
     onDragOver: (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => void;
-    /**
-     * DOM 事件：离开目标，清理悬停状态
-     */
+    /** DOM 事件：离开目标，清理悬停状态 */
     onDragLeave: (id: string) => void;
-    /**
-     * DOM 事件：在目标上释放后执行移动
-     */
+    /** DOM 事件：在目标上释放后执行移动 */
     onDrop: (targetId: string) => void;
-    /**
-     * 可直接 v-bind 到节点的拖拽属性集合
-     */
-    dragProps: {
-      /**
-       * 是否可拖拽
-       */
+    /** 可直接 v-bind 到节点的拖拽属性集合（逐节点） */
+    dragProps: (id: string, behavior?: DragBehavior) => {
+      /** 是否可拖拽 */
       draggable: boolean;
-      /**
-       * 原生拖拽开始事件处理
-       */
+      /** 原生拖拽开始事件处理 */
       onDragstart: (e: DragEvent) => void;
-      /**
-       * 原生拖拽悬停事件处理
-       */
+      /** 原生拖拽悬停事件处理 */
       onDragover: (e: DragEvent) => void;
-      /**
-       * 原生拖拽离开事件处理
-       */
+      /** 原生拖拽离开事件处理 */
       onDragleave: (e: DragEvent) => void;
-      /**
-       * 原生拖拽释放事件处理
-       */
+      /** 原生拖拽释放事件处理 */
       onDrop: (e: DragEvent) => void;
     };
+    /** 统一占位样式绑定对象 */
+    ghostStyle: (opts?: {
+      padding?: boolean;
+      margin?: boolean;
+    }) => Record<string, any>;
   }
   /**
    * 节点扩展（DnD）
    */
   interface SpliceTreeNode {
-    /**
-     * 获取当前节点的悬停落点位置
-     */
+    /** 获取当前节点的悬停落点位置 */
     getDropPosition: () => (DropPosition | undefined);
-    /**
-     * 当前节点是否为拖拽源
-     */
+    /** 当前节点是否为拖拽源 */
     isDragging: () => boolean;
+    /** 当前节点是否被禁用  */
+    isDisabled?: () => boolean;
   }
 }
 declare const dnd: SpliceTreePlugin;
 //#endregion
-export { DropPosition, dnd as default, dnd };
+export { type DndNode, type DndOptions, DropPosition, dnd as default, dnd };

package/dist/index.js

@@ -1,28 +1,61 @@
-//#region src/index.ts
-/**
-* 拖拽落点位置
-* - BEFORE: 目标之前插入
-* - INSIDE: 作为目标的子节点插入
-* - AFTER:  目标之后插入
-*/
+//#region src/types.ts
 let DropPosition = /* @__PURE__ */ function(DropPosition$1) {
 	DropPosition$1[DropPosition$1["BEFORE"] = -1] = "BEFORE";
 	DropPosition$1[DropPosition$1["INSIDE"] = 0] = "INSIDE";
 	DropPosition$1[DropPosition$1["AFTER"] = 1] = "AFTER";
 	return DropPosition$1;
 }({});
+
+//#endregion
+//#region src/position.ts
+function computePosition(targetId, el, e, src) {
+	const rect = el.getBoundingClientRect();
+	const y = ("clientY" in e ? e.clientY : 0) - rect.top;
+	const ratio = Math.max(0, Math.min(1, rect.height ? y / rect.height : 0));
+	if (ratio < .33) return DropPosition.BEFORE;
+	if (ratio > .66) return DropPosition.AFTER;
+	if (src?.id === targetId) return;
+	if (src?.getParent()?.id === targetId) return;
+	return DropPosition.INSIDE;
+}
+
+//#endregion
+//#region src/index.ts
 const dnd = {
 	name: "dnd",
 	setup(ctx) {
-		const { autoUpdateParent = true, autoExpandOnDrop = true } = ctx.options?.configuration?.dnd ?? {};
-		const parentField = ctx.tree.options?.configuration?.parentField ?? ctx.tree.options?.parentField ?? "parent";
+		const { autoExpandOnDrop = true, autoUpdateParent = true, readonly = false } = ctx.options?.configuration?.dnd ?? {};
+		const parentField = ctx.tree.options?.configuration?.parentField ?? "parent";
 		let draggingId;
 		const hoverPositions = /* @__PURE__ */ new Map();
+		let ghostTop = 0;
+		let ghostHeight = 0;
+		let ghostPos;
+		let ghostInsetLeft = 0;
+		let ghostInsetRight = 0;
+		let ghostMarginLeft = 0;
+		let ghostMarginRight = 0;
+		const behaviors = /* @__PURE__ */ new Map();
+		const isDisabledById = (_id) => !!readonly;
+		const getDraggedNodeIds = (primaryId) => {
+			const tree = ctx.tree;
+			if (tree.selectedKeys && tree.selectedKeys.has(primaryId)) {
+				const selected = new Set(tree.selectedKeys);
+				const validIds = Array.from(selected).filter((id) => {
+					if (isDisabledById(id)) return false;
+					if (behaviors.get(id)?.draggable === false) return false;
+					return true;
+				});
+				return ctx.tree.items().filter((node) => validIds.includes(node.id)).map((n) => n.id);
+			}
+			return [primaryId];
+		};
 		/**
 		* 开始拖拽：记录拖拽源并通知视图刷新（用于高亮拖拽源）
 		* @param id 源节点 id
 		*/
 		const onDragStart = (id) => {
+			if (isDisabledById(id)) return;
 			draggingId = id;
 			ctx.events.emit({
 				name: "visibility",
@@ -37,16 +70,6 @@ const dnd = {
 		* @param el 目标节点元素
 		* @param e 拖拽/鼠标事件
 		*/
-		const computePosition = (id, el, e) => {
-			const rect = el.getBoundingClientRect();
-			const y = ("clientY" in e ? e.clientY : 0) - rect.top;
-			const ratio = Math.max(0, Math.min(1, y / rect.height));
-			if (ratio < .33) return DropPosition.BEFORE;
-			if (ratio > .66) return DropPosition.AFTER;
-			if (draggingId === id) return;
-			if (ctx.tree.getNode(draggingId)?.getParent()?.id === id) return;
-			return DropPosition.INSIDE;
-		};
 		/**
 		* 悬停：更新目标的悬停位置映射并刷新视图
 		* @param id 目标节点 id
@@ -54,9 +77,86 @@ const dnd = {
 		* @param e 拖拽/鼠标事件
 		*/
 		const onDragOver = (id, el, e) => {
-			const pos = computePosition(id, el, e);
-			if (pos === void 0) hoverPositions.delete(id);
-			else hoverPositions.set(id, pos);
+			if (!draggingId) return;
+			const draggedIds = getDraggedNodeIds(draggingId);
+			const targetNode = ctx.tree.getNode(id);
+			if (draggedIds.includes(id)) {
+				hoverPositions.delete(id);
+				ctx.events.emit({
+					name: "visibility",
+					keys: ctx.tree.expandedKeys()
+				});
+				return;
+			}
+			let ancestor = targetNode?.getParent();
+			while (ancestor) {
+				if (draggedIds.includes(ancestor.id)) {
+					hoverPositions.delete(id);
+					ctx.events.emit({
+						name: "visibility",
+						keys: ctx.tree.expandedKeys()
+					});
+					return;
+				}
+				ancestor = ancestor.getParent();
+			}
+			const pos = computePosition(id, el, e, void 0);
+			if (!targetNode || pos === void 0) {
+				hoverPositions.delete(id);
+				ctx.events.emit({
+					name: "visibility",
+					keys: ctx.tree.expandedKeys()
+				});
+				return;
+			}
+			if (pos === DropPosition.INSIDE) {
+				if (draggedIds.some((dId) => {
+					return ctx.tree.getNode(dId)?.getParent()?.id === id;
+				})) {
+					hoverPositions.delete(id);
+					ctx.events.emit({
+						name: "visibility",
+						keys: ctx.tree.expandedKeys()
+					});
+					return;
+				}
+				if (!draggedIds.every((dId) => {
+					return behaviors.get(dId)?.nestable !== false;
+				})) {
+					hoverPositions.delete(id);
+					ctx.events.emit({
+						name: "visibility",
+						keys: ctx.tree.expandedKeys()
+					});
+					return;
+				}
+			} else if (!draggedIds.every((dId) => {
+				return behaviors.get(dId)?.sortable !== false;
+			})) {
+				hoverPositions.delete(id);
+				ctx.events.emit({
+					name: "visibility",
+					keys: ctx.tree.expandedKeys()
+				});
+				return;
+			}
+			hoverPositions.set(id, pos);
+			ghostTop = el.offsetTop;
+			ghostHeight = el.offsetHeight;
+			ghostPos = pos;
+			const parent = el.parentElement;
+			if (parent) {
+				const styles = getComputedStyle(parent);
+				ghostInsetLeft = Number.parseFloat(styles.paddingLeft || "0");
+				ghostInsetRight = Number.parseFloat(styles.paddingRight || "0");
+				ghostMarginLeft = Number.parseFloat(styles.marginLeft || "0");
+				ghostMarginRight = Number.parseFloat(styles.marginRight || "0");
+			} else {
+				ghostInsetLeft = 0;
+				ghostInsetRight = 0;
+				ghostMarginLeft = 0;
+				ghostMarginRight = 0;
+			}
 			ctx.events.emit({
 				name: "visibility",
 				keys: ctx.tree.expandedKeys()
@@ -85,10 +185,15 @@ const dnd = {
 			const src = ctx.tree.getNode(srcId);
 			const target = ctx.tree.getNode(targetId);
 			if (!src || !target) return;
+			if (readonly) return;
+			const ov = behaviors.get(src.id);
+			if (ov?.draggable === false) return;
+			if (position === DropPosition.INSIDE && ov?.nestable === false) return;
+			if (position !== DropPosition.INSIDE && ov?.sortable === false) return;
 			if (srcId === targetId) return;
 			const srcParentId = src.getParent()?.id;
+			if (position === DropPosition.INSIDE && srcParentId === targetId) return;
 			if (position === DropPosition.INSIDE) {
-				if (targetId === srcParentId) return;
 				if (autoUpdateParent) {
 					ctx.tree.moveNode(srcId, targetId);
 					Reflect.set(src.original, parentField, targetId);
@@ -151,9 +256,19 @@ const dnd = {
 		const onDrop = (targetId) => {
 			if (!draggingId) return;
 			const pos = hoverPositions.get(targetId);
-			if (pos === DropPosition.BEFORE) drop(draggingId, targetId, DropPosition.BEFORE);
-			else if (pos === DropPosition.AFTER) drop(draggingId, targetId, DropPosition.AFTER);
-			else if (pos === DropPosition.INSIDE) drop(draggingId, targetId, DropPosition.INSIDE);
+			if (pos === void 0) {
+				hoverPositions.clear();
+				draggingId = void 0;
+				ctx.events.emit({
+					name: "visibility",
+					keys: ctx.tree.expandedKeys()
+				});
+				return;
+			}
+			const draggedIds = getDraggedNodeIds(draggingId);
+			let idsToProcess = draggedIds;
+			if (pos === DropPosition.AFTER) idsToProcess = [...draggedIds].reverse();
+			for (const id of idsToProcess) drop(id, targetId, pos);
 			hoverPositions.clear();
 			draggingId = void 0;
 			ctx.events.emit({
@@ -161,21 +276,17 @@ const dnd = {
 				keys: ctx.tree.expandedKeys()
 			});
 		};
-		return {
-			drop,
-			onDragStart,
-			onDragOver,
-			onDragLeave,
-			onDrop,
-			hoverPositions,
-			get draggingId() {
-				return draggingId;
-			},
-			dragProps: {
-				draggable: true,
+		/**
+		* 绑定到节点的拖拽属性集，便于直接 v-bind
+		* @param id 节点 ID
+		*/
+		const dragProps = (id, behavior) => {
+			if (behavior) behaviors.set(id, behavior);
+			const canDrag = behavior?.draggable === false ? false : !isDisabledById(id);
+			return {
+				draggable: canDrag,
 				onDragstart: (e) => {
-					const id = e.currentTarget?.dataset?.id;
-					if (id) {
+					if (canDrag) {
 						e.dataTransfer?.setData("text/plain", id);
 						onDragStart(id);
 					}
@@ -183,24 +294,82 @@ const dnd = {
 				onDragover: (e) => {
 					e.preventDefault();
 					const el = e.currentTarget;
-					const id = el?.dataset?.id;
-					if (id) onDragOver(id, el, e);
+					onDragOver(id, el, e);
 				},
-				onDragleave: (e) => {
-					const id = e.currentTarget?.dataset?.id;
-					if (id) onDragLeave(id);
+				onDragleave: (_e) => {
+					onDragLeave(id);
 				},
 				onDrop: (e) => {
 					e.preventDefault();
-					const id = e.currentTarget?.dataset?.id;
-					if (id) onDrop(id);
+					onDrop(id);
 				}
-			}
+			};
+		};
+		const ghostStyle = (opts) => {
+			if (!draggingId || ghostPos === void 0) return { style: { display: "none" } };
+			const usePadding = opts?.padding ?? true;
+			const useMargin = opts?.margin ?? true;
+			const leftInset = usePadding ? ghostInsetLeft : 0;
+			const rightInset = usePadding ? ghostInsetRight : 0;
+			const leftMargin = useMargin ? ghostMarginLeft : 0;
+			const rightMargin = useMargin ? ghostMarginRight : 0;
+			const base = {
+				position: "absolute",
+				left: `${leftInset + leftMargin}px`,
+				right: `${rightInset + rightMargin}px`,
+				pointerEvents: "none"
+			};
+			if (ghostPos === DropPosition.BEFORE) return {
+				"style": {
+					...base,
+					top: `${ghostTop}px`,
+					height: "2px",
+					background: "var(--vp-code-color)",
+					borderRadius: "2px"
+				},
+				"data-drop-position": -1
+			};
+			if (ghostPos === DropPosition.AFTER) return {
+				"style": {
+					...base,
+					top: `${ghostTop + ghostHeight}px`,
+					height: "2px",
+					background: "var(--vp-code-color)",
+					borderRadius: "2px"
+				},
+				"data-drop-position": 1
+			};
+			return {
+				"style": {
+					...base,
+					top: `${ghostTop}px`,
+					height: `${ghostHeight}px`,
+					background: "var(--vp-code-color)",
+					opacity: .15,
+					borderRadius: "4px"
+				},
+				"data-drop-position": 0
+			};
+		};
+		return {
+			drop,
+			onDragStart,
+			onDragOver,
+			onDragLeave,
+			onDrop,
+			hoverPositions,
+			get draggingId() {
+				return draggingId;
+			},
+			dragProps,
+			ghostStyle
 		};
 	},
 	extendNode(node, ctx) {
 		node.getDropPosition = () => ctx.tree.hoverPositions.get(node.id);
 		node.isDragging = () => ctx.tree.draggingId === node.id;
+		const opts = ctx.options?.configuration?.dnd ?? {};
+		node.isDisabled = () => !!opts.readonly;
 	}
 };
 var src_default = dnd;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@splicetree/plugin-dnd",
   "type": "module",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "author": {
     "email": "michael.cocova@gmail.com",
     "name": "Michael Cocova"
@@ -23,7 +23,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@splicetree/core": "0.2.0"
+    "@splicetree/core": "1.0.0"
   },
   "scripts": {
     "dev": "tsdown --watch",

package/src/index.ts

@@ -1,23 +1,12 @@
 import type { SpliceTreePlugin, SpliceTreePluginContext } from '@splicetree/core'
+import type { DndNode, DndOptions, DragBehavior } from './types'
+import { computePosition } from './position'
+import { DropPosition } from './types'
 import '@splicetree/core'
 
-/**
- * 拖拽落点位置
- * - BEFORE: 目标之前插入
- * - INSIDE: 作为目标的子节点插入
- * - AFTER:  目标之后插入
- */
-export enum DropPosition {
-  BEFORE = -1,
-  INSIDE = 0,
-  AFTER = 1,
-}
 declare module '@splicetree/core' {
   interface SpliceTreeConfiguration {
-    dnd?: {
-      autoUpdateParent?: boolean
-      autoExpandOnDrop?: boolean
-    }
+    dnd?: DndOptions
   }
   interface SpliceTreeEventPayloadMap {
     /**
@@ -38,69 +27,46 @@ declare module '@splicetree/core' {
      * @param position 落点位置（前/内/后）
      */
     drop: (srcId: string, targetId: string, position: DropPosition) => void
-    /**
-     * 当前拖拽源节点 id
-     */
+    /** 当前拖拽源节点 id */
     draggingId?: string
-    /**
-     * 目标节点的悬停位置映射
-     */
+    /** 目标节点的悬停位置映射 */
     hoverPositions: Map<string, DropPosition>
-    /**
-     * DOM 事件：开始拖拽
-     */
+    /** DOM 事件：开始拖拽 */
     onDragStart: (id: string) => void
-    /**
-     * DOM 事件：悬停计算并更新位置
-     */
+    /** DOM 事件：悬停计算并更新位置 */
     onDragOver: (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => void
-    /**
-     * DOM 事件：离开目标，清理悬停状态
-     */
+    /** DOM 事件：离开目标，清理悬停状态 */
     onDragLeave: (id: string) => void
-    /**
-     * DOM 事件：在目标上释放后执行移动
-     */
+    /** DOM 事件：在目标上释放后执行移动 */
     onDrop: (targetId: string) => void
-    /**
-     * 可直接 v-bind 到节点的拖拽属性集合
-     */
-    dragProps: {
-      /**
-       * 是否可拖拽
-       */
+    /** 可直接 v-bind 到节点的拖拽属性集合（逐节点） */
+    dragProps: (id: string, behavior?: DragBehavior) => {
+      /** 是否可拖拽 */
       draggable: boolean
-      /**
-       * 原生拖拽开始事件处理
-       */
+      /** 原生拖拽开始事件处理 */
       onDragstart: (e: DragEvent) => void
-      /**
-       * 原生拖拽悬停事件处理
-       */
+      /** 原生拖拽悬停事件处理 */
       onDragover: (e: DragEvent) => void
-      /**
-       * 原生拖拽离开事件处理
-       */
+      /** 原生拖拽离开事件处理 */
       onDragleave: (e: DragEvent) => void
-      /**
-       * 原生拖拽释放事件处理
-       */
+      /** 原生拖拽释放事件处理 */
       onDrop: (e: DragEvent) => void
     }
+    /** 统一占位样式绑定对象 */
+    ghostStyle: (opts?: { padding?: boolean, margin?: boolean }) => Record<string, any>
   }
 
   /**
    * 节点扩展（DnD）
    */
   interface SpliceTreeNode {
-    /**
-     * 获取当前节点的悬停落点位置
-     */
+    /** 获取当前节点的悬停落点位置 */
     getDropPosition: () => (DropPosition | undefined)
-    /**
-     * 当前节点是否为拖拽源
-     */
+    /** 当前节点是否为拖拽源 */
     isDragging: () => boolean
+
+    /** 当前节点是否被禁用  */
+    isDisabled?: () => boolean
   }
 }
 
@@ -113,20 +79,56 @@ export const dnd: SpliceTreePlugin = {
    * - 通过 events 派发 move 与 visibility 事件驱动视图刷新
    */
   setup(ctx: SpliceTreePluginContext) {
-    const cfg = (ctx.options?.configuration?.dnd ?? {}) as {
-      autoUpdateParent?: boolean
-      autoExpandOnDrop?: boolean
-    }
-    const { autoUpdateParent = true, autoExpandOnDrop = true } = cfg
+    const opts = (ctx.options?.configuration?.dnd ?? {}) as DndOptions
+    const {
+      autoExpandOnDrop = true,
+      autoUpdateParent = true,
+      readonly = false,
+    } = opts
     const parentField = ctx.tree.options?.configuration?.parentField ?? 'parent'
     let draggingId: string | undefined
     const hoverPositions = new Map<string, DropPosition>()
+    let ghostTop = 0
+    let ghostHeight = 0
+    let ghostPos: DropPosition | undefined
+    let ghostInsetLeft = 0
+    let ghostInsetRight = 0
+    let ghostMarginLeft = 0
+    let ghostMarginRight = 0
+    const behaviors = new Map<string, DragBehavior>()
+
+    const isDisabledById = (_id: string | undefined): boolean => !!readonly
+
+    const getDraggedNodeIds = (primaryId: string): string[] => {
+      const tree = ctx.tree as any
+      if (tree.selectedKeys && tree.selectedKeys.has(primaryId)) {
+        const selected = new Set(tree.selectedKeys as Set<string>)
+        const validIds = Array.from(selected).filter((id) => {
+          if (isDisabledById(id)) {
+            return false
+          }
+          const ov = behaviors.get(id as string)
+          if (ov?.draggable === false) {
+            return false
+          }
+          return true
+        })
+
+        const allItems = ctx.tree.items()
+        const sorted = allItems.filter(node => validIds.includes(node.id)).map(n => n.id)
+        return sorted
+      }
+      return [primaryId]
+    }
 
     /**
      * 开始拖拽：记录拖拽源并通知视图刷新（用于高亮拖拽源）
      * @param id 源节点 id
      */
     const onDragStart = (id: string) => {
+      if (isDisabledById(id)) {
+        return
+      }
       draggingId = id
       ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
     }
@@ -139,25 +141,7 @@ export const dnd: SpliceTreePlugin = {
      * @param el 目标节点元素
      * @param e 拖拽/鼠标事件
      */
-    const computePosition = (id: string, el: HTMLElement, e: DragEvent | MouseEvent): DropPosition | undefined => {
-      const rect = el.getBoundingClientRect()
-      const y = ('clientY' in e ? e.clientY : 0) - rect.top
-      const ratio = Math.max(0, Math.min(1, y / rect.height))
-      if (ratio < 0.33) {
-        return DropPosition.BEFORE
-      }
-      if (ratio > 0.66) {
-        return DropPosition.AFTER
-      }
-      if (draggingId === id) {
-        return undefined
-      }
-      const parentId = ctx.tree.getNode(draggingId!)?.getParent()?.id
-      if (parentId === id) {
-        return undefined
-      }
-      return DropPosition.INSIDE
-    }
+    // 使用独立位置计算模块
 
     /**
      * 悬停：更新目标的悬停位置映射并刷新视图
@@ -166,11 +150,92 @@ export const dnd: SpliceTreePlugin = {
      * @param e 拖拽/鼠标事件
      */
     const onDragOver = (id: string, el: HTMLElement, e: DragEvent | MouseEvent) => {
-      const pos = computePosition(id, el, e)
-      if (pos === undefined) {
+      // 如果没有拖拽源，直接返回
+      if (!draggingId) {
+        return
+      }
+
+      const draggedIds = getDraggedNodeIds(draggingId)
+      const targetNode = ctx.tree.getNode(id)
+
+      // 1. 目标节点不能是拖拽节点之一
+      if (draggedIds.includes(id)) {
+        hoverPositions.delete(id)
+        ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+        return
+      }
+
+      // 2. 目标节点不能是任何拖拽节点的后代（防止循环）
+      let ancestor = targetNode?.getParent()
+      while (ancestor) {
+        if (draggedIds.includes(ancestor.id)) {
+          hoverPositions.delete(id)
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+          return
+        }
+        ancestor = ancestor.getParent()
+      }
+
+      // 这里的 src 参数传 undefined，因为我们已经手动检查了 draggedIds
+      const pos = computePosition(id, el, e, undefined)
+
+      if (!targetNode || pos === undefined) {
         hoverPositions.delete(id)
+        ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+        return
+      }
+
+      // 3. 检查所有拖拽节点的行为约束
+      if (pos === DropPosition.INSIDE) {
+        // 如果目标已经是某个拖拽节点的父节点，则 INSIDE 无意义（或者是 no-op）
+        // computePosition 原逻辑是 parentId === targetId 返回 undefined
+        const isParentOfAny = draggedIds.some((dId) => {
+          const node = ctx.tree.getNode(dId)
+          return node?.getParent()?.id === id
+        })
+        if (isParentOfAny) {
+          hoverPositions.delete(id)
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+          return
+        }
+
+        const allNestable = draggedIds.every((dId) => {
+          const ov = behaviors.get(dId)
+          return ov?.nestable !== false
+        })
+        if (!allNestable) {
+          hoverPositions.delete(id)
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+          return
+        }
       } else {
-        hoverPositions.set(id, pos)
+        const allSortable = draggedIds.every((dId) => {
+          const ov = behaviors.get(dId)
+          return ov?.sortable !== false
+        })
+        if (!allSortable) {
+          hoverPositions.delete(id)
+          ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+          return
+        }
+      }
+
+      hoverPositions.set(id, pos)
+      ghostTop = el.offsetTop
+      ghostHeight = el.offsetHeight
+      ghostPos = pos
+      const parent = el.parentElement
+      if (parent) {
+        const styles = getComputedStyle(parent)
+        ghostInsetLeft = Number.parseFloat(styles.paddingLeft || '0')
+        ghostInsetRight = Number.parseFloat(styles.paddingRight || '0')
+        ghostMarginLeft = Number.parseFloat(styles.marginLeft || '0')
+        ghostMarginRight = Number.parseFloat(styles.marginRight || '0')
+      } else {
+        ghostInsetLeft = 0
+        ghostInsetRight = 0
+        ghostMarginLeft = 0
+        ghostMarginRight = 0
       }
       ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
     }
@@ -198,15 +263,29 @@ export const dnd: SpliceTreePlugin = {
       if (!src || !target) {
         return
       }
+      if (readonly) {
+        return
+      }
+      const ov = behaviors.get(src.id)
+      if (ov?.draggable === false) {
+        return
+      }
+      if (position === DropPosition.INSIDE && ov?.nestable === false) {
+        return
+      }
+      if (position !== DropPosition.INSIDE && ov?.sortable === false) {
+        return
+      }
+      // 基础非法：不能拖到自身或其父
       if (srcId === targetId) {
         return
       }
       const srcParentId = src.getParent()?.id
+      if (position === DropPosition.INSIDE && srcParentId === targetId) {
+        return
+      }
 
       if (position === DropPosition.INSIDE) {
-        if (targetId === srcParentId) {
-          return
-        }
         if (autoUpdateParent) {
           ctx.tree.moveNode(srcId, targetId)
           Reflect.set(src.original, parentField, targetId)
@@ -252,13 +331,23 @@ export const dnd: SpliceTreePlugin = {
         return
       }
       const pos = hoverPositions.get(targetId)
-      if (pos === DropPosition.BEFORE) {
-        drop(draggingId, targetId, DropPosition.BEFORE)
-      } else if (pos === DropPosition.AFTER) {
-        drop(draggingId, targetId, DropPosition.AFTER)
-      } else if (pos === DropPosition.INSIDE) {
-        drop(draggingId, targetId, DropPosition.INSIDE)
+      if (pos === undefined) {
+        hoverPositions.clear()
+        draggingId = undefined
+        ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
+        return
+      }
+
+      const draggedIds = getDraggedNodeIds(draggingId)
+      let idsToProcess = draggedIds
+      if (pos === DropPosition.AFTER) {
+        idsToProcess = [...draggedIds].reverse()
       }
+
+      for (const id of idsToProcess) {
+        drop(id, targetId, pos)
+      }
+
       hoverPositions.clear()
       draggingId = undefined
       ctx.events.emit({ name: 'visibility', keys: ctx.tree.expandedKeys() })
@@ -266,40 +355,56 @@ export const dnd: SpliceTreePlugin = {
 
     /**
      * 绑定到节点的拖拽属性集，便于直接 v-bind
+     * @param id 节点 ID
      */
-    const dragProps = {
-      draggable: true,
-      onDragstart: (e: DragEvent) => {
-        const el = e.currentTarget as HTMLElement
-        const id = el?.dataset?.id
-        if (id) {
-          e.dataTransfer?.setData('text/plain', id)
-          onDragStart(id)
-        }
-      },
-      onDragover: (e: DragEvent) => {
-        e.preventDefault()
-        const el = e.currentTarget as HTMLElement
-        const id = el?.dataset?.id
-        if (id) {
+    const dragProps = (id: string, behavior?: DragBehavior) => {
+      if (behavior) {
+        behaviors.set(id, behavior)
+      }
+      const canDrag = behavior?.draggable === false ? false : !isDisabledById(id)
+      return {
+        draggable: canDrag,
+        onDragstart: (e: DragEvent) => {
+          if (canDrag) {
+            e.dataTransfer?.setData('text/plain', id)
+            onDragStart(id)
+          }
+        },
+        onDragover: (e: DragEvent) => {
+          e.preventDefault()
+          const el = e.currentTarget as HTMLElement
           onDragOver(id, el, e)
-        }
-      },
-      onDragleave: (e: DragEvent) => {
-        const el = e.currentTarget as HTMLElement
-        const id = el?.dataset?.id
-        if (id) {
+        },
+        onDragleave: (_e: DragEvent) => {
           onDragLeave(id)
-        }
-      },
-      onDrop: (e: DragEvent) => {
-        e.preventDefault()
-        const el = e.currentTarget as HTMLElement
-        const id = el?.dataset?.id
-        if (id) {
+        },
+        onDrop: (e: DragEvent) => {
+          e.preventDefault()
           onDrop(id)
-        }
-      },
+        },
+      }
+    }
+
+    const ghostStyle = (opts?: { padding?: boolean, margin?: boolean }) => {
+      if (!draggingId || ghostPos === undefined) {
+        return { style: { display: 'none' } }
+      }
+      const usePadding = opts?.padding ?? true
+      const useMargin = opts?.margin ?? true
+      const leftInset = usePadding ? ghostInsetLeft : 0
+      const rightInset = usePadding ? ghostInsetRight : 0
+      const leftMargin = useMargin ? ghostMarginLeft : 0
+      const rightMargin = useMargin ? ghostMarginRight : 0
+      const left = `${leftInset + leftMargin}px`
+      const right = `${rightInset + rightMargin}px`
+      const base: Record<string, any> = { position: 'absolute', left, right, pointerEvents: 'none' }
+      if (ghostPos === DropPosition.BEFORE) {
+        return { 'style': { ...base, top: `${ghostTop}px`, height: '2px', background: 'var(--vp-code-color)', borderRadius: '2px' }, 'data-drop-position': -1 }
+      }
+      if (ghostPos === DropPosition.AFTER) {
+        return { 'style': { ...base, top: `${ghostTop + ghostHeight}px`, height: '2px', background: 'var(--vp-code-color)', borderRadius: '2px' }, 'data-drop-position': 1 }
+      }
+      return { 'style': { ...base, top: `${ghostTop}px`, height: `${ghostHeight}px`, background: 'var(--vp-code-color)', opacity: 0.15, borderRadius: '4px' }, 'data-drop-position': 0 }
     }
 
     return {
@@ -317,6 +422,7 @@ export const dnd: SpliceTreePlugin = {
       },
       // 通用 DOM 绑定集合
       dragProps,
+      ghostStyle,
     }
   },
   /**
@@ -327,7 +433,11 @@ export const dnd: SpliceTreePlugin = {
   extendNode(node, ctx) {
     node.getDropPosition = () => ctx.tree.hoverPositions.get(node.id)
     node.isDragging = () => ctx.tree.draggingId === node.id
+    const opts = (ctx.options?.configuration?.dnd ?? {}) as DndOptions
+    node.isDisabled = () => !!opts.readonly
   },
 }
 
 export default dnd
+export { DropPosition }
+export type { DndNode, DndOptions }

package/src/position.ts

@@ -0,0 +1,22 @@
+import type { SpliceTreeNode } from '@splicetree/core'
+import { DropPosition } from './types'
+
+export function computePosition(targetId: string, el: HTMLElement, e: DragEvent | MouseEvent, src?: SpliceTreeNode<any>): DropPosition | undefined {
+  const rect = el.getBoundingClientRect()
+  const y = ('clientY' in e ? e.clientY : 0) - rect.top
+  const ratio = Math.max(0, Math.min(1, rect.height ? y / rect.height : 0))
+  if (ratio < 0.33) {
+    return DropPosition.BEFORE
+  }
+  if (ratio > 0.66) {
+    return DropPosition.AFTER
+  }
+  if (src?.id === targetId) {
+    return undefined
+  }
+  const parentId = src?.getParent()?.id
+  if (parentId === targetId) {
+    return undefined
+  }
+  return DropPosition.INSIDE
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+/** dnd types */
+
+export interface DndNode {
+  id: string
+  level: number
+  parentId?: string
+  root?: boolean
+}
+
+export interface DragBehavior {
+  draggable?: boolean
+  sortable?: boolean
+  nestable?: boolean
+}
+
+export enum DropPosition {
+  BEFORE = -1,
+  INSIDE = 0,
+  AFTER = 1,
+}
+
+export interface DndOptions {
+  /** 执行拖拽后是否自动写回父字段并同步树结构 */
+  autoUpdateParent?: boolean
+  /** 拖入为子节点后是否自动展开目标节点 */
+  autoExpandOnDrop?: boolean
+  /** 全局只读，禁用所有拖拽与排序 */
+  readonly?: boolean
+}