syncfusion-angular-dashboard-layout

实现 Syncfusion Angular Dashboard Layout

Dashboard Layout 组件是一款功能强大的网格结构布局控件，可帮助你创建包含动态面板的响应式交互式仪表板。面板可以拖动、调整大小、添加和移除，其状态还可以持久化保存。本技能将指导你全面了解如何在 Angular 中实现、配置和自定义仪表板布局。

何时使用此技能

• 创建包含多个面板的可自定义仪表板布局
• 实现面板的拖放重新定位
• 启用面板在多个方向上的尺寸调整
• 动态添加或移除仪表板面板
• 让仪表板适配不同设备尺寸
• 保存和恢复仪表板布局配置
• 使用 CSS 自定义仪表板组件样式
• 将 Syncfusion 图表、网格或其他组件集成到面板内容中

组件概述

Dashboard Layout 组件提供：

• 基于网格的布局系统，支持配置列数和单元格尺寸
• 拖放支持，可重新排列面板并提供视觉反馈
• 多个方向上的尺寸调整（东、西、北、南等）
• 浮动面板，可自动填充空白区域
• 响应式行为，支持自定义媒体查询断点
• 通过序列化/反序列化方法实现状态持久化
• 动态面板管理，支持添加、移除和移动操作
• 用于跟踪用户交互的事件驱动架构

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• Angular CLI 设置和项目初始化
• 安装 Dashboard Layout 包（Ivy 和 ngcc 变体）
• CSS 导入和主题配置
• 两种面板定义方式（HTML 属性与属性绑定）
• 基本组件渲染和首次创建仪表板
• 单元格间距和布局初始化

添加和移除面板

📄 阅读： references/adding-removing-panels.md

• 使用 addPanel() 方法动态管理面板
• 使用 removePanel(id) 移除单个面板
• 使用 removeAll() 方法批量移除
• 用于动态生成的面板配置属性
• 用于生命周期管理的事件处理和回调

设置面板标题

📄 阅读： references/panel-headers.md

• 使用 header 属性配置面板标题
• 向标题中添加标题文本、标签和 HTML 内容
• 使用 CSS 自定义标题样式
• 在面板标题中嵌入 Syncfusion 组件
• 标题交互和用户体验模式

拖动和放置面板

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

• 默认拖放行为和面板碰撞处理
• 拖动事件：dragStart、drag、dragStop
• 使用 draggableHandle 属性自定义拖动手柄
• 使用 movePanel(id, row, col) 以编程方式移动面板
• 使用 allowDragging 禁用拖动功能
• 触控支持和用户交互模式

以编程方式移动面板

📄 阅读： references/moving-panels.md

• 使用 movePanel(id, row, col) 重新定位面板
• 无需用户交互即可移动面板
• 使用 change 事件跟踪面板移动
• 以编程方式交换面板位置
• 面板重新排列模式和使用场景

调整大小和浮动面板

📄 阅读： references/resizing-and-floating.md

• 使用 allowResizing 启用面板尺寸调整
• 不同方向的尺寸调整手柄（e-south-east、e-east、e-west、e-north、e-south）
• 尺寸调整事件：resizeStart、resize、resizeStop
• 使用 resizePanel(id, sizeX, sizeY) 以编程方式调整尺寸
• 最小和最大尺寸限制（minSizeX、minSizeY、maxSizeX、maxSizeY）
• 浮动行为和自动面板重新定位
• 为固定网格布局禁用浮动

保存和恢复状态

📄 阅读： references/save-restore-state.md

• 使用 serialize() 序列化仪表板布局
• 将布局状态保存到 localStorage、sessionStorage 或后端
• 从持久化配置恢复布局
• 实现布局模板和预设
• 状态持久化模式和最佳实践

响应式和自适应设计

📄 阅读： references/responsive-and-adaptive.md

• 内置响应式行为和自动适配
• 使用 mediaQuery 自定义响应式断点
• 在移动设备上采用堆叠布局（纵向列）
• 使用 cellAspectRatio 配置单元格宽高比
• 在不同分辨率下测试响应式布局
• 父元素尺寸设置（百分比尺寸与固定尺寸）

配置单元格间距

📄 阅读： references/cell-spacing-configuration.md

• 使用 cellSpacing 属性设置 [水平、垂直] 间距
• 为紧凑或宽松布局调整间距
• 为响应式设计动态调整间距
• 通过不对称间距模式营造视觉层次
• 实用示例：紧凑型仪表板、高管布局

图形表示和网格线

📄 阅读： references/grid-lines-and-visualization.md

