syncfusion-blazor-dashboard-layout

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Dashboard Layout with Syncfusion Blazor

使用Syncfusion Blazor实现仪表盘布局

The Syncfusion Blazor Dashboard Layout component provides a comprehensive solution for building responsive, interactive dashboards. This skill guides you through creating flexible panel-based layouts with advanced features including drag-and-drop, resizing, state persistence, and adaptive responsive design.

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

When to Use This Skill

何时使用本指南

Use this skill when you need to:

Create dashboard or grid-based panel layouts
Enable users to rearrange panels through drag-and-drop
Allow panel resizing with size constraints
Build responsive layouts that adapt to different screen sizes
Save and restore user layout configurations
Create complex multi-panel displays with headers and dynamic content
Customize panel styling and appearance
Prevent panel overlapping in dynamic scenarios

当您需要以下功能时，可使用本指南：

创建基于仪表板或网格的面板布局
允许用户通过拖拽重新排列面板
支持带尺寸约束的面板调整大小
构建可适配不同屏幕尺寸的响应式布局
保存和恢复用户布局配置
创建包含标题和动态内容的复杂多面板展示
自定义面板样式和外观
防止动态场景下的面板重叠

Component Overview

组件概述

SfDashboardLayout creates a grid-based dashboard where panels represent resizable, draggable containers organized on a configurable grid. Key capabilities:

Grid-based positioning using Row and Column properties
Flexible sizing with width (SizeX) and height (SizeY) in cell units
Size constraints with MinSizeX, MaxSizeX, MinSizeY, MaxSizeY properties
Drag-and-drop with automatic collision handling and panel pushing
Resizing with customizable resize handles in multiple directions
Floating panels that automatically move up to fill empty spaces
State persistence to localStorage with programmatic save/load/reset
Templates for headers and dynamic content
Responsive design with media query breakpoints for mobile adaptation
Cell-based grid with configurable columns, cell aspect ratio, and spacing

SfDashboardLayout 创建一个基于网格的仪表板，其中面板代表可调整大小、可拖拽的容器，这些容器在可配置的网格上进行组织。核心功能包括：

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

Documentation and Navigation Guide

文档与导航指南

Getting Started 📄 references/getting-started.md

Setting up Dashboard Layout in WebAssembly and Server apps
NuGet package installation (Syncfusion.Blazor.Layouts, Syncfusion.Blazor.Themes)
Configuring namespaces and Syncfusion services
Adding stylesheet and script resources
Creating first dashboard with basic panels

Core Layout Configuration 📄 references/panel-positioning-sizing.md

Panel Row and Column positioning
Setting panel dimensions with SizeX and SizeY
Min/Max size constraints (MinSizeX, MaxSizeX, MinSizeY, MaxSizeY)
Panel ID management and unique identification
Understanding cell-based grid system

Interactive Features 📄 references/drag-drop-functionality.md

Enabling drag-and-drop rearrangement
Automatic collision detection and panel pushing
Customizing drag handles with DraggableHandle property
Using CSS selectors for drag-handle targeting
Placeholder visualization during drag operations

📄 references/resizing-floating-panels.md

Enabling panel resizing with AllowResizing property
Customizing resize directions with ResizableHandles property
Floating panels with AllowFloating to utilize empty space
Floating behavior and automatic upward panel movement

Grid Configuration & Styling 📄 references/grid-configuration-styling.md

Configuring grid with Columns property
Cell aspect ratio with CellAspectRatio property
Cell spacing with CellSpacing property (row and column gaps)
Visualizing grid with ShowGridLines property
CSS customization of panel headers, content, and backgrounds
CSS classes: .e-panel-header, .e-panel-content, .e-resize

Responsive & Adaptive Design 📄 references/responsive-adaptive-design.md

Built-in responsive support for different screen sizes
MediaQuery property for custom breakpoints
Automatic stacking layout at low resolutions (default 600px)
Mobile-friendly configurations
Responsive behavior without manual configuration

Panel Templates & Headers 📄 references/panel-templates-headers.md

HeaderTemplate for panel titles and headers
ContentTemplate for panel main content
CssClass property for custom styling
Rendering HTML and components within panels
Empty space rendering prevention

State Management & Persistence 📄 references/state-persistence.md

Enabling persistence with EnablePersistence property
localStorage integration for automatic save/restore
GetPersistDataAsync for retrieving current state as string
SetPersistDataAsync for restoring saved state
ResetPersistDataAsync for clearing saved state
Component ID requirement for persistence

