dev-screen-starter/doc/charts-and-visual-kit-guide.md

8.7 KiB
Raw Permalink Blame History

图表工厂与 visual-kit 使用教程

本文档说明当前项目中已经封装的图表工厂和大屏视觉组件。推荐客户项目优先使用这些基础能力,再按项目需求做局部覆盖。

1. 基础引入

在大屏页面中使用图表工厂:

import { EChart, createAreaTrendOption } from '@dev-screen-starter/charts'

export function TrendPanel() {
  return (
    <EChart
      option={createAreaTrendOption({
        categories: ['08:00', '10:00', '12:00'],
        values: [120, 240, 380],
        name: '订单',
        color: '#63a4ff'
      })}
    />
  )
}

使用 visual-kit 时,入口文件需要额外引入样式:

import '@dev-screen-starter/visual-kit/styles.css'

然后在页面中使用组件:

import { CornerFrame, SectionTitle, StatusPill } from '@dev-screen-starter/visual-kit'

export function StatusBlock() {
  return (
    <CornerFrame tone="blue">
      <SectionTitle title="运行态" subtitle="实时监控" />
      <StatusPill label="稳定" />
    </CornerFrame>
  )
}

2. 图表工厂清单

图表工厂位于 @dev-screen-starter/charts。

EChart

ECharts React 容器,负责初始化、销毁、resize 和 loading 状态。

<EChart option={option} loading={false} />

createLineOption

折线图。支持单系列和多系列。

createLineOption({
  categories: ['一月', '二月', '三月'],
  values: [120, 180, 240],
  name: '销售额',
  color: '#63a4ff'
})

多系列:

createLineOption({
  categories: ['一月', '二月', '三月'],
  series: [
    { name: '线上', values: [120, 180, 240], color: '#63a4ff' },
    { name: '线下', values: [90, 140, 210], color: '#56d08a' }
  ]
})

createAreaTrendOption

面积趋势图。适合展示订单、产能、吞吐量等连续趋势。

createAreaTrendOption({
  categories: ['08:00', '10:00', '12:00'],
  values: [120, 240, 380],
  name: '吞吐量',
  color: '#56d08a'
})

createBarOption

普通柱状图。支持单系列和多系列。

createBarOption({
  categories: ['小程序', 'App', '门店'],
  values: [420, 360, 280],
  name: '订单',
  color: '#56d08a'
})

createStackedBarOption

堆叠柱状图。适合展示不同类型在同一类目下的构成。

createStackedBarOption({
  categories: ['华东', '华南', '华北'],
  series: [
    { name: '标准', values: [420, 360, 310], color: '#63a4ff' },
    { name: '加急', values: [140, 126, 112], color: '#d8a13e' },
    { name: '售后', values: [68, 54, 49], color: '#ec646c' }
  ]
})

createDualAxisOption

双轴折线柱状图。适合同时展示数量和比例。

createDualAxisOption({
  categories: ['08:00', '10:00', '12:00'],
  leftName: '订单',
  rightName: '履约率',
  bar: {
    name: '订单',
    values: [120, 240, 380],
    color: '#63a4ff'
  },
  line: {
    name: '履约率',
    values: [82, 85, 88],
    color: '#d8a13e'
  }
})

createRankBarOption

横向排名条。适合 TopN 排行。

createRankBarOption({
  categories: ['华东', '华南', '华北'],
  values: [960, 820, 680],
  name: '订单',
  color: '#7aa7ff'
})

createPieOption

环图或饼图。默认是环图。

createPieOption({
  data: [
    { name: '标准订单', value: 56 },
    { name: '加急订单', value: 24 }
  ],
  radius: ['46%', '68%']
})

createRosePieOption

玫瑰图。适合展示不同来源、类型、风险项的占比。

createRosePieOption({
  data: [
    { name: '库存', value: 32 },
    { name: '履约', value: 26 },
    { name: '接口', value: 18 }
  ]
})

createGaugeOption

仪表盘。适合履约率、达成率、利用率。

createGaugeOption({
  name: '履约率',
  value: 87,
  unit: '%',
  color: '#56d08a'
})

createRadarOption

雷达图。适合多维评分。

createRadarOption({
  indicators: [
    { name: '响应', max: 100 },
    { name: '履约', max: 100 },
    { name: '质量', max: 100 }
  ],
  values: [88, 76, 92],
  name: '质量评分',
  color: '#d8a13e'
})

mergeChartOption

用于在工厂默认配置基础上覆盖局部 ECharts option。推荐业务项目用它处理客户定制,避免复制整份 option。

import { createRankBarOption, mergeChartOption } from '@dev-screen-starter/charts'

