transone-chart 0.1.2

package/lib/component.ts

@@ -0,0 +1,149 @@
+/**
+ * 可选集成：基于 transone Component 的声明式图表组件 TcChart。
+ *
+ * 与 transone 组件系统集成，一份源码同时编译 Web 与小程序：
+ * - Web：canvas 元素由组件渲染，onMounted 后自动解析并渲染
+ * - 小程序：canvas 编译为 <canvas type="2d">，通过 SelectorQuery 获取节点
+ * - 未来原生：通过 resolve 注入自定义解析器
+ *
+ * 组件本身是薄壳：状态由父级以 option 传入（完全受控），
+ * 数据变化时自动 setOption + render。
+ */
+
+import {
+  Component,
+  h,
+  type VNode,
+} from 'transone';
+import type { ChartRenderContext, ChartOption } from './types';
+import type { ChartBase } from './core/chart';
+import { createChart } from './factory';
+import {
+  detectMiniProgramGlobal,
+  getMiniProgramCanvasNode,
+  resolveMiniProgramCanvas,
+} from './adapters/miniprogram';
+import { resolveWebCanvas } from './adapters/web';
+
+export interface TcChartProps {
+  /** 图表配置（line / bar / pie / radar）。 */
+  option: ChartOption;
+  /** 自定义解析器：把 canvas 元素/节点解析为渲染上下文。 */
+  resolve?: (
+    element: unknown
+  ) => Promise<ChartRenderContext> | ChartRenderContext;
+  className?: string;
+}
+
+interface TcChartState {
+  canvasId: string;
+}
+
+/** canvas 元素 id：Web 端仅作 DOM 属性；小程序端配合 SelectorQuery .in(实例) 隔离查询，多实例共存不冲突。 */
+const CANVAS_ID = 'tc-chart-canvas';
+
+export class TcChart extends Component<TcChartProps, TcChartState> {
+  private chart: ChartBase<ChartOption> | null = null;
+  private destroyed = false;
+
+  protected initState(): TcChartState {
+    return { canvasId: CANVAS_ID };
+  }
+
+  protected initStyles(): void {
+    this.styleManager.addStyle('tc-chart-canvas', {
+      selector: '.tc-chart__canvas',
+      properties: {
+        display: 'block',
+        height: '100%',
+        width: '100%',
+      },
+    });
+  }
+
+  protected render(): VNode {
+    return h('canvas', {
+      id: this.state.canvasId,
+      className: `tc-chart__canvas${this.props.className ? ` ${this.props.className}` : ''}`,
+      type: '2d',
+    });
+  }
+
+  protected onMounted(): void {
+    this.attachChart();
+  }
+
+  protected onUpdated(): void {
+    if (this.chart && !this.destroyed) {
+      this.chart.setOption(this.props.option).render();
+    } else if (!this.chart && !this.destroyed) {
+      this.attachChart();
+    }
+  }
+
+  protected onUnmounted(): void {
+    this.destroyed = true;
+    this.chart?.destroy();
+    this.chart = null;
+  }
+
+  /** 对外暴露图表实例（高级用法：手动 resize / 订阅事件）。 */
+  public getChart(): ChartBase<ChartOption> | null {
+    return this.chart;
+  }
+
+  private attachChart(): void {
+    if (this.destroyed) {
+      return;
+    }
+    this.resolveContext()
+      .then((context) => {
+        if (this.destroyed) {
+          return;
+        }
+        this.chart = createChart(context, this.props.option);
+        this.chart.render();
+      })
+      .catch((error: unknown) => {
+        console.error('[TcChart] attach failed:', error);
+      });
+  }
+
+  /** 组件根元素（canvas）。Web 端用于解析渲染上下文；小程序端经 SelectorQuery .in(实例) 查询，不依赖此方法。 */
+  public getElement(): HTMLCanvasElement | null {
+    return super.getElement() as HTMLCanvasElement | null;
+  }
+
+  private resolveContext(): Promise<ChartRenderContext> {
+    if (this.props.resolve) {
+      return Promise.resolve(this.props.resolve(this.getElement()));
+    }
+
+    const platform = detectMiniProgramGlobal();
+    if (platform) {
+      // 小程序：SelectorQuery 查询节点（组件可能尚未渲染完，有限重试）
+      const selector = `#${this.state.canvasId}`;
+      const attempt = (left: number): Promise<ChartRenderContext> =>
+        getMiniProgramCanvasNode({
+          platform,
+          instance: this,
+          selector,
+        })
+          .then((node) => resolveMiniProgramCanvas(node))
+          .catch((error: unknown) => {
+            if (left <= 0) {
+              throw error;
+            }
+            return new Promise((resolve) => setTimeout(resolve, 50)).then(() =>
+              attempt(left - 1)
+            );
+          });
+      return attempt(5);
+    }
+
+    // Web：canvas 元素即 HTMLCanvasElement
+    return Promise.resolve(
+      resolveWebCanvas(this.getElement() as unknown as HTMLCanvasElement)
+    );
+  }
+}

package/lib/core/axis.ts

