syncfusion-aspnetcore-dashboard-layout

实现仪表板布局

Syncfusion Dashboard Layout 控件是一种功能强大的网格布局系统，可让开发者创建交互式仪表板，并灵活管理面板。面板可以按自定义网格排列、调整大小、拖动、重新排序，也可以动态添加或移除，以满足动态仪表板的需求。

何时使用此技能

在需要以下功能时，请使用 Dashboard Layout 控件：

• 创建基于网格的仪表板，采用灵活的面板结构
• 启用拖放功能，允许用户重新排列面板
• 实现响应式布局，适应不同的屏幕尺寸
• 添加可调整大小的面板，并设置最小／最大尺寸限制
• 启用浮动面板，自动填充空网格单元格
• 管理面板状态，并在不同会话间保留布局
• 处理动态面板操作（添加、移除、移动、更新面板）
• 使用 HTML 或模板自定义面板标题和内容
• 支持 RTL 布局，适配从右向左书写的语言

组件概览

Dashboard Layout 包含：

1. 主容器 - 用于容纳面板的网格布局
2. 面板 - 包含内容的独立网格单元格
3. 网格系统 - 可配置的列和单元格间距
4. 交互功能 - 拖动、调整大小和动态操作
5. 状态管理 - 持久化和序列化功能

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• ASP.NET Core 项目配置
• TagHelper 注册和设置
• 资源引用（样式和脚本）
• Dashboard Layout 基本初始化
• 两种初始化方式（内容模板与 tag helper）

核心配置

📄 阅读： references/configuring-layouts.md

• 使用 columns 属性设置网格系统
• 配置单元格间距和宽高比
• 使用 row 和 column 属性设置面板位置
• 布局结构和网格单元格管理
• 包含代码的完整示例

面板管理

📄 阅读： references/panel-operations.md

• 使用 addPanel 方法动态添加面板
• 移除面板和清空布局（removePanel、removeAll）
• 将面板移动到其他位置（movePanel）
• 更新现有面板（updatePanel）
• 使用 sizeX、sizeY 属性调整面板大小
• 为面板应用最小／最大尺寸限制

交互功能

📄 阅读： references/dragging-and-dropping.md

• 使用 allowDragging 属性启用拖放
• 了解拖动事件生命周期（dragStart、drag、dragStop）
• 使用 draggableHandle 选择器自定义拖动处理程序
• 面板碰撞检测和自适应重新定位
• 正确绑定事件以处理拖动事件

调整面板大小

📄 阅读： references/resizing-panels.md

• 使用 allowResizing 属性启用调整大小功能
• 使用 resizableHandles 属性配置可调整大小的手柄
• 了解调整大小事件生命周期（resizeStart、resize、resizeStop）
• 设置面板的最小和最大尺寸限制
• 在应用程序中处理调整大小事件

响应式行为

📄 阅读： references/responsive-layouts.md

• 使用 allowFloating 属性实现浮动面板
• 使用 mediaQuery 配置响应式断点
• 在移动设备上自动堆叠面板
• 使用 enableRtl 属性支持 RTL
• 使布局适应不同的屏幕分辨率

状态与持久化

📄 阅读： references/state-and-persistence.md

• 使用 enablePersistence 属性启用状态持久化
• 序列化仪表板配置（serialize 方法）
• 组件生命周期事件（created、destroyed）
• 管理页面重新加载时的状态
• 用于安全防护的 HTML 清理

完整 API 参考

📄 阅读： references/api-reference.md

• 所有 Dashboard Layout 属性及其说明和默认值
• 完整的方法签名和用法示例
• 事件定义和事件参数类型
• 面板模型属性和约束
• 指向详细功能文档的交叉引用

快速入门示例

以下是一个最简示例，展示如何使用规范的驼峰式 API 属性创建包含两个面板的 Dashboard Layout：

@{
    var cellSpacing = new double[] { 10, 10 };
}

<ejs-dashboardlayout id="dashboard" allowDragging="true" allowResizing="true" 
                      allowFloating="true" columns="6" cellSpacing="@cellSpacing">
    <e-dashboardlayout-panels>
        <e-dashboardlayout-panel id="panel1" sizeX="3" sizeY="2" row="0" col="0" 
                                 header="<div>Sales Report</div>" 
                                 content="<div class='content'>Sales data content goes here</div>">
        </e-dashboardlayout-panel>
        <e-dashboardlayout-panel id="panel2" sizeX="3" sizeY="2" row="0" col="3" 
                                 header="<div>Revenue Chart</div>" 
                                 content="<div class='content'>Revenue chart content goes here</div>">
        </e-dashboardlayout-panel>
    </e-dashboardlayout-panels>
</ejs-dashboardlayout>

常见模式

模式 1：启用所有交互

启用拖动、调整大小和浮动，以实现最高的交互性：

<ejs-dashboardlayout id="dashboard" allowDragging="true" allowResizing="true" 
                      allowFloating="true" columns="4">
    <e-dashboardlayout-panels>
        <e-dashboardlayout-panel id="panel1" sizeX="2" sizeY="1" row="0" col="0" 
                                 header="<div>Panel 1</div>" 
                                 content="<div class='content'>Content</div>">
        </e-dashboardlayout-panel>
    </e-dashboardlayout-panels>
</ejs-dashboardlayout>

模式 2：响应式断点

配置布局，使面板在移动设备上堆叠显示：

<ejs-dashboardlayout id="responsive-dashboard" mediaQuery="(max-width: 768px)" 
                      columns="6" allowFloating="true">
    <e-dashboardlayout-panels>
        <e-dashboardlayout-panel id="panel1" sizeX="3" sizeY="2" row="0" col="0" 
                                 content="<div>Panel 1</div>">
        </e-dashboardlayout-panel>
        <e-dashboardlayout-panel id="panel2" sizeX="3" sizeY="2" row="0" col="3" 
                                 content="<div>Panel 2</div>">
        </e-dashboardlayout-panel>
    </e-dashboardlayout-panels>
</ejs-dashboardlayout>

模式 3：动态面板操作

根据用户操作以编程方式添加面板——详见面板管理参考文档。

模式 4：持久化用户布局

跨会话保存和恢复仪表板配置——详见状态与持久化参考文档。

关键属性概览

属性	类型	用途	默认值
columns	number	网格列数	1
cellSpacing	number[]	面板之间的间距 [水平，垂直]	[5, 5]
allowDragging	boolean	启用拖放	true
allowResizing	boolean	启用面板大小调整	false
allowFloating	boolean	自动填充空单元格	true
draggableHandle	string	用于拖动的 CSS 选择器	null
resizableHandles	string[]	调整大小的手柄方向	['e-south-east']
mediaQuery	string	响应式断点	'max-width:600px'
enablePersistence	boolean	将状态保存到存储中	false
enableRtl	boolean	启用从右到左的布局	false
showGridLines	boolean	可视化网格结构	false

常见用例

1. 分析仪表板 - 排列支持调整大小和拖动的图表面板
2. 销售仪表板 - 通过可调整大小的指标面板监控 KPI
3. 项目管理 - 通过动态面板操作整理任务看板
4. 商业智能 - 显示报告并持久化状态
5. 管理门户 - 支持用户自定义布局的仪表板

---

后续步骤： 从入门参考文档开始设置 Dashboard Layout 项目，然后探索所需的具体功能。