Vue Grid Layout 完全介绍 – wiki基地

作者： /

Vue Grid Layout 完全介绍：构建强大、灵活、可交互的网格布局

在现代Web应用开发中，构建灵活、可交互的布局是一个常见的需求。特别是那些需要用户自定义界面的场景，如仪表盘、在线编辑器、或者可拖拽的组件面板。传统的CSS布局方式（如Flexbox或CSS Grid）虽然强大，但它们主要用于静态或响应式的布局，对于需要运行时拖拽、改变大小、自动排列（碰撞检测）等动态交互的场景，实现起来会异常复杂，甚至需要大量的JavaScript代码来处理DOM操作、位置计算、碰撞检测等逻辑。

这时，我们就需要一个专门的库来简化这项工作。在Vue生态系统中，vue-grid-layout 是一个非常流行且功能强大的选择。它提供了一套基于网格的布局系统，天然支持元素的拖拽、改变大小，并能自动处理元素之间的位置冲突，极大地降低了开发复杂动态布局的难度。

本文将对 vue-grid-layout 进行一次全面、深入的介绍，从基本概念到高级用法，帮助您掌握如何利用它来构建令人惊艳的交互式网格布局。

第一部分：初识 Vue Grid Layout

1.1 什么是 Vue Grid Layout？

vue-grid-layout 是一个基于 Vue.js 的可拖拽、可调整大小的响应式网格布局系统。它的灵感来源于流行的 JavaScript 库 React-Grid-Layout，并针对 Vue.js 的特性进行了优化。

核心理念是：将页面区域划分为一个虚拟的网格（grid），页面上的各个元素（或称之为“项”，item）占据网格中的特定位置和尺寸。vue-grid-layout 负责管理这些项在网格中的位置和大小，并提供拖拽和改变大小的功能，当用户操作时，自动更新项的位置和尺寸，并处理与其他项的碰撞问题。

1.2 为什么选择 Vue Grid Layout？

相比于手动实现或使用纯CSS，vue-grid-layout 提供了以下显著优势：

  • 强大的交互性: 内置支持元素的拖拽和改变大小，无需编写复杂的事件处理和DOM操作代码。
  • 自动碰撞检测和排列: 当拖拽或调整大小时，如果一个项与另一个项重叠，vue-grid-layout 会自动调整其他项的位置，避免重叠，并保持布局的紧凑性（通常是垂直方向）。
  • 简单的数据模型: 使用一个简单的JavaScript数组来描述整个布局，数组中的每个对象代表一个网格项，包含其位置 (x, y)、尺寸 (w, h) 和唯一标识 (i) 等信息。这使得布局状态的管理、保存和恢复变得非常直观。
  • 基于 Vue 的组件化: 作为 Vue 组件，它能很好地融入 Vue 项目，利用 Vue 的数据驱动、组件插槽等特性。
  • 响应式能力（有限但有用）: 虽然不是严格意义上的CSS Media Query响应式，但它可以通过调整网格列数 (colNum) 来适应不同屏幕宽度，从而实现一定程度的布局自适应。
  • 灵活性: 支持固定（Static）项、最小/最大尺寸限制、自定义拖拽/调整大小手柄等功能。

1.3 适用场景

vue-grid-layout 特别适合以下场景：

  • 仪表盘/数据可视化面板: 用户可以自由排列、调整图表、数据卡片等组件的位置和大小。
  • 可定制化的用户界面: 允许用户根据自己的喜好组织界面元素的布局。
  • 页面/表单构建器: 用户通过拖拽组件来构建页面或表单。
  • 任何需要复杂拖拽和放置交互的网格布局。

第二部分：快速上手

2.1 安装

使用 npm 或 yarn 进行安装：

“`bash
npm install vue-grid-layout –save

或

yarn add vue-grid-layout
“`

2.2 基本使用

vue-grid-layout 提供了两个主要组件：

  • <grid-layout>: 网格容器组件，负责管理整个网格的布局和行为。
  • <grid-item>: 网格项组件，代表网格中的一个可放置、可拖拽、可调整大小的元素。

基本的组件结构如下：

“`html

“`

