syncfusion-react-dashboard-layout

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion React Dashboard Layout

实现Syncfusion React Dashboard Layout

Syncfusion React Dashboard Layout is a powerful component for building responsive, interactive dashboard interfaces with draggable and resizable panels. It provides a flexible grid-based system for organizing content, automatic floating arrangement, and comprehensive state management.
Key Capabilities:
  • Multi-column grid layouts with flexible cell sizing
  • Drag-and-drop panel repositioning
  • Resizable panels with size constraints
  • Automatic floating arrangement (fills empty spaces)
  • Responsive design with media queries
  • Dynamic panel add/remove/update operations
  • State persistence across sessions
  • Comprehensive event system for monitoring changes
  • Accessibility support and RTL rendering
Syncfusion React Dashboard Layout是一款功能强大的组件,可用于构建带可拖拽、可调整大小面板的响应式交互式仪表板界面。它提供了灵活的基于网格的内容组织系统、自动浮动排列能力和完善的状态管理功能。
核心能力:
  • 支持灵活单元格尺寸的多列网格布局
  • 拖拽式面板重定位
  • 带尺寸约束的可调整大小面板
  • 自动浮动排列(自动填充空白区域)
  • 基于媒体查询的响应式设计
  • 动态面板增/删/改操作
  • 跨会话状态持久化
  • 用于监控变更的完善事件系统
  • 无障碍支持和RTL渲染

Documentation and Navigation Guide

文档与导航指南

Choose the reference that matches your current task:
选择与你当前任务匹配的参考内容:

🚀 Getting Started

🚀 快速开始

📄 Read: references/getting-started.md
  • Installation and package setup
  • CSS theme imports and configuration
  • Creating your first dashboard
  • Basic panel implementation
  • Common setup issues and solutions
📄 阅读: references/getting-started.md
  • 安装与包配置
  • CSS主题导入与配置
  • 创建你的第一个仪表板
  • 基础面板实现
  • 常见配置问题与解决方案

🎯 Core Concepts

🎯 核心概念

📄 Read: references/core-functionality.md
  • Panel creation and configuration (PanelModel interface)
  • Basic dragging and positioning
  • Basic resizing with constraints
  • Grid configuration fundamentals
  • Complete component overview
📄 Read: references/properties-reference.md
  • All 15 component properties documented
  • Layout properties (columns, cellSpacing, cellAspectRatio)
  • Customization options (enableRtl, enablePersistence, showGridLines)
  • Advanced properties (mediaQuery, draggableHandle, resizableHandles)
  • Complete property reference with patterns
📄 阅读: references/core-functionality.md
  • 面板创建与配置(PanelModel接口)
  • 基础拖拽与定位
  • 带约束的基础尺寸调整
  • 网格配置基础
  • 完整组件概览
📄 阅读: references/properties-reference.md
  • 全部15个组件属性文档
  • 布局属性(columns、cellSpacing、cellAspectRatio)
  • 自定义选项(enableRtl、enablePersistence、showGridLines)
  • 高级属性(mediaQuery、draggableHandle、resizableHandles)
  • 带示例的完整属性参考

🎨 User Interface & Customization

🎨 用户界面与自定义

📄 Read: references/panel-templates.md
  • Panel structure and composition
  • Header templates (text, HTML, interactive)
  • Content templates (HTML strings, JSX, Syncfusion components)
  • Embedding charts, grids, and widgets
  • Dynamic content updates
  • Template best practices and optimization
📄 Read: references/styling-customization.md
  • Complete CSS selector reference
  • Theme system integration (Tailwind, Bootstrap, Material, Fluent)
  • Header and content area styling
  • Resize handle styling and customization
  • Panel backgrounds, borders, and gradients
  • Dragging and interaction state styling
  • Advanced customization patterns
📄 阅读: references/panel-templates.md
  • 面板结构与组成
  • 头部模板(文本、HTML、交互式)
  • 内容模板(HTML字符串、JSX、Syncfusion组件)
  • 嵌入图表、网格和小组件
  • 动态内容更新
  • 模板最佳实践与优化
