438 lines
8.7 KiB
Markdown
438 lines
8.7 KiB
Markdown
# 图表工厂与 visual-kit 使用教程
|
|
|
|
本文档说明当前项目中已经封装的图表工厂和大屏视觉组件。推荐客户项目优先使用这些基础能力,再按项目需求做局部覆盖。
|
|
|
|
## 1. 基础引入
|
|
|
|
在大屏页面中使用图表工厂:
|
|
|
|
```tsx
|
|
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` 时,入口文件需要额外引入样式:
|
|
|
|
```ts
|
|
import '@dev-screen-starter/visual-kit/styles.css'
|
|
```
|
|
|
|
然后在页面中使用组件:
|
|
|
|
```tsx
|
|
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 状态。
|
|
|
|
```tsx
|
|
<EChart option={option} loading={false} />
|
|
```
|
|
|
|
### createLineOption
|
|
|
|
折线图。支持单系列和多系列。
|
|
|
|
```tsx
|
|
createLineOption({
|
|
categories: ['一月', '二月', '三月'],
|
|
values: [120, 180, 240],
|
|
name: '销售额',
|
|
color: '#63a4ff'
|
|
})
|
|
```
|
|
|
|
多系列:
|
|
|
|
```tsx
|
|
createLineOption({
|
|
categories: ['一月', '二月', '三月'],
|
|
series: [
|
|
{ name: '线上', values: [120, 180, 240], color: '#63a4ff' },
|
|
{ name: '线下', values: [90, 140, 210], color: '#56d08a' }
|
|
]
|
|
})
|
|
```
|
|
|
|
### createAreaTrendOption
|
|
|
|
面积趋势图。适合展示订单、产能、吞吐量等连续趋势。
|
|
|
|
```tsx
|
|
createAreaTrendOption({
|
|
categories: ['08:00', '10:00', '12:00'],
|
|
values: [120, 240, 380],
|
|
name: '吞吐量',
|
|
color: '#56d08a'
|
|
})
|
|
```
|
|
|
|
### createBarOption
|
|
|
|
普通柱状图。支持单系列和多系列。
|
|
|
|
```tsx
|
|
createBarOption({
|
|
categories: ['小程序', 'App', '门店'],
|
|
values: [420, 360, 280],
|
|
name: '订单',
|
|
color: '#56d08a'
|
|
})
|
|
```
|
|
|
|
### createStackedBarOption
|
|
|
|
堆叠柱状图。适合展示不同类型在同一类目下的构成。
|
|
|
|
```tsx
|
|
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
|
|
|
|
双轴折线柱状图。适合同时展示数量和比例。
|
|
|
|
```tsx
|
|
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 排行。
|
|
|
|
```tsx
|
|
createRankBarOption({
|
|
categories: ['华东', '华南', '华北'],
|
|
values: [960, 820, 680],
|
|
name: '订单',
|
|
color: '#7aa7ff'
|
|
})
|
|
```
|
|
|
|
### createPieOption
|
|
|
|
环图或饼图。默认是环图。
|
|
|
|
```tsx
|
|
createPieOption({
|
|
data: [
|
|
{ name: '标准订单', value: 56 },
|
|
{ name: '加急订单', value: 24 }
|
|
],
|
|
radius: ['46%', '68%']
|
|
})
|
|
```
|
|
|
|
### createRosePieOption
|
|
|
|
玫瑰图。适合展示不同来源、类型、风险项的占比。
|
|
|
|
```tsx
|
|
createRosePieOption({
|
|
data: [
|
|
{ name: '库存', value: 32 },
|
|
{ name: '履约', value: 26 },
|
|
{ name: '接口', value: 18 }
|
|
]
|
|
})
|
|
```
|
|
|
|
### createGaugeOption
|
|
|
|
仪表盘。适合履约率、达成率、利用率。
|
|
|
|
```tsx
|
|
createGaugeOption({
|
|
name: '履约率',
|
|
value: 87,
|
|
unit: '%',
|
|
color: '#56d08a'
|
|
})
|
|
```
|
|
|
|
### createRadarOption
|
|
|
|
雷达图。适合多维评分。
|
|
|
|
```tsx
|
|
createRadarOption({
|
|
indicators: [
|
|
{ name: '响应', max: 100 },
|
|
{ name: '履约', max: 100 },
|
|
{ name: '质量', max: 100 }
|
|
],
|
|
values: [88, 76, 92],
|
|
name: '质量评分',
|
|
color: '#d8a13e'
|
|
})
|
|
```
|
|
|
|
### mergeChartOption
|
|
|
|
用于在工厂默认配置基础上覆盖局部 ECharts option。推荐业务项目用它处理客户定制,避免复制整份 option。
|
|
|
|
```tsx
|
|
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
|
|
|
|
发光面板容器,适合包裹表格、列表、复杂信息块。
|
|
|
|
```tsx
|
|
<GlowPanel title="实时告警" tone="amber">
|
|
<div>内容</div>
|
|
</GlowPanel>
|
|
```
|
|
|
|
### CornerFrame
|
|
|
|
四角装饰框,适合状态摘要、小型信息区。
|
|
|
|
```tsx
|
|
<CornerFrame tone="blue">
|
|
<SectionTitle title="运行态" subtitle="实时监控" />
|
|
</CornerFrame>
|
|
```
|
|
|
|
### TitleBar
|
|
|
|
标题栏,支持右侧 action。
|
|
|
|
```tsx
|
|
<TitleBar
|
|
title="运行事件"
|
|
subtitle="自动滚动列表"
|
|
action={<TrendBadge label="较昨日" value="4.8%" direction="up" tone="green" />}
|
|
/>
|
|
```
|
|
|
|
### SectionTitle
|
|
|
|
小节标题,适合面板内部标题。
|
|
|
|
```tsx
|
|
<SectionTitle title="运行态" subtitle="visual-kit" size="sm" />
|
|
```
|
|
|
|
### Divider
|
|
|
|
装饰分割线。
|
|
|
|
```tsx
|
|
<Divider tone="blue" />
|
|
```
|
|
|
|
### DigitalNumber
|
|
|
|
普通数字强调组件。
|
|
|
|
```tsx
|
|
<DigitalNumber label="综合效率" value="92.6" unit="%" tone="green" />
|
|
```
|
|
|
|
### FlipNumber
|
|
|
|
数字翻牌风格组件,适合关键指标。
|
|
|
|
```tsx
|
|
<FlipNumber label="今日订单" value="1280" unit="单" tone="blue" />
|
|
```
|
|
|
|
### StatusPill
|
|
|
|
状态标签。
|
|
|
|
```tsx
|
|
<StatusPill label="稳定" />
|
|
<StatusPill label="预警" status="warning" />
|
|
<StatusPill label="异常" status="danger" />
|
|
```
|
|
|
|
### TrendBadge
|
|
|
|
趋势标记,适合展示环比、同比、较昨日。
|
|
|
|
```tsx
|
|
<TrendBadge label="较昨日" value="4.8%" direction="up" tone="green" />
|
|
<TrendBadge label="较昨日" value="2.1%" direction="down" tone="red" />
|
|
```
|
|
|
|
### ScrollTable
|
|
|
|
轻量表格,适合小范围告警、排行、流水数据。
|
|
|
|
```tsx
|
|
<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`。
|
|
|
|
```tsx
|
|
<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>
|
|
)}
|
|
/>
|
|
```
|
|
|
|
推荐父容器写法:
|
|
|
|
```css
|
|
.event-panel {
|
|
display: flex;
|
|
flex-direction: column;
|
|
height: 148px;
|
|
overflow: hidden;
|
|
}
|
|
|
|
.event-panel .vk-marquee-list {
|
|
flex: 1;
|
|
min-height: 0;
|
|
}
|
|
```
|
|
|
|
### WaterLevel
|
|
|
|
水位图,适合百分比容量、产能水位。
|
|
|
|
```tsx
|
|
<WaterLevel label="产能水位" value={76} unit="%" tone="blue" />
|
|
```
|
|
|
|
## 4. 推荐组合方式
|
|
|
|
### 指标状态卡
|
|
|
|
```tsx
|
|
<CornerFrame tone="blue">
|
|
<SectionTitle title="运行态" subtitle="系统状态" />
|
|
<Divider />
|
|
<StatusPill label="稳定" />
|
|
</CornerFrame>
|
|
```
|
|
|
|
### 图表面板
|
|
|
|
```tsx
|
|
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>
|
|
```
|
|
|
|
### 关键数字区
|
|
|
|
```tsx
|
|
<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 中,保证每个客户项目可以自由定制。
|
|
- 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。
|