rfkit-charts

服务于无线电监测产品的 Web 图表组件库。

• 仓库名：rfkit-charts
• npm 发布名：@rfkit/charts

安装

pnpm add @rfkit/charts

发布入口

当前对外正式入口只有两个：

• JS / TS：@rfkit/charts
• CSS bridge：@rfkit/charts/tailwind-bridge.css

默认直接从包根导入组件即可。组件运行所需样式会随包根入口自动加载，普通消费方不需要额外引 CSS。

快速开始

公开组件默认通过 ref 暴露 Publish 能力，不走 publish prop。

import { useEffect, useRef } from 'react';
import {
  ChartType,
  PSType,
  Spectrum,
  type Publish
} from '@rfkit/charts';

export function Demo() {
  const chartRef = useRef<Publish>(null);

  useEffect(() => {
    chartRef.current?.({
      pstype: PSType.Spectrum,
      data: new Float32Array([12, 28, 19, 35, 17])
    });
  }, []);

  return <Spectrum ref={chartRef} type={ChartType.SingleFrequency} />;
}

Publish 使用方式

大多数图表的数据输入都通过组件 ref 返回的 Publish 函数完成。

import { useEffect, useRef } from 'react';
import {
  Gauge,
  PSType,
  type Publish
} from '@rfkit/charts';

export function GaugeDemo() {
  const gaugeRef = useRef<Publish>(null);

  useEffect(() => {
    gaugeRef.current?.({
      pstype: PSType.Gauge,
      value: 42,
      limit: 60
    });

    gaugeRef.current?.({
      pstype: PSType.Reset
    });
  }, []);

  return <Gauge ref={gaugeRef} />;
}

常用公开类型：

• Publish
• PublishData
• PublishSpectrum
• PublishHeatmap
• PublishIQ
• PublishLevelStream
• PublishDial
• PublishGauge
• SetSeries
• SetSegments
• SetMarker

PublishDial 支持推送 series、range、yawAngle、isNorthFacing，以及可选 polygon: DialPolygon[] 绘制雷达多边形：每个多边形提供 values（各方向归一化值 0-1，长度即方向数，按 0..360 度均匀分布）、可选 color（缺省走主题主色）与可选 showDots（是否绘制顶点小圆点，缺省 true）。各方向值决定半径，连成闭合多边形，径向渐变填充 + 细描边 + 顶点圆点；series 已改为可选，纯雷达数据可以只传 polygon。

import { Dial, PSType, type Publish } from '@rfkit/charts';

const dialRef = useRef<Publish>(null);

dialRef.current?.({
  pstype: PSType.Dial,
  polygon: [{ values: [0.9, 0.6, 0.8, 0.45, 0.75, 0.5, 0.85, 0.7] }]
});

PublishSpectrum 支持推送内置频谱数据线，包括 data、maxData、minData、avgData、thresholdData、templateData、backgroundNoiseData 和 extraData。thresholdData 不传 segmentOffset / offset 时按整条门限替换；传入 segmentOffset 或 offset 时按局部门限写入。

extraData 默认保持完整数组设置语义；设置 segmentedExtraData: true 后，同一次推送中的每条额外频谱线会独立使用 segmentOffset + offset 拼接，并随主实时值同步缩放。

信号标注接入

信号标注数据由业务项目负责适配，图表只接收内部结构。有业务颜色时按约定传入，没有显式颜色时使用内置类型色。

import { PSType, SignalDataType } from '@rfkit/charts';

// 业务侧先把外部信号数据适配成 charts 内部结构（StationInfoType[] / SignalData[]）
publish({ pstype: PSType.Signal, type: SignalDataType.Station, data: stationData });
publish({ pstype: PSType.Signal, type: SignalDataType.Simple, data: simpleData });

同一来源后续发布会替换上一批数据，发布空数组可单独清空该来源。SignalData.details 可传入 name、organization、modulation 和 remark；频谱游标命中台站库或信号库时会展示两者共有的详情，合法信号库数据额外显示等级。