📄 阅读: references/styling-customization.md
  • 完整CSS选择器参考
  • 主题系统集成(Tailwind、Bootstrap、Material、Fluent)
  • 头部与内容区域样式
  • 尺寸调整手柄样式与自定义
  • 面板背景、边框与渐变
  • 拖拽与交互状态样式
  • 高级自定义模式

🎮 Interaction & Behavior

🎮 交互与行为

📄 Read: references/dragging-behavior.md
  • Enable and configure drag functionality
  • Drag events (dragStart, drag, dragStop)
  • Collision detection and panel pushing
  • Custom drag handles (header-only, icon-only, multiple)
  • Preventing specific panels from dragging
  • Visual feedback and placeholder styling
  • Programmatic panel movement
  • Undo/redo implementation
📄 Read: references/resizing-floating.md
  • Enable and configure resize functionality
  • Resize handle directions (SE, E, W, N, S, NW, NE, SW)
  • Size constraints (minSizeX, minSizeY, maxSizeX, maxSizeY)
  • Resize events (resizeStart, resize, resizeStop)
  • Floating behavior and gap filling
  • Programmatic resizing (resizePanel method)
  • Responsive resizing and aspect ratio maintenance
  • Best practices for resizing
📄 阅读: references/dragging-behavior.md
  • 启用与配置拖拽功能
  • 拖拽事件(dragStart、drag、dragStop)
  • 碰撞检测与面板推送
  • 自定义拖拽手柄(仅头部、仅图标、多个)
  • 禁止特定面板拖拽
  • 视觉反馈与占位符样式
  • 程序化面板移动
  • 撤销/重做实现
📄 阅读: references/resizing-floating.md
  • 启用与配置尺寸调整功能
  • 尺寸调整手柄方向(SE、E、W、N、S、NW、NE、SW)
  • 尺寸约束(minSizeX、minSizeY、maxSizeX、maxSizeY)
  • 尺寸调整事件(resizeStart、resize、resizeStop)
  • 浮动行为与空白填充
  • 程序化尺寸调整(resizePanel方法)
  • 响应式尺寸调整与宽高比维护
  • 尺寸调整最佳实践

⚙️ Configuration & Layout

⚙️ 配置与布局

📄 Read: references/cell-configuration.md
  • Grid columns and cell distribution
  • Cell sizing basics (sizeX, sizeY)
  • Cell aspect ratio configuration
  • Cell spacing and gap management
  • Cell calculation examples
  • Responsive cell configuration
  • Masonry, hero, and nested grid patterns
📄 Read: references/responsive-design.md
  • Built-in responsive behavior
  • Media query configuration and custom breakpoints
  • Standard breakpoint systems
  • Adaptive layouts for different screen sizes
  • Mobile-first approach
  • Touch device support and optimization
  • Testing responsive layouts
  • Performance optimization for responsiveness
📄 阅读: references/cell-configuration.md
  • 网格列与单元格分布
  • 单元格尺寸基础(sizeX、sizeY)
  • 单元格宽高比配置
  • 单元格间距与间隙管理
  • 单元格计算示例
  • 响应式单元格配置
  • 瀑布流、Hero区和嵌套网格模式
📄 阅读: references/responsive-design.md
  • 内置响应式行为
  • 媒体查询配置与自定义断点
  • 标准断点系统
  • 适配不同屏幕尺寸的自适应布局
  • 移动端优先方案
  • 触摸设备支持与优化
  • 响应式布局测试
  • 响应式性能优化

💾 Advanced Features

💾 高级特性

📄 Read: references/state-persistence.md
  • Serialize method for saving layout
  • Save/restore state patterns
  • localStorage integration
  • sessionStorage integration
  • Database API integration
  • Advanced state management (Redux, Context API)
  • Versioning and migration
  • Error recovery and backups
