npm package: @rfkit/charts
Description: a chart library based on all
Author: Hxgh
Latest version: 1.4.0

# rfkit-charts

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

## 安装

```shell
pnpm add @rfkit/charts
```

## 主题与 Tailwind 集成

默认情况下，消费方只需要安装并直接使用组件：

```ts
import { Spectrum } from '@rfkit/charts';
```

本库发布产物已经默认携带新 UI 所需的样式，并会自动注入 charts 侧需要的主题 / 尺寸变量定义。外部项目不需要再额外引入 `tailwind-bridge.css` 才能让组件正常显示。

也就是说，默认推荐接法仍然是：

```ts
import { Spectrum } from '@rfkit/charts';
```

如果你的应用已经在使用 `@rfkit/theme`，接法也不需要改。charts 会只读根节点上的这两个契约标识：

- `theme`
- `theme-follow-OS`

也就是说，外部继续这样初始化即可：

```ts
import {
  initTheme,
  toggleTheme,
  toggleThemeMode
} from '@rfkit/theme';

initTheme();
toggleTheme();
toggleThemeMode();
```

`initChartsTheme()` 现在主要用于两个场景：

- 你想覆盖 charts 默认的 `themeConfigs` / `sizeConfigs`
- 你想通过 `subscribeThemeChange` 订阅 charts 解析后的主题状态

只有在外部项目自己也使用 `Tailwind CSS v4 + shadcn/ui`，并且希望复用本库这套语义 token 时，才需要额外引入 bridge：

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

说明：

- 默认包入口已经自动携带组件运行所需样式，并自动注入 charts 侧默认主题 / 尺寸变量
- charts 默认只读取 `theme` / `theme-follow-OS`，不再把自己当主题真源
- `@rfkit/charts/tailwind-bridge.css` 只提供 Tailwind/shadcn 语义 token 复用能力，不包含全局 reset
- 如果外部项目继续使用 `@rfkit/theme` 的 `initTheme()` / `toggleTheme()` / `toggleThemeMode()`，charts 会自动跟随刷新
- 更完整的主题桥接说明见 [docs/theme-migration.md](/Users/hugh/workspace/github/rfkit-charts/docs/theme-migration.md)

更多项目说明见：[docs/README.md](/Users/hugh/workspace/github/rfkit-charts/docs/README.md)

## 基本使用

```jsx
import {
  // 频谱图
  Spectrum,
  LevelStream,
  // IQ图
  IQ,
  // 仪表图
  Gauge,
  Dial,
  // 辅助图形
  Heatmap,
  Occupancy,
} from '@rfkit/charts';

// 行为推送
const publishRef = useRef(null);
const handlePublishChange = (publish) => {
  publishRef.current? = publish;
};

// 图表类型
export enum ChartType {
  // 频谱图
  SingleFrequency = 'singleFrequency',
  Scan = 'scan',
  MScan = 'mscan',
  ScanDF360 = 'ScanDF360',
  DDC = 'ddc',
  Lite = 'lite',
  LiteNormalized = 'liteNormalized',
  LevelStream = 'levelStream',
  // IQ图
  IQEye = 'iqEye',
  IQLine = 'iqLine',
  IQPlanisphere = 'iqPlanisphere',
  IQStream = 'iqStream',
  // 辅助图形
  Heatmap = 'heatmap',
  Occupancy = 'occupancy',
}

// 频谱图
<Spectrum type="singleFrequency" publish={handlePublishChange} /> // 单频频谱
<Spectrum type="scan" publish={handlePublishChange} /> // 扫描频谱
<Spectrum type="scanDF360" publish={handlePublishChange} /> // 扫描测向概率统计
<Spectrum type="ddc" publish={handlePublishChange} channel onChannelChange /> // DCC
<Spectrum type="lite" publish={handlePublishChange} /> // 精简模式
<Spectrum type="liteNormalized" publish={handlePublishChange} /> // 精简模式（Y轴范围0-1）

// DDC特殊参数
export interface Props {
  channel?: number; // 默认32
  onChannelChange?: (c: {
    frequency: number;
    type: MarkerEventType;
    list: number[];
  }) => void;
}

// 电平瀑布图
<LevelStream />

// IQ类型
<IQ type={ChartType} publish={handlePublishChange} />

// 仪表盘
<Gauge publish={handlePublishChange} />
<Dial axisY={{range}} onChange={onChange} publish={handlePublishChange} />
```

**publish（行为推送工具）**

