# 项目框架说明 ## 1. 框架原则 Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。 框架关注: - 屏幕适配 - 图表生命周期 - 数据刷新 - 调试体验 - 视觉装饰 - 项目模板 - 部署约定 业务项目关注: - 客户视觉风格 - 页面布局 - 指标定义 - 图表配置 - 数据接口 - 动效和交互 ## 2. screen-core `screen-core` 提供大屏运行的基础组件。 ### ScreenStage 职责: - 固定设计稿尺寸,默认 `1920x1080`。 - 根据浏览器窗口自动缩放。 - 支持 `fit`、`fill`、`stretch`、`none`。 使用方式: ```tsx ``` `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 ``` ## 4. data `data` 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 `DataState`。 ### 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 ``` 原则: - `visual-kit` 可以包住 `charts`。 - `charts` 不依赖 `visual-kit`。 - 客户视觉差异较大时,可以复制组件到项目内定制。 ## 7. 项目模板 `templates/project-basic` 是新客户项目起点。 创建命令: ```bash pnpm new customer-a 客户A运营大屏 ``` 生成: ```txt apps/customer-a/ ``` 然后开发人员在该目录内自由实现客户页面。