【DevUI】Splitter 分割器组件使用详解

前言

本文是关于 DevUI Splitter 分割器组件 的详细使用示例与代码说明总结文章。该组件基于 Angular ^18.0.0 版本，用于创建可交互调整区域大小的页面布局。

📐 DevUI Splitter 分割器组件使用详解

Splitter（分割器）是一个强大的布局组件，它允许用户通过拖动分隔条（Split Bar）来动态调整相邻窗格（Pane）的尺寸，非常适合构建可定制的仪表盘、代码编辑器（如VS Code）、文件管理器等界面。

1. 核心结构与概念

一个分割器布局由以下部分构成：

• <d-splitter>：最外层容器，定义整个分割区域的方向和行为。
• <d-splitter-pane>：放置在 <d-splitter> 内部的窗格，用于承载具体内容。一个分割器可以包含多个窗格。
• 分隔条 (Split Bar)：相邻窗格之间的可拖动控制条，用户通过它来调整尺寸。

2. 基本用法与代码示例

2.1 水平分割（基本用法）

这是最常见的左右分割布局，通过设置 [orientation]="'horizontal'"（或使用默认值）实现。

<d-splitter style="height: 300px;">
  <d-splitter-pane [size]="'30%'" [minSize]="'20%'" [collapsible]="true">
    <div class="pane-content">
      <h2>左侧面板</h2>
      <div>宽度：30%， 最小宽度：20%</div>
    </div>
  </d-splitter-pane>
  <d-splitter-pane [minSize]="'15%'">
    <div class="pane-content">
      <h2>右侧面板</h2>
      <div>内容区</div>
    </div>
  </d-splitter-pane>
</d-splitter>

关键属性说明：

• [size]：设置窗格的初始大小，支持像素（px）和百分比（%）。
• [minSize] / [maxSize]：限制窗格调整的最小和最大尺寸。
• [collapsible]：设置为 true 时，窗格可以被完全折叠收起。

2.2 垂直分割

通过将 <d-splitter> 的 orientation 属性设置为 vertical，可以创建上下分割的布局。

<d-splitter style="height: 500px;" orientation="vertical">
  <d-splitter-pane size="200px" minSize="100px" [collapsible]="true">
    <div class="pane-content">
      <h2>顶部面板</h2>
      <div>高度：200px</div>
    </div>
  </d-splitter-pane>
  <d-splitter-pane>
    <div class="pane-content">
      <h2>中部面板</h2>
      <div>高度自适应</div>
    </div>
  </d-splitter-pane>
  <d-splitter-pane size="100px" [resizable]="false">
    <div class="pane-content">
      <h2>底部面板</h2>
      <div>高度：100px，且不可调整大小</div>
    </div>
  </d-splitter-pane>
</d-splitter>

垂直布局要点：

• 确保外层 <d-splitter> 有明确的 height（例如 500px 或 100%）。
• 通过 [resizable]="false" 可以禁止某个窗格被拖动调整。

2.3 组合嵌套布局

通过嵌套多个 <d-splitter>，可以实现复杂的混合布局（如先左右分，再上下分）。

<d-splitter style="height: 500px;" orientation="vertical">
  <d-splitter-pane size="400px">
    <!-- 第一层：水平分割 -->
    <d-splitter style="height: 100%;">
      <d-splitter-pane size="30%">
        <h3>左侧</h3>
      </d-splitter-pane>
      <d-splitter-pane>
        <!-- 第二层：在右侧窗格内嵌套垂直分割 -->
        <d-splitter style="height: 100%;" orientation="vertical">
          <d-splitter-pane size="50%">
            <h3>右上</h3>
          </d-splitter-pane>
          <d-splitter-pane>
            <h3>右下</h3>
          </d-splitter-pane>
        </d-splitter>
      </d-splitter-pane>
    </d-splitter>
  </d-splitter-pane>
  <d-splitter-pane>
    <h3>底部独立区域</h3>
  </d-splitter-pane>
</d-splitter>

