sggk-charts

面向业务场景的 React 图表组件库。

安装

pnpm add sggk-charts react react-dom

使用

import {Gantt, GanttLegend, GanttPanel} from 'sggk-charts';
import 'sggk-charts/style.css';

图表类型

排程类图表

甘特图（Gantt）

数据格式

export interface GanttTask {
  taskId: string;
  title: string;
  start: string | number | Date;
  end: string | number | Date;
  status: string;
  progress?: number;
  owner?: string;
  draggable?: boolean;
  meta?: Record<string, unknown>;
}

export interface GanttRow {
  rowId: string;
  name?: string;
  code?: string;
  tasks: GanttTask[];
  meta?: Record<string, unknown>;
}

export interface TimelineConfig {
  timelineStart: string | number | Date;
  timelineEnd: string | number | Date;
  pxPerHour?: number;
  shiftHours?: number;
  shifts?: string[];
  snapHours?: number;
}

核心能力

• 默认支持横向 + 纵向拖拽，可通过 enableVerticalDrag={false} 关闭纵向拖拽。
• 默认所有状态可拖拽，可通过 task.draggable 或 statusMap[status].draggable 禁止。
• 支持 onTaskClick，拖拽释放后不会误触发点击。
• 支持原生 tooltip 开关（showNativeTooltip）和自定义 tooltip 位置（tooltipPlacement）。
• 支持固定任务长度（fixedTaskHours，单位小时）。
• 支持时间线缩放（enableTimelineZoom），默认任务块宽度不随缩放变化（keepTaskSizeOnTimelineZoom=true）。
• 当 showShiftRow={false} 时，日期表头高度自动与时间线行高一致。
• 支持状态高亮联动（可选开启）：点击右上角状态图例时，非选中状态任务条按透明度弱化，再次点击同一状态可重置。

推荐入口：GanttPanel（外部工具栏）

• 在甘特图外部顶部提供工具栏（不是图内浮层）。
• 内置自动刷新开关、刷新中提示、时间线缩放、状态图例。
• 工具区默认顺序：自动刷新 -> 时间线缩放 -> 状态图例。
• 支持受控/非受控自动刷新，支持 onRefresh 轮询回调。
• 支持 className/style 与 toolbarClassName/toolbarStyle/ganttClassName/ganttStyle 自定义样式。
• 支持状态高亮开关与透明度配置：
  • enableStatusHighlight?: boolean，默认 false（关闭，不影响原行为）
  • statusHighlightOpacity?: number，默认 0.5（非选中状态透明度）

状态高亮联动（GanttPanel）

• 点击某个状态：该状态高亮，其他状态图例与任务条同步降透明。
• 再次点击同一状态：重置为全部正常显示。
• 该能力默认关闭，需显式开启：enableStatusHighlight.

调用示例

import {GanttPanel, type GanttRow, type TimelineConfig} from 'sggk-charts';
import 'sggk-charts/style.css';

const timeline: TimelineConfig = {
  timelineStart: '2026-03-13T00:00:00',
  timelineEnd: '2026-03-16T00:00:00',
  pxPerHour: 20,
  shiftHours: 8,
  shifts: ['中班', '夜班', '白班'],
  snapHours: 1,
};

const rows: GanttRow[] = [
  {
    rowId: 'HL5-503',
    name: '洪蓝5号码头',
    code: '503泊位',
    tasks: [
      {
        taskId: '53026',
        title: '皖瑞丰281',
        start: '2026-03-13 03:03:03',
        end: '2026-03-13 15:03:03',
        status: 'working',
      },
    ],
  },
];

const statusMap = {
  done: {label: '已完成', color: '#22C55E', textColor: '#fff'},
  working: {label: '作业中', color: '#3B82F6', textColor: '#fff'},
  queue: {label: '排队中', color: '#F59E0B', textColor: '#fff'},
  maintenance: {label: '维护中', color: '#6B7280', textColor: '#fff'},
};

export default function Page() {
  return (
    <GanttPanel
      rows={rows}
      timeline={timeline}
      statusMap={statusMap}
      enableStatusHighlight
      statusHighlightOpacity={0.5}
      ganttStyle={{height: 420}}
      autoRefreshInterval={15000}
      onRefresh={async () => {
        // 拉取最新甘特图数据
      }}
      renderToolbarLeft={() => <span>船舶靠港计划</span>}
      onTaskClick={(task, row) => {
        // 打开船舶信息抽屉
        console.log(task.taskId, row.rowId);
      }}
    />
  );
}

底层组件（Gantt）可选受控方式

import {Gantt} from 'sggk-charts';

<Gantt
  rows={rows}
  timeline={timeline}
  statusMap={statusMap}
  activeStatus={'working'} // null 表示不高亮任何状态
  inactiveOpacity={0.5}
/>

文档

• 详见 docs/README.md