creating-dashboards

创建仪表板

用途

此技能可用于创建精致的仪表板界面，通过协调的组件汇总并呈现数据，包括 KPI 卡片、图表、表格和筛选器。仪表板是集中式的数据驱动决策中心，可将其他技能（data-viz、tables、design-tokens）中的多种组件整合为统一的分析体验，并支持实时更新、响应式布局和交互式筛选。

适用场景

在以下场景中启用此技能：

• 构建商业智能或分析仪表板
• 创建高管报告界面
• 实现实时监控系统
• 设计展示指标和趋势的 KPI 面板
• 开发可自定义的组件布局
• 协调多个数据展示区域的筛选器
• 构建响应式数据密集型界面
• 实现拖放式仪表板编辑器
• 创建基于模板的分析系统
• 设计多租户 SaaS 仪表板

仪表板核心元素

KPI 卡片结构

┌────────────────────────────┐
│ Revenue (This Month)       │ ← Label with time period
│                            │
│  $1,245,832               │ ← Big number (primary metric)
│  ↑ 15.3% vs last month    │ ← Trend indicator with comparison
│  ▂▃▅▆▇█ (sparkline)       │ ← Mini visualization
└────────────────────────────┘

组件容器结构

• 标题栏，包含组件名称和操作
• 加载状态（骨架屏或旋转指示器）
• 错误边界，提供重试选项
• 用于调整布局的大小调整手柄
• 设置菜单（导出、配置、刷新）

仪表板布局类型

固定布局：由设计者定义位置，所有用户看到的布局一致 可自定义网格：用户可拖放组件、调整大小并保存布局 基于模板：预先构建的模式和特定行业的起始布局

仪表板全局控件

• 日期范围选择器（影响所有组件）
• 筛选器面板（在各组件间协调筛选）
• 刷新控件（手动刷新/自动刷新）
• 导出操作（PDF、图像、数据）
• 主题切换器（浅色/深色/自定义）

实现方法

1. 选择仪表板架构

快速分析仪表板 → 使用 Tremor 提供预构建的 KPI 卡片、图表和表格，只需极少代码：

npm install @tremor/react

可自定义仪表板 → 使用 react-grid-layout 支持拖放、可调整大小的组件和用户自定义布局：

npm install react-grid-layout

2. 设置全局状态管理

实现筛选器上下文，以协调各组件：

// Dashboard context for shared filters
const DashboardContext = createContext({
  filters: { dateRange: null, categories: [] },
  setFilters: () => {},
  refreshInterval: 30000
});

// Wrap dashboard with provider
<DashboardContext.Provider value={dashboardState}>
  <FilterPanel />
  <WidgetGrid />
</DashboardContext.Provider>

3. 实现数据获取策略

并行加载：同时获取所有组件的数据 延迟加载：优先加载可见组件，其他组件在滚动时加载 缓存更新：获取新数据期间从缓存提供数据

4. 配置实时更新

服务器发送事件（推荐用于仪表板）：

const eventSource = new EventSource('/api/dashboard/stream');
eventSource.onmessage = (event) => {
  const update = JSON.parse(event.data);
  updateWidget(update.widgetId, update.data);
};

5. 应用响应式设计

为不同屏幕尺寸定义断点：

• 桌面端（>1200px）：多列网格
• 平板端（768-1200px）：两列布局
• 移动端（<768px）：单列堆叠布局

使用 Tremor 快速入门

基础 KPI 仪表板

import { Card, Grid, Metric, Text, BadgeDelta, AreaChart } from '@tremor/react';

function QuickDashboard({ data }) {
  return (
    <Grid numItems={1} numItemsSm={2} numItemsLg={4} className="gap-4">
      {/* KPI Cards */}
      <Card>
        <Text>Total Revenue</Text>
        <Metric>$45,231.89</Metric>
        <BadgeDelta deltaType="increase">+12.5%</BadgeDelta>
      </Card>

      <Card>
        <Text>Active Users</Text>
        <Metric>1,234</Metric>
        <BadgeDelta deltaType="decrease">-2.3%</BadgeDelta>
      </Card>

      {/* Chart Widget */}
      <Card className="lg:col-span-2">
        <Text>Revenue Trend</Text>
        <AreaChart
          data={data.revenue}
          index="date"
          categories={["revenue"]}
          valueFormatter={(value) => `$${value.toLocaleString()}`}
        />
      </Card>
    </Grid>
  );
}