嵌套技巧：关键是为内层的 <d-splitter> 设置 height: 100%;，使其充满父级窗格。

3. 高级功能与控制

3.1 控制折叠方向

当一个窗格折叠时，默认会向后方（after）收起。通过 [collapseDirection] 属性可以指定向前方（before）折叠。

<d-splitter-pane [collapsible]="true" [collapseDirection]="'before'">
  <div>此面板折叠时会向前方（左侧）收起</div>
</d-splitter-pane>

3.2 折叠收缩与菜单模式 (shrink)

这是一个非常实用的功能，特别用于导航侧边栏。面板折叠后不会完全隐藏，而是收缩到一个更窄的宽度，仅显示图标菜单。

<d-splitter [showCollapseButton]="true">
  <d-splitter-pane
    [size]="'200px'"
    [minSize]="'20%'"
    [collapsed]="collapsed"
    [shrink]="true"
    [shrinkWidth]="40"
    [collapsible]="true"
    (collapsedChange)="onCollapsedChange($event)"
    (shrinkStatusChange)="onShrinkStatusChange($event)">
    <!-- 正常状态显示完整菜单 -->
    <div *ngIf="!isShrinked">
      <!-- 完整菜单内容 -->
    </div>
    <!-- 收缩状态显示图标 -->
    <div *ngIf="isShrinked">
      <!-- 图标菜单内容 -->
    </div>
  </d-splitter-pane>
  <d-splitter-pane>主内容区</d-splitter-pane>
</d-splitter>

关键属性：

• [shrink]="true"：启用收缩模式。
• [shrinkWidth]：设置收缩后的宽度（如 40px）。
• (shrinkStatusChange)：监听收缩状态变化，以便切换显示完整菜单或图标。

4. 事件与交互控制

Splitter 组件提供了丰富的事件，方便你响应用户操作。

事件名	触发时机	说明
(sizeChange)	窗格尺寸被拖动改变时	事件参数为改变后的大小（像素值）
(collapsedChange)	窗格折叠或展开状态切换时	事件参数为当前的布尔值状态
(shrinkStatusChange)	收缩模式的状态改变时	用于切换显示不同UI

5. 功能特性速查表

为了方便大家根据需求快速配置，下表总结了 Splitter 组件的核心功能：

功能场景	关键组件/属性	代码示例或说明
基础水平分割	<d-splitter> + <d-splitter-pane>	默认即为水平方向，无需特别设置。
基础垂直分割	<d-splitter orientation="vertical">	必须为外层容器设置明确高度。
设置初始与限制尺寸	[size], [minSize], [maxSize]	支持 px 和 % 单位。
允许折叠窗格	[collapsible]="true"	窗格可完全收起。
禁止调整大小	[resizable]="false"	应用于特定 <d-splitter-pane>。
指定折叠方向	[collapseDirection]="'before'"	可选 ‘before‘ 或 ‘after‘。
收缩菜单模式	[shrink]="true", [shrinkWidth]	折叠后变为窄边图标栏。
显示折叠按钮	[showCollapseButton]="true"	在分隔条上显示控制按钮。
创建复杂布局	嵌套 <d-splitter>	注意内层容器设置为 height: 100%。
响应尺寸变化	(sizeChange) 事件	可用来同步保存用户的布局偏好。

💡 总结与最佳实践

DevUI Splitter 组件是构建灵活、可定制用户界面的利器。要高效使用它，可以遵循以下步骤：

1. 规划布局：先明确需要水平、垂直还是嵌套分割。
2. 设定尺寸：为每个窗格合理设置 size, minSize, maxSize，确保布局稳定。
3. 按需添加功能：若需折叠，添加 collapsible；若需高级导航，考虑 shrink 模式。
4. 处理事件：通过 sizeChange 等事件保存用户布局设置，提升体验。

希望这篇文章能帮助您顺利地在项目中实现动态、专业的页面布局。

参考文档

MateChat：https://gitcode.com/DevCloudFE/MateChat

MateChat官网：https://matechat.gitcode.com

DevUI官网：https://devui.design/home