rfkit-charts

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

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

安装

pnpm add @rfkit/charts

正式版本由源码仓库内的 Release PR 自动发布到 npm；仓库里的本地 publish:* 脚本只作为维护调试或应急入口，不属于常规发布流程。

发布入口

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

• 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

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

• 工具栏枚举使用 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：

• 任意 src/** 源码路径
• test/** preview / example 宿主
• 仓库内部工程文档

主题变更摘要

当前主题系统已经完成二阶段收口，外部需要注意的 breaking change 主要有：

• initChartsTheme() 不再接受 themeConfigs / sizeConfigs / subscribeThemeChange
• 新配置入口改为 tokens / sizes / onChange
• applyChartsTheme() 与 applyChartsThemePreference() 已移除
• 默认运行时不再输出旧 --theme-* alias
• @rfkit/charts/tailwind-bridge.css 不再暴露 deprecated bridge token

文档边界

• 对外安装、接入方式、主题契约和常用用法以本文为准。
• 精确公开 API 以 @rfkit/charts 包根导出的类型声明和编辑器智能提示为准。
• npm 打包产物只同步根 README.md，不会把仓库内的 docs/* 一并作为公开文档入口发布。
• 仓库内部专题文档只在源码仓库内维护，不属于发布包对外文档入口。