📄 Read: references/methods-reference.md
  • All 9 component methods documented
  • Panel management: addPanel, removePanel, removeAll, updatePanel
  • Layout manipulation: movePanel, resizePanel
  • Serialization: serialize method
  • Utility methods: refreshDraggableHandle, destroy
  • Complete method examples and use cases
📄 Read: references/events-reference.md
  • All 10 component events documented
  • Lifecycle events: created, destroyed
  • Interaction events: dragStart, drag, dragStop, resizeStart, resize, resizeStop
  • Change event: monitoring panel additions, removals, position changes
  • Event arguments and properties
  • Complete event handling patterns
📄 阅读: references/state-persistence.md
  • 用于保存布局的serialize方法
  • 保存/恢复状态模式
  • localStorage集成
  • sessionStorage集成
  • 数据库API集成
  • 高级状态管理(Redux、Context API)
  • 版本控制与迁移
  • 错误恢复与备份
📄 阅读: references/methods-reference.md
  • 全部9个组件方法文档
  • 面板管理:addPanel、removePanel、removeAll、updatePanel
  • 布局操作:movePanel、resizePanel
  • 序列化:serialize方法
  • 工具方法:refreshDraggableHandle、destroy
  • 完整方法示例与使用场景
📄 阅读: references/events-reference.md
  • 全部10个组件事件文档
  • 生命周期事件:created、destroyed
  • 交互事件:dragStart、drag、dragStop、resizeStart、resize、resizeStop
  • 变更事件:监控面板新增、删除、位置变更
  • 事件参数与属性
  • 完整事件处理模式

♿ Compliance & Accessibility

♿ 合规与无障碍

📄 Read: references/accessibility-wcag.md
  • WCAG 2.2 Level AA compliance
  • Section 508 standards compliance
  • WAI-ARIA implementation (roles, properties, states)
  • Keyboard navigation and accessibility
  • Screen reader support
  • RTL (right-to-left) language support
  • Testing and validation procedures
  • Accessibility audit checklist
📄 阅读: references/accessibility-wcag.md
  • WCAG 2.2 Level AA合规
  • 第508节标准合规
  • WAI-ARIA实现(角色、属性、状态)
  • 键盘导航与无障碍支持
  • 屏幕阅读器支持
  • RTL(从右到左)语言支持
  • 测试与验证流程
  • 无障碍审计检查清单

Quick Start Example

快速开始示例

Create an interactive dashboard in minutes:
tsx
import React, { useRef } from 'react';
import { DashboardLayoutComponent } from '@syncfusion/ej2-react-layouts';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-layouts/styles/tailwind3.css';

function Dashboard() {
  const dashboardRef = useRef<DashboardLayoutComponent>(null);

  const panels = [
    {
      id: 'sales',
      header: 'Sales',
      content: '<div style="padding: 20px;">Sales data</div>',
      row: 0,
      col: 0,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'users',
      header: 'Users',
      content: '<div style="padding: 20px;">User analytics</div>',
      row: 0,
      col: 2,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'reports',
      header: 'Reports',
      content: '<div style="padding: 20px;">Report metrics</div>',
      row: 2,
      col: 0,
      sizeX: 4,
      sizeY: 1
    }
  ];

  return (
    <div style={{ padding: '20px' }}>
      <h1>Dashboard</h1>
      <DashboardLayoutComponent
        ref={dashboardRef}
        id='dashboard'
        columns={5}
        cellSpacing={[10, 10]}
        panels={panels}
        allowDragging={true}
        allowResizing={true}
        allowFloating={true}
        enablePersistence={true}
      >
      </DashboardLayoutComponent>
    </div>
  );
}

export default Dashboard;
几分钟内创建一个交互式仪表板:
tsx
import React, { useRef } from 'react';
import { DashboardLayoutComponent } from '@syncfusion/ej2-react-layouts';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-layouts/styles/tailwind3.css';

