Document chart and visual kit usage
This commit is contained in:
parent
517786c8a9
commit
3fae670e6b
@ -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)
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
|
||||
437
doc/charts-and-visual-kit-guide.md
Normal file
437
doc/charts-and-visual-kit-guide.md
Normal 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 中,保证每个客户项目可以自由定制。
|
||||
- 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。
|
||||
Loading…
x
Reference in New Issue
Block a user