代码解释：

  • layout 数据数组：这是核心。每个对象 { x, y, w, h, i } 定义了一个网格项。
    • x: 项在网格中的水平位置（列索引），从0开始。
    • y: 项在网格中的垂直位置（行索引），从0开始。
    • w: 项的宽度，占用的网格列数。
    • h: 项的高度，占用的网格行数（基于 row-height 计算实际像素高度）。
    • i: 项的唯一标识符，必需且唯一，通常使用字符串或数字。在 Vue 的 v-for 中也用作 :key。
  • <grid-layout> 组件的属性：
    • :layout.sync="layout": 关键属性。通过 .sync 修饰符实现了双向绑定。grid-layout 会监听 layout 数组的变化来渲染网格，同时当用户拖拽或调整大小时，grid-layout 会更新内部计算出的新位置和尺寸，并通过 .sync 将这些变化反映回组件的 layout 数据中。注意：在新版本的Vue中，.sync 已被 v-model 替代，但对于对象或数组属性，.sync 仍然是推荐的用法，或者手动监听 @update:layout 事件来更新数据。这里使用 .sync 是 vue-grid-layout 常用且兼容的方式。
    • :col-num="12": 定义网格的总列数。常见的有12列，方便进行1/2, 1/3, 1/4 等布局划分。
    • :row-height="30": 定义每一行网格的高度（单位：像素）。项的实际高度是 h * row-height + (h-1) * margin[1]。
    • :is-draggable="true": 是否允许拖拽网格项。
    • :is-resizable="true": 是否允许调整网格项的大小。
    • :vertical-compact="true": 是否开启垂直方向的紧凑排列。开启后，项会尽可能向上移动，填充网格中的空白区域。这是 vue-grid-layout 默认且推荐的行为。
    • :use-css-transforms="true": 是否使用 CSS transform 进行位置定位。通常开启以获得更好的性能。
  • <grid-item> 组件的属性：
    • :x, :y, :w, :h, :i: 这些属性直接绑定到 layout 数组中对应项的属性。grid-item 根据这些属性计算并设置自身的定位和尺寸。
    • :key="item.i": Vue 列表渲染中必需的唯一key，与 :i 相同。
    • <!-- 网格项的内容放在这里 -->: <grid-item> 使用默认插槽来放置其内部的实际内容，可以是任何Vue组件或HTML元素。

运行这段代码，您应该能看到一个包含12个可拖拽、可调整大小的方块组成的网格布局。

第三部分：深入理解核心概念与属性

3.1 网格系统的工作原理

vue-grid-layout 将容器宽度平均分配给 col-num 列。每列的宽度是 容器宽度 / col-num。每行的高度是固定的 row-height 像素。

一个网格项 (grid-item) 的位置和尺寸完全由其 x, y, w, h 属性决定：

  • x: 定义了项的左边缘所在的列索引。例如 x: 0 表示最左边，x: 1 表示从第二列开始。
  • y: 定义了项的上边缘所在的行索引。例如 y: 0 表示最上面，y: 1 表示从第二行开始。
  • w: 定义了项占据的列数。实际宽度是 w * (列宽) + (w-1) * margin[0]。
  • h: 定义了项占据的行数。实际高度是 h * row-height + (h-1) * margin[1]。

整个布局的高度由最底部的项决定，grid-layout 容器会自动调整其高度以包含所有项。

3.2 <grid-layout> 常用属性详解