function Dashboard() {
  const dashboardRef = useRef<DashboardLayoutComponent>(null);

  const panels = [
    {
      id: 'sales',
      header: 'Sales',
      content: '<div style="padding: 20px;">Sales data</div>',
      row: 0,
      col: 0,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'users',
      header: 'Users',
      content: '<div style="padding: 20px;">User analytics</div>',
      row: 0,
      col: 2,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'reports',
      header: 'Reports',
      content: '<div style="padding: 20px;">Report metrics</div>',
      row: 2,
      col: 0,
      sizeX: 4,
      sizeY: 1
    }
  ];

  return (
    <div style={{ padding: '20px' }}>
      <h1>Dashboard</h1>
      <DashboardLayoutComponent
        ref={dashboardRef}
        id='dashboard'
        columns={5}
        cellSpacing={[10, 10]}
        panels={panels}
        allowDragging={true}
        allowResizing={true}
        allowFloating={true}
        enablePersistence={true}
      >
      </DashboardLayoutComponent>
    </div>
  );
}

export default Dashboard;

Common Patterns

常用模式

Pattern 1: Responsive Dashboard with Mobile Support

模式1:支持移动端的响应式仪表板

📖 Read: responsive-design.md for comprehensive mobile adaptation patterns
tsx
<DashboardLayoutComponent
  id='responsive-dashboard'
  columns={5}
  mediaQuery='max-width:768px'  // Single column on tablets/mobile
  cellSpacing={[10, 10]}
  allowDragging={true}
  allowResizing={true}
  panels={panels}
>
</DashboardLayoutComponent>
Key Features:
  • Responsive column adjustment based on screen size
  • Mobile-first design with media queries
  • Touch optimization for mobile devices
  • See
    responsive-design.md
    for breakpoint configuration and testing
📖 阅读: responsive-design.md 了解完整的移动端适配模式
tsx
<DashboardLayoutComponent
  id='responsive-dashboard'
  columns={5}
  mediaQuery='max-width:768px'  // 平板/移动端下为单列布局
  cellSpacing={[10, 10]}
  allowDragging={true}
  allowResizing={true}
  panels={panels}
>
</DashboardLayoutComponent>
核心特性:
  • 基于屏幕尺寸的响应式列数调整
  • 基于媒体查询的移动端优先设计
  • 针对移动端的触摸优化
  • 查看
    responsive-design.md
    了解断点配置与测试方法

Pattern 2: Save and Restore User Layout

模式2:保存与恢复用户布局

📖 Read: state-persistence.md for complete state serialization and storage options
tsx
const handleSaveLayout = () => {
  const layout = dashboardRef.current?.serialize();
  localStorage.setItem('userDashboard', JSON.stringify(layout));
};

const handleRestoreLayout = () => {
  const saved = localStorage.getItem('userDashboard');
  if (saved) {
    const layout = JSON.parse(saved);
    dashboardRef.current?.removeAll();
    layout.forEach(panel => {
      dashboardRef.current?.addPanel(panel);
    });
  }
};
Key Features:
  • serialize() method exports current layout state
  • localStorage for client-side persistence
  • See
    state-persistence.md
    for API integration, Redux/Context patterns, and auto-save
📖 阅读: state-persistence.md 了解完整的状态序列化与存储选项
tsx
const handleSaveLayout = () => {
  const layout = dashboardRef.current?.serialize();
  localStorage.setItem('userDashboard', JSON.stringify(layout));
};

const handleRestoreLayout = () => {
  const saved = localStorage.getItem('userDashboard');
  if (saved) {
    const layout = JSON.parse(saved);
    dashboardRef.current?.removeAll();
    layout.forEach(panel => {
      dashboardRef.current?.addPanel(panel);
    });
  }
};
核心特性:
  • serialize()方法导出当前布局状态
  • 用localStorage实现客户端持久化
  • 查看
    state-persistence.md
    了解API集成、Redux/Context模式与自动保存功能

Pattern 3: Dynamic Panel Management

模式3:动态面板管理

📖 Read: core-functionality.md for panel addition/removal and runtime management
tsx
const handleAddPanel = () => {
  dashboardRef.current?.addPanel({
    id: `panel-${Date.now()}`,
    header: 'New Panel',
    content: 'Panel content',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1
  });
};

