transone-chart 0.1.2

package/lib/core/scale.ts

@@ -0,0 +1,183 @@
+/**
+ * 比例尺：把数据域（domain）映射到像素范围（range）。
+ *
+ * - LinearScale：数值 → 像素，自动 nice 刻度（0.5 / 1 / 2 / 5 步进）
+ * - CategoryScale：类目索引 → 像素带（band），供柱状图计算柱宽
+ *
+ * 纯函数与轻量类实现，零平台依赖，便于单元测试。
+ */
+
+/** 数值域映射接口。 */
+export interface LinearScaleOptions {
+  /** 数据最小值（未指定则按数据自动 nice）。 */
+  min?: number;
+  /** 数据最大值（未指定则按数据自动 nice）。 */
+  max?: number;
+  /** 期望刻度分段数，默认 5。 */
+  splitCount?: number;
+}
+
+export interface ScaleResult {
+  /** 映射后的像素坐标（已夹取到 range 内）。 */
+  scale(value: number): number;
+  /** nice 后的实际最小值。 */
+  min: number;
+  /** nice 后的实际最大值。 */
+  max: number;
+  /** 刻度值数组（含 min/max）。 */
+  ticks: number[];
+}
+
+/**
+ * 计算 nice 刻度：把任意 [min, max] 数据范围规整为"美观"范围与刻度。
+ * 步进从 1 / 2 / 5 × 10^n 中选择，保证刻度间距整齐。
+ */
+export function niceTicks(
+  rawMin: number,
+  rawMax: number,
+  splitCount = 5
+): { min: number; max: number; step: number; ticks: number[] } {
+  let min = rawMin;
+  let max = rawMax;
+
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    throw new Error('niceTicks: domain must be finite numbers');
+  }
+  if (min === max) {
+    // 常量数据：人为撑开一个单位区间，避免除以零
+    const pad = Math.abs(min) > 1 ? Math.abs(min) * 0.1 : 1;
+    min -= pad;
+    max += pad;
+  }
+  if (min > max) {
+    [min, max] = [max, min];
+  }
+
+  const span = max - min;
+  const roughStep = span / Math.max(1, splitCount);
+  const step = niceStep(roughStep);
+
+  const niceMin = Math.floor(min / step) * step;
+  const niceMax = Math.ceil(max / step) * step;
+
+  const ticks: number[] = [];
+  for (let v = niceMin; v <= niceMax + step * 1e-9; v += step) {
+    // 浮点误差收敛：四舍五入到 step 的小数位数
+    ticks.push(roundToStep(v, step));
+  }
+
+  return { min: niceMin, max: niceMax, step, ticks };
+}
+
+function niceStep(rough: number): number {
+  const power = Math.pow(10, Math.floor(Math.log10(rough)));
+  const fraction = rough / power;
+  let niceFraction: number;
+  if (fraction <= 1) {
+    niceFraction = 1;
+  } else if (fraction <= 2) {
+    niceFraction = 2;
+  } else if (fraction <= 5) {
+    niceFraction = 5;
+  } else {
+    niceFraction = 10;
+  }
+  return niceFraction * power;
+}
+
+function roundToStep(value: number, step: number): number {
+  const decimals = Math.max(0, -Math.floor(Math.log10(step)) + 1);
+  return Number(value.toFixed(decimals));
+}
+
+/** 线性比例尺：domain → [rangeStart, rangeEnd]，自动 nice。 */
+export class LinearScale {
+  public readonly min: number;
+  public readonly max: number;
+  public readonly ticks: number[];
+  public readonly step: number;
+
+  private readonly rangeStart: number;
+  private readonly rangeEnd: number;
+
+  public constructor(
+    dataMin: number,
+    dataMax: number,
+    rangeStart: number,
+    rangeEnd: number,
+    options: LinearScaleOptions = {}
+  ) {
+    const { min: explicitMin, max: explicitMax, splitCount = 5 } = options;
+
+    let min = explicitMin;
+    let max = explicitMax;
+
+    if (min === undefined || max === undefined) {
+      const auto = niceTicks(dataMin, dataMax, splitCount);
+      min = min ?? auto.min;
+      max = max ?? auto.max;
+      this.ticks = auto.ticks;
+      this.step = auto.step;
+    } else {
+      this.step = (max - min) / Math.max(1, splitCount);
+      this.ticks = [];
+      for (let i = 0; i <= splitCount; i += 1) {
+        this.ticks.push(min + i * this.step);
+      }
+    }
+
+    this.min = min;
+    this.max = max;
+    this.rangeStart = rangeStart;
+    this.rangeEnd = rangeEnd;
+  }
+
+  /** 数值 → 像素坐标（反向轴传 rangeEnd > rangeStart 即自然反转）。 */
+  public scale(value: number): number {
+    const ratio = (value - this.min) / (this.max - this.min);
+    return this.rangeStart + ratio * (this.rangeEnd - this.rangeStart);
+  }
+}
+
+/** 类目比例尺：N 个类目 → range 内均分带（band）。 */
+export class CategoryScale {
+  /** 每个类目带的像素宽度。 */
+  public readonly bandWidth: number;
+  /** 类目带之间的间距占比（0~1），默认 0.35。 */
+  public readonly innerGapRatio: number;
+
+  private readonly rangeStart: number;
+
+  public constructor(
+    public readonly categories: readonly unknown[],
+    rangeStart: number,
+    rangeEnd: number,
+    innerGapRatio = 0.35
+  ) {
+    this.innerGapRatio = innerGapRatio;
+    this.rangeStart = rangeStart;
+    const count = Math.max(1, categories.length);
+    this.bandWidth = (rangeEnd - rangeStart) / count;
+  }
+
+  /** 第 index 个类目的带起始（绝对像素坐标）。 */
+  public bandStart(index: number): number {
+    return this.rangeStart + this.bandWidth * index;
+  }
+
+  /** 第 index 个类目的带中心（绝对像素坐标）。 */
+  public center(index: number): number {
+    return this.bandStart(index) + this.bandWidth / 2;
+  }
+
+  /** 可用绘图宽度 = 带宽 × (1 - innerGapRatio)。 */
+  public innerWidth(): number {
+    return this.bandWidth * (1 - this.innerGapRatio);
+  }
+
+  /** 每组（多系列）子柱宽度：按系列数均分可用宽度，并预留 20% 间隙。 */
+  public groupInnerWidth(groupCount: number): number {
+    const usable = this.innerWidth();
+    return usable / Math.max(1, groupCount) * 0.8;
+  }
+}

