dev-screen-starter/doc/framework.md
2026-05-29 00:29:53 +08:00

3.3 KiB
Raw Blame History

项目框架说明

1. 框架原则

Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。

框架关注:

  • 屏幕适配
  • 图表生命周期
  • 数据刷新
  • 调试体验
  • 视觉装饰
  • 项目模板
  • 部署约定

业务项目关注:

  • 客户视觉风格
  • 页面布局
  • 指标定义
  • 图表配置
  • 数据接口
  • 动效和交互

2. screen-core

screen-core 提供大屏运行的基础组件。

ScreenStage

职责:

  • 固定设计稿尺寸,默认 1920x1080。
  • 根据浏览器窗口自动缩放。
  • 支持 fit、fill、stretch、none。

使用方式:

<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:雷达图。

推荐用法:

<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. 项目模板

6. visual-kit

visual-kit 提供轻量大屏视觉材料,不承担图表逻辑。

当前提供:

  • GlowPanel:带轻微光感的内容面板。
  • CornerFrame:四角框容器。
  • SectionTitle:区块标题。
  • DigitalNumber:数字强调。
  • StatusPill:状态标签。
  • ScrollTable:紧凑滚动表格结构。
  • 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/

然后开发人员在该目录内自由实现客户页面。