diff --git a/README.md b/README.md index 9380b48..b89ea75 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/apps/demo-screen/src/styles/screen.css b/apps/demo-screen/src/styles/screen.css index 7bfbe98..0b2c732 100644 --- a/apps/demo-screen/src/styles/screen.css +++ b/apps/demo-screen/src/styles/screen.css @@ -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; } diff --git a/doc/charts-and-visual-kit-guide.md b/doc/charts-and-visual-kit-guide.md new file mode 100644 index 0000000..b1015bf --- /dev/null +++ b/doc/charts-and-visual-kit-guide.md @@ -0,0 +1,437 @@ +# 图表工厂与 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 中,保证每个客户项目可以自由定制。 +- 自动滚动、图表、翻牌等组件都要放在有明确宽高的容器中,避免缩放后溢出。