const handleRemovePanel = (panelId: string) => {
  dashboardRef.current?.removePanel(panelId);
};
Key Features:
  • Runtime panel creation and deletion
  • Unique panel IDs and positioning
  • Event handling for panel changes
  • See
    methods-reference.md
    for all available panel methods
📖 阅读: core-functionality.md 了解面板增删与运行时管理方法
tsx
const handleAddPanel = () => {
  dashboardRef.current?.addPanel({
    id: `panel-${Date.now()}`,
    header: 'New Panel',
    content: 'Panel content',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1
  });
};

const handleRemovePanel = (panelId: string) => {
  dashboardRef.current?.removePanel(panelId);
};
核心特性:
  • 运行时面板创建与删除
  • 唯一面板ID与定位
  • 面板变更事件处理
  • 查看
    methods-reference.md
    了解所有可用的面板方法

Pattern 4: Constrained Panel Sizes

模式4:约束面板尺寸

📖 Read: cell-configuration.md and resizing-floating.md for size constraints and resizing behavior
tsx
const constrainedPanels = [
  {
    id: 'fixed-panel',
    header: 'Fixed Size',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 2,  // Cannot shrink
    maxSizeX: 2,  // Cannot expand
    minSizeY: 1,
    maxSizeY: 1
  },
  {
    id: 'flexible-panel',
    header: 'Flexible',
    row: 0,
    col: 2,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 1,  // Can shrink to 1 cell
    maxSizeX: 4   // Can expand to 4 cells
  }
];
Key Features:
  • minSizeX/Y and maxSizeX/Y constraints
  • Fixed vs. flexible panel sizing
  • Programmatic size updates via resizePanel()
  • See
    cell-configuration.md
    for grid calculations and
    resizing-floating.md
    for advanced resize patterns
📖 阅读: cell-configuration.mdresizing-floating.md 了解尺寸约束与调整行为
tsx
const constrainedPanels = [
  {
    id: 'fixed-panel',
    header: 'Fixed Size',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 2,  // 不可缩小
    maxSizeX: 2,  // 不可放大
    minSizeY: 1,
    maxSizeY: 1
  },
  {
    id: 'flexible-panel',
    header: 'Flexible',
    row: 0,
    col: 2,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 1,  // 最小可缩小到1个单元格
    maxSizeX: 4   // 最大可放大到4个单元格
  }
];
核心特性:
  • minSizeX/Y和maxSizeX/Y约束
  • 固定与灵活面板尺寸
  • 通过resizePanel()实现程序化尺寸更新
  • 查看
    cell-configuration.md
    了解网格计算方法,查看
    resizing-floating.md
    了解高级尺寸调整模式

Pattern 5: Monitor Layout Changes

模式5:监控布局变更

📖 Read: events-reference.md for all available events and handlers
tsx
const handleChange = (args: ChangeEventArgs) => {
  console.log('Panels added:', args.addedPanels);
  console.log('Panels removed:', args.removedPanels);
  console.log('Panels position changed:', args.changedPanels);
  console.log('User interaction:', args.isInteracted);
};

<DashboardLayoutComponent
  panels={panels}
  change={handleChange}
>
</DashboardLayoutComponent>
Key Features:
  • Change event fires on any layout modification
  • Access to added, removed, and repositioned panels
  • User interaction detection
  • See
    events-reference.md
    for drag, resize, and other event handlers
📖 阅读: events-reference.md 了解所有可用事件与处理函数
tsx
const handleChange = (args: ChangeEventArgs) => {
  console.log('Panels added:', args.addedPanels);
  console.log('Panels removed:', args.removedPanels);
  console.log('Panels position changed:', args.changedPanels);
  console.log('User interaction:', args.isInteracted);
};

<DashboardLayoutComponent
  panels={panels}
  change={handleChange}
>
</DashboardLayoutComponent>
核心特性:
  • 任何布局修改都会触发change事件
  • 可获取新增、删除、重定位的面板信息
  • 用户交互检测
  • 查看
    events-reference.md
    了解拖拽、尺寸调整等其他事件处理方式

