syncfusion-blazor-splitter

实现 Syncfusion Blazor Splitter

Syncfusion Blazor Splitter 组件是一种基于布局的容器，可将容器区域拆分为可调整大小和可折叠的窗格。需要创建包含多个可由用户调整的内容区域的复杂布局时，请使用此技能。

何时使用此技能

在需要执行以下操作时，请使用此技能：

• 创建分栏布局 — 将 UI 划分为多个窗格（2 个、3 个或更多），供用户调整大小
• 处理窗格配置 — 控制窗格大小、最小/最大限制、可见性和可折叠性
• 管理用户交互 — 响应调整大小事件、折叠/展开操作和状态变更
• 构建复杂界面 — 创建代码编辑器布局、仪表板面板或多区域仪表板
• 持久化窗格状态 — 保存并恢复窗格大小和折叠状态，使其在页面刷新后保持不变
• 应用自定义样式 — 自定义分隔条、调整大小手柄和组件整体外观

组件概述

Splitter 使用灵活的布局将容器空间划分为独立窗格：

• 默认模式：水平方向，使用垂直分隔线（从左到右拆分）
• 垂直模式：垂直方向，使用水平分隔线（从上到下拆分）
• 嵌套 Splitter：支持在窗格中嵌套 Splitter，以构建复杂布局
• 可调整大小：用户可拖动分隔线，实时调整窗格大小
• 可折叠：可选的折叠/展开按钮，可隐藏窗格并腾出空间
• 持久化：内置将用户偏好设置持久化到 localStorage 的功能

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• WebAssembly 与 Blazor Web App 配置
• 命名空间导入和服务注册
• 样式表和脚本资源
• 基本的水平和垂直 Splitter 实现
• 首次渲染和初始化

拆分窗格和布局

📄 阅读： references/split-panes.md

• 水平布局（默认方向）
• 垂直布局（Orientation.Vertical）
• 多窗格配置
• 分隔线自定义（SeparatorSize）
• 嵌套 Splitter 模式
• 基于 Flex 的自动调整大小行为
• 动态添加和移除窗格（AddPaneAsync、RemovePaneAsync）

窗格配置和设置

📄 阅读： references/pane-configuration.md

• 窗格大小（固定像素、百分比、自动）
• 最小/最大尺寸限制
• 可见性控制（显示/隐藏窗格）
• 带切换按钮的可折叠窗格
• 内容模板和纯文本
• 集成其他 Blazor 组件

事件和交互

📄 阅读： references/events-and-interactions.md

• Created 事件生命周期
• OnResizeStart、Resizing、OnResizeStop 事件
• OnCollapse、OnExpand 事件处理程序
• Collapsed、Expanded 完成事件
• 事件参数和回调结构
• 常见事件处理模式

调整大小、展开和折叠

📄 阅读： references/resizing-and-expand-collapse.md

• 调整大小行为和拖动手柄元素
• 禁止调整大小（Resizable 属性）
• 调整大小期间的最小/最大尺寸验证
• 启用/禁用可折叠窗格
• 以编程方式调用展开/折叠方法
• 初始折叠状态配置
• 自定义调整大小图标和光标
• 分隔线模板自定义（自定义 HTML 模板）

样式和主题

📄 阅读： references/styling-and-theming.md

• 自定义分隔条外观
• 设置调整大小手柄样式
• 自定义调整大小箭头
• 隐藏/显示调整大小处理器
• 窗格的 CSS 类选择器
• 主题集成（Bootstrap、Fluent 等）

状态管理与持久化

📄 阅读： references/state-management.md

• 启用状态持久化（EnablePersistence）
• 双向数据绑定（@bind-Collapsed、@bind-Size）
• 保存/恢复窗格大小和折叠状态
• 集成 LocalStorage
• 将窗格属性绑定到组件状态

高级场景与布局

📄 阅读： references/advanced-scenarios.md

• 代码编辑器风格布局（嵌套水平 + 垂直布局）
• Outlook 风格布局，包含 TreeView 和 ListView
• 仪表板和多面板布局
• 复杂布局的性能优化
• 嵌套分隔器的最佳实践
• 常见问题排查和边缘情况

完整 API 参考

📄 阅读： references/api-reference.md

• 所有 SfSplitter 属性、方法和事件
• SplitterPane 属性详情
• 事件参数和处理程序
• 每个 API 的完整代码示例
• Content 属性与 ContentTemplate 对比
• RTL、持久化和高级属性用法

快速入门示例

包含两个窗格的水平分隔器

@using Syncfusion.Blazor.Layouts