• 使用 showGridLines 属性可视化网格结构
• 了解网格单元格、行、列和间距
• 在设计时可视化网格，以规划布局
• 调试面板定位和尺寸
• 网格线使用最佳实践

从右向左语言支持

📄 阅读： references/rtl-support.md

• 使用 enableRtl 属性启用 RTL 渲染
• 支持阿拉伯语、希伯来语、波斯语和乌尔都语
• 为语言切换动态启用或禁用 RTL
• 集成 HTML dir 属性
• 使用 CSS 逻辑属性实现 RTL 感知样式
• 拖放交互中的 RTL 注意事项

样式和自定义

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

• 用于自定义面板、标题和内容的 CSS 选择器
• 面板标题和内容样式（.e-panel-header、.e-panel-content）
• 调整大小手柄自定义（.e-resize）
• 仪表板背景样式
• 使用 row、col、sizeX、sizeY 属性设置面板位置和尺寸
• 最小/最大尺寸约束和网格结构
• 将 Syncfusion 组件（图表、网格、仪表）集成到面板内容中
• 面向旧版 Angular 设置的 SystemJS 配置

详细示例和代码示例请参阅：

• getting-started.md - 快速入门和基础设置示例
• 特定参考文件中的常见模式和实现示例

API 参考

组件属性（共 14 个）

布局配置

属性	类型	默认值	描述
columns	number	5	网格布局中的列数。面板在此列网格中定位。
cellSpacing	number[]	[10, 10]	面板之间的间距：[水平、垂直]，单位为像素。用于在面板周围留出视觉间隔和内边距。
cellAspectRatio	number	Auto (1:1)	单元格的宽高比。例如：100/50 表示单元格宽度是高度的两倍。
mediaQuery	string	'max-width: 600px'	用于响应式堆叠布局的 CSS 媒体查询断点。低于此断点时，面板将纵向堆叠。
showGridLines	boolean	false	为 true 时，可视化网格单元格和结构，以便在设计时进行调试和布局规划。

交互功能

属性	类型	默认值	描述
allowDragging	boolean	true	启用或禁用面板拖放功能。启用后，用户可以通过拖动重新排列面板。
allowResizing	boolean	false	启用或禁用面板调整大小功能。启用后，面板边缘会显示调整大小手柄。
allowFloating	boolean	true	启用或禁用浮动行为。启用后，面板会自动向上移动，以填补因其他面板移动或调整大小而留下的空白。
resizableHandles	string[]	['e-south-east']	调整大小手柄方向数组：'e-south-east'、'e-east'、'e-west'、'e-north'、'e-south'、'e-south-west'。用于控制用户可调整面板大小的方向。
draggableHandle	string	null	用于拖动手柄元素的 CSS 选择器字符串。设置后，用户只能抓住此特定元素（例如，'.e-panel-header'）进行拖动。

内容和样式

属性	类型	默认值	描述
panels	PanelModel[]	[]	面板配置数组，用于定义仪表板布局结构和内容。
enableRtl	boolean	false	为从右向左书写的语言（阿拉伯语、希伯来语、波斯语、乌尔都语）启用从右向左渲染。
enableHtmlSanitizer	boolean	true	对面板中的 HTML 内容进行清理，以防止 XSS 攻击。仅在内容可信时设为 false。
enablePersistence	boolean	false	启用后，会在浏览器存储中自动保存和恢复仪表板状态，使其在页面重新加载后保持不变。

面板属性（共 13 项）

属性	类型	默认值	描述
位置和尺寸
row	number	0	在网格中的起始行位置（从 0 开始索引），用于确定垂直位置。
col	number	0	在网格中的起始列位置（从 0 开始索引），用于确定水平位置。
sizeX	number	1	面板的宽度，以单元格为单位。例如：sizeX=2 表示跨越 2 个网格列。
sizeY	number	1	面板的高度，以单元格为单位。例如：sizeY=2 表示跨越 2 个网格行。
尺寸限制
minSizeX	number	1	最小宽度，以单元格为单位。防止面板调整后的宽度小于此值。
minSizeY	number	1	最小高度，以单元格为单位。防止面板调整后的高度小于此值。
maxSizeX	number	null	最大宽度，以单元格为单位。null 表示不设限制。防止面板调整后的宽度大于此值。
maxSizeY	number	null	最大高度，以单元格为单位。null 表示不设限制。防止面板调整后的高度大于此值。
内容
id	string	''	面板的唯一标识符。movePanel()、resizePanel()、removePanel() 等方法需要此标识符。
header	string | HTMLElement | Function	undefined	标题栏内容。可以是 HTML 字符串、DOM 元素或返回内容的函数。
content	string | HTMLElement | Function	undefined	主体内容。可以是 HTML 字符串、DOM 元素或返回内容的函数（例如，图表、网格）。
样式和状态
cssClass	string	''	要应用于面板的自定义 CSS 类名，用于设置样式和主题。
enabled	boolean	true	设为 false 时会禁用面板，使其无法交互。
zIndex	number	1000	用于控制层叠顺序的 CSS z-index。值越大，显示位置越靠上。

