SepSplitPanes 分屏面板组件 v1.0.0

支持横向/纵向多分屏布局 · 拖拽分隔线调整尺寸 · minSize 约束 · localStorage 持久化 · 动态增删面板 · 编程式 resize

1. 基础横向分屏（拖拽中间分隔线调整）

功能说明：direction: 'horizontal' 横向分屏，sizes 设置初始比例，minSize 限制最小尺寸。拖拽中间灰色分隔线可实时调整左右比例。

HTML 声明式标签
左面板
width: 40%

拖拽右侧分隔线调整宽度
右面板
width: 60%
JS API 初始化
左面板
width: 40%

拖拽右侧分隔线调整宽度
右面板
width: 60%
当前尺寸: 40%, 60%

2. 纵向分屏（上下拖拽）

功能说明：direction: 'vertical' 纵向分屏，分隔线水平显示，上下拖拽调整高度比。

HTML 声明式标签
上面板
height: 30%
下面板
height: 70%
JS API 初始化
上面板
height: 30%
下面板
height: 70%

3. 三栏分屏

功能说明：支持任意数量面板，多条分隔线可独立拖拽调整。每两个相邻面板间自动插入一条分隔线。

HTML 声明式标签
面板 A
25%
面板 B
50%
面板 C
25%
JS API 初始化
面板 A
25%
面板 B
50%
面板 C
25%
尺寸: 25%, 50%, 25%

4. 编程式调整尺寸 (resize API)

功能说明：inst.resize(sizes) 编程式设置面板尺寸数组，支持百分比字符串。inst.getSizes() 获取当前尺寸。

HTML 声明式标签
面板 1
面板 2
面板 3
JS API 初始化
面板 1
面板 2
面板 3

5. 动态增删面板 (addPane / removePane)

功能说明：inst.addPane(content, idx) 动态添加面板，inst.removePane(idx) 移除面板。增删后自动重新均分尺寸并重建分隔线。

HTML 声明式标签
面板 1
面板 2
JS API 初始化
面板 1
面板 2
面板数: 2

6. 持久化 + 嵌套分屏

功能说明：persistKey 开启后，拖拽的尺寸会保存到 localStorage，刷新页面后自动恢复。
左面板内部嵌套了一个纵向分屏，演示分屏的嵌套组合能力。

HTML 声明式标签
嵌套上
嵌套下
右面板
拖拽左边缘调整左右比例
JS API 初始化
嵌套上
嵌套下
右面板
拖拽左边缘调整左右比例

P1 增强功能

可折叠面板
左面板（可折叠）
右面板（可折叠）
悬停分隔线显示折叠按钮
自定义分隔线外观 + 尺寸提示
拖拽时显示尺寸百分比提示
分隔线颜色/尺寸/悬停色可配置
分隔线 8px、悬停蓝色、拖拽显示尺寸提示

7. P0 增强功能

JS API 初始化
P0-1 容器尺寸自适应 (resizeMode: proportion)
左面板
拖动浏览器窗口，面板按比例自适应
右面板
resizeMode: 'proportion' — ResizeObserver 监听容器尺寸
P0-2 拖拽命中区扩大 (hitSlop: 16)
分隔线仅 4px 宽，但可拖拽区域扩大到 36px
即使鼠标偏离分隔线也能拖拽
hitSlop: 16 — 每侧扩大 16px 透明命中区
P0-3 拖到边界自动折叠 (collapseOnEdge)
左面板
将分隔线用力拖到最左/最右边缘超过 30px，自动折叠
右面板
collapseOnEdge: true, collapseThreshold: 30

8. P1 增强功能（扩展）