除了上面基本使用中提到的属性，<grid-layout> 还有许多其他重要的属性：

  • :margin="[10, 10]": 定义网格项之间的水平和垂直外边距（单位：像素）。数组第一个值是水平外边距，第二个值是垂直外边距。默认是 [10, 10]。
  • :container-padding="[10, 10]": 定义网格容器内部的水平和垂直内边距（单位：像素）。数组第一个值是水平内边距，第二个值是垂直内边距。默认是 null (即 margin 的值)。
  • :is-mirrored="false": 是否开启镜像模式。在 RTL (Right-to-Left) 语言布局中可能有用，会使布局从右到左排列。
  • :auto-size="true": grid-layout 容器是否根据内容自动调整高度。通常保持为 true。
  • :vertical-compact="true": 是否开启垂直紧凑排列。推荐开启。
  • :restore-on-drag="false": 在开始拖拽时是否恢复到拖拽前的原始位置。设置为 true 可以防止拖拽过程中误触碰撞导致布局混乱，松开鼠标时才应用最终位置。
  • :prevent-collision="false": 是否启用简单的碰撞阻止。如果设置为 true，在拖拽或调整大小时，vue-grid-layout 会尝试阻止当前项与任何其他项重叠。这与 vertical-compact 的自动向下移动不同，它可能会阻止操作本身。通常与 vertical-compact 一起使用，但需要理解其行为可能不如 vertical-compact 智能。
  • :layout-type="null": 允许指定布局类型，目前支持 "horizontal" 水平排列（不常用，且可能行为不稳定）。默认或 null 是垂直紧凑。
  • :responsive="false": 重要但容易误解。这个属性本身并不能使布局在不同屏幕尺寸下自动改变网格项的 w, h。它更多是与 breakpoints 和 cols 属性配合使用，用于在不同断点下改变网格的总列数 (colNum)，然后布局会基于新的列数重新计算项的位置和尺寸。真正的响应式通常需要您自己根据断点提供不同的 layout 数组，或者监听窗口大小变化并动态更新 colNum。详细说明见响应式部分。
  • :breakpoints="{lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0}": 当 :responsive="true" 时使用，定义响应式断点和对应的容器宽度（单位：像素）。
  • :cols="{lg: 12, md: 10, sm: 6, xs: 4, xxs: 2}": 当 :responsive="true" 时使用，定义每个断点下对应的 colNum。

3.3 <grid-item> 常用属性详解

除了 x, y, w, h, i 这五个必需属性，<grid-item> 也有一些重要的额外属性：

  • :static="false": 如果设置为 true，该网格项将固定在当前位置和尺寸，既不能被拖拽，也不能改变大小，其他项也不能移动到它占据的空间。
  • :min-w="1": 设置该项的最小宽度，单位是网格列数。
  • :max-w="Infinity": 设置该项的最大宽度，单位是网格列数。
  • :min-h="1": 设置该项的最小高度，单位是网格行数。
  • :max-h="Infinity": 设置该项的最大高度，单位是网格行数。
  • :is-draggable="null": 覆盖父容器 grid-layout 的 is-draggable 属性。设置为 true 或 false 可以单独控制该项是否可拖拽。null 表示继承父容器设置。
  • :is-resizable="null": 覆盖父容器 grid-layout 的 is-resizable 属性。设置为 true 或 false 可以单独控制该项是否可调整大小。null 表示继承父容器设置。
  • :drag-ignore="'.no-drag'": 设置一个CSS选择器字符串。匹配该选择器的元素上的拖拽事件将被忽略，不会触发网格项的拖拽。常用于项内部的可交互元素（如按钮、输入框），防止拖拽父容器而不是操作这些元素。
  • :resize-ignore="'.no-resize'": 类似 drag-ignore，用于忽略特定元素上的调整大小事件。
  • :drag-allow-from="'.drag-handle'": 设置一个CSS选择器字符串。只有在匹配该选择器的元素上按下鼠标并拖拽时，才允许拖拽整个网格项。常用于创建自定义拖拽手柄。
  • :resize-handle="'.resize-handle'": 设置一个CSS选择器字符串。只有在匹配该选择器的元素上按下鼠标并拖拽时，才允许调整网格项的大小。常用于创建自定义调整大小手柄。默认情况下，调整大小手柄是一个小小的三角形位于项的右下角。

3.4 关于 :layout.sync 和布局更新

:layout.sync 是 vue-grid-layout 核心的用法。它意味着：

  1. 您在 data 中定义了一个 layout 数组，作为网格的初始状态。
  2. vue-grid-layout 读取这个数组来渲染网格。
  3. 当用户拖拽或调整大小时，或者网格因为其他项移动而需要重新排列时，vue-grid-layout 会计算出新的 layout 数组状态。
  4. 通过 .sync，vue-grid-layout 会触发一个名为 update:layout 的事件，并将新的 layout 数组作为参数传递。
  5. Vue 接收到这个事件后，会自动更新您的 layout 数据，从而驱动视图重新渲染。

