syncfusion-javascript-dashboard-layout

用途

Syncfusion JavaScript Dashboard Layout 是一个基于网格的布局组件，用于创建带有可拖拽、可缩放面板的交互式仪表盘界面。它通过媒体查询支持响应式行为，并允许保存和恢复布局配置。该技能文档面向使用 Syncfusion TypeScript/JavaScript 组件实现仪表盘布局的开发者。

主要能力

• 网格系统：面板通过 row、col、sizeX、sizeY 定位，columns 定义网格总列数，cellSpacing 控制面板之间的水平和垂直间距。
• 面板配置：定义面板属性（sizeX、sizeY、row、col）、面板标题与内容模板、CSS 类与样式，以及以程序方式设置面板尺寸和位置。
• 拖拽与移动：启用/禁用拖拽，自定义拖拽手柄（draggableHandle），面板碰撞检测与重新排序，拖拽事件（dragStart、drag、dragStop）。
• 程序化移动：使用 movePanel() 方法定位，交换面板与布局重组，基于优先级和列的排列，恢复已保存布局。
• 缩放：启用/禁用缩放，可配置缩放手柄（e-south-east、e-east、e-west、e-north、e-south），缩放事件与事件参数，使用 resizePanel() 方法程序化缩放。minSizeX/maxSizeX 与 minSizeY/maxSizeY 约束缩放。
• 面板操作：通过 addPanel() 动态添加、removePanel() 移除、removeAll() 移除全部，serialize() 序列化布局。
• 浮动与响应式：启用 allowFloating 自动填充空位，使用 mediaQuery 实现响应式堆叠，配置单元格宽高比，适配不同屏幕尺寸。
• 持久化：serialize() 保存布局，从保存状态恢复，enablePersistence 状态持久化，localStorage 集成。
• 事件处理：生命周期事件（created、destroyed），拖拽事件（DragStartArgs、DraggedEventArgs、DragStopArgs），缩放事件（ResizeArgs），面板位置更新的 change 事件。

使用方式

通过 npm 包 @syncfusion/ej2-layouts 引入 DashboardLayout。快速开始示例：

import { DashboardLayout } from '@syncfusion/ej2-layouts';

let dashboard = new DashboardLayout({
    cellSpacing: [10, 10],
    columns: 5,
    panels: [
        { 'id': 'Panel1', 'sizeX': 2, 'sizeY': 2, 'row': 0, 'col': 0, content: '<div class="content">Panel 1</div>' },
        { 'id': 'Panel2', 'sizeX': 3, 'sizeY': 2, 'row': 0, 'col': 2, content: '<div class="content">Panel 2</div>' }
    ]
});
dashboard.appendTo('#dashboard_layout');

常见模式包括：启用完整交互（allowDragging、allowResizing、allowFloating）、处理拖拽事件、保存与恢复布局（serialize 后赋回 dashboard.panels）、响应式仪表盘（mediaQuery 与 enablePersistence）。文档按导航指南组织，依次涵盖入门、面板配置、拖拽移动、程序化移动、缩放、面板操作、浮动与响应式、持久化与状态、事件处理以及完整 API 参考。

适用场景

适合分析报表仪表盘、可定制小组件布局、数据监控界面、用户可配置 UI 布局以及实时数据可视化中枢。不适合静态固定布局、简单页面布局（可用 CSS Grid 或 Flexbox）以及单列布局。