dev-screen-starter/doc/framework.md

145 lines
2.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">
<YourScreen />
</ScreenStage>
```
### Panel
用于常规图表面板或信息区域。
### MetricCard
用于指标展示。项目中可以直接使用,也可以复制后按客户视觉重写。
## 3. charts
`charts` 提供 ECharts 基础封装。
### EChart
职责:
- 初始化 ECharts 实例。
- 监听容器尺寸变化并自动 resize。
- 支持 loading 状态。
- 组件卸载时自动 dispose。
### withChartDefaults
提供基础 tooltip、grid、文字风格配置。项目里可以按客户视觉覆盖。
### 图表工厂
图表工厂只生成 ECharts option,不限制项目继续覆盖配置。
当前提供:
- `createLineOption`:折线图,支持单序列和多序列。
- `createBarOption`:柱状图,支持单序列和多序列。
- `createRankBarOption`:横向排名条。
- `createPieOption`:饼图/环图。
- `createGaugeOption`:仪表盘。
- `createRadarOption`:雷达图。
推荐用法:
```tsx
<EChart
option={createLineOption({
categories: ['08:00', '10:00', '12:00'],
values: [120, 240, 380],
name: '订单'
})}
/>
```
## 4. data
`data` 提供轻量数据工具。
### requestJson
封装基础 JSON 请求。
### usePollingData
用于定时刷新接口数据。
适合:
- 30 秒刷新指标。
- 5 秒刷新告警。
- 项目开发时接 mock loader。
不适合:
- 高频毫秒级数据。
- 大规模实时流。
这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。
## 5. debug
`debug` 提供开发时调试组件。
### DebugBadge
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
## 6. 项目模板
`templates/project-basic` 是新客户项目起点。
创建命令:
```bash
pnpm new customer-a 客户A运营大屏
```
生成:
```txt
apps/customer-a/
```
然后开发人员在该目录内自由实现客户页面。