Document chart and visual kit usage

This commit is contained in:
Mac mini git server 2026-05-30 23:34:26 +08:00
parent 517786c8a9
commit 3fae670e6b
3 changed files with 440 additions and 2 deletions

View File

@ -99,3 +99,4 @@ pnpm build
- [项目规划](doc/project-plan.md)
- [项目框架说明](doc/framework.md)
- [交付流程](doc/delivery-workflow.md)
- [图表工厂与 visual-kit 使用教程](doc/charts-and-visual-kit-guide.md)

View File

@ -52,12 +52,12 @@ body {
border-radius: 8px;
display: flex;
flex-direction: column;
height: 150px;
height: 148px;
left: 56px;
overflow: hidden;
padding: 16px;
position: absolute;
top: 150px;
top: 230px;
width: 580px;
}

View File

@ -0,0 +1,437 @@
# 图表工厂与 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 中,保证每个客户项目可以自由定制。
- 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。