树形筛选默认在台站库、信号库、类型和等级节点后显示当前发布数据的数量；业务侧可通过 signal={{ showCount: false }} 关闭数量显示，筛选和数据本身不受影响。

内置颜色直接复用主题的 success、primary、warning、destructive 和 mutedForeground 语义 token；需要整体调整时通过 initChartsTheme({ tokens: { semantic: ... } }) 覆盖，单条业务标注仍使用 color 覆盖。

筛选树与游标详情直接使用类型或等级文字表达颜色，不再额外显示色点。信号库的“合法”父级保持中性文字，具体等级文字与图上标注颜色一致；其他类型文字与对应标注颜色一致。单条数据传入 color 时仍保持最高优先级；rgba(...) 的透明度只作用于图上标注，文字使用相同 RGB 色相的不透明颜色保证可读性。

台站数据需要提供 startFrequency / stopFrequency（也可以由 MHz 中心频率和 kHz 带宽在业务侧计算）。

独立 Heatmap 可以显式开启 X/Y 同步缩放：

<Heatmap
  ref={heatmapRef}
  zoom={{ xy: true, overview: { show: true } }}
/>

开启后，滚轮会围绕指针位置同步缩放频率列和时间行，左键拖拽会同时平移两个方向。overview.show 会在发生缩放后于右上角以小尺寸半透明悬浮显示全量瀑布缩略图，恢复全景后自动隐藏且不改变主图布局；点击空白区域居中、拖动视口框平移，双击主图或 Overview 恢复全景。框选边界越出视口时可通过主图边缘代理手柄继续调整；完全离开视口时可点击 Overview 中的虚线框定位，二者均不会自动改变框选或缩放倍率。外部也可以调用 heatmapRef.current?.resetViewport?.() 恢复完整 XY 范围。

这些开关默认关闭，只作用于独立 Heatmap；Spectrum 组合使用的 HeatmapPortal 仍由频谱图统一控制，不显示 Overview，也不注册单独的缩放操作。

工具栏相关命名统一使用：

• 工具栏枚举使用 ToolbarItemType
• 组件参数使用 toolbar

主题接入

charts 只读取根节点上的两个契约：

• theme="light" | "dark"
• theme-follow-OS="true" | "false"

应用层直接写这两个属性即可：

document.documentElement.setAttribute('theme', 'dark');
document.documentElement.setAttribute('theme-follow-OS', 'false');

如果宿主已经在用 @rfkit/theme，通常不需要额外迁移，因为它写的也是同一套根契约。

initChartsTheme()

initChartsTheme() 现在只承担三件事：

• 覆盖 charts 默认 tokens
• 覆盖默认 sizes
• 通过 onChange 订阅解析后的主题状态

import { initChartsTheme } from '@rfkit/charts';

initChartsTheme({
  onChange: ({ followOS, theme, contractTheme }) => {
    console.log(followOS, theme, contractTheme);
  },
  tokens: {
    semantic: {
      primary: {
        light: '#2A51F7',
        dark: '#4371F8'
      }
    }
  },
  sizes: {
    spacing: {
      base: {
        middle: '8px',
        small: '4px'
      }
    }
  }
});

读取和订阅主题状态

import {
  getChartsThemeState,
  subscribeChartsThemeChange
} from '@rfkit/charts';

const state = getChartsThemeState();
console.log(state.theme, state.preference);

const cleanup = subscribeChartsThemeChange((nextState) => {
  console.log(nextState.followOS, nextState.contractTheme);
});

cleanup();

tailwind-bridge.css

只有当宿主自己也在用 Tailwind CSS v4 + shadcn/ui，并且想复用 charts 的 canonical token 时，才需要额外引入：

@import "tailwindcss";
@import "@rfkit/charts/tailwind-bridge.css";

这份 bridge 的边界是：

• 只做 canonical charts token 到 Tailwind / shadcn 语义色板的映射
• 不包含全局 reset
• 不再兜底旧 --theme-* 变量
• 不负责替宿主生成 :root 上的 canonical token

文档边界

• 精确公开 API 以 @rfkit/charts 包根导出的类型声明为准。
• npm 打包产物只同步根 README.md。