这意味着您的 layout 数据始终是网格的“单一数据源”。任何对布局的改变（无论是用户交互还是程序逻辑）都应该最终反映在 layout 数组中。

注意： 直接修改 layout 数组中项的属性（如 item.x = 5）通常是安全的，Vue 的响应式系统会捕捉到这些变化并更新视图。但是，如果您需要添加或移除项，必须使用 Vue 能够检测到的数组变动方法，例如 splice, push, pop 等，或者创建新的数组实例替换旧的数组。

“`javascript
// 添加一个新项
this.layout.push({ x: 0, y: Infinity, w: 2, h: 2, i: this.newItemId++ });
// y: Infinity 会让 grid-layout 将其放置在当前网格的最下方可用位置

// 移除一个项 (假设要移除 i 为 ‘someId’ 的项)
const index = this.layout.findIndex(item => item.i === ‘someId’);
if (index !== -1) {
this.layout.splice(index, 1);
}
“`

3.5 唯一标识 i 的重要性

每个 grid-item 都必须有一个唯一的 i 属性。这个 i 属性有两个主要作用：

  1. 作为 Vue 列表渲染的 :key: 帮助 Vue 跟踪每个节点的身份，提高渲染性能和列表状态管理。
  2. 作为 vue-grid-layout 内部识别和管理项的标识: vue-grid-layout 使用 i 来查找、更新和操作特定的网格项。

确保 i 的唯一性和稳定性对于 vue-grid-layout 的正常工作至关重要。避免在渲染过程中动态生成不稳定的 i 值。

第四部分：响应式与断点

vue-grid-layout 的响应式能力与传统的CSS Media Query响应式有所不同。它不是通过改变元素的CSS样式来实现布局的响应，而是通过在不同的容器宽度断点下，改变网格的总列数 (colNum) 来实现布局的自适应。

当 :responsive="true" 并且设置了 :breakpoints 和 :cols 属性时，vue-grid-layout 会监听容器的宽度。当容器宽度跨越某个断点时，它会：

  1. 确定当前所属的断点（例如，容器宽度在 768px 到 995px 之间，属于 sm 断点）。
  2. 获取该断点对应的 colNum 值（例如，cols 中 sm 对应的是 6）。
  3. 将 grid-layout 的 colNum 属性设置为这个新的值。
  4. 基于新的 colNum 和现有的 layout 数据，重新计算所有网格项的实际像素位置和尺寸，并更新视图。

重要提示：

  • 这种方式不会改变 layout 数组中每个项的 w 和 h 值。w 和 h 始终是相对于当前断点下的总列数 (colNum)。一个 w: 4 的项，在 colNum: 12 时占据总宽度的 1/3，但在 colNum: 6 时会占据总宽度的 2/3。
  • 如果您需要在不同断点下完全改变某些项的 w、h 甚至 x、y，或者根据断点显示/隐藏某些项，您需要自己管理不同断点下的不同 layout 数组。一种常见的做法是根据当前断点动态切换绑定到 :layout 的数据源。vue-grid-layout 提供了 @breakpoint-changed 事件，您可以监听此事件，根据新的断点名称加载或计算对应的布局数据。

“`html

``
通过监听@breakpoint-changed事件并动态切换:layout和:col-num`，您可以实现更灵活的响应式行为。

第五部分：事件处理

vue-grid-layout 暴露了多个事件，允许您在布局发生变化时执行相应的逻辑。这些事件对于保存用户自定义布局状态、触发动画或其他副作用非常有用。