完整实现请参阅 examples/tremor-dashboard.tsx。

可自定义仪表板实现

拖放式网格布局

import { Responsive, WidthProvider } from 'react-grid-layout';
import 'react-grid-layout/css/styles.css';

const ResponsiveGridLayout = WidthProvider(Responsive);

function CustomizableDashboard() {
  const [layouts, setLayouts] = useState(getStoredLayouts());

  return (
    <ResponsiveGridLayout
      layouts={layouts}
      breakpoints={{ lg: 1200, md: 996, sm: 768 }}
      cols={{ lg: 12, md: 10, sm: 6 }}
      rowHeight={60}
      onLayoutChange={(layout, layouts) => {
        setLayouts(layouts);
        localStorage.setItem('dashboardLayout', JSON.stringify(layouts));
      }}
      draggableHandle=".widget-header"
    >
      <div key="kpi1">
        <KPIWidget data={kpiData} />
      </div>
      <div key="chart1">
        <ChartWidget data={chartData} />
      </div>
      <div key="table1">
        <TableWidget data={tableData} />
      </div>
    </ResponsiveGridLayout>
  );
}

包含组件目录的完整示例请参阅 examples/customizable-dashboard.tsx。

实时数据模式

服务器发送事件（推荐）

最适合从服务器向仪表板进行单向更新：

function useSSEUpdates(endpoint) {
  useEffect(() => {
    const eventSource = new EventSource(endpoint);

    eventSource.onmessage = (event) => {
      const update = JSON.parse(event.data);
      // Update specific widget or all widgets
      dispatch({ type: 'UPDATE_WIDGET', payload: update });
    };

    return () => eventSource.close();
  }, [endpoint]);
}

WebSocket（用于双向通信）

当仪表板需要向服务器发送命令时使用：

const ws = new WebSocket('ws://localhost:3000/dashboard');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  updateDashboard(data);
};
// Send filter changes to server
ws.send(JSON.stringify({ type: 'FILTER_CHANGE', filters }));

智能轮询备用方案

适用于不支持 WebSocket/SSE 的环境：

function useSmartPolling(fetchData, interval = 30000) {
  const [isPaused, setIsPaused] = useState(false);

  useEffect(() => {
    if (isPaused || document.hidden) return;

    const timer = setInterval(fetchData, interval);
    return () => clearInterval(timer);
  }, [isPaused, interval]);

  // Pause when tab inactive
  useEffect(() => {
    const handleVisibilityChange = () => {
      setIsPaused(document.hidden);
    };
    document.addEventListener('visibilitychange', handleVisibilityChange);
    return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
  }, []);
}

有关错误处理和重新连接等详细模式，请参阅 references/real-time-updates.md。

性能优化

延迟加载策略

function DashboardGrid({ widgets }) {
  const [visibleWidgets, setVisibleWidgets] = useState(new Set());

  return widgets.map(widget => (
    <LazyLoad
      key={widget.id}
      height={widget.height}
      offset={100}
      once
      placeholder={<WidgetSkeleton />}
    >
      <Widget {...widget} />
    </LazyLoad>
  ));
}

并行数据获取

// Fetch all widget data simultaneously
const loadDashboard = async () => {
  const [kpis, charts, tables] = await Promise.all([
    fetchKPIs(),
    fetchChartData(),
    fetchTableData()
  ]);

  return { kpis, charts, tables };
};

组件级缓存

function CachedWidget({ id, fetcher, ttl = 60000 }) {
  const cache = useRef({ data: null, timestamp: 0 });

  const getData = async () => {
    const now = Date.now();
    if (cache.current.data && now - cache.current.timestamp < ttl) {
      return cache.current.data;
    }

    const fresh = await fetcher();
    cache.current = { data: fresh, timestamp: now };
    return fresh;
  };

  // Use cached data while fetching fresh
  return <Widget data={cache.current.data} onRefresh={getData} />;
}

如需分析并优化仪表板性能，请运行：

python scripts/optimize-dashboard-performance.py --analyze dashboard-config.json

跨技能集成

使用数据可视化组件

图表组件请参考 data-viz 技能：

// Use charts from data-viz skill
import { createChart } from '../data-viz/chart-factory';

