# 图表工厂与 visual-kit 使用教程 本文档说明当前项目中已经封装的图表工厂和大屏视觉组件。推荐客户项目优先使用这些基础能力,再按项目需求做局部覆盖。 ## 1. 基础引入 在大屏页面中使用图表工厂: ```tsx import { EChart, createAreaTrendOption } from '@dev-screen-starter/charts' export function TrendPanel() { return ( ) } ``` 使用 `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 ( ) } ``` ## 2. 图表工厂清单 图表工厂位于 `@dev-screen-starter/charts`。 ### EChart ECharts React 容器,负责初始化、销毁、resize 和 loading 状态。 ```tsx ``` ### 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
内容
``` ### CornerFrame 四角装饰框,适合状态摘要、小型信息区。 ```tsx ``` ### TitleBar 标题栏,支持右侧 action。 ```tsx } /> ``` ### SectionTitle 小节标题,适合面板内部标题。 ```tsx ``` ### Divider 装饰分割线。 ```tsx ``` ### DigitalNumber 普通数字强调组件。 ```tsx ``` ### FlipNumber 数字翻牌风格组件,适合关键指标。 ```tsx ``` ### StatusPill 状态标签。 ```tsx ``` ### TrendBadge 趋势标记,适合展示环比、同比、较昨日。 ```tsx ``` ### ScrollTable 轻量表格,适合小范围告警、排行、流水数据。 ```tsx ``` ### MarqueeList 自动滚动列表。父容器需要有明确高度,并建议设置 `overflow: hidden`。 ```tsx (
{row.level} {row.message} {row.time}
)} /> ``` 推荐父容器写法: ```css .event-panel { display: flex; flex-direction: column; height: 148px; overflow: hidden; } .event-panel .vk-marquee-list { flex: 1; min-height: 0; } ``` ### WaterLevel 水位图,适合百分比容量、产能水位。 ```tsx ``` ## 4. 推荐组合方式 ### 指标状态卡 ```tsx ``` ### 图表面板 ```tsx import { Panel } from '@dev-screen-starter/screen-core' import { EChart, createStackedBarOption } from '@dev-screen-starter/charts' ``` ### 关键数字区 ```tsx ``` ## 5. 使用建议 - 简单图表优先使用工厂函数,不要每个项目都重新写完整 ECharts option。 - 客户定制样式优先用 `mergeChartOption` 做局部覆盖。 - `visual-kit` 只负责大屏常见视觉部件,不承载业务逻辑。 - 项目级布局仍写在业务页面 CSS 中,保证每个客户项目可以自由定制。 - 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。