企业官网建设流程全解析

简介：本资源是一个基于 Cocos Creator 实现的可交互拖拽排序列表完整工程，面向游戏开发初学者与中级开发者，解决 UI 中动态重排内容项的核心交互需求，适用于排行榜、技能栏、背包整理等常见游戏场景。压缩包共16个文件，含3个核心 TypeScript 脚本（实现拖拽逻辑、排序状态管理与节点位置更新）、5个 JSON 配置与序列化数据文件、1个主场景 fire 文件及配套 meta 元数据，整体体积仅243KB，轻量易集成。已有113人学习下载，资源结构清晰，Script 目录封装了事件监听（onDragStart/onDragMove/onDragEnd）、数组索引实时同步、视图批量重布局等关键逻辑，附带完整项目配置（tsconfig.json、project.json）与开发环境适配文件（.gitignore、.DS_Store），开箱即用，便于快速理解 Cocos Creator 中拖拽交互与 UI 动态刷新的协同机制。

1. 拖拽排序列表不是“加个 ondragstart 就完事”：Cocos Creator 3.x 中真实可用的交互闭环实现

你试过在 Cocos Creator 里拖拽列表项排序吗？别急着点运行——90% 的人卡在「拖起来能动，松手就回弹到原位」，或者「拖到中间位置没反应，只能拖到头尾才生效」，更别说多指触控、快速连续拖拽、跨容器排序这些真实业务场景。这不是 UI 组件库缺失的问题，而是 Cocos Creator 的事件系统、节点层级、坐标转换和排序逻辑之间存在三重隐性耦合：触摸事件坐标系与 Canvas 坐标系不一致、拖拽中节点脱离父容器导致 transform 失效、插入位置判断依赖视觉锚点而非逻辑索引。这份资源不是封装好的插件，而是一套经过 3 个上线项目验证的「可打断、可撤销、支持滚动容器」的拖拽排序落地方案，包含完整 TypeScript 实现、滚动边界处理策略、防抖插入判定逻辑，以及最关键的——如何让拖拽过程中的 placeholder 节点真正跟随手指移动而不抖动。适合正在开发后台管理页、任务看板、自定义组件面板、游戏内背包排序等需要用户主动组织数据顺序的 Cocos Creator 3.2+ 项目工程师。

2. 从零构建拖拽排序核心：事件监听、占位符生成与插入位置计算

2.1 为什么不用cc.Node自带的on('touchstart')？——事件穿透与坐标归一化必须重写

Cocos Creator 默认的touchstart事件在 ScrollView 或嵌套 Layout 容器中会因事件冒泡/拦截机制丢失原始触摸点，尤其当列表项本身含 Button 或 Image 组件时，event.getLocation()返回的是相对于触发节点的局部坐标，而非整个列表容器的全局坐标。直接使用会导致拖拽起点偏移、占位符错位。正确做法是统一在列表容器（如ScrollView.content）上监听touchstart，并手动做坐标归一化：

// 在列表容器脚本中（非单个 item） private _onTouchStart(event: cc.EventTouch) { const touch = event.getTouches()[0]; // 关键：将触摸点从屏幕坐标转为 content 节点的局部坐标 const worldPos = touch.getLocation(); const localPos = this.content.convertToNodeSpaceAR(worldPos); // 找到被点击的 item（需提前给每个 item 设置 name 或 tag） const hitItem = this._findItemByPosition(localPos); if (!hitItem) return; this._draggingItem = hitItem; this._dragStartLocalPos = localPos; this._dragStartIndex = this._getItemIndex(hitItem); // 立即禁用 ScrollView 滚动，防止拖拽时误触发 this.scrollView.scrollEventsEnabled = false; }

提示：convertToNodeSpaceAR比convertToNodeSpace更可靠，它自动处理了缩放、旋转、锚点偏移带来的坐标偏差，这是 Cocos Creator 3.x 中少有人提但极其关键的坐标转换函数。

2.2 占位符（Placeholder）不是 clone 节点：用空 Sprite + 动态尺寸模拟视觉反馈

很多教程教 clone item 节点作为 placeholder，这在 Cocos Creator 中极易引发内存泄漏和渲染异常——clone 后的节点仍持有原始脚本引用，且未正确挂载到新父节点下。真实项目中我们用一个纯 Sprite 节点模拟 placeholder，尺寸、颜色、透明度完全复刻原 item 的可视区域：

