Add unified data sources and stage debug
This commit is contained in:
1 parent
3fae670e6b
commit
5b300dee0d
18 files changed
+940
-72
No files matched your search
+1
-1
@@ -5,5 +5,5 @@ dist/
|
||||
.DS_Store
|
||||
*.log
|
||||
coverage/
|
||||
data/
|
||||
/data/
|
||||
uploads/
|
||||
@@ -100,3 +100,4 @@ pnpm build
|
||||
- [项目框架说明](doc/framework.md)
|
||||
- [交付流程](doc/delivery-workflow.md)
|
||||
- [图表工厂与 visual-kit 使用教程](doc/charts-and-visual-kit-guide.md)
|
||||
- [外部数据接入设计与使用教程](doc/data-integration-guide.md)
|
||||
@@ -0,0 +1,45 @@
|
||||
import { defineDataSources, mockSource } from '@dev-screen-starter/data'
|
||||
import {
|
||||
alertRows,
|
||||
capacityTrend,
|
||||
fulfillmentMix,
|
||||
issueRose,
|
||||
metrics,
|
||||
operationEvents,
|
||||
qualityRadar,
|
||||
regionRank,
|
||||
stackedOrders
|
||||
} from './mockData'
|
||||
|
||||
export const demoDataSources = defineDataSources({
|
||||
metrics: mockSource({
|
||||
data: metrics,
|
||||
intervalMs: 15000
|
||||
}),
|
||||
alerts: mockSource({
|
||||
data: alertRows,
|
||||
intervalMs: 12000
|
||||
}),
|
||||
operationEvents: mockSource({
|
||||
data: operationEvents,
|
||||
intervalMs: 10000
|
||||
}),
|
||||
capacityTrend: mockSource({
|
||||
data: capacityTrend
|
||||
}),
|
||||
stackedOrders: mockSource({
|
||||
data: stackedOrders
|
||||
}),
|
||||
regionRank: mockSource({
|
||||
data: regionRank
|
||||
}),
|
||||
issueRose: mockSource({
|
||||
data: issueRose
|
||||
}),
|
||||
fulfillmentMix: mockSource({
|
||||
data: fulfillmentMix
|
||||
}),
|
||||
qualityRadar: mockSource({
|
||||
data: qualityRadar
|
||||
})
|
||||
})
|
||||
@@ -8,8 +8,7 @@ import {
|
||||
createStackedBarOption,
|
||||
EChart
|
||||
} from '@dev-screen-starter/charts'
|
||||
import { DebugBadge } from '@dev-screen-starter/debug'
|
||||
import { MetricCard, Panel, ScreenStage } from '@dev-screen-starter/screen-core'
|
||||
import { MetricCard, Panel, ScreenStage, type ScaleMode } from '@dev-screen-starter/screen-core'
|
||||
import {
|
||||
CornerFrame,
|
||||
Divider,
|
||||
@@ -23,24 +22,42 @@ import {
|
||||
TrendBadge,
|
||||
WaterLevel
|
||||
} from '@dev-screen-starter/visual-kit'
|
||||
import {
|
||||
alertRows,
|
||||
capacityTrend,
|
||||
fulfillmentMix,
|
||||
issueRose,
|
||||
metrics,
|
||||
operationEvents,
|
||||
qualityRadar,
|
||||
regionRank,
|
||||
stackedOrders
|
||||
} from '../demo/mockData'
|
||||
import { useScreenDataSources } from '@dev-screen-starter/data'
|
||||
import { demoDataSources } from '../demo/dataSources'
|
||||
|
||||
const scaleModes: ScaleMode[] = ['fit', 'fill', 'stretch', 'none']
|
||||
|
||||
function readScaleMode(): ScaleMode {
|
||||
if (typeof window === 'undefined') {
|
||||
return 'fit'
|
||||
}
|
||||
|
||||
const value = new URLSearchParams(window.location.search).get('scaleMode')
|
||||
return scaleModes.includes(value as ScaleMode) ? (value as ScaleMode) : 'fit'
|
||||
}
|
||||
|
||||
export function DemoOverview() {
|
||||
const scaleMode = readScaleMode()
|
||||
const data = useScreenDataSources(demoDataSources)
|
||||
const metrics = data.metrics.data ?? []
|
||||
const alertRows = data.alerts.data ?? []
|
||||
const operationEvents = data.operationEvents.data ?? []
|
||||
const capacityTrend = data.capacityTrend.data
|
||||
const stackedOrders = data.stackedOrders.data
|
||||
const regionRank = data.regionRank.data
|
||||
const issueRose = data.issueRose.data ?? []
|
||||
const fulfillmentMix = data.fulfillmentMix.data
|
||||
const qualityRadar = data.qualityRadar.data
|
||||
|
||||
return (
|
||||
<ScreenStage background="#061826">
|
||||
<ScreenStage background="#061826" scaleMode={scaleMode} debug>
|
||||
<header className="screen-title">
|
||||
<span>客户项目大屏模板</span>
|
||||
<strong>运营态势总览</strong>
|
||||
<div className="screen-title-meta">
|
||||
<span>HTTP / WebSocket / MQTT / SignalR ready</span>
|
||||
<span>scaleMode={scaleMode}</span>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<section className="visual-strip">
|
||||
@@ -96,32 +113,38 @@ export function DemoOverview() {
|
||||
|
||||
<section className="chart-grid">
|
||||
<Panel title="面积趋势:吞吐走势">
|
||||
<EChart
|
||||
option={createAreaTrendOption({
|
||||
categories: capacityTrend.xAxis,
|
||||
series: capacityTrend.series
|
||||
})}
|
||||
/>
|
||||
{capacityTrend ? (
|
||||
<EChart
|
||||
option={createAreaTrendOption({
|
||||
categories: capacityTrend.xAxis,
|
||||
series: capacityTrend.series
|
||||
})}
|
||||
/>
|
||||
) : null}
|
||||
</Panel>
|
||||
|
||||
<Panel title="堆叠柱:区域订单">
|
||||
<EChart
|
||||
option={createStackedBarOption({
|
||||
categories: stackedOrders.categories,
|
||||
series: stackedOrders.series
|
||||
})}
|
||||
/>
|
||||
{stackedOrders ? (
|
||||
<EChart
|
||||
option={createStackedBarOption({
|
||||
categories: stackedOrders.categories,
|
||||
series: stackedOrders.series
|
||||
})}
|
||||
/>
|
||||
) : null}
|
||||
</Panel>
|
||||
|
||||
<Panel title="排名条:区域排行">
|
||||
<EChart
|
||||
option={createRankBarOption({
|
||||
categories: regionRank.categories,
|
||||
values: regionRank.values,
|
||||
name: '订单',
|
||||
color: '#7aa7ff'
|
||||
})}
|
||||
/>
|
||||
{regionRank ? (
|
||||
<EChart
|
||||
option={createRankBarOption({
|
||||
categories: regionRank.categories,
|
||||
values: regionRank.values,
|
||||
name: '订单',
|
||||
color: '#7aa7ff'
|
||||
})}
|
||||
/>
|
||||
) : null}
|
||||
</Panel>
|
||||
|
||||
<Panel title="玫瑰图:异常来源">
|
||||
@@ -129,34 +152,36 @@ export function DemoOverview() {
|
||||
</Panel>
|
||||
|
||||
<Panel title="双轴图:订单与履约">
|
||||
<EChart
|
||||
option={createDualAxisOption({
|
||||
categories: fulfillmentMix.categories,
|
||||
leftName: '订单',
|
||||
rightName: '履约率',
|
||||
bar: { name: '订单', values: fulfillmentMix.orders, color: '#63a4ff' },
|
||||
line: { name: '履约率', values: fulfillmentMix.rates, color: '#d8a13e' }
|
||||
})}
|
||||
/>
|
||||
{fulfillmentMix ? (
|
||||
<EChart
|
||||
option={createDualAxisOption({
|
||||
categories: fulfillmentMix.categories,
|
||||
leftName: '订单',
|
||||
rightName: '履约率',
|
||||
bar: { name: '订单', values: fulfillmentMix.orders, color: '#63a4ff' },
|
||||
line: { name: '履约率', values: fulfillmentMix.rates, color: '#d8a13e' }
|
||||
})}
|
||||
/>
|
||||
) : null}
|
||||
</Panel>
|
||||
|
||||
<Panel title="雷达图:运营质量">
|
||||
<EChart
|
||||
option={createRadarOption({
|
||||
indicators: qualityRadar.indicators,
|
||||
values: qualityRadar.values,
|
||||
name: '质量评分',
|
||||
color: '#d8a13e'
|
||||
})}
|
||||
/>
|
||||
{qualityRadar ? (
|
||||
<EChart
|
||||
option={createRadarOption({
|
||||
indicators: qualityRadar.indicators,
|
||||
values: qualityRadar.values,
|
||||
name: '质量评分',
|
||||
color: '#d8a13e'
|
||||
})}
|
||||
/>
|
||||
) : null}
|
||||
</Panel>
|
||||
|
||||
<Panel title="仪表盘:履约率" className="compact-panel">
|
||||
<EChart option={createGaugeOption({ name: '履约率', value: 87, unit: '%', color: '#56d08a' })} />
|
||||
</Panel>
|
||||
</section>
|
||||
|
||||
<DebugBadge enabled scale={1} />
|
||||
</ScreenStage>
|
||||
)
|
||||
}
|
||||
@@ -46,6 +46,19 @@ body {
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
.screen-title-meta {
|
||||
display: flex;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.screen-title-meta span {
|
||||
border: 1px solid rgb(99 164 255 / 22%);
|
||||
border-radius: 999px;
|
||||
color: #9fb4cc;
|
||||
font-size: 12px;
|
||||
padding: 5px 9px;
|
||||
}
|
||||
|
||||
.event-strip {
|
||||
background: rgb(8 22 36 / 72%);
|
||||
border: 1px solid rgb(88 130 171 / 34%);
|
||||
@@ -202,6 +215,27 @@ body {
|
||||
right: 18px;
|
||||
}
|
||||
|
||||
.screen-stage-debug {
|
||||
background: rgb(3 8 13 / 84%);
|
||||
border: 1px solid rgb(100 135 170 / 35%);
|
||||
border-radius: 6px;
|
||||
bottom: 18px;
|
||||
color: #9fb4cc;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 10px;
|
||||
max-width: min(760px, calc(100vw - 36px));
|
||||
padding: 8px 10px;
|
||||
position: absolute;
|
||||
right: 18px;
|
||||
z-index: 10;
|
||||
}
|
||||
|
||||
.screen-stage-debug span {
|
||||
font-size: 12px;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.visual-status-row {
|
||||
display: flex;
|
||||
gap: 8px;
|
||||
|
||||
@@ -0,0 +1,292 @@
|
||||
# 外部数据接入设计与使用教程
|
||||
|
||||
本文档说明 Dev Screen Starter 的统一数据源设计。目标是让一个大屏页面可以集中声明多个数据源,并同时支持 HTTP、WebSocket、SignalR、MQTT 等不同协议。
|
||||
|
||||
## 1. 核心原则
|
||||
|
||||
一个大屏页面可以有多个图表和多个数据源。不同数据源可以使用不同协议:
|
||||
|
||||
- 指标卡来自 HTTP 轮询。
|
||||
- 告警列表来自 WebSocket 推送。
|
||||
- 设备状态来自 MQTT topic。
|
||||
- .NET 后端事件来自 SignalR hub。
|
||||
|
||||
页面不应该在组件里分散写 `fetch`、`new WebSocket`、MQTT 订阅等细节。推荐把数据源集中放在一个文件中:
|
||||
|
||||
```txt
|
||||
apps/demo-screen/src/demo/dataSources.ts
|
||||
```
|
||||
|
||||
业务组件只消费统一的 `DataState<T>`。
|
||||
|
||||
## 2. 当前实现状态
|
||||
|
||||
已实现:
|
||||
|
||||
- `mockSource`
|
||||
- `httpSource`
|
||||
- `websocketSource`
|
||||
- `defineDataSources`
|
||||
- `useScreenDataSources`
|
||||
|
||||
已预留类型和声明函数:
|
||||
|
||||
- `signalrSource`
|
||||
- `mqttSource`
|
||||
|
||||
SignalR 和 MQTT 当前不会引入 SDK,也不会真实连接;它们会返回 `idle` 状态和提示信息。后续客户项目需要时,再接入具体 SDK 或后端网关。
|
||||
|
||||
## 3. 统一状态模型
|
||||
|
||||
每个数据源都会返回同一种结构:
|
||||
|
||||
```ts
|
||||
type DataState<T> = {
|
||||
data: T | null
|
||||
loading: boolean
|
||||
error: string | null
|
||||
status: 'idle' | 'connecting' | 'open' | 'closed' | 'error'
|
||||
lastUpdated?: number
|
||||
sourceType?: 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
|
||||
}
|
||||
```
|
||||
|
||||
组件不需要关心底层协议,只看 `data/loading/error/status`。
|
||||
|
||||
## 4. 页面集中声明数据源
|
||||
|
||||
示例:
|
||||
|
||||
```ts
|
||||
import {
|
||||
defineDataSources,
|
||||
httpSource,
|
||||
mockSource,
|
||||
mqttSource,
|
||||
signalrSource,
|
||||
websocketSource
|
||||
} from '@dev-screen-starter/data'
|
||||
|
||||
export const screenDataSources = defineDataSources({
|
||||
overview: httpSource({
|
||||
url: '/api/overview',
|
||||
intervalMs: 10000,
|
||||
transform: (raw) => ({
|
||||
todayOrders: raw.today_orders,
|
||||
onlineDevices: raw.online_devices,
|
||||
alertCount: raw.alert_count
|
||||
})
|
||||
}),
|
||||
|
||||
orderTrend: httpSource({
|
||||
url: '/api/order-trend',
|
||||
intervalMs: 30000,
|
||||
transform: (raw) => ({
|
||||
categories: raw.times,
|
||||
values: raw.items.map((item) => item.count)
|
||||
})
|
||||
}),
|
||||
|
||||
alerts: websocketSource({
|
||||
url: 'ws://localhost:3000/ws/alerts',
|
||||
mode: 'append',
|
||||
maxItems: 20,
|
||||
transform: (raw) => ({
|
||||
time: raw.time,
|
||||
area: raw.area,
|
||||
status: raw.message
|
||||
})
|
||||
}),
|
||||
|
||||
deviceStatus: mqttSource({
|
||||
url: 'ws://broker.example.com/mqtt',
|
||||
topic: 'factory/device/status',
|
||||
mode: 'replace'
|
||||
}),
|
||||
|
||||
dotnetEvents: signalrSource({
|
||||
url: '/hubs/screen',
|
||||
method: 'screenEvent',
|
||||
mode: 'append',
|
||||
maxItems: 50
|
||||
}),
|
||||
|
||||
localFallback: mockSource({
|
||||
data: {
|
||||
title: '本地 mock 数据'
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
## 5. 页面消费数据源
|
||||
|
||||
```tsx
|
||||
import { useScreenDataSources } from '@dev-screen-starter/data'
|
||||
import { screenDataSources } from './dataSources'
|
||||
|
||||
export function ProjectScreen() {
|
||||
const data = useScreenDataSources(screenDataSources)
|
||||
|
||||
const overview = data.overview.data
|
||||
const alerts = data.alerts.data ?? []
|
||||
|
||||
return (
|
||||
<>
|
||||
<MetricCard label="今日订单" value={overview?.todayOrders ?? 0} unit="单" />
|
||||
<AlertList rows={alerts} />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## 6. HTTP 数据源
|
||||
|
||||
适合:
|
||||
|
||||
- 指标卡
|
||||
- 趋势图
|
||||
- 排行图
|
||||
- 低频刷新数据
|
||||
- 页面初始化数据
|
||||
|
||||
```ts
|
||||
const sources = defineDataSources({
|
||||
overview: httpSource({
|
||||
url: '/api/overview',
|
||||
intervalMs: 10000,
|
||||
transform: (raw) => ({
|
||||
orders: raw.orders,
|
||||
devices: raw.devices
|
||||
})
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
字段说明:
|
||||
|
||||
- `url`: 请求地址。
|
||||
- `init`: `fetch` 的 RequestInit 参数。
|
||||
- `intervalMs`: 轮询间隔,不传则只请求一次。
|
||||
- `immediate`: 是否立即请求,默认 `true`。
|
||||
- `transform`: 数据清洗函数。
|
||||
|
||||
## 7. WebSocket 数据源
|
||||
|
||||
适合:
|
||||
|
||||
- 实时告警
|
||||
- 订单流水
|
||||
- 设备状态
|
||||
- 秒级推送数据
|
||||
|
||||
```ts
|
||||
const sources = defineDataSources({
|
||||
alerts: websocketSource({
|
||||
url: 'ws://localhost:3000/ws/alerts',
|
||||
mode: 'append',
|
||||
maxItems: 20,
|
||||
transform: (raw) => ({
|
||||
time: raw.time,
|
||||
message: raw.message
|
||||
})
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
字段说明:
|
||||
|
||||
- `url`: WebSocket 地址。
|
||||
- `protocols`: 可选 WebSocket protocols。
|
||||
- `mode`: `replace` 或 `append`,默认 `replace`。
|
||||
- `maxItems`: `append` 模式最多保留多少条。
|
||||
- `transform`: 单条消息的清洗函数。
|
||||
|
||||
WebSocket 消息如果是字符串,会优先尝试 `JSON.parse`。如果不是 JSON,会把原始字符串传给 `transform`。
|
||||
|
||||
## 8. MQTT 数据源
|
||||
|
||||
当前已预留类型:
|
||||
|
||||
```ts
|
||||
deviceStatus: mqttSource({
|
||||
url: 'ws://broker.example.com/mqtt',
|
||||
topic: 'factory/device/status',
|
||||
mode: 'replace'
|
||||
})
|
||||
```
|
||||
|
||||
建议:
|
||||
|
||||
- 浏览器端 MQTT 通常使用 MQTT over WebSocket。
|
||||
- 如果客户现场已有 MQTT broker,可以按项目接入 MQTT SDK。
|
||||
- 如果鉴权复杂,优先让后端网关把 MQTT 转成 WebSocket,再给大屏消费。
|
||||
|
||||
## 9. SignalR 数据源
|
||||
|
||||
当前已预留类型:
|
||||
|
||||
```ts
|
||||
dotnetEvents: signalrSource({
|
||||
url: '/hubs/screen',
|
||||
method: 'screenEvent',
|
||||
mode: 'append',
|
||||
maxItems: 50
|
||||
})
|
||||
```
|
||||
|
||||
建议:
|
||||
|
||||
- 客户后端是 .NET 时再引入 SignalR SDK。
|
||||
- SignalR 适配器应只放在 `packages/data` 或客户项目的数据层,不要散落在业务组件里。
|
||||
|
||||
## 10. Demo 当前接入方式
|
||||
|
||||
当前 demo 使用 `mockSource` 模拟集中数据源:
|
||||
|
||||
```ts
|
||||
export const demoDataSources = defineDataSources({
|
||||
metrics: mockSource({ data: metrics, intervalMs: 15000 }),
|
||||
alerts: mockSource({ data: alertRows, intervalMs: 12000 }),
|
||||
operationEvents: mockSource({ data: operationEvents, intervalMs: 10000 }),
|
||||
capacityTrend: mockSource({ data: capacityTrend })
|
||||
})
|
||||
```
|
||||
|
||||
页面中统一消费:
|
||||
|
||||
```ts
|
||||
const data = useScreenDataSources(demoDataSources)
|
||||
const metrics = data.metrics.data ?? []
|
||||
const alertRows = data.alerts.data ?? []
|
||||
```
|
||||
|
||||
后续替换成真实接口时,只需要改 `dataSources.ts`,页面渲染结构可以尽量少改。
|
||||
|
||||
## 11. 推荐落地顺序
|
||||
|
||||
第一步:
|
||||
|
||||
- 使用 `mockSource` 完成页面开发。
|
||||
- 用 `transform` 提前对齐组件需要的数据结构。
|
||||
|
||||
第二步:
|
||||
|
||||
- 把初始化数据换成 `httpSource`。
|
||||
- 对接客户 REST API。
|
||||
|
||||
第三步:
|
||||
|
||||
- 把告警、设备状态、流水数据换成 `websocketSource`。
|
||||
|
||||
第四步:
|
||||
|
||||
- 项目确实需要时,再引入 MQTT 或 SignalR SDK,实现对应 adapter。
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
- `dataSources` 建议定义在组件外部,保证引用稳定。
|
||||
- 高频数据不要全部刷新整页,只更新对应数据源。
|
||||
- WebSocket 的 `append` 模式要设置 `maxItems`,避免列表无限增长。
|
||||
- 数据清洗放在 `transform`,展示组件只消费干净数据。
|
||||
- 真实项目里要补鉴权、断线重连、心跳、错误提示策略。
|
||||
+43
-12
@@ -38,11 +38,27 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
使用方式:
|
||||
|
||||
```tsx
|
||||
<ScreenStage background="#061826">
|
||||
<ScreenStage background="#061826" scaleMode="fit" debug>
|
||||
<YourScreen />
|
||||
</ScreenStage>
|
||||
```
|
||||
|
||||
`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
|
||||
|
||||
用于常规图表面板或信息区域。
|
||||
@@ -75,11 +91,16 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
当前提供:
|
||||
|
||||
- `createLineOption`:折线图,支持单序列和多序列。
|
||||
- `createAreaTrendOption`:面积趋势图。
|
||||
- `createBarOption`:柱状图,支持单序列和多序列。
|
||||
- `createStackedBarOption`:堆叠柱状图。
|
||||
- `createDualAxisOption`:双轴折线柱状图。
|
||||
- `createRankBarOption`:横向排名条。
|
||||
- `createPieOption`:饼图/环图。
|
||||
- `createRosePieOption`:玫瑰图。
|
||||
- `createGaugeOption`:仪表盘。
|
||||
- `createRadarOption`:雷达图。
|
||||
- `mergeChartOption`:在默认工厂配置基础上做局部覆盖。
|
||||
|
||||
推荐用法:
|
||||
|
||||
@@ -95,7 +116,7 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
## 4. data
|
||||
|
||||
`data` 提供轻量数据工具。
|
||||
`data` 提供统一数据源工具。一个页面可以集中声明多个数据源,并让不同组件消费同一种 `DataState<T>`。
|
||||
|
||||
### requestJson
|
||||
|
||||
@@ -105,18 +126,25 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
用于定时刷新接口数据。
|
||||
|
||||
适合:
|
||||
### useScreenDataSources
|
||||
|
||||
- 30 秒刷新指标。
|
||||
- 5 秒刷新告警。
|
||||
- 项目开发时接 mock loader。
|
||||
统一消费页面级数据源:
|
||||
|
||||
不适合:
|
||||
```tsx
|
||||
const data = useScreenDataSources(screenDataSources)
|
||||
const metrics = data.metrics.data ?? []
|
||||
```
|
||||
|
||||
- 高频毫秒级数据。
|
||||
- 大规模实时流。
|
||||
配套声明函数:
|
||||
|
||||
这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。
|
||||
- `defineDataSources`
|
||||
- `mockSource`
|
||||
- `httpSource`
|
||||
- `websocketSource`
|
||||
- `mqttSource`
|
||||
- `signalrSource`
|
||||
|
||||
其中 `mockSource`、`httpSource`、`websocketSource` 已可用;`mqttSource`、`signalrSource` 已预留类型和声明入口,具体 SDK 在客户项目需要时再接。
|
||||
|
||||
## 5. debug
|
||||
|
||||
@@ -126,8 +154,6 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
|
||||
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
|
||||
|
||||
## 6. 项目模板
|
||||
|
||||
## 6. visual-kit
|
||||
|
||||
`visual-kit` 提供轻量大屏视觉材料,不承担图表逻辑。
|
||||
@@ -137,9 +163,14 @@ Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个
|
||||
- `GlowPanel`:带轻微光感的内容面板。
|
||||
- `CornerFrame`:四角框容器。
|
||||
- `SectionTitle`:区块标题。
|
||||
- `TitleBar`:标题栏,支持右侧 action。
|
||||
- `Divider`:装饰分割线。
|
||||
- `DigitalNumber`:数字强调。
|
||||
- `FlipNumber`:数字翻牌。
|
||||
- `StatusPill`:状态标签。
|
||||
- `TrendBadge`:趋势标签。
|
||||
- `ScrollTable`:紧凑滚动表格结构。
|
||||
- `MarqueeList`:自动滚动列表。
|
||||
- `WaterLevel`:水位图。
|
||||
|
||||
推荐组合:
|
||||
|
||||
+5
-2
@@ -98,6 +98,8 @@ doc/
|
||||
- `TrendBadge`
|
||||
- `MarqueeList`
|
||||
- demo-screen 已改为使用图表工厂和 visual-kit 组合出项目型模板。
|
||||
- `ScreenStage` 已增强 debug 信息展示,支持运行时查看设计尺寸、视口尺寸、缩放模式和缩放比例。
|
||||
- demo-screen 支持通过 `?scaleMode=fit|fill|stretch|none` 验证不同屏幕适配策略。
|
||||
|
||||
后续计划:
|
||||
|
||||
@@ -126,13 +128,14 @@ doc/
|
||||
- 基础装饰组件支持 `className`、`style`、`tone`、`size` 等通用属性。
|
||||
- 图表工厂覆盖常用交付场景,并保留 ECharts 原生 option 覆盖能力。
|
||||
- demo-screen 已包含状态区、运行事件、指标卡、趋势、堆叠、排行、玫瑰、双轴、雷达和仪表盘示例。
|
||||
- `data` 包已新增统一数据源设计,支持页面集中声明 mock、HTTP、WebSocket 数据源,并预留 MQTT、SignalR 类型。
|
||||
|
||||
下一步建议:
|
||||
|
||||
- 做 `ChartPanel` 组合组件,把 `Panel + EChart + loading/empty/error` 固化下来。
|
||||
- 给 `data` 包增加 mock/real 数据源切换。
|
||||
- 给 `data` 包补 WebSocket 重连、心跳、鉴权 header/token 约定。
|
||||
- 增加 `.env.example` 和项目级接口配置约定。
|
||||
- 对 `ScreenStage` 做 1366x768、1920x1080、4K 的浏览器截图验收。
|
||||
- 对 `ScreenStage` 做更多截图验收,覆盖 1366x768、1920x1080、4K 和不同 `scaleMode`。
|
||||
|
||||
## 8. 成功标准
|
||||
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"name": "@dev-screen-starter/data",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"exports": {
|
||||
".": "./src/index.ts"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc --noEmit",
|
||||
"typecheck": "tsc --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"react": "^19.1.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/react": "^19.1.16",
|
||||
"typescript": "^5.9.2"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
export * from './usePollingData'
|
||||
export * from './useScreenDataSources'
|
||||
export * from './request'
|
||||
export * from './sources'
|
||||
export * from './types'
|
||||
@@ -0,0 +1,9 @@
|
||||
export async function requestJson<T>(url: string, init?: RequestInit): Promise<T> {
|
||||
const response = await fetch(url, init)
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`Request failed: ${response.status}`)
|
||||
}
|
||||
|
||||
return response.json() as Promise<T>
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import type {
|
||||
DataSource,
|
||||
HttpDataSource,
|
||||
MockDataSource,
|
||||
MqttDataSource,
|
||||
SignalRDataSource,
|
||||
WebSocketDataSource
|
||||
} from './types'
|
||||
|
||||
export function mockSource<Result>(source: Omit<MockDataSource<Result>, 'type'>): MockDataSource<Result> {
|
||||
return { type: 'mock', ...source }
|
||||
}
|
||||
|
||||
export function httpSource<Result, Raw = Result>(source: Omit<HttpDataSource<Result, Raw>, 'type'>): HttpDataSource<Result, Raw> {
|
||||
return { type: 'http', ...source }
|
||||
}
|
||||
|
||||
export function websocketSource<Result, Raw = Result>(
|
||||
source: Omit<WebSocketDataSource<Result, Raw>, 'type'>
|
||||
): WebSocketDataSource<Result, Raw> {
|
||||
return { type: 'websocket', ...source }
|
||||
}
|
||||
|
||||
export function signalrSource<Result, Raw = Result>(
|
||||
source: Omit<SignalRDataSource<Result, Raw>, 'type'>
|
||||
): SignalRDataSource<Result, Raw> {
|
||||
return { type: 'signalr', ...source }
|
||||
}
|
||||
|
||||
export function mqttSource<Result, Raw = Result>(source: Omit<MqttDataSource<Result, Raw>, 'type'>): MqttDataSource<Result, Raw> {
|
||||
return { type: 'mqtt', ...source }
|
||||
}
|
||||
|
||||
export function defineDataSources<TSources extends Record<string, DataSource<any, any>>>(sources: TSources): TSources {
|
||||
return sources
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
export type DataSourceType = 'mock' | 'http' | 'websocket' | 'signalr' | 'mqtt'
|
||||
|
||||
export type DataConnectionStatus = 'idle' | 'connecting' | 'open' | 'closed' | 'error'
|
||||
|
||||
export type RealtimeUpdateMode = 'replace' | 'append'
|
||||
|
||||
export type DataState<T> = {
|
||||
data: T | null
|
||||
loading: boolean
|
||||
error: string | null
|
||||
status: DataConnectionStatus
|
||||
lastUpdated?: number
|
||||
sourceType?: DataSourceType
|
||||
}
|
||||
|
||||
export type DataTransform<Raw, Result> = (raw: Raw, previous: Result | null) => Result
|
||||
|
||||
type BaseDataSource<Result, Raw = unknown> = {
|
||||
enabled?: boolean
|
||||
transform?: DataTransform<Raw, Result>
|
||||
}
|
||||
|
||||
export type MockDataSource<Result> = BaseDataSource<Result, Result> & {
|
||||
type: 'mock'
|
||||
data: Result | (() => Result)
|
||||
intervalMs?: number
|
||||
}
|
||||
|
||||
export type HttpDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
|
||||
type: 'http'
|
||||
url: string
|
||||
init?: RequestInit
|
||||
intervalMs?: number
|
||||
immediate?: boolean
|
||||
}
|
||||
|
||||
export type WebSocketDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
|
||||
type: 'websocket'
|
||||
url: string
|
||||
protocols?: string | string[]
|
||||
mode?: RealtimeUpdateMode
|
||||
maxItems?: number
|
||||
}
|
||||
|
||||
export type SignalRDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
|
||||
type: 'signalr'
|
||||
url: string
|
||||
method: string
|
||||
mode?: RealtimeUpdateMode
|
||||
maxItems?: number
|
||||
}
|
||||
|
||||
export type MqttDataSource<Result, Raw = unknown> = BaseDataSource<Result, Raw> & {
|
||||
type: 'mqtt'
|
||||
url: string
|
||||
topic: string
|
||||
mode?: RealtimeUpdateMode
|
||||
maxItems?: number
|
||||
}
|
||||
|
||||
export type DataSource<Result = unknown, Raw = unknown> =
|
||||
| MockDataSource<Result>
|
||||
| HttpDataSource<Result, Raw>
|
||||
| WebSocketDataSource<Result, Raw>
|
||||
| SignalRDataSource<Result, Raw>
|
||||
| MqttDataSource<Result, Raw>
|
||||
|
||||
export type DataSourceMap = Record<string, DataSource<any, any>>
|
||||
|
||||
export type InferDataSourceResult<TSource> = TSource extends DataSource<infer Result, any> ? Result : never
|
||||
|
||||
export type DataStates<TSources extends DataSourceMap> = {
|
||||
[Key in keyof TSources]: DataState<InferDataSourceResult<TSources[Key]>>
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
import { useEffect, useState } from 'react'
|
||||
|
||||
type PollingState<T> = {
|
||||
data?: T
|
||||
loading: boolean
|
||||
error?: string
|
||||
updatedAt?: string
|
||||
}
|
||||
|
||||
export function usePollingData<T>(loader: () => Promise<T>, intervalMs = 30000): PollingState<T> {
|
||||
const [state, setState] = useState<PollingState<T>>({ loading: true })
|
||||
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
|
||||
const run = async () => {
|
||||
try {
|
||||
const data = await loader()
|
||||
if (active) {
|
||||
setState({ data, loading: false, updatedAt: new Date().toISOString() })
|
||||
}
|
||||
} catch (error) {
|
||||
if (active) {
|
||||
setState((current) => ({
|
||||
...current,
|
||||
loading: false,
|
||||
error: error instanceof Error ? error.message : String(error)
|
||||
}))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void run()
|
||||
const timer = window.setInterval(run, intervalMs)
|
||||
|
||||
return () => {
|
||||
active = false
|
||||
window.clearInterval(timer)
|
||||
}
|
||||
}, [intervalMs, loader])
|
||||
|
||||
return state
|
||||
}
|
||||
@@ -0,0 +1,193 @@
|
||||
import { useEffect, useMemo, useState } from 'react'
|
||||
import { requestJson } from './request'
|
||||
import type { DataSource, DataSourceMap, DataState, DataStates, RealtimeUpdateMode } from './types'
|
||||
|
||||
function createInitialState(source: DataSource<unknown, unknown>): DataState<unknown> {
|
||||
return {
|
||||
data: null,
|
||||
loading: source.enabled === false ? false : true,
|
||||
error: null,
|
||||
status: source.enabled === false ? 'idle' : 'connecting',
|
||||
sourceType: source.type
|
||||
}
|
||||
}
|
||||
|
||||
function readMockValue<T>(value: T | (() => T)): T {
|
||||
return typeof value === 'function' ? (value as () => T)() : value
|
||||
}
|
||||
|
||||
function parsePayload(payload: unknown): unknown {
|
||||
if (typeof payload !== 'string') {
|
||||
return payload
|
||||
}
|
||||
|
||||
try {
|
||||
return JSON.parse(payload) as unknown
|
||||
} catch {
|
||||
return payload
|
||||
}
|
||||
}
|
||||
|
||||
function applyTransform(
|
||||
source: DataSource<unknown, unknown>,
|
||||
raw: unknown,
|
||||
previous: unknown
|
||||
): unknown {
|
||||
return source.transform ? source.transform(raw, previous) : raw
|
||||
}
|
||||
|
||||
function mergeRealtimeData(
|
||||
current: unknown,
|
||||
next: unknown,
|
||||
mode: RealtimeUpdateMode = 'replace',
|
||||
maxItems = 100
|
||||
): unknown {
|
||||
if (mode !== 'append') {
|
||||
return next
|
||||
}
|
||||
|
||||
const currentItems = Array.isArray(current) ? current : []
|
||||
const nextItems = Array.isArray(next) ? next : [next]
|
||||
|
||||
return [...nextItems, ...currentItems].slice(0, maxItems)
|
||||
}
|
||||
|
||||
function toErrorMessage(error: unknown): string {
|
||||
return error instanceof Error ? error.message : String(error)
|
||||
}
|
||||
|
||||
export function useScreenDataSources<TSources extends DataSourceMap>(sources: TSources): DataStates<TSources> {
|
||||
const sourceEntries = useMemo(() => Object.entries(sources), [sources])
|
||||
|
||||
const [states, setStates] = useState<Record<string, DataState<unknown>>>(() =>
|
||||
Object.fromEntries(sourceEntries.map(([key, source]) => [key, createInitialState(source)]))
|
||||
)
|
||||
|
||||
useEffect(() => {
|
||||
setStates(Object.fromEntries(sourceEntries.map(([key, source]) => [key, createInitialState(source)])))
|
||||
|
||||
const cleanups: Array<() => void> = []
|
||||
|
||||
for (const [key, source] of sourceEntries) {
|
||||
if (source.enabled === false) {
|
||||
continue
|
||||
}
|
||||
|
||||
const updateState = (patch: Partial<DataState<unknown>>) => {
|
||||
setStates((current) => ({
|
||||
...current,
|
||||
[key]: {
|
||||
...current[key],
|
||||
...patch,
|
||||
sourceType: source.type
|
||||
}
|
||||
}))
|
||||
}
|
||||
|
||||
const commitData = (raw: unknown, mode?: RealtimeUpdateMode, maxItems?: number) => {
|
||||
setStates((current) => {
|
||||
const previous = current[key]?.data ?? null
|
||||
const transformed = applyTransform(source, raw, previous)
|
||||
const data = source.type === 'websocket' || source.type === 'signalr' || source.type === 'mqtt'
|
||||
? mergeRealtimeData(previous, transformed, mode, maxItems)
|
||||
: transformed
|
||||
|
||||
return {
|
||||
...current,
|
||||
[key]: {
|
||||
data,
|
||||
loading: false,
|
||||
error: null,
|
||||
status: 'open',
|
||||
lastUpdated: Date.now(),
|
||||
sourceType: source.type
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
if (source.type === 'mock') {
|
||||
const run = () => commitData(readMockValue(source.data))
|
||||
run()
|
||||
|
||||
if (source.intervalMs) {
|
||||
const timer = window.setInterval(run, source.intervalMs)
|
||||
cleanups.push(() => window.clearInterval(timer))
|
||||
}
|
||||
}
|
||||
|
||||
if (source.type === 'http') {
|
||||
let active = true
|
||||
let abortController: AbortController | null = null
|
||||
|
||||
const run = async () => {
|
||||
abortController?.abort()
|
||||
abortController = new AbortController()
|
||||
updateState({ loading: true, error: null, status: 'connecting' })
|
||||
|
||||
try {
|
||||
const raw = await requestJson<unknown>(source.url, {
|
||||
...source.init,
|
||||
signal: abortController.signal
|
||||
})
|
||||
|
||||
if (active) {
|
||||
commitData(raw)
|
||||
}
|
||||
} catch (error) {
|
||||
if (active && !(error instanceof DOMException && error.name === 'AbortError')) {
|
||||
updateState({ loading: false, error: toErrorMessage(error), status: 'error' })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (source.immediate !== false) {
|
||||
void run()
|
||||
}
|
||||
|
||||
if (source.intervalMs) {
|
||||
const timer = window.setInterval(run, source.intervalMs)
|
||||
cleanups.push(() => window.clearInterval(timer))
|
||||
}
|
||||
|
||||
cleanups.push(() => {
|
||||
active = false
|
||||
abortController?.abort()
|
||||
})
|
||||
}
|
||||
|
||||
if (source.type === 'websocket') {
|
||||
if (typeof WebSocket === 'undefined') {
|
||||
updateState({ loading: false, error: 'WebSocket is not available in this runtime.', status: 'error' })
|
||||
continue
|
||||
}
|
||||
|
||||
updateState({ status: 'connecting', error: null })
|
||||
const socket = new WebSocket(source.url, source.protocols)
|
||||
|
||||
socket.addEventListener('open', () => updateState({ loading: false, status: 'open', error: null }))
|
||||
socket.addEventListener('message', (event) => {
|
||||
commitData(parsePayload(event.data), source.mode, source.maxItems)
|
||||
})
|
||||
socket.addEventListener('close', () => updateState({ loading: false, status: 'closed' }))
|
||||
socket.addEventListener('error', () => updateState({ loading: false, status: 'error', error: 'WebSocket connection error.' }))
|
||||
|
||||
cleanups.push(() => socket.close())
|
||||
}
|
||||
|
||||
if (source.type === 'signalr' || source.type === 'mqtt') {
|
||||
updateState({
|
||||
loading: false,
|
||||
status: 'idle',
|
||||
error: `${source.type} adapter is declared but not installed yet.`
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return () => {
|
||||
cleanups.forEach((cleanup) => cleanup())
|
||||
}
|
||||
}, [sourceEntries])
|
||||
|
||||
return states as DataStates<TSources>
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"jsx": "react-jsx"
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
@@ -1,16 +1,31 @@
|
||||
import { type CSSProperties, type ReactNode, useEffect, useMemo, useState } from 'react'
|
||||
import { calculateStageScale, type ScaleMode } from './scale'
|
||||
import { calculateStageScale, type ScaleMode, type StageMetrics } from './scale'
|
||||
|
||||
type ScreenStageProps = {
|
||||
width?: number
|
||||
height?: number
|
||||
scaleMode?: ScaleMode
|
||||
background?: string
|
||||
className?: string
|
||||
debug?: boolean
|
||||
children: ReactNode
|
||||
}
|
||||
|
||||
export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', background = '#061826', children }: ScreenStageProps) {
|
||||
const [viewport, setViewport] = useState({ width: window.innerWidth, height: window.innerHeight })
|
||||
const defaultViewport = () => ({
|
||||
width: typeof window === 'undefined' ? 1920 : window.innerWidth,
|
||||
height: typeof window === 'undefined' ? 1080 : window.innerHeight
|
||||
})
|
||||
|
||||
export function ScreenStage({
|
||||
width = 1920,
|
||||
height = 1080,
|
||||
scaleMode = 'fit',
|
||||
background = '#061826',
|
||||
className = '',
|
||||
debug = false,
|
||||
children
|
||||
}: ScreenStageProps) {
|
||||
const [viewport, setViewport] = useState(defaultViewport)
|
||||
|
||||
useEffect(() => {
|
||||
const onResize = () => setViewport({ width: window.innerWidth, height: window.innerHeight })
|
||||
@@ -20,6 +35,19 @@ export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', ba
|
||||
|
||||
const scale = useMemo(() => calculateStageScale({ width, height, scaleMode }, viewport.width, viewport.height), [height, scaleMode, viewport.height, viewport.width, width])
|
||||
|
||||
const metrics: StageMetrics = useMemo(
|
||||
() => ({
|
||||
designWidth: width,
|
||||
designHeight: height,
|
||||
viewportWidth: viewport.width,
|
||||
viewportHeight: viewport.height,
|
||||
scaleMode,
|
||||
scaleX: scale.scaleX,
|
||||
scaleY: scale.scaleY
|
||||
}),
|
||||
[height, scale.scaleX, scale.scaleY, scaleMode, viewport.height, viewport.width, width]
|
||||
)
|
||||
|
||||
const stageStyle: CSSProperties = {
|
||||
width,
|
||||
height,
|
||||
@@ -29,9 +57,21 @@ export function ScreenStage({ width = 1920, height = 1080, scaleMode = 'fit', ba
|
||||
|
||||
return (
|
||||
<main className="screen-viewport">
|
||||
<section className="screen-stage" style={stageStyle}>
|
||||
<section className={`screen-stage ${className}`} style={stageStyle}>
|
||||
{children}
|
||||
</section>
|
||||
{debug ? <StageDebug metrics={metrics} /> : null}
|
||||
</main>
|
||||
)
|
||||
}
|
||||
|
||||
function StageDebug({ metrics }: { metrics: StageMetrics }) {
|
||||
return (
|
||||
<aside className="screen-stage-debug">
|
||||
<span>design {metrics.designWidth}x{metrics.designHeight}</span>
|
||||
<span>viewport {metrics.viewportWidth}x{metrics.viewportHeight}</span>
|
||||
<span>mode {metrics.scaleMode}</span>
|
||||
<span>scale {metrics.scaleX.toFixed(3)} / {metrics.scaleY.toFixed(3)}</span>
|
||||
</aside>
|
||||
)
|
||||
}
|
||||
@@ -11,6 +11,16 @@ export type StageScale = {
|
||||
scaleY: number
|
||||
}
|
||||
|
||||
export type StageMetrics = {
|
||||
designWidth: number
|
||||
designHeight: number
|
||||
viewportWidth: number
|
||||
viewportHeight: number
|
||||
scaleMode: ScaleMode
|
||||
scaleX: number
|
||||
scaleY: number
|
||||
}
|
||||
|
||||
export function calculateStageScale(screen: ScreenSize, viewportWidth: number, viewportHeight: number): StageScale {
|
||||
const scaleMode = screen.scaleMode ?? 'fit'
|
||||
|
||||
|
||||
Reference in new issue
Block a user