```typescript
export enum PSType {
  // 频谱数据
  SPECTRUM = 'spectrum',
  // 天线因子数据
  ANTENNA_FACTOR = 'antennaFactor',
  // 占用度数据
  OCCUPANCY = 'occupancy',
  // 电平流数据
  LEVEL_STREAM = 'levelStream',
  // 瀑布图数据
  HEATMAP = 'heatmap',
  // IQ数据
  IQ = 'IQ',
  // 示向度盘
  DIAL = 'dial',
  // 刻度尺
  GAUGE = 'gauge',

  // 频谱线属性
  SERIES = 'series',
  // 频谱带宽规则：一般用于单频频谱
  SPECTRUM_BANDWIDTH = 'spectrumBandwidth',
  // 多段扫描规则：一般用于扫描数据的多段组合
  SEGMENTS = 'segments',
  // 多路DCC
  CHANNELS = 'channels',
  // Marker
  MARKER = 'marker',

  // 图形操作
  RESET = 'reset',
}

// 系列配置
interface SeriesConfig {
  readonly name: string;
  // 内外可设置属性
  label?: string;
  color?: string;
}

// 推送频谱线属性
export interface SetSeries extends SeriesConfig {
  pstype: PSType.Series;
}

// 设置频谱带宽规则
export interface SetSpectrumBandwidth extends SpectrumBandwidth {
  pstype: PSType.SpectrumBandwidth;
}

// 设置多段扫描规则
export interface SetSegments {
  pstype: PSType.Segments;
  event?: SegmentsEvent; // 事件类型：默认覆盖数据
  data?: SegmentsOriginal[]; // 多段扫描规则：设置数据才使用
  index?: number; // 段索引：需要外部聚焦某段才使用
}

// 设置天线因子
export interface SetAntennaFactor {
  pstype: PSType.AntennaFactor;
  data: Float32Array;
}

// 设置台站库信息
export interface SetStationInfo {
  pstype: PSType.StationInfo;
  data: StationInfoType[];
}

// 设置多路DCC信道
export interface SetChannels {
  pstype: PSType.Channels;
  event: MarkerEventType;
  frequency?: number;
}

// 设置Marker
export interface SetMarker {
  pstype: PSType.Marker;
  event: MarkerEventType;
  marker?: Partial<MarkerType>;
  frequencies?: number[]; // 设计规定：frequencies必须是频率数据
  silent?: boolean; // 是否通知外部onChange回调
}

// 额外的频谱数据
export interface SpectrumExtraData {
  [key: string]: Float32Array;
}
// 推送频谱数据
export interface PublishSpectrum {
  pstype: PSType.Spectrum;
  data?: Float32Array;
  // 一般仅在静态绘制
  maxData?: Float32Array;
  minData?: Float32Array;
  avgData?: Float32Array;
  backgroundNoiseData?: Float32Array;
  templateData?: Float32Array;
  extraData?: SpectrumExtraData;
  // 瀑布图可选参数
  timestamp?: string;
  // 扫描可选参数
  offset?: number; // 当前段的点偏移量
  segmentOffset?: number; // 当前段的索引
}

// 推送瀑布图数据
export interface PublishHeatmap {
  pstype: PSType.Heatmap;
  data: TimestampedFloat32Array[];
  timestamps: number[];
}

// 推送占用度数据
export interface PublishOccupancy {
  pstype: PSType.Occupancy;
  data: Float32Array;
  totalOccupancy: number;
}

// 推送电平流数据
export interface PublishLevelStream {
  pstype: PSType.LevelStream;
  data: number;
}

// 推送IQ数据
export interface PublishIQ {
  pstype: PSType.IQ;
  IData: number[];
  Qdata: number[];
}

// 推送Dial数据
export interface PublishDial {
  pstype?: PSType.Dial;
  series: Array<{
    value: number;
    color: string;
  }>;
  range?: number[]; // 概率范围 0-360
  yawAngle?: number; // 偏航角 0-360
  isNorthFacing?: boolean; // 是否朝北
}

// 推送Gauge数据
export interface PublishGauge {
  pstype?: PSType.Gauge;
  value: number; // 值
  limit: number; // 门限值
}

// 推送图形操作
export interface Reset {
  pstype: PSType.Reset;
}

// 推送渲染数据（内部）
export interface Render {
  pstype: PSType.Render;
  [key: string]: unknown;
}

export type PublishData =
  | SetSeries
  | SetSpectrumBandwidth
  | SetSegments
  | SetChannels
  | SetMarker
  | SetAntennaFactor
  | PublishSpectrum
  | PublishHeatmap
  | PublishOccupancy
  | PublishLevelStream
  | PublishIQ
  | PublishDial
  | PublishGauge
  | Reset
  | Render;
```