@@ -0,0 +1,174 @@
+/**
+ * 坐标轴绘制：数值轴（默认纵向居左、横向图居底）与类目轴（默认横向居底、
+ * 横向图居左）。网格线与刻度标签统一在这里绘制，数据系列只画在 plot 内。
+ *
+ * 位置计算全部基于布局结果与比例尺，与平台无关。
+ */
+
+import type { ICanvas2D } from './canvas';
+import type { Box } from './layout';
+import { CategoryScale, LinearScale } from './scale';
+import { applyFont } from './text';
+import {
+  DEFAULT_AXIS_COLOR,
+  DEFAULT_GRID_COLOR,
+  DEFAULT_TEXT_COLOR,
+} from '../types';
+
+export interface ValueAxisDrawOptions {
+  /** 绘图区。 */
+  plot: Box;
+  /** 数值比例尺：纵向图 range=[plot.bottom, plot.top]，横向图 range=[plot.left, plot.right]。 */
+  scale: LinearScale;
+  /** 刻度标签（长度需与 scale.ticks 一致）。 */
+  labels: readonly string[];
+  /** 横向图：数值轴位于底部。 */
+  horizontal?: boolean;
+  axisColor?: string;
+  labelFontSize?: number;
+  labelColor?: string;
+  gridColor?: string;
+  gridLineWidth?: number;
+  gridLineDash?: readonly number[];
+  showGrid?: boolean;
+}
+
+export interface CategoryAxisDrawOptions {
+  plot: Box;
+  scale: CategoryScale;
+  labels: readonly string[];
+  /** 横向图：类目轴位于左侧。 */
+  horizontal?: boolean;
+  axisColor?: string;
+  labelFontSize?: number;
+  labelColor?: string;
+  gridColor?: string;
+  gridLineWidth?: number;
+  showGrid?: boolean;
+}
+
+export class AxisDrawer {
+  public constructor(private readonly ctx: ICanvas2D) {}
+
+  /** 绘制数值轴：网格横线（或纵向图时） + 刻度标签。 */
+  public drawValueAxis(options: ValueAxisDrawOptions): void {
+    const {
+      plot,
+      scale,
+      labels,
+      horizontal = false,
+      labelFontSize = 11,
+      labelColor = DEFAULT_TEXT_COLOR,
+      gridColor = DEFAULT_GRID_COLOR,
+      gridLineWidth = 1,
+      gridLineDash,
+      showGrid = true,
+    } = options;
+
+    const ticks = scale.ticks;
+    const { ctx } = this;
+
+    for (let i = 0; i < ticks.length; i += 1) {
+      const pos = scale.scale(ticks[i]);
+      const label = labels[i] ?? String(ticks[i]);
+
+      if (showGrid) {
+        ctx.save();
+        ctx.strokeStyle = gridColor;
+        ctx.lineWidth = gridLineWidth;
+        if (gridLineDash && gridLineDash.length > 0) {
+          ctx.setLineDash(gridLineDash);
+        }
+        ctx.beginPath();
+        if (horizontal) {
+          ctx.moveTo(plot.x, pos);
+          ctx.lineTo(plot.x + plot.width, pos);
+        } else {
+          ctx.moveTo(plot.x, pos);
+          ctx.lineTo(plot.x + plot.width, pos);
+        }
+        ctx.stroke();
+        ctx.restore();
+      }
+
+      applyFont(ctx, labelFontSize);
+      ctx.fillStyle = labelColor;
+      ctx.textBaseline = 'middle';
+      if (horizontal) {
+        ctx.textAlign = 'center';
+        ctx.fillText(label, pos, plot.y + plot.height + 8);
+      } else {
+        ctx.textAlign = 'right';
+        ctx.fillText(label, plot.x - 8, pos);
+      }
+    }
+  }
+
+  /** 绘制类目轴：轴线 + 类目标签（可选竖网格）。 */
+  public drawCategoryAxis(options: CategoryAxisDrawOptions): void {
+    const {
+      plot,
+      scale,
+      labels,
+      horizontal = false,
+      axisColor = DEFAULT_AXIS_COLOR,
+      labelFontSize = 11,
+      labelColor = DEFAULT_TEXT_COLOR,
+      gridColor = DEFAULT_GRID_COLOR,
+      gridLineWidth = 1,
+      showGrid = false,
+    } = options;
+
+    const { ctx } = this;
+    const count = labels.length;
+
+    if (showGrid) {
+      ctx.save();
+      ctx.strokeStyle = gridColor;
+      ctx.lineWidth = gridLineWidth;
+      ctx.beginPath();
+      for (let i = 0; i < count; i += 1) {
+        const pos = scale.center(i);
+        if (horizontal) {
+          ctx.moveTo(plot.x, pos);
+          ctx.lineTo(plot.x + plot.width, pos);
+        } else {
+          ctx.moveTo(pos, plot.y);
+          ctx.lineTo(pos, plot.y + plot.height);
+        }
+      }
+      ctx.stroke();
+      ctx.restore();
+    }
+
+    applyFont(ctx, labelFontSize);
+    ctx.fillStyle = labelColor;
+    ctx.textBaseline = 'middle';
+
+    for (let i = 0; i < count; i += 1) {
+      const pos = scale.center(i);
+      if (horizontal) {
+        ctx.textAlign = 'right';
+        ctx.fillText(labels[i], plot.x - 8, pos);
+      } else {
+        ctx.textAlign = 'center';
+        ctx.fillText(labels[i], pos, plot.y + plot.height + 8);
+      }
+    }
+
+    // 轴线
+    ctx.save();
+    ctx.strokeStyle = axisColor;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    if (horizontal) {
+      ctx.moveTo(plot.x, plot.y);
+      ctx.lineTo(plot.x, plot.y + plot.height);
+    } else {
+      ctx.moveTo(plot.x, plot.y + plot.height);
+      ctx.lineTo(plot.x + plot.width, plot.y + plot.height);
+    }
+    ctx.stroke();
+    ctx.restore();
+  }
+}