以下是一些常用的事件：

  • @layout-created(): 网格布局首次创建时触发，此时DOM元素可能还未完全渲染。
  • @layout-before-mount(): 网格布局在挂载前触发。
  • @layout-mounted(newLayout): 网格布局首次挂载到DOM后触发。newLayout 是当前的布局数组。
  • @layout-updated(newLayout): 最常用。当网格布局发生任何变化（拖拽结束、调整大小结束、项添加/移除、因为碰撞导致位置改变等）并重新计算完成后触发。newLayout 是更新后的布局数组。您通常会监听此事件来保存布局状态。
  • @breakpoint-changed(newBreakpoint, newCols): 当容器宽度跨越断点，导致 colNum 改变时触发。
  • @drag-start(i, newX, newY): 开始拖拽某个项时触发。i 是项的ID，newX, newY 是拖拽开始时的网格位置。
  • @drag-move(i, newX, newY): 拖拽过程中，项的网格位置发生变化时持续触发。newX, newY 是当前拖拽到的网格位置。
  • @drag-end(i, newX, newY): 拖拽结束时触发。newX, newY 是拖拽结束时项的网格位置。
  • @resize-start(i, newH, newW): 开始调整某个项的大小时触发。newH, newW 是调整大小开始时的网格尺寸。
  • @resize-move(i, newH, newW): 调整大小过程中，项的网格尺寸发生变化时持续触发。newH, newW 是当前调整到的网格尺寸。
  • @resize-end(i, newH, newW): 调整大小结束时触发。newH, newW 是调整大小结束时项的网格尺寸。

示例：保存布局到 Local Storage

监听 @layout-updated 事件并将 newLayout 存储到浏览器的 Local Storage 是一个常见的用法。

“`html

“`

通过这种方式，用户下次访问页面时，就可以看到他们上次保存的布局状态。

第六部分：高级用法与定制

6.1 自定义拖拽和调整大小手柄

默认的调整大小手柄可能不满足UI需求。您可以使用 drag-allow-from 或 resize-handle 属性来指定自定义手柄。

“`html

``
通过指定drag-allow-from=”.drag-handle”，只有点击.drag-handle元素并拖拽时，整个grid-item才能被拖拽。类似地，通过resize-handle=”.resize-handle”，只有拖拽.resize-handle元素时，才能调整grid-item的大小。您还需要一些CSS来隐藏默认的手柄（.vue-resizable-handle`）。

6.2 避免某些区域触发拖拽

使用 drag-ignore 属性可以指定一个选择器，当鼠标在匹配该选择器的元素上按下时，将不会触发 grid-item 的拖拽。这对于项内部包含按钮、链接、输入框等交互元素时非常有用。

“`html

这个区域可以拖拽

这个区域 **不能** 拖拽父容器


``
点击按钮或.no-drag-area内部将不会触发外部grid-item` 的拖拽。

6.3 使用插槽

grid-item 的内容通过默认插槽 <slot></slot> 注入。这意味着您可以在 grid-item 内部放置任何复杂的组件或内容。

html
<grid-item ...>
<MyCustomChart :data="chartData" />
</grid-item>

6.4 动态添加和移除项

如前所述，通过操作 layout 数组实现。确保为新添加的项提供唯一的 i 值。

“`javascript
// 添加
this.layout.push({ x: …, y: …, w: …, h: …, i: uniqueId });

// 移除
this.layout = this.layout.filter(item => item.i !== itemIdToRemove);
// 或者
const index = this.layout.findIndex(item => item.i === itemIdToRemove);
if (index !== -1) {
this.layout.splice(index, 1);
}
``
使用.filter()创建新数组并替换旧数组是安全的响应式更新方式。使用splice` 直接修改原数组也是响应式的。

6.5 性能考虑

对于包含大量（例如几百个）网格项的复杂布局，可能会遇到性能问题，尤其是在频繁拖拽和更新时。以下是一些优化建议：

  • 开启 use-css-transforms="true": 这是默认值，确保没有关闭它。CSS Transforms 通常比修改 top/left 属性有更好的硬件加速性能。
  • 限制项数量: 考虑分页或虚拟滚动来减少同时渲染的网格项数量。
  • Debounce/Throttle 布局保存: 如果您在 @layout-updated 事件中执行耗时操作（如保存到数据库），考虑使用 Lodash 的 debounce 或 throttle 函数来限制执行频率。
  • 使用 Static 项: 如果某些项不需要拖拽或改变大小，将其设置为 static 可以减少不必要的计算开销。
  • 优化网格项内部组件: 确保 <grid-item> 内部的组件渲染高效。避免在 grid-item 内部执行昂贵的计算或DOM操作。