Key API Overview

核心API概览

Component Properties

组件属性

📖 Full Reference: properties-reference.md
  • columns - Number of grid columns (default: 1) → See
    cell-configuration.md
  • cellSpacing - Spacing between panels [horizontal, vertical] → See
    cell-configuration.md
  • panels - Array of PanelModel objects defining layout → See
    panel-templates.md
  • allowDragging - Enable panel drag-and-drop (default: true) → See
    dragging-behavior.md
  • allowResizing - Enable panel resizing (default: false) → See
    resizing-floating.md
  • allowFloating - Auto-fill empty spaces (default: true) → See
    resizing-floating.md
  • enablePersistence - Save layout state (default: false) → See
    state-persistence.md
  • mediaQuery - Responsive breakpoint for mobile layouts → See
    responsive-design.md
  • draggableHandle - Custom drag handle selector → See
    dragging-behavior.md
  • resizableHandles - Resize handle directions → See
    resizing-floating.md
  • cssClass - Custom CSS classes → See
    styling-customization.md
📖 完整参考: properties-reference.md
  • columns - 网格列数(默认:1)→ 查看
    cell-configuration.md
  • cellSpacing - 面板间距[水平, 垂直] → 查看
    cell-configuration.md
  • panels - 定义布局的PanelModel对象数组 → 查看
    panel-templates.md
  • allowDragging - 启用面板拖拽功能(默认:true)→ 查看
    dragging-behavior.md
  • allowResizing - 启用面板尺寸调整功能(默认:false)→ 查看
    resizing-floating.md
  • allowFloating - 自动填充空白区域(默认:true)→ 查看
    resizing-floating.md
  • enablePersistence - 保存布局状态(默认:false)→ 查看
    state-persistence.md
  • mediaQuery - 移动端布局响应式断点 → 查看
    responsive-design.md
  • draggableHandle - 自定义拖拽手柄选择器 → 查看
    dragging-behavior.md
  • resizableHandles - 尺寸调整手柄方向 → 查看
    resizing-floating.md
  • cssClass - 自定义CSS类 → 查看
    styling-customization.md

Core Methods

核心方法

📖 Full Reference: methods-reference.md
  • addPanel(panel) - Add new panel at runtime → See
    core-functionality.md
  • removePanel(id) - Remove panel by ID → See
    core-functionality.md
  • removeAll() - Clear all panels → See
    core-functionality.md
  • updatePanel(panel) - Modify existing panel → See
    core-functionality.md
  • movePanel(id, row, col) - Change panel position → See
    dragging-behavior.md
  • resizePanel(id, sizeX, sizeY) - Adjust panel dimensions → See
    resizing-floating.md
  • serialize() - Get current layout state → See
    state-persistence.md
📖 完整参考: methods-reference.md
  • addPanel(panel) - 运行时新增面板 → 查看
    core-functionality.md
  • removePanel(id) - 按ID删除面板 → 查看
    core-functionality.md
  • removeAll() - 清空所有面板 → 查看
    core-functionality.md
  • updatePanel(panel) - 修改现有面板 → 查看
    core-functionality.md
  • movePanel(id, row, col) - 修改面板位置 → 查看
    dragging-behavior.md
  • resizePanel(id, sizeX, sizeY) - 调整面板尺寸 → 查看
    resizing-floating.md
  • serialize() - 获取当前布局状态 → 查看
    state-persistence.md

Important Events

重要事件

📖 Full Reference: events-reference.md
  • created - Component initialized
  • dragStart / drag / dragStop - Drag operations → See
    dragging-behavior.md
  • resizeStart / resize / resizeStop - Resize operations → See
    resizing-floating.md
  • change - Layout changed (additions, removals, movements) → See
    events-reference.md
📖 完整参考: events-reference.md
  • created - 组件初始化完成
  • dragStart / drag / dragStop - 拖拽操作相关 → 查看
    dragging-behavior.md
  • resizeStart / resize / resizeStop - 尺寸调整操作相关 → 查看
    resizing-floating.md
  • change - 布局变更(新增、删除、移动)→ 查看
    events-reference.md

