216 lines
5.0 KiB
Markdown
216 lines
5.0 KiB
Markdown
# 项目框架说明
|
||
|
||
## 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 在客户项目需要时再接。
|
||
|
||
HTTP 数据源支持 `baseUrl`、`query`、`headers`、`authToken`、`timeoutMs`。WebSocket 数据源支持断线重连和心跳。
|
||
|
||
## 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` 是新客户项目起点,默认包含:
|
||
|
||
- `ScreenStage` 适配和 debug。
|
||
- `dataSources.ts` 页面级数据源声明。
|
||
- `mockData.ts` 本地 mock 数据。
|
||
- `ChartPanel` 图表面板。
|
||
- `visual-kit` 状态区和告警区。
|
||
- `.env.example` 接口配置示例。
|
||
|
||
创建命令:
|
||
|
||
```bash
|
||
pnpm new customer-a 客户A运营大屏
|
||
```
|
||
|
||
生成:
|
||
|
||
```txt
|
||
apps/customer-a/
|
||
```
|
||
|
||
然后开发人员在该目录内自由实现客户页面。
|