6.6 与 Vuex 等状态管理集成

在大型应用中，您可能希望将布局状态 layout 存储在 Vuex 或其他状态管理库中。

  1. 将 layout 数组存储在 Vuex store 的 state 中。
  2. 在组件中，使用 computed 属性映射 state 中的 layout。
  3. 监听 grid-layout 的 @layout-updated 事件。
  4. 在事件处理函数中，dispatch 一个 action，将新的布局数组提交给 store 中的 mutation 来更新 state。

“`javascript
// 在 Vuex Store 中
const store = new Vuex.Store({
state: {
gridLayout: [ / 初始布局 / ]
},
mutations: {
updateGridLayout(state, newLayout) {
state.gridLayout = newLayout;
}
},
actions: {
saveLayout({ commit }, layout) {
// 可以在这里添加异步操作，例如保存到后端
// …
commit(‘updateGridLayout’, layout);
}
}
});

// 在 Vue 组件中
export default {
components: { GridLayout, GridItem },
computed: {
layout: {
get() {
return this.$store.state.gridLayout;
},
// 需要一个 setter 来配合 .sync，或者监听事件
// 这里选择监听事件更清晰，不使用 .sync 的双向绑定
// set(value) { / … / }
}
},
methods: {
handleLayoutUpdated(newLayout) {
this.$store.dispatch(‘saveLayout’, newLayout);
}
}
};


“`
这种方式将布局状态的管理与组件解耦，使其更易于维护和调试。

第七部分：可能遇到的问题与解决方案

  • 布局混乱或重叠: 确保每个 grid-item 的 i 属性是唯一的。检查 layout 数组中的 x, y, w, h 值是否合理（例如，x + w 不超过 col-num）。开启 vertical-compact 通常能解决大部分重叠问题。
  • 拖拽或调整大小时闪烁: 确保 layout 数组的更新是响应式的。如果手动操作DOM或使用了非响应式的方式修改 layout，可能导致视图不同步。使用 .sync 或正确监听 @layout-updated 事件更新数据是关键。
  • 性能下降: 参考上面性能考虑部分的建议。
  • 响应式行为不符合预期: 理解 vue-grid-layout 的响应式是通过改变 col-num 实现的，而不是像CSS Media Query那样改变元素的具体样式。如果需要在不同断点下完全不同的布局，需要手动切换 layout 数组。
  • 无法拖拽或调整大小: 检查 grid-layout 的 is-draggable 和 is-resizable 属性是否为 true。检查 grid-item 的 static 属性是否为 true，或者 is-draggable/is-resizable 是否被显式设置为 false。检查是否使用了 drag-ignore 或 drag-allow-from / resize-handle 属性导致事件被忽略或需要特定手柄。

第八部分：总结

vue-grid-layout 是一个用于构建动态、可交互网格布局的强大且灵活的Vue组件库。它通过简单的数据模型和内置的拖拽、调整大小、碰撞检测功能，极大地简化了仪表盘、自定义界面等复杂应用的开发。

通过本文的介绍，您应该对 vue-grid-layout 的核心概念、基本用法、常用属性、事件处理以及一些高级技巧有了全面的了解。掌握其工作原理，特别是 layout 数据与网格渲染的关系，以及响应式的工作方式，是高效使用它的关键。

虽然它可能不像纯CSS Grid那样适合所有的静态布局需求，但对于需要用户进行拖拽、放置、调整大小等运行时交互的场景，vue-grid-layout 无疑是一个非常优秀且值得信赖的选择。开始在您的项目中尝试使用它吧，相信它能帮助您构建出更加灵活和用户友好的界面！

进一步学习:

  • 查阅 vue-grid-layout 的官方文档：(通常可以在 npm 或 GitHub 找到链接) 官方文档是了解最新特性和所有属性的权威来源。
  • 查看 vue-grid-layout 的示例：库通常会提供各种用例的示例代码，通过阅读和运行这些示例可以更快地掌握用法。
  • 参考社区讨论和 Stack Overflow 上的相关问题：解决实际开发中遇到的具体问题。

希望这篇文章对您有所帮助！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部