JS API 初始化
P1-1 自定义分隔线渲染 (renderSeparator)
分隔线上添加了自定义图标 ⇔
renderSeparator(sep, idx) 回调可注入任意内容
renderSeparator: (sep, idx) => { sep.appendChild(icon) }
P1-2 双击行为可配置 (doubleClickAction)
左面板
双击分隔线 → collapse-nearest 按光标位置智能折叠最近面板
右面板
双击分隔线测试不同动作
P1-3 布局序列化 (getLayout / setLayout)
调整面板尺寸后，点击"保存布局"，再调整后点"恢复布局"
可用于保存用户自定义工作台布局
布局未保存
P1-4 相邻面板约束传播（三面板拖拽）
面板 A
minSize: 120
面板 B
minSize: 120
面板 C
minSize: 120
拖中间分隔线到极限时，约束会向两侧面板传播

9. P2 增强功能

JS API 初始化
P2-1 方向动态切换 (setDirection)
面板 1
面板 2
当前方向: horizontal
P2-2 面板优先级回退 (panePriorities)
主内容区
priority: 1（最高）
侧边栏
priority: 2
辅助区
priority: 3（最低）
缩小窗口时，低优先级面板先被压缩
P2-3 拖拽幽灵预览线 (ghostPreview)
拖拽时只移动半透明幽灵线
松手才应用尺寸，减少重排
适合面板内容复杂的场景
ghostPreview: true — 拖拽显示幽灵线
P2-4 RTL 支持 (rtl: true)
右侧面板（RTL 起始）
鼠标向右拖 → 右侧面板增大
左侧面板
rtl: true — 从右到左布局，拖拽方向反转

10. P3 标题栏 + 面板最大化

JS API 初始化
P3-1 标题栏 + 折叠/最大化按钮
面板一内容
面板二内容
面板三内容
paneTitles + maximizable + collapsible

11. P4 面板锁定 + 折叠到指定尺寸

JS API 初始化
P4-1 锁定中间面板 (lockedPanes: [1])
左侧可拖拽
中间已锁定（不可改尺寸）
右侧可拖拽
lockedPanes 锁定的面板尺寸不会被拖拽改变
P4-2 折叠到指定尺寸 (collapseSize: 60px)
双击分隔线折叠到此面板
折叠后保留 60px 宽度
collapseSize 控制折叠后保留的尺寸

12. P5 键盘变速 + 分隔线预设

JS API 初始化
P5-1 键盘步进变速 (Tab 聚焦 → ←/→ + Ctrl=大步 / Shift=小步)
Tab 到分隔线后按方向键调整
Ctrl + 方向键 = 大步(5倍) / Shift = 小步
step + stepFastMul + stepSlowMul
P5-2 分隔线预设 (line / gutter / invisible / dots / double-line)
line 预设
细线条分隔

13. 布局保存与加载

JS API 初始化
JS API 初始化 — getLayout / setLayout / saveLayout / loadLayout
调整布局后点击保存
恢复上次保存的布局
本地存储 key=demo_layout_key

14. 新增强功能（P0-P3）

JS API 初始化
P0-1 dragInterval 拖拽步进（每 20px 吸附一格）
面板 A
面板 B
dragInterval: 20 — 拖拽按步长跳跃
P1-1 preferredSizes 首选尺寸 + visible 面板显隐
面板 1（首选 30%）
面板 2（首选 50%）
面板 3（首选 20%）
P1-2 expandOnClick 点击分隔线展开（双击折叠后单击展开）
双击分隔线折叠 → 单击展开
expandOnClick: true
expandOnClick + doubleClickAction: collapse
P2-1 undo/redo 撤销重做（拖拽后 Ctrl+Z 效果）
拖拽调整后可撤销
undoStack: 20
canUndo: false / canRedo: false
P2-2 presets 布局预设快速切换
面板 1
面板 2
面板 3
P3-1 focusable 活跃面板聚焦（点击面板高亮）
点击此面板聚焦
点击此面板聚焦
点击此面板聚焦
当前活跃: -
P3-2 syncScroll 同步滚动（拖动滚动条多面板联动）
左侧长内容

滚动我试试

右侧同步

继续滚动

同步到底

同步到底
右侧长内容

同步左侧

继续滚动

同步到底

同步到底