const revenueChart = createChart('area', {
  data: revenueData,
  xAxis: 'date',
  yAxis: 'revenue',
  theme: dashboardTheme
});

集成数据表格

数据网格请参考 tables 技能：

// Use advanced tables from tables skill
import { DataGrid } from '../tables/data-grid';

<DataGrid
  data={transactions}
  columns={columnDefs}
  pagination={true}
  sorting={true}
  filtering={true}
/>

应用设计令牌

使用 design-tokens 技能实现一致的主题：

// Dashboard-specific tokens from design-tokens skill
const dashboardTokens = {
  '--dashboard-bg': 'var(--color-bg-secondary)',
  '--widget-bg': 'var(--color-white)',
  '--widget-shadow': 'var(--shadow-lg)',
  '--kpi-value-size': 'var(--font-size-4xl)',
  '--kpi-trend-positive': 'var(--color-success)',
  '--kpi-trend-negative': 'var(--color-error)'
};

筛选输入组件

可选使用 forms skill 配置筛选控件：

// Advanced filter inputs from forms skill
import { DateRangePicker, MultiSelect } from '../forms/inputs';

<FilterPanel>
  <DateRangePicker onChange={handleDateChange} />
  <MultiSelect options={categories} onChange={handleCategoryFilter} />
</FilterPanel>

库选择指南

适合选择 Tremor 的情况：

• 需要快速构建仪表板
• 希望使用预设样式、专业的组件
• 项目使用 Tailwind CSS
• 构建标准分析界面
• 定制需求有限

适合选择 react-grid-layout 的情况：

• 用户需要自定义布局
• 需要拖放功能
• 不同用户需要不同视图
• 构建仪表板编辑器工具
• 灵活性是首要考虑因素

适合两者结合使用的情况：

• 使用 Tremor 构建微件内容（KPI、图表）
• 使用 react-grid-layout 管理布局
• 兼得两者的优势

捆绑资源

脚本（无令牌执行）

• scripts/generate-dashboard-layout.py - 生成响应式网格配置
• scripts/calculate-kpi-metrics.py - 计算趋势、对比和迷你图
• scripts/validate-widget-config.py - 验证微件和筛选器配置
• scripts/optimize-dashboard-performance.py - 分析并优化性能
• scripts/export-dashboard.py - 将仪表板导出为多种格式

无需将脚本加载到上下文中即可直接运行：

python scripts/calculate-kpi-metrics.py --data metrics.json --period monthly

参考资料（详细模式）

• references/kpi-card-patterns.md - KPI 卡片设计模式和变体
• references/layout-strategies.md - 网格系统和响应式方案
• references/real-time-updates.md - WebSocket、SSE 和轮询实现
• references/filter-coordination.md - 微件间筛选器同步
• references/performance-optimization.md - 高级优化技巧
• references/library-guide.md - Tremor 和 react-grid-layout 详细指南

示例（完整实现）

• examples/sales-dashboard.tsx - 完整的销售分析仪表板
• examples/monitoring-dashboard.tsx - 带告警的实时监控
• examples/executive-dashboard.tsx - 精致的高管报告
• examples/customizable-dashboard.tsx - 支持拖放和持久化
• examples/tremor-dashboard.tsx - 快速实现 Tremor
• examples/filter-context.tsx - 全局筛选器协调

资源文件（模板和配置）

• assets/dashboard-templates.json - 预构建的仪表板布局
• assets/widget-library.json - 微件目录和配置
• assets/grid-layouts.json - 响应式网格配置
• assets/kpi-formats.json - 数字格式规则
• assets/theme-tokens.json - 仪表板专用设计令牌

仪表板创建工作流

1. 定义需求：固定布局还是可自定义？实时还是静态？
2. 选择库：快速构建选 Tremor，灵活布局选 react-grid-layout
3. 搭建结构：全局状态、筛选器上下文、布局系统
4. 构建微件：KPI 卡片、图表（data-viz）、表格（tables skill）
5. 实现数据流：获取策略、缓存、更新
6. 添加交互功能：筛选器、下钻、导出
7. 优化性能：延迟加载、并行获取、缓存
8. 应用主题：使用 design-tokens 保持样式一致
9. 测试响应式布局：桌面、平板、移动设备断点
10. 部署和监控：跟踪性能和用户参与度

如需了解特定模式和详细实现，请查看上述捆绑资源。