Splitter 布局分割器

创建可拖拽调整尺寸的多面板布局。手柄在悬浮、拖拽或键盘聚焦时显示。

命令行安装

npx @loongship-kit/ui add splitter

组件结构

角色	组件	职责	使用条件
根组件	SplitterGroup	管理方向、尺寸和布局持久化	必需
面板	SplitterPanel	声明可调整尺寸的内容区域	至少两个
调整手柄	SplitterResizeHandle	提供拖拽和键盘调整交互	相邻面板间需要

水平分割

Navigation

Vessel workspace

查看代码

<script setup lang="ts">
import { SplitterGroup, SplitterPanel, SplitterResizeHandle } from '@/components/loongship/splitter'
</script>

<template>
  <div style="height: 240px;">
    <SplitterGroup>
      <SplitterPanel :default-size="35" :min-size="20">
        <div>Navigation</div>
      </SplitterPanel>
      <SplitterResizeHandle />
      <SplitterPanel :default-size="65" :min-size="30">
        <div>Vessel workspace</div>
      </SplitterPanel>
    </SplitterGroup>
  </div>
</template>

垂直分割

设置 direction="vertical" 创建上下分割布局。手柄会自动切换为纵向调整光标和水平反馈线。

Chart

Voyage table

查看代码

<script setup lang="ts">
import { SplitterGroup, SplitterPanel, SplitterResizeHandle } from '@/components/loongship/splitter'
</script>

<template>
  <div style="height: 240px;">
    <SplitterGroup direction="vertical">
      <SplitterPanel :default-size="45" :min-size="25">
        <div>Chart</div>
      </SplitterPanel>
      <SplitterResizeHandle />
      <SplitterPanel :default-size="55" :min-size="25">
        <div>Voyage table</div>
      </SplitterPanel>
    </SplitterGroup>
  </div>
</template>

尺寸约束、折叠与持久化

尺寸单位与持久化

面板尺寸默认使用百分比。设置 size-unit="px" 后，defaultSize、minSize、maxSize 和 collapsedSize 均使用像素。autoSaveId 会通过 localStorage 保存同一组面板的布局。

Collapsible tools

Main content

查看代码

<script setup lang="ts">
import { SplitterGroup, SplitterPanel, SplitterResizeHandle } from '@/components/loongship/splitter'
</script>

<template>
  <div style="height: 240px;">
    <SplitterGroup auto-save-id="vessel-workspace">
      <SplitterPanel
        collapsible
        :collapsed-size="0"
        :default-size="30"
        :min-size="15"
        :max-size="50"
      >
        <div>Collapsible tools</div>
      </SplitterPanel>
      <SplitterResizeHandle />
      <SplitterPanel :default-size="70" :min-size="40">
        <div>Main content</div>
      </SplitterPanel>
    </SplitterGroup>
  </div>
</template>

API

SplitterGroup（主组件）

属性

属性	类型	默认值	说明
direction	'horizontal' | 'vertical'	'horizontal'	面板排列和调整方向
autoSaveId	string | null	null	用于持久化布局的唯一标识
keyboardResizeBy	number | null	10	方向键每次调整的比例步长
storage	{ getItem; setItem }	localStorage	自定义布局存储实现
id	string | null	自动生成	分割组唯一标识
as	string | Component	'div'	渲染元素
asChild	boolean	false	将属性合并到唯一子元素
class	ClassValue	-	自定义类名

事件

事件	参数	说明
layout	sizes: number[]	初始化或调整后触发，返回各面板尺寸

插槽

插槽	参数	说明
default	{ layout: number[] }	当前面板尺寸

子组件

SplitterPanel — 可调整尺寸的内容面板

属性

属性	类型	默认值	说明
defaultSize	number	自动均分	初始尺寸
minSize	number	10	最小尺寸
maxSize	number	100	最大尺寸
collapsible	boolean	false	是否允许折叠
collapsedSize	number	0	折叠后的尺寸
sizeUnit	'%' | 'px'	'%'	尺寸属性使用的单位
order	number	DOM 顺序	条件渲染面板时的稳定顺序
id	string	自动生成	面板唯一标识
as	string | Component	'div'	渲染元素
asChild	boolean	false	将属性合并到唯一子元素
class	ClassValue	-	自定义类名

事件

事件	参数	说明
collapse	—	面板折叠后触发
expand	—	面板展开后触发
resize	(size: number, previousSize: number)	面板尺寸变化后触发

插槽

插槽	参数	说明
default	{ isCollapsed, isExpanded, collapse, expand, resize }	面板状态与控制方法

暴露成员

成员	类型	说明
collapse()	() => void	折叠可折叠面板
expand()	() => void	恢复到折叠前尺寸
resize(size)	(size: number) => void	调整到指定尺寸
getSize()	() => number	获取当前尺寸
isCollapsed	boolean	当前是否折叠
isExpanded	boolean	当前是否展开

SplitterResizeHandle — 拖拽与键盘调整手柄

属性

属性	类型	默认值	说明
disabled	boolean	false	禁用拖拽和键盘调整
hitAreaMargins	{ coarse?: number; fine?: number }	{ coarse: 15, fine: 5 }	触摸和鼠标命中区边距
tabindex	number	0	键盘 Tab 顺序
id	string	自动生成	手柄唯一标识
nonce	string	全局配置	动态光标样式的 CSP nonce
as	string | Component	'div'	渲染元素
asChild	boolean	false	将属性合并到唯一子元素
class	ClassValue	-	自定义类名

事件

事件	参数	说明
dragging	isDragging: boolean	拖拽开始和结束时触发

插槽

插槽	参数	说明
default	—	可选的自定义手柄内容；默认不渲染抓手图标

键盘操作与嵌套

手柄使用 role="separator"，支持方向键、Home、End 和 F6 键盘操作。嵌套布局只需在任意 SplitterPanel 内继续放置一组 SplitterGroup。