syncfusion-blazor-dashboard-layout

使用 Syncfusion Blazor 实现仪表板布局

Syncfusion Blazor Dashboard Layout 组件为构建响应式交互式仪表板提供了全面的解决方案。本技能将指导你创建灵活的面板式布局，并使用拖放、调整大小、状态持久化和自适应响应式设计等高级功能。

何时使用此技能

在以下情况下使用此技能：

• 创建仪表板或基于网格的面板布局
• 允许用户通过拖放重新排列面板
• 允许调整面板大小并设置尺寸限制
• 构建能够适应不同屏幕尺寸的响应式布局
• 保存和恢复用户的布局配置
• 创建带有标题和动态内容的复杂多面板视图
• 自定义面板样式和外观
• 防止动态场景中的面板重叠

组件概述

SfDashboardLayout 可创建基于网格的仪表板，其中的面板是可调整大小、可拖动的容器，并按照可配置的网格进行排列。主要功能：

• 基于网格定位，使用 Row 和 Column 属性
• 灵活调整尺寸，以单元格为单位设置宽度（SizeX）和高度（SizeY）
• 尺寸限制，使用 MinSizeX、MaxSizeX、MinSizeY、MaxSizeY 属性
• 拖放，支持自动碰撞处理和面板推移
• 调整大小，支持在多个方向自定义调整手柄
• 浮动面板，自动上移以填充空白区域
• 状态持久化到 localStorage，并支持通过编程方式保存、加载和重置
• 模板，用于标题和动态内容
• 响应式设计，使用媒体查询断点适配移动设备
• 基于单元格的网格，支持配置列数、单元格纵横比和间距

文档与导航指南

快速入门 📄 references/getting-started.md

• 在 WebAssembly 和 Server 应用中设置 Dashboard Layout
• 安装 NuGet 包（Syncfusion.Blazor.Layouts、Syncfusion.Blazor.Themes）
• 配置命名空间和 Syncfusion 服务
• 添加样式表和脚本资源
• 使用基本面板创建第一个仪表板

核心布局配置 📄 references/panel-positioning-sizing.md

• 面板的行和列定位
• 使用 SizeX 和 SizeY 设置面板尺寸
• 最小/最大尺寸限制（MinSizeX、MaxSizeX、MinSizeY、MaxSizeY）
• 面板 ID 管理和唯一标识
• 了解基于单元格的网格系统

交互功能 📄 references/drag-drop-functionality.md

• 启用拖放重新排列
• 自动碰撞检测和面板推移
• 使用 DraggableHandle 属性自定义拖动手柄
• 使用 CSS 选择器定位拖动手柄
• 拖动操作期间的占位符可视化

📄 references/resizing-floating-panels.md

• 使用 AllowResizing 属性启用面板调整大小
• 使用 ResizableHandles 属性自定义调整方向
• 使用 AllowFloating 让浮动面板利用空白空间
• 浮动行为和面板自动向上移动

网格配置与样式 📄 references/grid-configuration-styling.md

• 使用 Columns 属性配置网格
• 使用 CellAspectRatio 属性设置单元格宽高比
• 使用 CellSpacing 属性设置单元格间距（行和列间隙）
• 使用 ShowGridLines 属性显示网格
• 使用 CSS 自定义面板标题、内容和背景
• CSS 类：.e-panel-header、.e-panel-content、.e-resize

响应式与自适应设计 📄 references/responsive-adaptive-design.md

• 内置对不同屏幕尺寸的响应式支持
• 使用 MediaQuery 属性自定义断点
• 低分辨率下自动切换为堆叠布局（默认 600px）
• 适合移动设备的配置
• 无需手动配置即可实现响应式行为

面板模板与标题 📄 references/panel-templates-headers.md

• 使用 HeaderTemplate 设置面板标题和页眉
• 使用 ContentTemplate 设置面板主要内容
• 使用 CssClass 属性自定义样式
• 在面板中渲染 HTML 和组件
• 防止渲染空白区域

状态管理与持久化 📄 references/state-persistence.md

• 使用 EnablePersistence 属性启用持久化
• 集成 localStorage 以自动保存/恢复
• 使用 GetPersistDataAsync 将当前状态作为字符串获取
• 使用 SetPersistDataAsync 恢复已保存的状态
• 使用 ResetPersistDataAsync 清除已保存的状态
• 持久化需要组件 ID

API 参考 📄 references/api-reference.md

• 完整的 SfDashboardLayout 组件 API 文档
• 全部 14 个属性，包括类型、默认值和可接受的值
• 全部 11 个方法，包括参数、返回类型和说明
• 全部 8 个事件，包括参数类型和用法示例
• DashboardLayoutPanel 组件属性（共 17 个）
• 用于以编程方式提供面板数据的 PanelModel 类属性
• 事件参数类及完整示例
• ResizableHandle 枚举及全部 8 个方向值
• 每个属性和方法的可运行代码示例
• 相关文档的交叉引用