const option = mergeChartOption(
  createRankBarOption({
    categories: ['华东', '华南', '华北'],
    values: [960, 820, 680]
  }),
  {
    grid: { left: 120 },
    series: [{ label: { color: '#f0f7ff', fontSize: 14 } }]
  }
)

3. visual-kit 组件清单

visual-kit 位于 @dev-screen-starter/visual-kit。大多数组件支持这些通用属性:

  • className
  • style
  • tone: blue | green | amber | red
  • size: sm | md | lg

GlowPanel

发光面板容器,适合包裹表格、列表、复杂信息块。

<GlowPanel title="实时告警" tone="amber">
  <div>内容</div>
</GlowPanel>

CornerFrame

四角装饰框,适合状态摘要、小型信息区。

<CornerFrame tone="blue">
  <SectionTitle title="运行态" subtitle="实时监控" />
</CornerFrame>

TitleBar

标题栏,支持右侧 action。

<TitleBar
  title="运行事件"
  subtitle="自动滚动列表"
  action={<TrendBadge label="较昨日" value="4.8%" direction="up" tone="green" />}
/>

SectionTitle

小节标题,适合面板内部标题。

<SectionTitle title="运行态" subtitle="visual-kit" size="sm" />

Divider

装饰分割线。

<Divider tone="blue" />

DigitalNumber

普通数字强调组件。

<DigitalNumber label="综合效率" value="92.6" unit="%" tone="green" />

FlipNumber

数字翻牌风格组件,适合关键指标。

<FlipNumber label="今日订单" value="1280" unit="单" tone="blue" />

StatusPill

状态标签。

<StatusPill label="稳定" />
<StatusPill label="预警" status="warning" />
<StatusPill label="异常" status="danger" />

TrendBadge

趋势标记,适合展示环比、同比、较昨日。

<TrendBadge label="较昨日" value="4.8%" direction="up" tone="green" />
<TrendBadge label="较昨日" value="2.1%" direction="down" tone="red" />

ScrollTable

轻量表格,适合小范围告警、排行、流水数据。

<ScrollTable
  columns={[
    { key: 'time', title: '时间', width: '68px' },
    { key: 'area', title: '区域' },
    { key: 'status', title: '状态' }
  ]}
  rows={[
    { time: '18:20', area: '华东仓', status: '履约延迟' },
    { time: '18:12', area: '华南仓', status: '库存预警' }
  ]}
/>

MarqueeList

自动滚动列表。父容器需要有明确高度,并建议设置 overflow: hidden。

<MarqueeList
  rows={[
    { level: 'P1', message: '华东仓出库队列恢复', time: '18:31' },
    { level: 'P2', message: '华南库存同步延迟', time: '18:24' }
  ]}
  renderRow={(row) => (
    <div className="event-row">
      <strong>{row.level}</strong>
      <span>{row.message}</span>
      <small>{row.time}</small>
    </div>
  )}
/>

推荐父容器写法:

.event-panel {
  display: flex;
  flex-direction: column;
  height: 148px;
  overflow: hidden;
}

.event-panel .vk-marquee-list {
  flex: 1;
  min-height: 0;
}

WaterLevel

水位图,适合百分比容量、产能水位。

<WaterLevel label="产能水位" value={76} unit="%" tone="blue" />

4. 推荐组合方式

指标状态卡

<CornerFrame tone="blue">
  <SectionTitle title="运行态" subtitle="系统状态" />
  <Divider />
  <StatusPill label="稳定" />
</CornerFrame>

图表面板

import { Panel } from '@dev-screen-starter/screen-core'
import { EChart, createStackedBarOption } from '@dev-screen-starter/charts'

<Panel title="堆叠柱:区域订单">
  <EChart
    option={createStackedBarOption({
      categories: ['华东', '华南', '华北'],
      series: [
        { name: '标准', values: [420, 360, 310], color: '#63a4ff' },
        { name: '加急', values: [140, 126, 112], color: '#d8a13e' }
      ]
    })}
  />
</Panel>

关键数字区

<GlowPanel tone="green">
  <FlipNumber label="综合效率" value="92.6" unit="%" tone="green" />
  <TrendBadge label="较昨日" value="4.8%" direction="up" tone="green" />
</GlowPanel>

5. 使用建议

  • 简单图表优先使用工厂函数,不要每个项目都重新写完整 ECharts option。
  • 客户定制样式优先用 mergeChartOption 做局部覆盖。
  • visual-kit 只负责大屏常见视觉部件,不承载业务逻辑。
  • 项目级布局仍写在业务页面 CSS 中,保证每个客户项目可以自由定制。
  • 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。