dev-screen-starter/doc/framework.md

5.0 KiB
Raw Permalink Blame History

项目框架说明

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 ?? []

配套声明函数:

  • defineDataSources
  • mockSource
  • httpSource
  • websocketSource
  • mqttSource
  • signalrSource

其中 mockSource、httpSource、websocketSource 已可用;mqttSource、signalrSource 已预留类型和声明入口,具体 SDK 在客户项目需要时再接。

HTTP 数据源支持 baseUrl、query、headers、authToken、timeoutMs。WebSocket 数据源支持断线重连和心跳。

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 是新客户项目起点,默认包含:

  • ScreenStage 适配和 debug。
  • dataSources.ts 页面级数据源声明。
  • mockData.ts 本地 mock 数据。
  • ChartPanel 图表面板。
  • visual-kit 状态区和告警区。
  • .env.example 接口配置示例。

创建命令:

pnpm new customer-a 客户A运营大屏

生成:

apps/customer-a/

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