Styling & Customization

样式与自定义

📖 Full Reference: styling-customization.md
  • CSS selectors for all panel elements
  • Theme customization (Tailwind, Bootstrap, Material, Fluent)
  • Responsive styling patterns
  • Accessibility styling (WCAG 2.2)
📖 完整参考: styling-customization.md
  • 所有面板元素的CSS选择器
  • 主题自定义(Tailwind、Bootstrap、Material、Fluent)
  • 响应式样式模式
  • 无障碍样式(WCAG 2.2)

Common Use Cases

常见使用场景

🎯 Creating Dashboards: Implement customizable dashboard layouts with multiple content panels organized in a grid.
  • Read: core-functionality.md, panel-templates.md
🎯 User-Customizable Layouts: Allow users to rearrange and resize dashboard panels to their preference with automatic saving.
  • Read: dragging-behavior.md, resizing-floating.md, state-persistence.md
🎯 Responsive Interfaces: Build layouts that adapt from multi-column desktop views to single-column mobile views.
  • Read: responsive-design.md, cell-configuration.md
🎯 Real-Time Monitoring: Display multiple real-time data sources in resizable panels with live updates.
  • Read: panel-templates.md (component embedding), events-reference.md
🎯 Admin Panels: Create administrative interfaces with draggable widgets for system monitoring and control.
  • Read: dragging-behavior.md, styling-customization.md, accessibility-wcag.md
🎯 Data Visualization: Organize multiple charts, tables, and metrics in flexible, responsive panel layouts.
  • Read: panel-templates.md (embedding charts/grids), styling-customization.md
🎯 创建仪表板: 实现由网格中多个内容面板组成的可自定义仪表板布局
  • 阅读:core-functionality.mdpanel-templates.md
🎯 用户可自定义布局: 允许用户按偏好重排、调整仪表板面板尺寸并自动保存
  • 阅读:dragging-behavior.mdresizing-floating.mdstate-persistence.md
🎯 响应式界面: 构建可从多列桌面视图适配到单列移动端视图的布局
  • 阅读:responsive-design.mdcell-configuration.md
🎯 实时监控: 在可调整大小的面板中展示多个实时数据源并支持实时更新
  • 阅读:panel-templates.md(组件嵌入)、events-reference.md
🎯 管理后台面板: 创建带可拖拽小组件的管理界面,用于系统监控与控制
  • 阅读:dragging-behavior.mdstyling-customization.mdaccessibility-wcag.md
🎯 数据可视化: 在灵活响应的面板布局中组织多个图表、表格和指标
  • 阅读:panel-templates.md(嵌入图表/网格)、styling-customization.md

Panel Model Interface

Panel Model接口

typescript
interface PanelModel {
  id: string;              // Unique identifier (required)
  row: number;             // Row position (required)
  col: number;             // Column position (required)
  sizeX: number;           // Width in cells (default: 1)
  sizeY: number;           // Height in cells (default: 1)
  header?: string | HTMLElement | Function;
  content?: string | HTMLElement | Function;
  cssClass?: string;       // Custom CSS classes
  enabled?: boolean;       // Enable/disable (default: true)
  minSizeX?: number;       // Minimum width (default: 1)
  minSizeY?: number;       // Minimum height (default: 1)
  maxSizeX?: number;       // Maximum width
  maxSizeY?: number;       // Maximum height
  zIndex?: number;         // Stacking order
}
typescript
interface PanelModel {
  id: string;              // 唯一标识符(必填)
  row: number;             // 行位置(必填)
  col: number;             // 列位置(必填)
  sizeX: number;           // 宽度(单元格数,默认:1)
  sizeY: number;           // 高度(单元格数,默认:1)
  header?: string | HTMLElement | Function;
  content?: string | HTMLElement | Function;
  cssClass?: string;       // 自定义CSS类
  enabled?: boolean;       // 启用/禁用(默认:true)
  minSizeX?: number;       // 最小宽度(默认:1)
  minSizeY?: number;       // 最小高度(默认:1)
  maxSizeX?: number;       // 最大宽度
  maxSizeY?: number;       // 最大高度
  zIndex?: number;         // 堆叠顺序
}

