dev-screen-starter/doc/framework.md

207 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 项目框架说明
## 1. 框架原则
Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。
框架关注:
- 屏幕适配
- 图表生命周期
- 数据刷新
- 调试体验
- 视觉装饰
- 项目模板
- 部署约定
业务项目关注:
- 客户视觉风格
- 页面布局
- 指标定义
- 图表配置
- 数据接口
- 动效和交互
## 2. screen-core
`screen-core` 提供大屏运行的基础组件。
### ScreenStage
职责:
- 固定设计稿尺寸,默认 `1920x1080`。
- 根据浏览器窗口自动缩放。
- 支持 `fit`、`fill`、`stretch`、`none`。
使用方式:
```tsx
<ScreenStage background="#061826" scaleMode="fit" debug>
<YourScreen />
</ScreenStage>
```
`scaleMode` 支持:
- `fit`:完整显示设计稿,保持比例,可能留黑边,推荐默认使用。
- `fill`:铺满窗口,保持比例,可能裁切边缘。
- `stretch`:横向和纵向分别缩放,不留黑边,但会变形。
- `none`:不缩放,适合局部调试。
`debug` 开启后会显示设计尺寸、视口尺寸、缩放模式和缩放比例。demo 页面支持通过 URL 参数切换:
```txt
http://localhost:5173/?scaleMode=fit
http://localhost:5173/?scaleMode=fill
http://localhost:5173/?scaleMode=stretch
http://localhost:5173/?scaleMode=none
```
### Panel
用于常规图表面板或信息区域。
### MetricCard
用于指标展示。项目中可以直接使用,也可以复制后按客户视觉重写。
## 3. charts
`charts` 提供 ECharts 基础封装。
### EChart
职责:
- 初始化 ECharts 实例。
- 监听容器尺寸变化并自动 resize。
- 支持 loading 状态。
- 组件卸载时自动 dispose。
### withChartDefaults
提供基础 tooltip、grid、文字风格配置。项目里可以按客户视觉覆盖。
### 图表工厂
图表工厂只生成 ECharts option,不限制项目继续覆盖配置。
当前提供:
- `createLineOption`:折线图,支持单序列和多序列。
- `createAreaTrendOption`:面积趋势图。
- `createBarOption`:柱状图,支持单序列和多序列。
- `createStackedBarOption`:堆叠柱状图。
- `createDualAxisOption`:双轴折线柱状图。
- `createRankBarOption`:横向排名条。
- `createPieOption`:饼图/环图。
- `createRosePieOption`:玫瑰图。
- `createGaugeOption`:仪表盘。
- `createRadarOption`:雷达图。
- `mergeChartOption`:在默认工厂配置基础上做局部覆盖。
推荐用法:
```tsx
<EChart
option={createLineOption({
categories: ['08:00', '10:00', '12:00'],
values: [120, 240, 380],
name: '订单'
})}
/>
```
## 4. data
`data` 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 `DataState<T>`。
### requestJson
封装基础 JSON 请求。
### usePollingData
用于定时刷新接口数据。
### useScreenDataSources
统一消费页面级数据源:
```tsx
const data = useScreenDataSources(screenDataSources)
const metrics = data.metrics.data ?? []
```
配套声明函数:
- `defineDataSources`
- `mockSource`
- `httpSource`
- `websocketSource`
- `mqttSource`
- `signalrSource`
其中 `mockSource`、`httpSource`、`websocketSource` 已可用;`mqttSource`、`signalrSource` 已预留类型和声明入口,具体 SDK 在客户项目需要时再接。
## 5. debug
`debug` 提供开发时调试组件。
### DebugBadge
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
## 6. visual-kit
`visual-kit` 提供轻量大屏视觉材料,不承担图表逻辑。
当前提供:
- `GlowPanel`:带轻微光感的内容面板。
- `CornerFrame`:四角框容器。
- `SectionTitle`:区块标题。
- `TitleBar`:标题栏,支持右侧 action。
- `Divider`:装饰分割线。
- `DigitalNumber`:数字强调。
- `FlipNumber`:数字翻牌。
- `StatusPill`:状态标签。
- `TrendBadge`:趋势标签。
- `ScrollTable`:紧凑滚动表格结构。
- `MarqueeList`:自动滚动列表。
- `WaterLevel`:水位图。
推荐组合:
```tsx
<GlowPanel title="订单趋势">
<EChart option={createLineOption(data)} />
</GlowPanel>
```
原则:
- `visual-kit` 可以包住 `charts`。
- `charts` 不依赖 `visual-kit`。
- 客户视觉差异较大时,可以复制组件到项目内定制。
## 7. 项目模板
`templates/project-basic` 是新客户项目起点。
创建命令:
```bash
pnpm new customer-a 客户A运营大屏
```
生成:
```txt
apps/customer-a/
```
然后开发人员在该目录内自由实现客户页面。