Vue3 Splitpanes分割面板拖拽与resize事件用法

脚本专家

适用场景与组件定位
Splitpanes 是一个轻量级的 Vue 组件库，用来实现可拖拽的分栏布局，也就是常说的分割面板。它支持 Vue2 和 Vue3，常见于后台管理、文件管理器、数据看板等页面。用户拖动分隔条即可动态调整面板宽度或高度，避免把布局尺寸写死。

安装方式

2. npm install splitpanes
3. # 或
4. yarn add splitpanes

复制代码

Vue3 基础用法
下面的示例同时给出了默认的左右分栏和 horizontal 上下分栏。

2. <template>
3. <Splitpanes class="default-theme">
4. <Pane min-size="15" size="25">
5. <!-- 左侧内容 -->
6. </Pane>
7. <Pane>
8. <!-- 右侧内容 -->
9. </Pane>
10. </Splitpanes>
11. <!-- horizontal:横向布局 -->
12. <Splitpanes horizontal>
13. <Pane>上面内容</Pane>
14. <Pane>下面内容</Pane>
15. </Splitpanes>
16. </template>
17. <script setup>
18. import { Splitpanes, Pane } from 'splitpanes'
19. import 'splitpanes/dist/splitpanes.css'
20. </script>

复制代码

第一个 Splitpanes 没有设置 horizontal，因此按默认纵向布局展示为左右分栏。第一个 Pane 设置了 size="25"，表示初始宽度/高度为 25%，同时设置了 min-size="15" 作为该面板的最小尺寸限制。class="default-theme" 用于套用默认主题样式。

第二个 Splitpanes 加上 horizontal 后变为横向分割，即上下布局。使用时需要从 splitpanes 中导入 Splitpanes 和 Pane，并在 Vue3 的 script setup 中引入 splitpanes/dist/splitpanes.css。示例里的 default-theme 依赖默认样式文件，如果页面中分隔条或面板样式异常，应优先检查该 CSS 是否已引入。

主要参数与事件
size：面板初始宽度/高度，Number 类型，单位为百分比。
horizontal：是否横向分割，true 为上下布局；默认纵向，也就是左右布局。
@resize：拖动分隔条时触发，返回所有面板的尺寸数组。
@resized：拖动结束时触发，返回所有面板的尺寸数组。
default-theme：设置主题样式，官网提供默认样式，也可以按项目需要自定义。

实际使用时，如果要边拖动边响应尺寸变化，可以监听 resize；如果只关心拖拽结束后的最终结果，可以监听 resized，避免在拖动过程中频繁处理业务逻辑。两者返回的都是所有面板的尺寸数组，适合与布局状态保存、面板尺寸联动等场景配合。

排查与兼容性注意
1. 页面没有默认主题效果时，先确认是否引入了 splitpanes/dist/splitpanes.css。
2. 分栏方向不符合预期时，检查 horizontal 是否按需设置；默认是左右布局，设置后才变为上下布局。
3. size 的单位是百分比，不是像素值；配置初始尺寸时应按百分比理解。
4. resize 与 resized 的触发时机不同，前者在拖动过程中触发，后者在拖动结束时触发，按业务需要选择。
5. Vue3 的 script setup 中直接导入组件即可使用；如果使用其他写法，需要保证 Splitpanes 和 Pane 已正确注册。
6. Splitpanes 兼容 Vue2 和 Vue3，Vue3 项目可直接按上述方式接入；主题样式可通过 default-theme 使用默认方案，也可在现有样式基础上自定义。

热心网友1

挺实用的一篇，正好我最近在后台项目里想给侧边栏加个拖拽宽度，之前一直是写死的百分比，改起来很别扭。示例把左右和上下两种布局放在一起对比，一眼就能看懂 horizontal 加不加的区别，size 和 min-size 用百分比这点也提醒得及时，我一开始大概率会当成像素去填。 有个小地方想请教下：@resize 和 @resized 返回的是所有面板的尺寸数组，那这个数组里元素的顺序是不是就对应 Pane 的排列顺序，每项直接就是百分比数值？我打算在 resized 里把尺寸存到本地，下次进来再按位置还原，不太确定需不需要额外处理。 另外 default-theme 那段你说也可以自定义样式，这个具体是覆盖哪几个类名，还是直接丢掉这个 class 自己写？如果方便的话，希望后面能补一小段自定义主题的例子。整体这篇已经把安装、基础用法、事件和排查点都串起来了，收藏了。

热心网友4

正好在做后台的分栏布局，这篇整理得很清楚，收藏了。 补充几个自己踩过的坑，供参考： 一是 resize 的触发频率确实很高，拖动一下能吐出几十次事件，如果里面要做图表重绘或者请求之类的联动，最好自己加一层节流或 requestAnimationFrame，不然会明显卡。resized 里做最终状态的持久化就省心很多，比如存到 localStorage，下次进来按存的百分比恢复。 二是 size 是百分比这点一定要记住，我一开始按像素理解，写了个 300 进去，结果直接压成 3% 的宽度，还纳闷了半天。另外多个 Pane 的 min-size 之和别超过 100，否则拖到某个位置会出现面板卡住、分隔条回弹的情况。 三是 horizontal 的命名确实有点反直觉，加上之后是上下分，不加反而是左右分，团队里新人第一次用基本都要问一遍。 四是动态增删 Pane 的时候记得加 key，特别是面板数量会变（比如做多个可关闭的对比视图）的场景，不加 key 偶尔会出现尺寸错乱。 还有就是样式那个问题，除了 splitpanes.css 没引入，还有一种情况是全局样式里给分栏容器设了固定高度或者 overflow，导致分隔条看起来"消失"，其实是被裁掉或者压成 1px 了，排查时可以先把容器的 flex 和高度约束去掉看看。 整体这套 API 够简洁，Vue3 直接 script setup 导

热心网友5

这篇整理得挺实用，方向、事件和排查点基本都覆盖到了，尤其是把 resize 和 resized 的触发时机区分开这一点，很多人一开始容易混。 补充几个实际用下来容易踩的坑： 一是父容器高度。上下分栏时如果外层没有明确高度，百分比尺寸经常算不出来，面板会塌成一条。一般给 Splitpanes 的直接父级设 height: 100% 或者固定高度，再让它撑满，问题就少了。 二是 resize 频率。拖动过程中触发很密集，如果里面要做比较重的计算，比如重新算图表尺寸或者发请求，最好加个节流，或者干脆只监听 resized，在拖动结束时统一处理。保存布局状态到 localStorage 也建议放在 resized 里，避免拖动过程中疯狂写存储。 三是尺寸数组的顺序。回调里拿到的尺寸数组是按 Pane 的排列顺序来的，保存和恢复布局时最好把面板的 key 或顺序对应好，不然以后调整了面板数量容易错位。 四是 min-size 和 size 的配合。初始 size 如果设得比 min-size 还小，实际渲染会按最小尺寸来，调试时看到尺寸对不上不一定是组件的问题，先检查这两个值。 另外 default-theme 只是给了一套基础样式，项目里想改分隔条颜色、宽度、hover 效果，直接覆盖对应类名或者用 CSS 变量就行，不用整个换主题。 整体来说这篇作为入门和速查都够用了，收藏一下以后查事件