Quick Reference Guide

快速参考指南

TaskRead This Documentation
Get Startedgetting-started.md - Installation, setup, themes
Learn Panel Managementcore-functionality.md - Create, update, remove panels
Customize Panel Contentpanel-templates.md - Headers, templates, component embedding
Make It Draggabledragging-behavior.md - Drag events, collision, custom handles
Make It Resizableresizing-floating.md - Resize handles, constraints, floating
Configure Grid Systemcell-configuration.md - Columns, spacing, aspect ratio, responsive grids
Make It Responsiveresponsive-design.md - Breakpoints, mobile, touch optimization
Save User Layoutsstate-persistence.md - serialize(), localStorage, API, Redux, Context
Style & Themestyling-customization.md - CSS selectors, themes, responsive styling
Make It Accessibleaccessibility-wcag.md - WCAG 2.2, WAI-ARIA, screen readers, RTL
API Referenceproperties-reference.md, methods-reference.md, events-reference.md
Advanced Patternsadvanced-features.md - Custom integrations, performance optimization
任务参考文档
快速上手getting-started.md - 安装、配置、主题
学习面板管理core-functionality.md - 创建、更新、删除面板
自定义面板内容panel-templates.md - 头部、模板、组件嵌入
实现拖拽功能dragging-behavior.md - 拖拽事件、碰撞、自定义手柄
实现尺寸调整resizing-floating.md - 尺寸调整手柄、约束、浮动
配置网格系统cell-configuration.md - 列数、间距、宽高比、响应式网格
实现响应式适配responsive-design.md - 断点、移动端、触摸优化
保存用户布局state-persistence.md - serialize()、localStorage、API、Redux、Context
样式与主题styling-customization.md - CSS选择器、主题、响应式样式
实现无障碍支持accessibility-wcag.md - WCAG 2.2、WAI-ARIA、屏幕阅读器、RTL
API参考properties-reference.mdmethods-reference.mdevents-reference.md
高级模式advanced-features.md - 自定义集成、性能优化

Implementation Roadmap

实施路线图

Phase 1 - Foundation (Start Here):
  1. Read getting-started.md for setup
  2. Review core-functionality.md for panel basics
  3. Check properties-reference.md for all available options
Phase 2 - Interaction (Build Functionality): 4. Implement dragging: dragging-behavior.md 5. Implement resizing: resizing-floating.md 6. Configure grid: cell-configuration.md
Phase 3 - Content (Customize Visuals): 7. Create panel templates: panel-templates.md 8. Apply styling: styling-customization.md
Phase 4 - Polish (Production Ready): 9. Optimize for mobile: responsive-design.md 10. Add accessibility: accessibility-wcag.md 11. Implement persistence: state-persistence.md
Phase 5 - Advanced (Expert Features): 12. Explore patterns: advanced-features.md 13. Refer to event/method APIs: events-reference.md, methods-reference.md
阶段1 - 基础(从这里开始):
  1. 阅读getting-started.md完成配置
  2. 查看core-functionality.md学习面板基础
  3. 查阅properties-reference.md了解所有可用选项
阶段2 - 交互(构建功能): 4. 实现拖拽功能:dragging-behavior.md 5. 实现尺寸调整功能:resizing-floating.md 6. 配置网格:cell-configuration.md
阶段3 - 内容(自定义视觉效果): 7. 创建面板模板:panel-templates.md 8. 应用样式:styling-customization.md
阶段4 - 打磨(生产就绪): 9. 移动端优化:responsive-design.md 10. 添加无障碍支持:accessibility-wcag.md 11. 实现持久化:state-persistence.md
阶段5 - 高级(专家特性): 12. 探索模式:advanced-features.md 13. 参考事件/方法API:events-reference.mdmethods-reference.md