syncfusion-javascript-dashboard-layout

实现 Syncfusion TypeScript Dashboard Layout

DashboardLayout 是一个功能强大的基于网格的布局组件，可用于创建带有可拖动、可调整大小面板的交互式仪表板界面。它支持动态面板管理、浮动布局、状态持久化，以及通过媒体查询实现响应式行为。用户可以重新排列面板、沿多个方向调整面板大小，并保存或还原布局配置。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包依赖项
• 使用 HTML 属性或脚本进行设置
• 基本面板配置（行、列、单元格间距）
• 运行你的第一个仪表板应用

面板配置

📄 阅读： references/panel-configuration.md

• 定义面板属性（sizeX、sizeY、row、col）
• 面板标题和内容模板
• CSS 类和样式
• 以编程方式设置面板大小和位置

拖动和移动面板

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

• 启用或禁用拖动功能
• 自定义拖动手柄（draggableHandle）
• 面板碰撞检测和重新排序
• 拖动事件（dragStart、drag、dragStop）

以编程方式移动面板

📄 阅读： references/moving-panels.md

• 使用 movePanel() 方法以编程方式定位面板
• 交换面板并重新组织布局
• 基于优先级和列的排列
• 还原已保存的布局配置

调整面板大小

📄 阅读： references/resizing-panels.md

• 启用或禁用调整大小功能
• 可配置的调整大小手柄（e-south-east、e-east、e-west、e-north、e-south）
• 调整大小事件及事件参数
• 使用 resizePanel() 方法以编程方式调整大小

面板操作

📄 阅读： references/panel-manipulation.md

• 使用 addPanel() 动态添加面板
• 使用 removePanel() 移除面板
• 使用 removeAll() 移除所有面板
• 使用 serialize() 序列化面板布局

浮动和响应式布局

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

• 启用浮动以自动填充空白区域
• 使用媒体查询实现响应式堆叠行为
• 配置单元格宽高比
• 适配不同屏幕尺寸的布局

持久化和状态管理

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

• 使用 serialize() 保存布局配置
• 从已保存的状态还原布局
• 使用 enablePersistence 持久化状态
• 集成 localStorage 以支持浏览器会话

事件处理

📄 阅读： references/events-handling.md

• 生命周期事件（created、destroyed）
• 携带 DragStartArgs、DraggedEventArgs、DragStopArgs 的拖动事件
• 携带 ResizeArgs 的调整大小事件
• 面板位置更新的 Change 事件

完整 API 参考

📄 阅读： references/api-reference.md

• 所有 DashboardLayout 属性及其用法
• 所有 Panel 属性和配置选项
• 带参数的完整事件签名
• 所有方法及其参数和示例
• 类型定义和枚举

快速开始

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

// Initialize Dashboard Layout with 5 columns
let dashboard: DashboardLayout = 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>' 
        }
    ]
});

// Render to container
dashboard.appendTo('#dashboard_layout');

常见模式

模式 1：启用完整交互功能

const dashboard = new DashboardLayout({
    allowDragging: true,      // Enable drag and reorder
    allowResizing: true,       // Enable resize
    allowFloating: true,       // Auto-fill empty spaces
    cellSpacing: [10, 10],
    columns: 6,
    panels: [
        { 'sizeX': 2, 'sizeY': 2, 'row': 0, 'col': 0, content: '<div>Widget 1</div>' },
        { 'sizeX': 2, 'sizeY': 2, 'row': 0, 'col': 2, content: '<div>Widget 2</div>' }
    ]
});
dashboard.appendTo('#dashboard');

模式 2：处理拖动事件

const dashboard = new DashboardLayout({
    columns: 5,
    dragStart: (args) => console.log('Drag started on panel:', args.element),
    drag: (args) => console.log('Dragging panel...'),
    dragStop: (args) => {
        console.log('Drag completed. Modified panels:', args.panels);
    },
    panels: [...] // panel configuration
});
dashboard.appendTo('#dashboard');

模式 3：保存和还原布局

const dashboard = new DashboardLayout({
    columns: 5,
    panels: [...]
});
dashboard.appendTo('#dashboard');

// Save current layout
const savedLayout = dashboard.serialize();

// Later: Restore layout
dashboard.panels = savedLayout;

模式 4：响应式仪表板

const dashboard = new DashboardLayout({
    columns: 6,
    mediaQuery: '(max-width: 600px)',  // Stack panels below 600px
    enablePersistence: true,            // Remember user layout
    panels: [...]
});
dashboard.appendTo('#dashboard');

核心概念

网格系统

• 使用 row、col、sizeX 和 sizeY 在网格上定位面板
• columns 定义可用网格列的总数
• cellSpacing 控制面板之间的水平和垂直间距

面板尺寸

• sizeX：网格单元格宽度（例如，sizeX: 2 表示占 2 列）
• sizeY：网格单元格高度
• minSizeX/maxSizeX 和 minSizeY/maxSizeY：限制调整尺寸的操作

交互

• 拖动：当 allowDragging = true 时，可重新排列面板
• 调整尺寸：使用手柄调整面板尺寸（e-south-east、e-east 等）
• 浮动：当 allowFloating = true 时，面板会移动以填充空单元格

事件

• dragStart/drag/dragStop：监控和控制拖动操作
• resizeStart/resize/resizeStop：监控和控制尺寸调整操作
• change：面板位置更新时触发
• created/destroyed：生命周期事件

何时使用 DashboardLayout

✅ 非常适合：

• 分析和报告仪表板
• 可自定义的小组件布局
• 数据监控界面
• 用户可配置的 UI 布局
• 实时数据可视化中心

❌ 不太适合：

• 静态、固定布局
• 简单的页面布局（使用 CSS Grid 或 Flexbox）
• 单列布局

---

后续步骤：

1. 从导航指南中选择你的使用场景
2. 阅读相关参考文件
3. 查看 API 参考，了解完整的属性和方法文档
4. 查看适用于你具体场景的代码示例

完整的 API 文档请参阅 references/api-reference.md。