private _createPlaceholder(item: cc.Node): cc.Node { const placeholder = new cc.Node('placeholder'); const sprite = placeholder.addComponent(cc.Sprite); sprite.type = cc.Sprite.Type.SLICED; // 支持拉伸 sprite.sizeMode = cc.Sprite.SizeMode.CUSTOM; // 复制 item 的宽高（注意：需在 item 已完成 layout 后获取） const rect = item.getBoundingBoxToWorld(); const size = this.content.convertToWorldSpaceAR(cc.v2(0, 0)); const worldSize = this.content.convertToWorldSpaceAR(cc.v2(rect.width, rect.height)); const localSize = this.content.convertToNodeSpaceAR(worldSize).sub(this.content.convertToNodeSpaceAR(size)); placeholder.setContentSize(localSize); placeholder.color = new cc.Color(200, 200, 200, 100); // 灰色半透 // 添加到 content 下，zIndex 设为 -1，确保在所有 item 下层 placeholder.parent = this.content; placeholder.setSiblingIndex(-1); return placeholder; }

逻辑说明：

• getBoundingBoxToWorld()获取世界坐标包围盒，避免因父节点缩放导致尺寸失真；
• convertToWorldSpaceAR → convertToNodeSpaceAR是唯一能准确还原 item 在 content 内部实际占用像素尺寸的链式转换；
• setSiblingIndex(-1)让 placeholder 永远处于最底层，不遮挡其他 item，也不影响点击穿透。

2.3 插入位置不是“离谁近就插哪”：基于视觉中线的动态锚点判定算法

简单用distance < threshold判定插入位置，在快速拖拽或 item 高度不一时会频繁跳变。我们采用“当前 item 中线 vs 所有 item 中线距离”的稳定判定法，并引入滞后阈值（hysteresis）防抖：

private _getInsertIndex(touchLocalPos: cc.Vec2): number { const items = this._getSortedItems(); // 按 current siblingIndex 排序 if (items.length === 0) return 0; // 计算每个 item 的中线 y 坐标（在 content 局部坐标系下） const itemMidYs: number[] = items.map(item => { const rect = item.getBoundingBoxToWorld(); const worldCenter = rect.center; return this.content.convertToNodeSpaceAR(worldCenter).y; }); const currentY = touchLocalPos.y; let insertIndex = 0; // 找到第一个 itemMidY > currentY 的索引，即插入点应在该 item 之前 for (let i = 0; i < itemMidYs.length; i++) { if (itemMidYs[i] > currentY) { insertIndex = i; break; } } // 滞后判定：仅当 currentY 跨越 itemMidY ± 15px 时才更新 insertIndex if (this._lastInsertIndex !== -1 && Math.abs(currentY - itemMidYs[this._lastInsertIndex]) < 15) { insertIndex = this._lastInsertIndex; } else { this._lastInsertIndex = insertIndex; } return insertIndex; }

参数说明：

• 15px是经验阈值，适配 720p~1080p 屏幕，可根据实际 item 高度按比例调整（如itemHeight * 0.2）；
• this._lastInsertIndex缓存上一次有效插入索引，避免手指微抖导致插入点来回跳；
• 此算法天然支持 item 高度不一、滚动中动态加载新 item 的场景，无需重新计算全部位置。

3. 滚动容器兼容：ScrollView 拖拽跟随与边界减速控制

3.1 拖拽中 ScrollView 不该“静止”：用scrollToOffset实现手指驱动滚动

当拖拽 item 移动到 ScrollView 边界时，若 ScrollView 不响应，用户会感觉“拖不动”。但直接启用scrollEventsEnabled = true会导致 touchmove 事件被 ScrollView 拦截，拖拽中断。解法是关闭 ScrollView 自动事件，改用scrollToOffset主动控制滚动量：

private _onTouchMove(event: cc.EventTouch) { if (!this._draggingItem) return; const touch = event.getTouches()[0]; const worldPos = touch.getLocation(); const localPos = this.content.convertToNodeSpaceAR(worldPos); // 更新 placeholder 位置 this._placeholder.setPosition(localPos); // 计算 content 当前 scroll offset（注意：ScrollView 的 contentOffset 是负值） const currentOffset = this.scrollView.getContentPosition(); const contentHeight = this.content.height; const viewHeight = this.scrollView.node.height; // 手指靠近顶部/底部 100px 时触发滚动 const topTrigger = 100; const bottomTrigger = viewHeight - 100; if (localPos.y > bottomTrigger && currentOffset.y > -(contentHeight - viewHeight)) { // 向下滚动：offset.y 减小（负得更多） const scrollSpeed = Math.min(20, (localPos.y - bottomTrigger) * 0.5); this.scrollView.scrollToOffset(cc.v2(0, currentOffset.y - scrollSpeed), 0.01, false); } else if (localPos.y < topTrigger && currentOffset.y < 0) { // 向上滚动：offset.y 增大（负得更少） const scrollSpeed = Math.min(20, (topTrigger - localPos.y) * 0.5); this.scrollView.scrollToOffset(cc.v2(0, currentOffset.y + scrollSpeed), 0.01, false); } }

逻辑说明：

• scrollToOffset(..., 0.01, false)使用极短动画时间（0.01s）实现“瞬移”效果，避免滚动延迟感；
• scrollSpeed与手指离边界距离成正比，但上限设为 20px/frame，防止滚动过快失控；
• currentOffset.y > -(contentHeight - viewHeight)是 ScrollView 滚动到底部的判定条件，必须校验，否则会滚出空白区。

3.2 滚动时 placeholder 位置不能“断连”：动态补偿 content 偏移量

当 ScrollView 滚动时，this.content的世界坐标发生变化，但this._placeholder的 position 是相对于this.content的局部坐标，因此无需重设 position —— 这是 Cocos Creator 的父子关系优势。但需注意：如果 placeholder 是直接 addChild 到 scene root，则必须手动减去滚动偏移。我们的方案中 placeholder 始终 parent 为this.content，所以天然跟随滚动，这是设计前提。

3.3 边界减速不是“加个 easing”：用cc.tween实现物理感回弹

松手瞬间若直接 snap 到目标位置，体验生硬。我们用cc.tween模拟弹簧阻尼效果，让 placeholder 和 dragging item 同步回弹：

private _onTouchEnd() { if (!this._draggingItem || !this._placeholder) return; const targetIndex = this._getInsertIndex(this._placeholder.position); const targetPos = this._getTargetPosition(targetIndex); // 同时 tween placeholder 和 dragging item cc.tween(this._placeholder) .to(0.2, { position: targetPos }, { easing: 'cubicOut' }) .call(() => { this._insertItemAtIndex(this._draggingItem, targetIndex); this._cleanupDragState(); }) .start(); cc.tween(this._draggingItem) .to(0.2, { position: targetPos }, { easing: 'cubicOut' }) .start(); }

参数说明：

• cubicOut提供先快后慢的减速感，比quadOut更自然；
• 0.2s是实测最佳时长，短于 0.15s 显突兀，长于 0.25s 显拖沓；
• this._getTargetPosition(index)返回该索引对应 item 的目标坐标，需根据当前 layout（VerticalLayout / GridLayout）动态计算。

4. 避坑：Cocos Creator 拖拽排序的五个血泪经验

4.1 现象：拖拽过程中 item 突然消失或位置错乱

原因：在touchstart后立即调用item.removeFromParent()，但未设置item.active = false，导致渲染系统仍在尝试绘制已移除节点，引发 WebGL 错误或纹理丢失。
解决：移除前先item.active = false，并在touchend插入后item.active = true；或更稳妥地——全程不 removeFromParent，只修改item.parent为cc.Canvas.instance（画布根节点），拖拽结束再 re-parent 回 content。

4.2 现象：ScrollView 滚动后，placeholder 偏移量越来越大

原因：this._placeholder.setPosition(localPos)中的localPos是基于this.content的坐标，但this.content在滚动时其position会变化，而convertToNodeSpaceAR已内部处理此偏移，所以只要保证localPos计算逻辑不变，就不会偏移。真正错误在于：在touchmove中重复创建 placeholder 节点，旧节点未销毁，新旧节点叠加导致视觉错乱。
解决：_createPlaceholder前先if (this._placeholder) this._placeholder.destroy()；且_placeholder必须声明为类成员变量，不可在函数内const placeholder = ...。

4.3 现象：快速连续拖拽两次，第二次拖拽起点错位

原因：_dragStartLocalPos未在touchend后重置，第二次touchstart仍沿用第一次的起始坐标，导致localPos - _dragStartLocalPos计算偏移错误。
解决：在_onTouchEnd()结尾强制重置this._dragStartLocalPos = null，并在_onTouchStart()开头加if (this._draggingItem) return防重入。

4.4 现象：Android 打包 APK 后，拖拽响应延迟或失效

原因：Cocos Creator 3.x 在 Android 平台默认启用cc.macro.ENABLE_MULTI_TOUCH = false，导致多指操作干扰单指拖拽，且触摸事件队列积压。
解决：在app.js或main.ts初始化处添加：

cc.macro.ENABLE_MULTI_TOUCH = true; cc.game.config['orientation'] = 'portrait'; // 强制竖屏，减少横竖屏切换干扰

4.5 现象：列表项含 RichText 或 Mask 组件时，拖拽中文字闪烁或 mask 失效

原因：RichText 的 layout 是异步的，getBoundingBoxToWorld()在 layout 未完成时返回错误尺寸；Mask 组件在节点脱离原 parent 后，maskTarget 关系断裂。
解决：

• 对 RichText，改用richText.getComponent(cc.Label).getBounds()获取文本框尺寸；
• 对 Mask，拖拽开始前const mask = item.getComponent(cc.Mask); mask.enabled = false;，拖拽结束后mask.enabled = true；
• 更彻底的方案：拖拽期间将 item 的opacity设为 0，placeholder 显示完整视觉，避免任何渲染副作用。

5. 数据同步与撤销机制：让排序结果真正落库，且支持 Ctrl+Z

5.1 排序完成 ≠ 数据更新：必须显式触发数据源变更通知

Cocos Creator 的 UI 绑定（如cc.Label.string）不会自动响应数组顺序变化。若你的列表数据源是this.items: ItemData[]，排序后必须：

1. 用Array.splice+Array.splice交换元素，而非Array.sort()（后者不触发引用变更）；
2. 触发自定义事件通知 ViewModel；
3. 若用cc.Component绑定，需手动调用this.refreshView()。

private _insertItemAtIndex(item: cc.Node, targetIndex: number) { const currentIndex = this._getItemIndex(item); const dataItem = this._data[currentIndex]; // 从原位置删除 this._data.splice(currentIndex > targetIndex ? currentIndex : currentIndex + 1, 1); // 插入到目标位置（注意：currentIndex > targetIndex 时，原数组已少一位） this._data.splice(targetIndex, 0, dataItem); // 通知外部：排序已完成，数据已变更 this.node.emit('list-reordered', { oldIndex: currentIndex, newIndex: targetIndex, data: this._data }); // 刷新 UI：重建所有 item（安全但略重）或仅调整 siblingIndex（轻量但需确保 layout 逻辑健壮） this._refreshItemsFromData(); }

5.2 撤销（Undo）不是存快照：用操作日志 + 增量回滚降低内存占用

为每个排序操作记录oldIndex和newIndex，而非深拷贝整个数组（100 个 item 时内存暴增）。撤销时只需执行反向交换：

interface ReorderLog { oldIndex: number; newIndex: number; } private _undoStack: ReorderLog[] = []; private _logReorder(oldIndex: number, newIndex: number) { this._undoStack.push({ oldIndex, newIndex }); // 限制栈大小，防内存溢出 if (this._undoStack.length > 20) { this._undoStack.shift(); } } public undoLastReorder() { const log = this._undoStack.pop(); if (!log) return; // 反向操作：把 newIndex 的 item 插回 oldIndex const dataItem = this._data[log.newIndex]; this._data.splice(log.newIndex > log.oldIndex ? log.newIndex : log.newIndex + 1, 1); this._data.splice(log.oldIndex, 0, dataItem); this._refreshItemsFromData(); this.node.emit('list-undone', log); }

注意：log.newIndex > log.oldIndex的判断逻辑与_insertItemAtIndex中一致，确保正向/反向操作严格对称。

5.3 防二次提交：服务端排序接口必须带 version 字段校验

前端排序后立即调用api.updateOrder(items.map(i => i.id))存在并发风险。正确做法是：

• 每次排序后，本地递增this._version++；
• 请求体携带version: this._version；
• 服务端校验DB.version == request.version，不通过则返回409 Conflict；
• 前端收到 409 后，强制刷新列表并清空 undo stack。

从那以后我每次写拖拽排序，都强制走一遍「touchstart → touchmove → touchend」的坐标链路打印，用cc.log('world:', worldPos, 'local:', localPos)确认三者关系无误；也养成了在onEnable里检查cc.macro.ENABLE_MULTI_TOUCH的习惯，哪怕项目只跑 iOS。这些动作花不了 30 秒，却能避开 80% 的坐标类玄学问题。希望帮到你。

本文还有配套的精品资源，点击获取