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 使用默认方案，也可在现有样式基础上自定义。