# 项目框架说明 ## 1. 框架原则 Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。 框架关注: - 屏幕适配 - 图表生命周期 - 数据刷新 - 调试体验 - 视觉装饰 - 项目模板 - 部署约定 业务项目关注: - 客户视觉风格 - 页面布局 - 指标定义 - 图表配置 - 数据接口 - 动效和交互 ## 2. screen-core `screen-core` 提供大屏运行的基础组件。 ### ScreenStage 职责: - 固定设计稿尺寸,默认 `1920x1080`。 - 根据浏览器窗口自动缩放。 - 支持 `fit`、`fill`、`stretch`、`none`。 使用方式: ```tsx ``` ### Panel 用于常规图表面板或信息区域。 ### MetricCard 用于指标展示。项目中可以直接使用,也可以复制后按客户视觉重写。 ## 3. charts `charts` 提供 ECharts 基础封装。 ### EChart 职责: - 初始化 ECharts 实例。 - 监听容器尺寸变化并自动 resize。 - 支持 loading 状态。 - 组件卸载时自动 dispose。 ### withChartDefaults 提供基础 tooltip、grid、文字风格配置。项目里可以按客户视觉覆盖。 ### 图表工厂 图表工厂只生成 ECharts option,不限制项目继续覆盖配置。 当前提供: - `createLineOption`:折线图,支持单序列和多序列。 - `createBarOption`:柱状图,支持单序列和多序列。 - `createRankBarOption`:横向排名条。 - `createPieOption`:饼图/环图。 - `createGaugeOption`:仪表盘。 - `createRadarOption`:雷达图。 推荐用法: ```tsx ``` ## 4. data `data` 提供轻量数据工具。 ### requestJson 封装基础 JSON 请求。 ### usePollingData 用于定时刷新接口数据。 适合: - 30 秒刷新指标。 - 5 秒刷新告警。 - 项目开发时接 mock loader。 不适合: - 高频毫秒级数据。 - 大规模实时流。 这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。 ## 5. debug `debug` 提供开发时调试组件。 ### DebugBadge 显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。 ## 6. 项目模板 ## 6. visual-kit `visual-kit` 提供轻量大屏视觉材料,不承担图表逻辑。 当前提供: - `GlowPanel`:带轻微光感的内容面板。 - `CornerFrame`:四角框容器。 - `SectionTitle`:区块标题。 - `DigitalNumber`:数字强调。 - `StatusPill`:状态标签。 - `ScrollTable`:紧凑滚动表格结构。 - `WaterLevel`:水位图。 推荐组合: ```tsx ``` 原则: - `visual-kit` 可以包住 `charts`。 - `charts` 不依赖 `visual-kit`。 - 客户视觉差异较大时,可以复制组件到项目内定制。 ## 7. 项目模板 `templates/project-basic` 是新客户项目起点。 创建命令: ```bash pnpm new customer-a 客户A运营大屏 ``` 生成: ```txt apps/customer-a/ ``` 然后开发人员在该目录内自由实现客户页面。