事件（共 9 项）

拖动事件

事件	参数	描述
dragStart	DragStartArgs	用户开始拖动面板时触发。参数：cancel（用于阻止拖动的 bool）、element（HTMLElement）、event（MouseEvent|TouchEvent）。可用于验证或阻止特定拖动操作。
drag	DraggedEventArgs	拖动过程中持续触发。参数：element（正在拖动的 HTMLElement）、event（MouseEvent|TouchEvent）、target（光标下方的 HTMLElement）。可用于在拖动过程中提供视觉反馈。每秒触发 60 次以上——对开销较大的操作进行节流。
dragStop	DragStopArgs	拖动完成或释放时触发。参数：cancel（用于还原位置的 bool）、element、event、panels（受影响面板的 PanelModel[]）、target。可用于保存最终位置或验证放置位置。

调整大小事件

事件	参数	描述
resizeStart	ResizeArgs	开始调整大小时触发。参数：element（HTMLElement）、event（MouseEvent|TouchEvent）、isInteracted（true=用户操作，false=程序化操作）、panels（受影响的 PanelModel[]）。
resize	ResizeArgs	调整大小过程中持续触发。参数与 resizeStart 相同。可用于实时验证或显示新的尺寸。触发频率较高——对开销较大的操作进行节流。
resizeStop	ResizeArgs	调整大小完成时触发。参数与 resize 相同。可用于确定面板大小或保存状态。

布局变更事件

事件	参数	描述
change	ChangeEventArgs	布局发生变化时触发（面板添加、移除、移动或调整大小）。参数：addedPanels（PanelModel[]）、changedPanels（PanelModel[]）、isInteracted（bool）、removedPanels（PanelModel[]）。可用于检测并响应所有布局修改。
created	Object	仪表板组件完成初始化并渲染后触发。可用于执行初始化后的设置。
destroyed	Object	仪表板组件销毁时触发。可用于执行清理操作。

方法

面板管理

方法	签名	返回值	描述
addPanel	addPanel(panel: PanelModel)	void	动态向仪表板添加新面板。面板将根据其 row/col 属性定位。会触发 change 事件。
removePanel	removePanel(panelId: string)	void	根据 ID 移除指定面板。会触发 change 事件。如果 allowFloating=true，其他面板可能会向上浮动。
removeAll	removeAll()	void	移除仪表板中的所有面板。清空整个布局。
movePanel	movePanel(panelId: string, row: number, col: number)	void	将面板重新定位到新的网格位置。如果启用了浮动，将触发类似拖动的行为。会触发 change 事件。
resizePanel	resizePanel(panelId: string, sizeX: number, sizeY: number)	void	将面板调整为新的尺寸（以单元格计）。遵循 minSize/maxSize 限制。会触发 isInteracted=false 的调整大小事件。会触发 change 事件。

状态管理

方法	签名	返回值	描述
serialize	serialize()	PanelModel[]	捕获并返回当前仪表板布局状态，形式为 PanelModel 对象数组。可与 localStorage 或数据库配合使用，以持久化用户配置。也可用于创建布局模板/预设。

组件生命周期

方法	签名	返回值	描述
updatePanel	updatePanel(panelId: string, panelModel: PanelModel)	void	更新现有面板的属性。无需移除并重新添加面板，即可更改标题、内容或其他面板属性。触发带有 changedPanels 的 change 事件。
refreshDraggableHandle	refreshDraggableHandle()	void	刷新可拖动句柄选择器。当 DOM 结构发生变化或需要重新评估 draggableHandle CSS 选择器时调用。适用于外部 DOM 修改后。
destroy	destroy()	void	销毁 Dashboard Layout 组件并清理所有资源。触发 destroyed 事件。请在组件卸载前调用，以防止内存泄漏。

事件参数参考

DragStartArgs

{
  cancel: boolean;              // Set to true to prevent the drag operation
  element: HTMLElement;         // The panel element being dragged
  event: MouseEvent | TouchEvent; // The original browser event
}