package/lib/core/canvas.ts

@@ -0,0 +1,130 @@
+/**
+ * 跨端 Canvas 2D 契约（ICanvas2D）。
+ *
+ * 这是 transone-chart 与平台解耦的唯一边界：
+ * - Web：HTMLCanvasElement.getContext('2d') 天然满足，适配器薄封装
+ * - 小程序：微信 / 阿里 / 字节的 Canvas 2D（type="2d"）节点上下文与 Web 接口基本对齐
+ * - 未来原生 App：Skia / ArkUI 等原生 canvas 只需实现本接口即可接入同一套引擎
+ *
+ * 接口刻意收敛为图表实际需要的最小真子集，避免依赖平台各自的扩展 API；
+ * 绘制一律使用「beginPath → 路径命令 → fill()/stroke() 无参」形式，
+ * 不依赖 Path2D 等小程序端可能缺失的高级对象。
+ */
+
+export interface IGradient {
+  addColorStop(offset: number, color: string): void;
+}
+
+export type CanvasLineCap = 'butt' | 'round' | 'square';
+export type CanvasLineJoin = 'bevel' | 'round' | 'miter';
+export type CanvasTextAlign =
+  | 'left'
+  | 'right'
+  | 'center'
+  | 'start'
+  | 'end';
+export type CanvasTextBaseline =
+  | 'top'
+  | 'hanging'
+  | 'middle'
+  | 'alphabetic'
+  | 'ideographic'
+  | 'bottom';
+
+export interface ICanvas2D {
+  /* —— 状态管理 —— */
+  save(): void;
+  restore(): void;
+  translate(x: number, y: number): void;
+  scale(x: number, y: number): void;
+  rotate(angle: number): void;
+
+  /* —— 样式属性 —— */
+  fillStyle: string | IGradient;
+  strokeStyle: string | IGradient;
+  lineWidth: number;
+  lineCap: CanvasLineCap;
+  lineJoin: CanvasLineJoin;
+  globalAlpha: number;
+  font: string;
+  textAlign: CanvasTextAlign;
+  textBaseline: CanvasTextBaseline;
+
+  /* —— 路径 —— */
+  beginPath(): void;
+  closePath(): void;
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  bezierCurveTo(
+    cp1x: number,
+    cp1y: number,
+    cp2x: number,
+    cp2y: number,
+    x: number,
+    y: number
+  ): void;
+  arc(
+    x: number,
+    y: number,
+    radius: number,
+    startAngle: number,
+    endAngle: number,
+    counterclockwise?: boolean
+  ): void;
+  arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+  rect(x: number, y: number, width: number, height: number): void;
+  ellipse(
+    x: number,
+    y: number,
+    radiusX: number,
+    radiusY: number,
+    rotation: number,
+    startAngle: number,
+    endAngle: number,
+    counterclockwise?: boolean
+  ): void;
+
+  /* —— 绘制 —— */
+  fill(): void;
+  stroke(): void;
+  fillRect(x: number, y: number, width: number, height: number): void;
+  clearRect(x: number, y: number, width: number, height: number): void;
+  clip(): void;
+  setLineDash(segments: readonly number[]): void;
+
+  /* —— 渐变 —— */
+  createLinearGradient(
+    x0: number,
+    y0: number,
+    x1: number,
+    y1: number
+  ): IGradient;
+  createRadialGradient(
+    x0: number,
+    y0: number,
+    r0: number,
+    x1: number,
+    y1: number,
+    r1: number
+  ): IGradient;
+
+  /* —— 文字 —— */
+  fillText(text: string, x: number, y: number, maxWidth?: number): void;
+  measureText(text: string): { width: number };
+}
+
+/**
+ * ICanvas2D 的便捷判断：任意对象只要实现了最小方法集即视为满足契约。
+ * 用于适配器防御与测试 mock 的类型断言，不承担运行时校验。
+ */
+export function isCanvas2DLike(value: unknown): value is ICanvas2D {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ICanvas2D).save === 'function' &&
+    typeof (value as ICanvas2D).beginPath === 'function' &&
+    typeof (value as ICanvas2D).fill === 'function' &&
+    typeof (value as ICanvas2D).stroke === 'function' &&
+    typeof (value as ICanvas2D).fillText === 'function'
+  );
+}