前端UI组件【免费下载链接】vue-grid-layoutA draggable and resizable grid layout, for Vue.js.项目地址https://gitcode.com/gh_mirrors/vu/vue-grid-layout点击查看免费下载导读在 vue-grid-layout 的网格布局中拖拽与缩放一个格子时默认行为是“推开”其他格子级联移动让布局始终保持无重叠。而preventCollision防止碰撞属性则彻底改变这一行为开启后被拖拽的格子遇到占位冲突时会原地停止不再把其他格子挤走。本文以官方指南 07 - Prevent Collision 为主题结合 GridLayout 属性文档 与 GridLayout.vue、utils.js 的源码实现深入讲解该属性的含义、拖拽与缩放两种场景下的底层处理逻辑以及如何在自己的项目里复现官方示例的交互效果。一、preventCollision 是什么属性定义与默认值在GridLayout组件中preventCollision是一个布尔型 prop其官方定义与默认值如下见 properties.md项目值类型Boolean必填否默认值false含义决定网格项在被拖拽覆盖时是否会移动推开其他项对应的组件源码声明位于 GridLayout.vuepreventCollision: { type: Boolean, default: false },从源码看该属性直接参与拖拽时的布局计算在 GridLayout.vue 的拖拽回调中它被作为最后一个参数传入核心的moveElement函数this.layout moveElement(this.layout, l, x, y, true, this.preventCollision);因此它不是一个“展示层”开关而是从算法层面决定碰撞后采取哪种策略的关键参数。理解moveElement的内部逻辑就能彻底理解防止碰撞的行为本质。二、两种碰撞策略的本质区别为了直观理解我们先看两种模式下的行为差异默认模式preventCollision: false拖拽格子 A 到格子 B 的位置时B 会被“挤”到下一行或合适的空位A 顺利落到目标位置布局始终不重叠。这种级联移动让拖拽体验非常“顺滑”。防止碰撞模式preventCollision: true拖拽 A 时如果目标位置与 B 重叠A 会停在与 B 相邻的合法位置或者干脆停在原地B 纹丝不动。适合仪表盘、监控面板等“格子位置具有固定语义”、不希望用户无意间打乱既有布局的场景。官方演示见 07-prevent-collision.md正是让用户直观对比勾选 “Prevent Collision” 后再尝试把格子拖到已被占据的区域会发现被拖格子无法覆盖已有格子只能贴着它们停下。仓库根目录的演示工程 App.vue 中同样提供了一个 “Prevent Collision” 复选框绑定的数据项初始值为falseApp.vue并透传给grid-layout的:prevent-collisionpropApp.vueinput typecheckbox v-modelpreventCollision/ Prevent Collision ... grid-layout :layout.synclayout :col-numparseInt(colNum) :row-heightrowHeight :prevent-collisionpreventCollision ...三、源码原理moveElement 中的碰撞裁决moveElement定义于 utils.js它负责“移动一个元素并级联移动所有与之碰撞的元素”。其核心流程是记下元素移动前的旧坐标oldX/oldY更新元素到新坐标x/y并标记moved true按“行、列”排序布局后用getAllCollisions找出所有与新位置重叠的格子裁决如果preventCollision为true且存在碰撞则回滚坐标、清除moved标记、直接返回原布局——也就是“禁止这次移动”utils.jsif (preventCollision collisions.length) { l.x oldX; l.y oldY; l.moved false; return layout; }如果preventCollision为false默认则逐个把碰撞格子“推离”当前位置moveElementAwayFromCollision实现级联让位。由此可见防止碰撞并不是“复杂地寻找替代位置”而是简单干脆地拒绝越界一旦目标格与任何非静态格子重叠本次移动整体回滚拖拽中的格子停留在旧位置。静态格子的特例值得注意的是在默认模式级联移动下moveElement对static静态格子有特殊处理静态格子不会被推动冲突时反而是被拖拽的格子自己让开utils.js。这意味着即使不开preventCollision被标记为static的格子也天然具备“不被挤走”的特性二者可以组合使用以更精细地控制哪些区域允许被覆盖。四、缩放resize场景下的防止碰撞防止碰撞不仅作用于拖拽也作用于缩放。在 GridLayout.vue 的resizeEvent中当preventCollision为true时组件会先基于“缩放后的假想尺寸”检测碰撞let hasCollisions; if (this.preventCollision) { const collisions getAllCollisions(this.layout, { ...l, w, h }).filter( layoutItem layoutItem.i ! l.i ); hasCollisions collisions.length 0; // If were colliding, we need adjust the placeholder. if (hasCollisions) { // adjust w h to maximum allowed space let leastX Infinity, leastY Infinity; collisions.forEach(layoutItem { if (layoutItem.x l.x) leastX Math.min(leastX, layoutItem.x); if (layoutItem.y l.y) leastY Math.min(leastY, layoutItem.y); }); if (Number.isFinite(leastX)) l.w leastX - l.x; if (Number.isFinite(leastY)) l.h leastY - l.y; } }这里的关键在于不是直接禁止缩放而是把格子的w/h收缩到“可容纳的最大尺寸”。例如右侧 3 个格子处有障碍则宽度被限制为“障碍格 x 坐标 − 当前 x 坐标”下方同理限制高度。这样既防止了重叠又保留了用户“尽可能放大”的操作意图体验比单纯回滚更细腻。五、完整实战示例在自己的项目中启用防止碰撞把官方演示的思路搬到自己的组件中通常需要三部分一个布尔开关、绑定到grid-layout的 prop、以及一组带位置信息的 layout 数据。template div label input typecheckbox v-modelpreventCollision/ Prevent Collision /label grid-layout :layout.synclayout :col-num12 :row-height30 :prevent-collisionpreventCollision layout-updatedlayoutUpdatedEvent grid-item v-foritem in layout :keyitem.i :xitem.x :yitem.y :witem.w :hitem.h span classtext{{ item.i }}/span /grid-item /grid-layout /div /template script import VueGridLayout from vue-grid-layout; export default { components: { GridLayout: VueGridLayout.GridLayout, GridItem: VueGridLayout.GridItem }, data() { return { preventCollision: false, layout: [ { x: 0, y: 0, w: 2, h: 2, i: 0 }, { x: 2, y: 0, w: 2, h: 2, i: 1 }, { x: 4, y: 0, w: 2, h: 2, i: 2 } ] }; }, methods: { layoutUpdatedEvent(newLayout) { console.log(layout updated:, newLayout); } } }; /script要点说明layout数组中的每个对象都必须包含i唯一标识、x、y、w、hw以列为单位、h以行为单位详见 properties.md组件通过.sync修饰符双向同步 layoutlayout-updated可在拖拽/缩放结束后拿到最新布局运行演示工程时勾选/取消 “Prevent Collision” 复选框即可实时对比两种碰撞策略。六、与相关属性的配合与适用场景preventCollision通常需要结合其他属性才能达到理想效果restoreOnDrag默认false开启后拖拽结束不进行“上浮压实”配合防止碰撞可以最大程度保留用户摆放的原始坐标避免松手后格子又被compact顶到别处相关实现见 GridLayout.vueverticalCompact默认true控制布局是否垂直压实。在防止碰撞场景下若希望“留白也保留”可考虑关闭垂直压实static对个别格子开启静态属性使它们既不可拖拽、也不可被其他格子推动实现“绝对锚定”区域isDraggable/isResizable若只是不希望某几个格子被移动用这两个 per-item 属性更精准无需全局开启防止碰撞。典型适用场景包括运维监控大屏中告警卡片的位置固定、报表看板的区块锁定、以及“格子即业务实体”的排班/排产类界面。需要注意preventCollision是全局行为开关若需要“部分格子可被覆盖、部分不可”应优先使用static或 item 级isDraggable组合实现。七、注意事项preventCollision在拖拽与缩放中都会生效但策略不同拖拽是整体回滚缩放是收缩到最大可用尺寸两者都是为了避免布局重叠防止碰撞模式下拖拽的“自由度”明显下降格子可能“卡住”无法跨越障碍交互时需要给用户清晰的视觉反馈如拖拽中的半透明占位符该属性属于GridLayout级配置item 无法单独覆盖若个别格子需要例外请结合 static 属性 使用本文所有行为描述均对应当前仓库源码版本见 GridLayout.vue、utils.js升级依赖前请以目标版本的实际行为为准。小结防止碰撞并非简单的“禁止拖动”而是由moveElement的碰撞裁决与resizeEvent的尺寸收缩共同构成的完整策略。理解 utils.js 中preventCollision collisions.length这一关键分支以及 GridLayout.vue 中对缩放尺寸的裁剪逻辑你就能在仪表盘、看板、排班表等场景中准确预判格子行为并组合restoreOnDrag、verticalCompact、static等属性设计出符合业务预期的交互方案。赞分享前端UI组件【免费下载链接】vue-grid-layoutA draggable and resizable grid layout, for Vue.js.项目地址https://gitcode.com/gh_mirrors/vu/vue-grid-layout点击查看免费下载相关推荐Flow PHP核心组件深度解析理解DataFrame、Rows与Row的架构设计Flow PHP核心组件深度解析理解DataFrame、Rows与Row的架构设计 想要构建高效、类型安全的PHP数据处理管道Flow PHP框架的核心组件如何精通vue-grid-layout从配置到实战的完整指南如何精通vue grid layout从配置到实战的完整指南 还在为Vue项目中的拖拽布局配置而头疼吗作为Vue.js生态中最强大的网格系统之一vue g前端UI组件Vue Grid Layout 终极防碰撞指南如何彻底解决网格项目重叠问题Vue Grid Layout 终极防碰撞指南如何彻底解决网格项目重叠问题 在构建现代化仪表板、管理系统或数据可视化应用时网格布局系统是不可或缺的工具。 V前端UI组件上一篇Gemma-4-31B模型高效部署方案硬件配置与性能优化实践下一篇Paperless-ngx 多语言部署 3 个参数速成中文界面、chi_sim OCR 与日期解析全配通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
vue-grid-layout 防止碰撞（preventCollision）机制：从配置到源码的完整解析
前端UI组件【免费下载链接】vue-grid-layoutA draggable and resizable grid layout, for Vue.js.项目地址https://gitcode.com/gh_mirrors/vu/vue-grid-layout点击查看免费下载导读在 vue-grid-layout 的网格布局中拖拽与缩放一个格子时默认行为是“推开”其他格子级联移动让布局始终保持无重叠。而preventCollision防止碰撞属性则彻底改变这一行为开启后被拖拽的格子遇到占位冲突时会原地停止不再把其他格子挤走。本文以官方指南 07 - Prevent Collision 为主题结合 GridLayout 属性文档 与 GridLayout.vue、utils.js 的源码实现深入讲解该属性的含义、拖拽与缩放两种场景下的底层处理逻辑以及如何在自己的项目里复现官方示例的交互效果。一、preventCollision 是什么属性定义与默认值在GridLayout组件中preventCollision是一个布尔型 prop其官方定义与默认值如下见 properties.md项目值类型Boolean必填否默认值false含义决定网格项在被拖拽覆盖时是否会移动推开其他项对应的组件源码声明位于 GridLayout.vuepreventCollision: { type: Boolean, default: false },从源码看该属性直接参与拖拽时的布局计算在 GridLayout.vue 的拖拽回调中它被作为最后一个参数传入核心的moveElement函数this.layout moveElement(this.layout, l, x, y, true, this.preventCollision);因此它不是一个“展示层”开关而是从算法层面决定碰撞后采取哪种策略的关键参数。理解moveElement的内部逻辑就能彻底理解防止碰撞的行为本质。二、两种碰撞策略的本质区别为了直观理解我们先看两种模式下的行为差异默认模式preventCollision: false拖拽格子 A 到格子 B 的位置时B 会被“挤”到下一行或合适的空位A 顺利落到目标位置布局始终不重叠。这种级联移动让拖拽体验非常“顺滑”。防止碰撞模式preventCollision: true拖拽 A 时如果目标位置与 B 重叠A 会停在与 B 相邻的合法位置或者干脆停在原地B 纹丝不动。适合仪表盘、监控面板等“格子位置具有固定语义”、不希望用户无意间打乱既有布局的场景。官方演示见 07-prevent-collision.md正是让用户直观对比勾选 “Prevent Collision” 后再尝试把格子拖到已被占据的区域会发现被拖格子无法覆盖已有格子只能贴着它们停下。仓库根目录的演示工程 App.vue 中同样提供了一个 “Prevent Collision” 复选框绑定的数据项初始值为falseApp.vue并透传给grid-layout的:prevent-collisionpropApp.vueinput typecheckbox v-modelpreventCollision/ Prevent Collision ... grid-layout :layout.synclayout :col-numparseInt(colNum) :row-heightrowHeight :prevent-collisionpreventCollision ...三、源码原理moveElement 中的碰撞裁决moveElement定义于 utils.js它负责“移动一个元素并级联移动所有与之碰撞的元素”。其核心流程是记下元素移动前的旧坐标oldX/oldY更新元素到新坐标x/y并标记moved true按“行、列”排序布局后用getAllCollisions找出所有与新位置重叠的格子裁决如果preventCollision为true且存在碰撞则回滚坐标、清除moved标记、直接返回原布局——也就是“禁止这次移动”utils.jsif (preventCollision collisions.length) { l.x oldX; l.y oldY; l.moved false; return layout; }如果preventCollision为false默认则逐个把碰撞格子“推离”当前位置moveElementAwayFromCollision实现级联让位。由此可见防止碰撞并不是“复杂地寻找替代位置”而是简单干脆地拒绝越界一旦目标格与任何非静态格子重叠本次移动整体回滚拖拽中的格子停留在旧位置。静态格子的特例值得注意的是在默认模式级联移动下moveElement对static静态格子有特殊处理静态格子不会被推动冲突时反而是被拖拽的格子自己让开utils.js。这意味着即使不开preventCollision被标记为static的格子也天然具备“不被挤走”的特性二者可以组合使用以更精细地控制哪些区域允许被覆盖。四、缩放resize场景下的防止碰撞防止碰撞不仅作用于拖拽也作用于缩放。在 GridLayout.vue 的resizeEvent中当preventCollision为true时组件会先基于“缩放后的假想尺寸”检测碰撞let hasCollisions; if (this.preventCollision) { const collisions getAllCollisions(this.layout, { ...l, w, h }).filter( layoutItem layoutItem.i ! l.i ); hasCollisions collisions.length 0; // If were colliding, we need adjust the placeholder. if (hasCollisions) { // adjust w h to maximum allowed space let leastX Infinity, leastY Infinity; collisions.forEach(layoutItem { if (layoutItem.x l.x) leastX Math.min(leastX, layoutItem.x); if (layoutItem.y l.y) leastY Math.min(leastY, layoutItem.y); }); if (Number.isFinite(leastX)) l.w leastX - l.x; if (Number.isFinite(leastY)) l.h leastY - l.y; } }这里的关键在于不是直接禁止缩放而是把格子的w/h收缩到“可容纳的最大尺寸”。例如右侧 3 个格子处有障碍则宽度被限制为“障碍格 x 坐标 − 当前 x 坐标”下方同理限制高度。这样既防止了重叠又保留了用户“尽可能放大”的操作意图体验比单纯回滚更细腻。五、完整实战示例在自己的项目中启用防止碰撞把官方演示的思路搬到自己的组件中通常需要三部分一个布尔开关、绑定到grid-layout的 prop、以及一组带位置信息的 layout 数据。template div label input typecheckbox v-modelpreventCollision/ Prevent Collision /label grid-layout :layout.synclayout :col-num12 :row-height30 :prevent-collisionpreventCollision layout-updatedlayoutUpdatedEvent grid-item v-foritem in layout :keyitem.i :xitem.x :yitem.y :witem.w :hitem.h span classtext{{ item.i }}/span /grid-item /grid-layout /div /template script import VueGridLayout from vue-grid-layout; export default { components: { GridLayout: VueGridLayout.GridLayout, GridItem: VueGridLayout.GridItem }, data() { return { preventCollision: false, layout: [ { x: 0, y: 0, w: 2, h: 2, i: 0 }, { x: 2, y: 0, w: 2, h: 2, i: 1 }, { x: 4, y: 0, w: 2, h: 2, i: 2 } ] }; }, methods: { layoutUpdatedEvent(newLayout) { console.log(layout updated:, newLayout); } } }; /script要点说明layout数组中的每个对象都必须包含i唯一标识、x、y、w、hw以列为单位、h以行为单位详见 properties.md组件通过.sync修饰符双向同步 layoutlayout-updated可在拖拽/缩放结束后拿到最新布局运行演示工程时勾选/取消 “Prevent Collision” 复选框即可实时对比两种碰撞策略。六、与相关属性的配合与适用场景preventCollision通常需要结合其他属性才能达到理想效果restoreOnDrag默认false开启后拖拽结束不进行“上浮压实”配合防止碰撞可以最大程度保留用户摆放的原始坐标避免松手后格子又被compact顶到别处相关实现见 GridLayout.vueverticalCompact默认true控制布局是否垂直压实。在防止碰撞场景下若希望“留白也保留”可考虑关闭垂直压实static对个别格子开启静态属性使它们既不可拖拽、也不可被其他格子推动实现“绝对锚定”区域isDraggable/isResizable若只是不希望某几个格子被移动用这两个 per-item 属性更精准无需全局开启防止碰撞。典型适用场景包括运维监控大屏中告警卡片的位置固定、报表看板的区块锁定、以及“格子即业务实体”的排班/排产类界面。需要注意preventCollision是全局行为开关若需要“部分格子可被覆盖、部分不可”应优先使用static或 item 级isDraggable组合实现。七、注意事项preventCollision在拖拽与缩放中都会生效但策略不同拖拽是整体回滚缩放是收缩到最大可用尺寸两者都是为了避免布局重叠防止碰撞模式下拖拽的“自由度”明显下降格子可能“卡住”无法跨越障碍交互时需要给用户清晰的视觉反馈如拖拽中的半透明占位符该属性属于GridLayout级配置item 无法单独覆盖若个别格子需要例外请结合 static 属性 使用本文所有行为描述均对应当前仓库源码版本见 GridLayout.vue、utils.js升级依赖前请以目标版本的实际行为为准。小结防止碰撞并非简单的“禁止拖动”而是由moveElement的碰撞裁决与resizeEvent的尺寸收缩共同构成的完整策略。理解 utils.js 中preventCollision collisions.length这一关键分支以及 GridLayout.vue 中对缩放尺寸的裁剪逻辑你就能在仪表盘、看板、排班表等场景中准确预判格子行为并组合restoreOnDrag、verticalCompact、static等属性设计出符合业务预期的交互方案。赞分享前端UI组件【免费下载链接】vue-grid-layoutA draggable and resizable grid layout, for Vue.js.项目地址https://gitcode.com/gh_mirrors/vu/vue-grid-layout点击查看免费下载相关推荐Flow PHP核心组件深度解析理解DataFrame、Rows与Row的架构设计Flow PHP核心组件深度解析理解DataFrame、Rows与Row的架构设计 想要构建高效、类型安全的PHP数据处理管道Flow PHP框架的核心组件如何精通vue-grid-layout从配置到实战的完整指南如何精通vue grid layout从配置到实战的完整指南 还在为Vue项目中的拖拽布局配置而头疼吗作为Vue.js生态中最强大的网格系统之一vue g前端UI组件Vue Grid Layout 终极防碰撞指南如何彻底解决网格项目重叠问题Vue Grid Layout 终极防碰撞指南如何彻底解决网格项目重叠问题 在构建现代化仪表板、管理系统或数据可视化应用时网格布局系统是不可或缺的工具。 V前端UI组件上一篇Gemma-4-31B模型高效部署方案硬件配置与性能优化实践下一篇Paperless-ngx 多语言部署 3 个参数速成中文界面、chi_sim OCR 与日期解析全配通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