高级场景与故障排除 📄 references/advanced-scenarios.md

• 在动态渲染中使用唯一 ID 防止面板重叠
• 配置所有面板位于同一位置
• 复杂布局的性能优化
• 复杂的多面板显示模式
• 常见问题和边缘情况的故障排除

快速入门示例

@using Syncfusion.Blazor.Layouts

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" Columns="5">
    <DashboardLayoutPanels>
        <DashboardLayoutPanel>
            <HeaderTemplate><div>Panel 1</div></HeaderTemplate>
            <ContentTemplate><div>Your content here</div></ContentTemplate>
        </DashboardLayoutPanel>
        <DashboardLayoutPanel SizeX=2 SizeY=2 Column=1>
            <HeaderTemplate><div>Panel 2</div></HeaderTemplate>
            <ContentTemplate><div>Your content here</div></ContentTemplate>
        </DashboardLayoutPanel>
        <DashboardLayoutPanel SizeY=2 Column=3>
            <HeaderTemplate><div>Panel 3</div></HeaderTemplate>
            <ContentTemplate><div>Your content here</div></ContentTemplate>
        </DashboardLayoutPanel>
    </DashboardLayoutPanels>
</SfDashboardLayout>

<style>
    .e-panel-header {
        background-color: rgba(0, 0, 0, .1);
        text-align: center;
    }
    .e-panel-content {
        text-align: center;
        margin-top: 10px;
    }
</style>

常见模式

基本的三面板仪表板

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" Columns="6">
    <DashboardLayoutPanels>
        <DashboardLayoutPanel SizeX=2>
            <HeaderTemplate><div>Metrics</div></HeaderTemplate>
            <ContentTemplate><div>250,000</div></ContentTemplate>
        </DashboardLayoutPanel>
        <DashboardLayoutPanel SizeX=2 Column=2>
            <HeaderTemplate><div>Users</div></HeaderTemplate>
            <ContentTemplate><div>45,200</div></ContentTemplate>
        </DashboardLayoutPanel>
        <DashboardLayoutPanel SizeX=2 Column=4>
            <HeaderTemplate><div>Revenue</div></HeaderTemplate>
            <ContentTemplate><div>$125,000</div></ContentTemplate>
        </DashboardLayoutPanel>
    </DashboardLayoutPanels>
</SfDashboardLayout>

支持拖放和调整大小

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" 
    Columns="6" 
    AllowDragging="true" 
    AllowResizing="true">
    
</SfDashboardLayout>

响应式移动端布局

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" 
    Columns="5" 
    MediaQuery="max-width:600px">
    
</SfDashboardLayout>

状态持久化模式

<SfDashboardLayout ID="dashboard" EnablePersistence="true" CellSpacing="@(new double[]{10, 10})">
    
</SfDashboardLayout>

关键属性参考

属性	用途	常见值
Columns	每行的网格单元格数	4、5、6、12
Row	面板的垂直位置（从 0 开始）	0、1、2、...
Column	面板的水平位置（从 0 开始）	0、1、2、...
SizeX	面板宽度（以单元格计）	1、2、3、...
SizeY	面板高度（以单元格计）	1、2、3、...
MinSizeX/MinSizeY	最小尺寸限制	1、2、...
MaxSizeX/MaxSizeY	最大尺寸限制	null（无限制）或指定值
CellSpacing	面板间距（行、列）	[10, 10]、[20, 20]
CellAspectRatio	高宽比	1、2、0.5
AllowDragging	启用面板重新排列	true、false
AllowResizing	启用面板大小调整	true、false
AllowFloating	自动填充空白区域	true、false
DraggableHandle	拖动区域的 CSS 选择器	".e-panel-header"
ResizableHandles	调整大小的方向	"e"（东）、"south-east" 等
MediaQuery	移动端断点	"max-width:600px"
EnablePersistence	将状态保存到 localStorage	true、false
ID	唯一组件 ID（持久化必需）	"dashboard"、"layout1"

使用场景示例

数据分析仪表板 使用仪表板网格搭配图表、网格和指标面板。启用大小调整功能，让用户能够专注于重要指标。

管理控制面板 在面板中组合多个 Syncfusion 组件（网格、图表、表单）。持久化布局，以便记住管理员的偏好设置。

SEO 监控仪表板 使用仪表板网格显示分析指标和图表。使用浮动面板，在面板移动时自动优化空间。

个人工作区 允许用户通过拖放、调整大小和持久化功能完全自定义布局，打造理想的工作区。

响应式移动端仪表板 针对桌面端进行设计，并使用 MediaQuery 断点，在移动端自动适配为单列堆叠布局。