<SfSplitter Height="240px" Width="100%">
    <SplitterPanes>
        <SplitterPane Size="300px">
            <ContentTemplate>
                <div style="padding: 10px;">
                    <h3>Left Pane</h3>
                    <p>Content here</p>
                </div>
            </ContentTemplate>
        </SplitterPane>
        <SplitterPane>
            <ContentTemplate>
                <div style="padding: 10px;">
                    <h3>Right Pane</h3>
                    <p>Content here</p>
                </div>
            </ContentTemplate>
        </SplitterPane>
    </SplitterPanes>
</SfSplitter>

带折叠按钮的垂直分隔器

@using Syncfusion.Blazor.Layouts

<SfSplitter Height="300px" Width="100%" Orientation="Orientation.Vertical">
    <SplitterPanes>
        <SplitterPane Size="100px" Collapsible="true">
            <ContentTemplate>
                <div style="padding: 10px;">Top Pane</div>
            </ContentTemplate>
        </SplitterPane>
        <SplitterPane Collapsible="true">
            <ContentTemplate>
                <div style="padding: 10px;">Bottom Pane</div>
            </ContentTemplate>
        </SplitterPane>
    </SplitterPanes>
</SfSplitter>

常见模式

模式 1：响应式三窗格布局

<SfSplitter Height="400px" Width="100%">
    <SplitterPanes>
        <SplitterPane Size="20%" Min="150px" Collapsible="true">
            <ContentTemplate><div>Sidebar</div></ContentTemplate>
        </SplitterPane>
        <SplitterPane Size="60%" Min="300px">
            <ContentTemplate><div>Main Content</div></ContentTemplate>
        </SplitterPane>
        <SplitterPane Size="20%" Min="150px" Collapsible="true">
            <ContentTemplate><div>Details Panel</div></ContentTemplate>
        </SplitterPane>
    </SplitterPanes>
</SfSplitter>

适用场景：仪表板布局、IDE 风格界面、内容管理系统。

模式 2：嵌套分隔器（代码编辑器布局）

<SfSplitter Height="400px" Orientation="Orientation.Vertical">
    <SplitterPanes>
        <SplitterPane Size="60%">
            <SfSplitter Height="100%">
                <SplitterPanes>
                    <SplitterPane Size="30%"><ContentTemplate>HTML</ContentTemplate></SplitterPane>
                    <SplitterPane Size="30%"><ContentTemplate>CSS</ContentTemplate></SplitterPane>
                    <SplitterPane Size="40%"><ContentTemplate>JS</ContentTemplate></SplitterPane>
                </SplitterPanes>
            </SfSplitter>
        </SplitterPane>
        <SplitterPane Size="40%"><ContentTemplate>Preview</ContentTemplate></SplitterPane>
    </SplitterPanes>
</SfSplitter>

适用场景：代码编辑器、预览窗格、复杂的仪表板布局。

模式 3：带状态绑定的可折叠侧边栏

<SfSplitter Height="300px" Width="100%">
    <SplitterPanes>
        <SplitterPane Size="250px" Min="50px" Collapsible="true" @bind-Collapsed="@sidebarCollapsed">
            <ContentTemplate><div>Navigation</div></ContentTemplate>
        </SplitterPane>
        <SplitterPane>
            <ContentTemplate><div>Main Area</div></ContentTemplate>
        </SplitterPane>
    </SplitterPanes>
</SfSplitter>

@code {
    private bool sidebarCollapsed = false;
}

适用场景：需要动态切换侧边栏并与 UI 状态同步的应用程序。

关键属性和配置

属性	类型	说明	默认值
Height	string	容器高度	必填
Width	string	容器宽度	100%
Orientation	Orientation	水平或垂直	Horizontal
SeparatorSize	int	分隔条厚度（像素）	1
EnablePersistence	bool	将状态保存到 localStorage	false
Size	string	窗格宽度/高度（px 或 %）	Auto
Min	string	窗格最小尺寸	0
Max	string	窗格最大尺寸	Unlimited
Resizable	bool	允许调整窗格大小	true
Collapsible	bool	显示折叠/展开按钮	false
Visible	bool	显示/隐藏窗格	true
Collapsed	bool	初始折叠状态	false

常见用例

1. 代码编辑器界面 — 顶部窗格用于代码标签页，底部窗格用于输出。在顶部窗格中使用嵌套水平分隔器。

2. 管理仪表板 — 左侧边栏用于导航，主区域用于内容。添加右侧面板以显示详情或设置。

3. 邮件客户端 — 左侧窗格用于文件夹列表，中间窗格用于邮件列表，右侧窗格用于邮件内容。

4. 项目管理工具 — 使用多个可折叠面板展示时间线、任务和甘特图。

5. 数据分析仪表板 — 使用可调整大小的面板展示图表、表格和筛选器，并持久化状态。

---

后续步骤：

• 从入门指南开始，了解设置说明
• 阅读分割窗格，了解布局选项
• 查看窗格配置，了解自定义选项
• 查看高级场景，了解复杂布局