8.7 KiB
8.7 KiB
图表工厂与 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。大多数组件支持这些通用属性:
classNamestyletone:blue | green | amber | redsize: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 中,保证每个客户项目可以自由定制。
- 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。