同步到底
syncScroll: true — 任一面板滚动，其他面板同步
P1-3 elementStyle 自定义面板样式（grid / fr 单位）
自定义 width: 1fr
自定义 width: 2fr
自定义 width: 1fr
elementStyle 函数替代默认 flex 布局

15. 嵌套分屏（Nested Split）

左侧固定 + 右侧上下分屏，支持 getLayout/setLayout 递归保存嵌套布局，内外层均自动持久化。

JS API 初始化 — 外层 + 内层嵌套
左侧导航（固定 200px）
右上：主内容区
右下：详情/日志区
嵌套布局: -

16. 面板拖拽重排（Pane Reorder）

开启 paneReorderable 后，拖拽面板标题可改变面板顺序。锁定面板不可参与重排。

JS API 初始化 — paneReorderable + lockedPanes
面板 A（第一个）
面板 B（第二个）
面板 C（第三个，锁定）
顺序: A, B, C

17. 折叠占位尺寸（collapsedSize）

设置 collapsedSize 后，折叠的面板会保留一条窄带显示标题（竖排），便于再次展开。

JS API 初始化 — collapsible + collapsedSize
左侧面板内容区
右侧面板内容区
collapsedSize: 32px

18. 面板内嵌标签页（SepTabs 组件）

去掉 SplitPanes 标题栏，折叠/最大化按钮注入到 SepTabs 标签栏右侧，省出一行空间，标签栏兼任标题区。

HTML 声明式标签
每个面板独立 SepTabs

20. 等分布局 + 右键菜单

右键分隔线呼出菜单：「等分布局」一键均分、「设置面板尺寸…」输入像素或百分比。双击分隔线也可等分布局。

JS API — distributeEvenly / 右键菜单
面板一
面板二
面板三
右键分隔线试试

21. 手柄样式预设（handleStyle）

4 种拖拽手柄视觉：dots（默认三点）/ line（仅线条）/ arrows（双向箭头）/ none（完全隐藏）。

JS API — handleStyle
面板 A
面板 B
当前: dots

22. 尺寸比例锁定（ratioLock）

ratioLock: [0, 1] 锁定面板0和面板1的尺寸比例，拖动它们之间的分隔线时比例不变，差额由面板2吸收。

JS API — ratioLock
面板0（锁定）
面板1（锁定）
面板2（吸收差额）
拖动面板0/1之间的分隔线，比例保持不变

23. 浮动面板（floatable）

点击标题栏 ⇱ 按钮，面板内容以独立窗口（Modal）形式浮动，支持拖拽、最大化；点击占位"收回"或关闭窗口可收回。

JS API — floatable
左侧面板内容
右侧面板内容，点击 ⇱ 浮动到新窗口
已浮动: 否

24. 面板加载状态（setPaneLoading）

异步加载内容时调用 setPaneLoading(idx, true) 显示 spinner 遮罩，完成后传 false 关闭。

JS API — setPaneLoading
面板一
面板二
isPaneLoading: false

25. 标题栏交互（单击折叠 / 双击最大化）

titleClickCollapse: true → 单击标题空白处折叠；titleDoubleClickMaximize: true → 双击标题最大化。

JS API — titleClickCollapse + titleDoubleClickMaximize
面板一
面板二
单击标题折叠 / 双击标题最大化

26. 键盘增强 + 拖拽尺寸提示

Tab 聚焦分隔线后：←→/↑↓ 微调（20px）、Ctrl+方向键 加速（×5）、Shift+方向键 减速（×0.25）、PageUp/PageDown 大跳步、Home/End 极限、Enter/Space 折叠。拖动时 showSizeTip 显示百分比+像素。

JS API — showSizeTip + keyboardStep
面板一
面板二
点击分隔线后用键盘操作，拖动看尺寸提示
Shift 拖拽多面板联动 + sizeTipFormatter
面板一
面板二（中间）
面板三
按住 Shift 拖动分隔线，联动调整相邻 3 个面板；尺寸提示使用自定义格式

27. 断言测试