DraggedEventArgs

{
  element: HTMLElement;         // The panel element being dragged
  event: MouseEvent | TouchEvent; // The original browser event (fires 60+ times/sec)
  target: HTMLElement;          // The element currently under the cursor
}

DragStopArgs

{
  cancel: boolean;              // Set to true to cancel/revert the drag
  element: HTMLElement;         // The panel element that was dragged
  event: MouseEvent | TouchEvent; // The drop/release event
  panels: PanelModel[];         // Array of panels affected by the drag (position changed)
  target: HTMLElement;          // The element at the drop location
}

ResizeArgs

{
  element: HTMLElement;         // The panel element being resized
  event: MouseEvent | TouchEvent; // The original browser event
  isInteracted: boolean;        // true = user resize, false = programmatic resize
  panels: PanelModel[];         // Array of panels affected by the resize
}

ChangeEventArgs

{
  addedPanels: PanelModel[];    // Panels added in this change
  changedPanels: PanelModel[];  // Panels whose position/size changed
  isInteracted: boolean;        // true = user action, false = programmatic
  removedPanels: PanelModel[];  // Panels removed in this change
}

方法示例和安全配置的详细信息，请参阅：

• adding-removing-panels.md - 面板管理的方法示例
• styling-and-customization.md - 安全和配置示例

常见用例

1. 分析仪表板： 在可调整大小的面板中显示图表和指标，用于数据监控
2. 管理面板： 支持添加、移除和拖放功能的动态小部件系统
3. 实时监控： 更新面板内容，同时保留布局状态
4. 移动端自适应门户： 面板在移动设备上堆叠显示，在桌面端采用网格布局
5. 用户自定义布局： 允许用户保存自己偏好的仪表板排列方式
6. 小部件商店： 从小部件库中动态添加新面板

相关主题

组件设置与配置

• Angular 模块设置： 在独立组件中导入 DashboardLayoutModule
• CSS 主题： 可用主题（material3、bootstrap5、fabric、tailwind）
• 自适应父级尺寸： 为流式布局选择百分比尺寸或固定尺寸
• 持久化与存储： enablePersistence 与手动 serialize() 方式的比较

事件处理与交互

• 拖动事件： dragStart（取消拖动）、drag（视觉反馈）、dragStop（完成拖动）
• 调整大小事件： resizeStart、resize（持续触发）、resizeStop（含约束验证）
• 变更检测： 使用 (change) 事件跟踪所有布局修改（添加／移除／移动／调整大小）
• 事件节流： 优化拖动（每秒 60 次以上）和调整大小事件的性能
• isInteracted 属性： 区分用户操作与程序化更改

高级功能

• 动态面板管理： addPanel()、removePanel()、removeAll() 方法
• 程序化移动： 使用 movePanel(id, row, col) 自动重新排列
• 程序化调整大小： 使用 resizePanel(id, sizeX, sizeY) 并强制执行约束
• 状态序列化： 使用 serialize() 方法保存／恢复布局
• 尺寸约束： 使用 minSizeX、minSizeY、maxSizeX、maxSizeY 设置面板边界
• 浮动行为： 使用 allowFloating 自动填补间隙

组件集成

• 嵌入图表： 将 Syncfusion Charts（Column、Line、Pie 等）用作面板内容
• 嵌入网格： 在面板中使用带有数据、排序和筛选功能的 Syncfusion Grids
• 嵌入仪表： 使用线性仪表和径向仪表显示指标与 KPI
• 自定义 HTML 内容： 使用 Function 类型动态生成内容
• 内容函数类型： 将 content/header 用作 (Function)，以实现延迟加载或响应式内容

样式与自定义

• CSS 类： .e-panel-header、.e-panel-content、.e-resize、.e-dashboardlayout
• 面板样式： 使用 cssClass 属性为每个面板自定义主题
• 标题自定义： 使用 Function/HTMLElement 类型创建动态标题
• 拖动手柄自定义： 使用 draggableHandle CSS 选择器限制可拖动区域
• RTL 支持： 在从右到左的布局中，结合 enableRtl 与 resizableHandles 行为

性能与优化

• 大型仪表板渲染： 针对 100+ 个面板的技术
• 虚拟滚动： 何时考虑为超大型仪表板采用替代布局
• 事件节流： 管理拖动（60+/秒）和调整大小事件的频率
• 内存管理： 在 destroy 事件中清理面板
• 变更事件筛选： 仅跟踪相关变更（addedPanels、changedPanels、removedPanels）