package/lib/core/text.ts

@@ -0,0 +1,70 @@
+/**
+ * 文字辅助：统一的 font 字符串拼接与文本测量。
+ * 所有测量都走 ICanvas2D.measureText，保证跨端一致。
+ */
+
+import type { ICanvas2D } from './canvas';
+import { DEFAULT_FONT_FAMILY } from '../types';
+
+export interface TextStyle {
+  fontSize?: number;
+  family?: string;
+}
+
+/** 构造 canvas font 字符串（小程序与 Web 语义一致）。 */
+export function toFont(size: number, family = DEFAULT_FONT_FAMILY): string {
+  return `${size}px ${family}`;
+}
+
+/** 设置当前文字样式并返回 font 字符串。 */
+export function applyFont(
+  ctx: ICanvas2D,
+  size: number,
+  family = DEFAULT_FONT_FAMILY
+): string {
+  const font = toFont(size, family);
+  ctx.font = font;
+  return font;
+}
+
+/** 测量文本宽度（自动设置 font）。 */
+export function measureWidth(
+  ctx: ICanvas2D,
+  text: string,
+  fontSize: number,
+  family = DEFAULT_FONT_FAMILY
+): number {
+  applyFont(ctx, fontSize, family);
+  return ctx.measureText(text).width;
+}
+
+/**
+ * 截断文本到指定像素宽度（超宽加省略号）。
+ * 用于类目轴标签过长时避免溢出绘图区。
+ */
+export function truncate(
+  ctx: ICanvas2D,
+  text: string,
+  maxWidth: number,
+  fontSize: number,
+  family = DEFAULT_FONT_FAMILY
+): string {
+  if (maxWidth <= 0 || measureWidth(ctx, text, fontSize, family) <= maxWidth) {
+    return text;
+  }
+  const ellipsis = '…';
+  let lo = 0;
+  let hi = text.length;
+  let result = text;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const candidate = text.slice(0, mid) + ellipsis;
+    if (measureWidth(ctx, candidate, fontSize, family) <= maxWidth) {
+      result = candidate;
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return result;
+}

package/lib/factory.ts

@@ -0,0 +1,62 @@
+/**
+ * 图表工厂：按 option.type 分发到具体图表策略类（策略模式入口）。
+ *
+ * 用法（Web）：
+ *   const chart = createWebChart(canvasEl, { type: 'line', ... });
+ *   chart.render();
+ *
+ * 用法（小程序，页面 onReady 后）：
+ *   const node = await getMiniProgramCanvasNode({ selector: '#chart' });
+ *   const chart = createMiniProgramChart(node, option);
+ *   chart.render();
+ */
+
+import type { ChartOption, ChartRenderContext } from './types';
+import type { ChartBase } from './core/chart';
+import { LineChart } from './charts/line';
+import { BarChart } from './charts/bar';
+import { PieChart } from './charts/pie';
+import { RadarChart } from './charts/radar';
+import { resolveMiniProgramCanvas } from './adapters/miniprogram';
+import type { MiniProgramCanvasNode } from './adapters/miniprogram';
+import { resolveWebCanvas } from './adapters/web';
+import type { ResolveCanvasOptions } from './adapters/types';
+
+/** 按类型创建图表实例（引擎核心入口）。 */
+export function createChart<T extends ChartOption>(
+  context: ChartRenderContext,
+  option: T
+): ChartBase<T> {
+  switch (option.type) {
+    case 'line':
+      return new LineChart(context, option) as unknown as ChartBase<T>;
+    case 'bar':
+      return new BarChart(context, option) as unknown as ChartBase<T>;
+    case 'pie':
+      return new PieChart(context, option) as unknown as ChartBase<T>;
+    case 'radar':
+      return new RadarChart(context, option) as unknown as ChartBase<T>;
+    default:
+      throw new Error(
+        `createChart: unsupported chart type "${(option as ChartOption).type}"`
+      );
+  }
+}
+
+/** Web 便捷入口：从 HTMLCanvasElement 直接创建并渲染。 */
+export function createWebChart<T extends ChartOption>(
+  canvas: HTMLCanvasElement,
+  option: T,
+  resolveOptions: ResolveCanvasOptions = {}
+): ChartBase<T> {
+  return createChart(resolveWebCanvas(canvas, resolveOptions), option);
+}
+
+/** 小程序便捷入口：从 Canvas 2D 节点直接创建并渲染。 */
+export function createMiniProgramChart<T extends ChartOption>(
+  node: MiniProgramCanvasNode,
+  option: T,
+  resolveOptions: ResolveCanvasOptions = {}
+): ChartBase<T> {
+  return createChart(resolveMiniProgramCanvas(node, resolveOptions), option);
+}

package/lib/index.ts

@@ -0,0 +1,69 @@
+/**
+ * transone-chart：TransOne 跨端图表库。
+ *
+ * 一份 TypeScript 源码，基于 Canvas 2D 渲染：
+ * - Web：HTMLCanvasElement 直接可用
+ * - 小程序：微信 / 阿里 / 字节 Canvas 2D 节点
+ * - 未来原生 App：实现 ICanvas2D 契约即可接入（见 adapters/native.ts）
+ *
+ * 一期图表：折线 / 柱状 / 饼图 / 雷达。
+ */
+
+// 公共类型与默认主题
+export * from './types';
+
+// 核心：跨端 Canvas 契约
+export type { ICanvas2D, IGradient } from './core/canvas';
+export { isCanvas2DLike } from './core/canvas';
+export type {
+  CanvasLineCap,
+  CanvasLineJoin,
+  CanvasTextAlign,
+  CanvasTextBaseline,
+} from './core/canvas';
+
+// 比例尺
+export { LinearScale, CategoryScale, niceTicks } from './core/scale';
+export type { LinearScaleOptions, ScaleResult } from './core/scale';
+
+// 布局
+export { computeLayout } from './core/layout';
+export type { Box, LayoutInput, LayoutResult, Padding } from './core/layout';
+
+// 图表基类
+export { ChartBase } from './core/chart';
+export type { CartesianScales } from './core/chart';
+
+// 四种图表
+export { LineChart } from './charts/line';
+export { BarChart } from './charts/bar';
+export { PieChart } from './charts/pie';
+export { RadarChart } from './charts/radar';
+
+// 工厂入口
+export {
+  createChart,
+  createWebChart,
+  createMiniProgramChart,
+} from './factory';
+
+// 适配器
+export {
+  resolveWebCanvas,
+  resolveMiniProgramCanvas,
+  getMiniProgramCanvasNode,
+  getMiniProgramGlobal,
+  detectMiniProgramPixelRatio,
+  detectPixelRatio,
+  resolveNativeCanvas,
+} from './adapters';
+export type {
+  MiniProgramCanvasNode,
+  MiniProgramGlobal,
+  NativeCanvasHost,
+  ResolveCanvasOptions,
+} from './adapters';
+
+// 可选组件集成（依赖 transone）
+export { TcChart } from './component';
+export type { TcChartProps } from './component';

package/lib/types.ts

@@ -0,0 +1,218 @@
+/**
+ * transone-chart 公共类型定义。
+ *
+ * 所有图表共用一份 Option 风格配置（对齐 ECharts 心智：xAxis / yAxis /
+ * series / legend / title），但实现零依赖、纯 Canvas 2D 绘制。
+ */
+
+/** 一期支持的图表类型。 */
+export type ChartType = 'line' | 'bar' | 'pie' | 'radar';
+
+/** 默认主题色板（与 transone-ui 主色一致，可按需覆盖）。 */
+export const DEFAULT_PALETTE: readonly string[] = [
+  '#1677ff',
+  '#00b578',
+  '#ff8f1f',
+  '#ff3141',
+  '#eb2f96',
+  '#722ed1',
+  '#13c2c2',
+  '#faad14',
+  '#2f54eb',
+  '#a0d911',
+];
+
+export const DEFAULT_TEXT_COLOR = '#323233';
+export const DEFAULT_AXIS_COLOR = '#c8c9cc';
+export const DEFAULT_GRID_COLOR = '#ebedf0';
+export const DEFAULT_FONT_FAMILY =
+  "-apple-system, BlinkMacSystemFont, 'Helvetica Neue', 'PingFang SC', 'Microsoft YaHei', sans-serif";
+
+/** 标题配置。 */
+export interface TitleOption {
+  text: string;
+  fontSize?: number;
+  color?: string;
+  /** 标题与绘图区之间的留白，默认 16。 */
+  padding?: number;
+}
+
+/** 图例配置。 */
+export interface LegendOption {
+  show?: boolean;
+  /** 图例位置：顶部横向 / 底部横向 / 右侧纵向。 */
+  position?: 'top' | 'bottom' | 'right';
+  fontSize?: number;
+  color?: string;
+  /** 图例色块边长（正方形），默认 12。 */
+  markerSize?: number;
+  /** 图例项之间的水平间距，默认 16。 */
+  itemGap?: number;
+}
+
+/** 数值轴（y 轴/雷达数值）配置。 */
+export interface ValueAxisOption {
+  /** 显式最小值；缺省自动 nice。 */
+  min?: number;
+  /** 显式最大值；缺省自动 nice。 */
+  max?: number;
+  /** 刻度分段数，默认 5。 */
+  splitCount?: number;
+  labelFontSize?: number;
+  labelColor?: string;
+  gridColor?: string;
+  gridLineWidth?: number;
+  /** 网格虚线，如 [4, 4]；默认实线。 */
+  gridLineDash?: number[];
+  /** 是否显示网格，默认 true。 */
+  showGrid?: boolean;
+  /** 刻度标签格式化。 */
+  format?: (value: number) => string;
+}
+
+/** 类目轴（x 轴/雷达指标）配置。 */
+export interface CategoryAxisOption {
+  labels: readonly string[];
+  labelFontSize?: number;
+  labelColor?: string;
+  gridColor?: string;
+  gridLineWidth?: number;
+  /** 是否显示类目网格竖线，默认 false。 */
+  showGrid?: boolean;
+}
+
+/** —— 折线图 —— */
+
+export interface LineSeries {
+  name?: string;
+  data: readonly number[];
+  color?: string;
+  /** 平滑曲线（三次贝塞尔插值），默认 false。 */
+  smooth?: boolean;
+  /** 是否填充系列与数值轴之间的面积，默认 false。 */
+  area?: boolean;
+  /** 是否绘制数据点标记，默认 true。 */
+  showSymbol?: boolean;
+  lineWidth?: number;
+}
+
+export interface LineChartOption {
+  type: 'line';
+  title?: TitleOption;
+  legend?: LegendOption;
+  xAxis: CategoryAxisOption;
+  yAxis?: ValueAxisOption;
+  series: readonly LineSeries[];
+  /** 数值轴是否从 0 开始（数据全为正时强制含 0），默认 false（按数据范围紧凑显示）。 */
+  startFromZero?: boolean;
+  /** 背景色（如 'rgba(22,119,255,0.06)'），默认无。 */
+  backgroundColor?: string;
+}
+
+/** —— 柱状图 —— */
+
+export interface BarSeries {
+  name?: string;
+  data: readonly number[];
+  color?: string;
+  /** 堆叠组名；同名系列纵向堆叠。 */
+  stack?: string;
+  /** 柱体宽度（px），缺省按类目带自动计算。 */
+  barWidth?: number;
+  /** 柱体圆角，默认 0。 */
+  borderRadius?: number;
+}
+
+export interface BarChartOption {
+  type: 'bar';
+  title?: TitleOption;
+  legend?: LegendOption;
+  xAxis: CategoryAxisOption;
+  yAxis?: ValueAxisOption;
+  series: readonly BarSeries[];
+  /** 横向柱状图（类目轴转纵向、数值轴转横向），默认 false。 */
+  horizontal?: boolean;
+  backgroundColor?: string;
+}
+
+/** —— 饼图 —— */
+
+export interface PieDatum {
+  name: string;
+  value: number;
+  color?: string;
+}
+
+export interface PieChartOption {
+  type: 'pie';
+  data: readonly PieDatum[];
+  title?: TitleOption;
+  legend?: LegendOption;
+  /** 外半径：数字（px）或百分比字符串（相对 min(width, height) / 2），默认 '60%'。 */
+  radius?: number | string;
+  /** 内半径：0 为饼图；>0 为环形图，默认 0。 */
+  innerRadius?: number | string;
+  /** 是否显示扇区标签（名称 + 百分比），默认 true。 */
+  showLabel?: boolean;
+  labelFontSize?: number;
+  labelColor?: string;
+  /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
+  startAngle?: number;
+  backgroundColor?: string;
+}
+
+/** —— 雷达图 —— */
+
+export interface RadarIndicator {
+  name: string;
+  /** 指标最大值；缺省取所有系列该指标的最大值。 */
+  max?: number;
+}
+
+export interface RadarSeries {
+  name?: string;
+  data: readonly number[];
+  color?: string;
+  /** 是否填充多边形区域，默认 true。 */
+  area?: boolean;
+  lineWidth?: number;
+}
+
+export interface RadarChartOption {
+  type: 'radar';
+  indicators: readonly RadarIndicator[];
+  series: readonly RadarSeries[];
+  title?: TitleOption;
+  legend?: LegendOption;
+  /** 网格层数，默认 5。 */
+  splitCount?: number;
+  gridColor?: string;
+  gridLineWidth?: number;
+  labelFontSize?: number;
+  labelColor?: string;
+  /** 雷达中心半径（px），缺省取 min(width, height) / 2 的 60%。 */
+  radius?: number;
+  /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
+  startAngle?: number;
+  backgroundColor?: string;
+}
+
+export type ChartOption =
+  | LineChartOption
+  | BarChartOption
+  | PieChartOption
+  | RadarChartOption;
+
+/** 图表渲染上下文（适配器解析后的产物）。 */
+export interface ChartRenderContext {
+  /** 跨端 Canvas 2D 上下文。 */
+  ctx: import('./core/canvas').ICanvas2D;
+  /** 逻辑宽度（CSS px）。 */
+  width: number;
+  /** 逻辑高度（CSS px）。 */
+  height: number;
+  /** 设备像素比。 */
+  dpr: number;
+  /** 自定义色板，缺省使用 DEFAULT_PALETTE。 */
+  palette?: readonly string[];
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "transone-chart",
+  "version": "0.1.2",
+  "description": "TransOne 跨端图表库：一份 TypeScript 源码，基于 Canvas 2D 渲染，兼容 Web 与多端小程序，预留原生 App（iOS/Android/鸿蒙）扩展",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./lib/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/adapters/index.js",
+      "types": "./dist/adapters/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "build:types": "bunx tsc --project tsconfig.build.json",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "transone": ">=0.3.0"
+  },
+  "devDependencies": {
+    "transone": "0.3.0"
+  },
+  "keywords": [
+    "transone",
+    "chart",
+    "canvas",
+    "cross-platform",
+    "miniprogram",
+    "web",
+    "typescript"
+  ],
+  "homepage": "https://geektech-team.github.io/transone/chart/",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "dist",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}