API Reference 📄 references/api-reference.md

Complete SfDashboardLayout component API documentation
All 14 properties with types, defaults, and accepted values
All 11 methods with parameters, return types, and descriptions
All 8 events with argument types and usage examples
DashboardLayoutPanel component properties (17 total)
PanelModel class properties for programmatic panel data
Event argument classes with complete examples
ResizableHandle enumeration with all 8 direction values
Working code examples for every property and method
Cross-references to related documentation

Advanced Scenarios & Troubleshooting 📄 references/advanced-scenarios.md

Preventing panel overlap with unique IDs in dynamic rendering
All panels at same position configuration
Performance optimization for complex layouts
Complex multi-panel display patterns
Troubleshooting common issues and edge cases

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

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

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

面板的Row和Column定位
使用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类属性
带完整示例的事件参数类
包含所有8个方向值的ResizableHandle枚举
每个属性和方法的可运行代码示例
相关文档的交叉引用

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

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

Quick Start Example

快速入门示例

csharp

@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>

csharp

@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>

Common Patterns

常见模式

Basic 3-Panel Dashboard

csharp

<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>

With Drag-Drop and Resizing

csharp

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

Responsive Mobile Layout

csharp

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" 
    Columns="5" 
    MediaQuery="max-width:600px">
    <!-- Automatically stacks to single column below 600px -->
</SfDashboardLayout>

State Persistence Pattern

csharp

<SfDashboardLayout ID="dashboard" EnablePersistence="true" CellSpacing="@(new double[]{10, 10})">
    <!-- Automatically saves to localStorage on changes -->
</SfDashboardLayout>

基础三面板仪表板

csharp

<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>

带拖拽和调整大小功能

csharp

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

响应式移动端布局

csharp

<SfDashboardLayout CellSpacing="@(new double[]{10, 10})" 
    Columns="5" 
    MediaQuery="max-width:600px">
    <!-- Automatically stacks to single column below 600px -->
</SfDashboardLayout>

状态持久化模式

csharp

<SfDashboardLayout ID="dashboard" EnablePersistence="true" CellSpacing="@(new double[]{10, 10})">
    <!-- Automatically saves to localStorage on changes -->
</SfDashboardLayout>

Key Properties Reference

核心属性参考

Property	Purpose	Common Values
Columns	Number of grid cells per row	4, 5, 6, 12
Row	Panel vertical position (0-based)	0, 1, 2, ...
Column	Panel horizontal position (0-based)	0, 1, 2, ...
SizeX	Panel width in cells	1, 2, 3, ...
SizeY	Panel height in cells	1, 2, 3, ...
MinSizeX/MinSizeY	Minimum size constraints	1, 2, ...
MaxSizeX/MaxSizeY	Maximum size constraints	null (unlimited) or specific value
CellSpacing	Gap between panels (row, column)	[10, 10], [20, 20]
CellAspectRatio	Height-to-width ratio	1, 2, 0.5
AllowDragging	Enable panel rearrangement	true, false
AllowResizing	Enable panel resizing	true, false
AllowFloating	Auto-fill empty spaces	true, false
DraggableHandle	CSS selector for drag area	".e-panel-header"
ResizableHandles	Resize directions	"e" (east), "south-east", etc.
MediaQuery	Mobile breakpoint	"max-width:600px"
EnablePersistence	Save state to localStorage	true, false
ID	Unique component ID (required for persistence)	"dashboard", "layout1"

属性	用途	常见值
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"

Use Case Examples

使用场景示例

Data Analytics Dashboard Use dashboard grid with Charts, Grids, and metrics panels. Enable resizing so users can focus on important metrics.

Admin Control Panel Combine multiple Syncfusion components (grids, charts, forms) in panels. Persist layout so admin preferences are remembered.

SEO Monitoring Dashboard Display analytics metrics and charts using dashboard grid. Use floating panels to automatically optimize space as panels are moved.

Personal Workspace Let users customize their layout completely with drag-drop, resizing, and persistence to create their ideal workspace.

Responsive Mobile Dashboard Design for desktop, automatically adapts to single-column stacked layout on mobile using MediaQuery breakpoints.

数据分析仪表板 在仪表板网格中使用图表、表格和指标面板。启用调整大小功能，让用户可以聚焦于重要指标。

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

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

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

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