4.6 KiB
4.6 KiB
项目框架说明
1. 框架原则
Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。
框架关注:
- 屏幕适配
- 图表生命周期
- 数据刷新
- 调试体验
- 视觉装饰
- 项目模板
- 部署约定
业务项目关注:
- 客户视觉风格
- 页面布局
- 指标定义
- 图表配置
- 数据接口
- 动效和交互
2. screen-core
screen-core 提供大屏运行的基础组件。
ScreenStage
职责:
- 固定设计稿尺寸,默认
1920x1080。 - 根据浏览器窗口自动缩放。
- 支持
fit、fill、stretch、none。
使用方式:
<ScreenStage background="#061826" scaleMode="fit" debug>
<YourScreen />
</ScreenStage>
scaleMode 支持:
fit:完整显示设计稿,保持比例,可能留黑边,推荐默认使用。fill:铺满窗口,保持比例,可能裁切边缘。stretch:横向和纵向分别缩放,不留黑边,但会变形。none:不缩放,适合局部调试。
debug 开启后会显示设计尺寸、视口尺寸、缩放模式和缩放比例。demo 页面支持通过 URL 参数切换:
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:在默认工厂配置基础上做局部覆盖。
推荐用法:
<EChart
option={createLineOption({
categories: ['08:00', '10:00', '12:00'],
values: [120, 240, 380],
name: '订单'
})}
/>
4. data
data 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 DataState<T>。
requestJson
封装基础 JSON 请求。
usePollingData
用于定时刷新接口数据。
useScreenDataSources
统一消费页面级数据源:
const data = useScreenDataSources(screenDataSources)
const metrics = data.metrics.data ?? []
配套声明函数:
defineDataSourcesmockSourcehttpSourcewebsocketSourcemqttSourcesignalrSource
其中 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:水位图。
推荐组合:
<GlowPanel title="订单趋势">
<EChart option={createLineOption(data)} />
</GlowPanel>
原则:
visual-kit可以包住charts。charts不依赖visual-kit。- 客户视觉差异较大时,可以复制组件到项目内定制。
7. 项目模板
templates/project-basic 是新客户项目起点。
创建命令:
pnpm new customer-a 客户A运营大屏
生成:
apps/customer-a/
然后开发人员在该目录内自由实现客户页面。