transone-chart 0.1.2 → 0.2.0

package/lib/component.ts

@@ -7,7 +7,10 @@
  * - 未来原生：通过 resolve 注入自定义解析器
  *
  * 组件本身是薄壳：状态由父级以 option 传入（完全受控），
- * 数据变化时自动 setOption + render。
+ * 数据变化时自动 setOption + render；
+ * 容器 / 窗口尺寸变化时防抖（150ms）自动重绘：
+ * - Web：ResizeObserver 观察 canvas，重测 clientWidth/Height 后增量 resize + render
+ * - 小程序：平台窗口尺寸回调触发后重建图表（SelectorQuery 取最新节点尺寸）
  */
 
 import {
@@ -17,12 +20,15 @@ import {
 } from 'transone';
 import type { ChartRenderContext, ChartOption } from './types';
 import type { ChartBase } from './core/chart';
+import { debounce, type Debounced } from './core/debounce';
 import { createChart } from './factory';
 import {
   detectMiniProgramGlobal,
   getMiniProgramCanvasNode,
+  getMiniProgramGlobal,
   resolveMiniProgramCanvas,
 } from './adapters/miniprogram';
+import { detectPixelRatio } from './adapters/types';
 import { resolveWebCanvas } from './adapters/web';
 
 export interface TcChartProps {
@@ -42,9 +48,22 @@ interface TcChartState {
 /** canvas 元素 id：Web 端仅作 DOM 属性；小程序端配合 SelectorQuery .in(实例) 隔离查询，多实例共存不冲突。 */
 const CANVAS_ID = 'tc-chart-canvas';
 
+/** 尺寸变化自动重绘的防抖窗口（毫秒）。连续 resize 事件只在此窗口后重绘一次。 */
+const RESIZE_DEBOUNCE_MS = 150;
+
+interface MpWindowResizeApi {
+  onWindowResize?: (callback: () => void) => unknown;
+  offWindowResize?: (callback: () => void) => unknown;
+}
+
 export class TcChart extends Component<TcChartProps, TcChartState> {
   private chart: ChartBase<ChartOption> | null = null;
   private destroyed = false;
+  private resizeDebounced: Debounced<() => void> | null = null;
+  private resizeObserver: ResizeObserver | null = null;
+  private mpResizeHandler: (() => void) | null = null;
+  /** Web 端 hover 事件句柄（mousemove / mouseleave），卸载时移除。 */
+  private hoverHandlers: Array<[string, (e: Event) => void]> = [];
 
   protected initState(): TcChartState {
     return { canvasId: CANVAS_ID };
@@ -71,6 +90,8 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
 
   protected onMounted(): void {
     this.attachChart();
+    this.setupAutoResize();
+    this.setupHoverEvents();
   }
 
   protected onUpdated(): void {
@@ -82,6 +103,8 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
   }
 
   protected onUnmounted(): void {
+    this.teardownAutoResize();
+    this.teardownHoverEvents();
     this.destroyed = true;
     this.chart?.destroy();
     this.chart = null;
@@ -98,7 +121,8 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
     }
     this.resolveContext()
       .then((context) => {
-        if (this.destroyed) {
+        if (this.destroyed || !context) {
+          // 非浏览器环境（SSR / 构建期静态渲染）或显式跳过：渲染交给客户端水合阶段。
           return;
         }
         this.chart = createChart(context, this.props.option);
@@ -109,12 +133,151 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
       });
   }
 
-  /** 组件根元素（canvas）。Web 端用于解析渲染上下文；小程序端经 SelectorQuery .in(实例) 查询，不依赖此方法。 */
+  /**
+   * Web 端返回根 canvas；小程序端此方法不会被调用（走 SelectorQuery）。
+   * 注意：方法体不能写 super.X() —— transone-cli 编译小程序时会把组件方法拍平为
+   * Component options 的普通函数属性，super 在普通函数里非法（JSCore 直接报错）。
+   * 基类 el 为 protected，此处直接取用；返回类型收窄在使用点做断言。
+   */
   public getElement(): HTMLCanvasElement | null {
-    return super.getElement() as HTMLCanvasElement | null;
+    return this.el as HTMLCanvasElement | null;
+  }
+
+  /* —— 悬浮提示（tooltip）：Web mousemove / mouseleave —— */
+
+  /** Web 端绑定 hover 事件：鼠标移动命中数据点即显示 tooltip，离开清除。 */
+  private setupHoverEvents(): void {
+    if (this.destroyed || this.hoverHandlers.length > 0) {
+      return;
+    }
+    // 小程序端暂无鼠标事件，一期仅 Web；后续可在 touchstart/touchmove 接入同一 setHover API
+    if (detectMiniProgramGlobal()) {
+      return;
+    }
+    const element = this.getElement() as HTMLCanvasElement | null;
+    if (!element || typeof element.addEventListener !== 'function') {
+      return;
+    }
+
+    const onMove = (event: Event): void => {
+      const chart = this.chart;
+      if (!chart) {
+        return;
+      }
+      const mouse = event as MouseEvent;
+      const rect = element.getBoundingClientRect();
+      const relX = mouse.clientX - rect.left;
+      const relY = mouse.clientY - rect.top;
+      // 同步图表逻辑尺寸，避免 resize 防抖窗口内坐标系偏移导致命中错位
+      const w = rect.width;
+      const h = rect.height;
+      if (w > 0 && h > 0) {
+        chart.resize(w, h);
+      }
+      chart.setHover(relX, relY);
+    };
+    const onLeave = (): void => {
+      this.chart?.clearHover();
+    };
+
+    element.addEventListener('mousemove', onMove);
+    element.addEventListener('mouseleave', onLeave);
+    this.hoverHandlers = [
+      ['mousemove', onMove],
+      ['mouseleave', onLeave],
+    ];
+  }
+
+  private teardownHoverEvents(): void {
+    const element = this.getElement() as HTMLCanvasElement | null;
+    for (const [type, handler] of this.hoverHandlers) {
+      element?.removeEventListener(type, handler);
+    }
+    this.hoverHandlers = [];
+  }
+
+  /* —— 自动重绘：容器 / 窗口尺寸变化时防抖重绘 —— */
+
+  private setupAutoResize(): void {
+    if (this.destroyed || this.resizeDebounced) {
+      return;
+    }
+    this.resizeDebounced = debounce(() => this.handleResize(), RESIZE_DEBOUNCE_MS);
+
+    const platform = detectMiniProgramGlobal();
+    if (platform) {
+      // 小程序：各平台均有窗口尺寸回调（横竖屏切换 / 分屏等场景）
+      const mp = getMiniProgramGlobal(platform) as MpWindowResizeApi | null;
+      if (mp && typeof mp.onWindowResize === 'function') {
+        this.mpResizeHandler = () => this.resizeDebounced!.run();
+        mp.onWindowResize(this.mpResizeHandler);
+      }
+      return;
+    }
+
+    // Web：ResizeObserver 观察 canvas 自身（CSS 宽高 100%，容器变化即触发）。
+    // SSR / 构建期无真实元素与 ResizeObserver，跳过。
+    const element = this.getElement() as HTMLCanvasElement | null;
+    if (
+      element &&
+      typeof element.getContext === 'function' &&
+      typeof ResizeObserver === 'function'
+    ) {
+      this.resizeObserver = new ResizeObserver(() => this.resizeDebounced!.run());
+      this.resizeObserver.observe(element);
+    }
+  }
+
+  private teardownAutoResize(): void {
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.resizeDebounced?.cancel();
+    this.resizeDebounced = null;
+    if (this.mpResizeHandler) {
+      const platform = detectMiniProgramGlobal();
+      const mp = platform
+        ? (getMiniProgramGlobal(platform) as MpWindowResizeApi | null)
+        : null;
+      if (mp && typeof mp.offWindowResize === 'function') {
+        mp.offWindowResize(this.mpResizeHandler);
+      }
+      this.mpResizeHandler = null;
+    }
+  }
+
+  private handleResize(): void {
+    if (this.destroyed) {
+      return;
+    }
+    if (detectMiniProgramGlobal()) {
+      // 小程序：窗口尺寸变化后 SelectorQuery 取到的节点尺寸已更新，
+      // 重建图表即可拿到最新尺寸（上下文持有节点实测宽高与 pixelRatio）。
+      this.chart?.destroy();
+      this.chart = null;
+      this.attachChart();
+      return;
+    }
+    const element = this.getElement() as HTMLCanvasElement | null;
+    if (!element || typeof element.getContext !== 'function') {
+      return;
+    }
+    const width = element.clientWidth || 0;
+    const height = element.clientHeight || 0;
+    if (width <= 0 || height <= 0) {
+      return;
+    }
+    if (!this.chart) {
+      this.attachChart();
+      return;
+    }
+    // 更新物理像素缓冲（逻辑尺寸 × DPR），并增量重绘（保留图表状态）
+    const dpr = detectPixelRatio();
+    element.width = Math.round(width * dpr);
+    element.height = Math.round(height * dpr);
+    this.chart.resize(width, height, dpr).render();
   }
 
-  private resolveContext(): Promise<ChartRenderContext> {
+  private resolveContext(): Promise<ChartRenderContext | null> {
     if (this.props.resolve) {
       return Promise.resolve(this.props.resolve(this.getElement()));
     }
@@ -141,9 +304,15 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
       return attempt(5);
     }
 
-    // Web：canvas 元素即 HTMLCanvasElement
+    // Web：canvas 元素即 HTMLCanvasElement。SSR / 构建期静态渲染环境下
+    // 元素没有真实 2d context（如 projectDom），返回 null 跳过渲染，
+    // 由客户端水合阶段（真实浏览器）完成绘制。
+    const element = this.getElement() as HTMLCanvasElement | null;
+    if (!element || typeof element.getContext !== 'function') {
+      return Promise.resolve(null);
+    }
     return Promise.resolve(
-      resolveWebCanvas(this.getElement() as unknown as HTMLCanvasElement)
+      resolveWebCanvas(element)
     );
   }
 }

package/lib/core/chart.ts

@@ -12,6 +12,7 @@
 
 import type { ICanvas2D } from './canvas';
 import { AxisDrawer } from './axis';
+import type { Box } from './layout';
 import {
   computeLayout,
   type LayoutInput,
@@ -27,6 +28,8 @@ import {
   type ChartRenderContext,
   type LegendOption,
   type TitleOption,
+  type TooltipOption,
+  type TooltipParams,
   type ValueAxisOption,
 } from '../types';
 
@@ -54,6 +57,12 @@ export abstract class ChartBase<T extends ChartOption> {
   /** 每次 render 构建的笛卡尔比例尺，供 drawSeries 读取。 */
   protected cartesian: CartesianScales | null = null;
 
+  /** 最近一次 render 的绘图区，供 hitTestSeries 使用。 */
+  protected plot: Box | null = null;
+
+  /** 当前悬浮命中的 tooltip 参数（由 setHover 触发 render 后绘制）。 */
+  protected hover: TooltipParams | null = null;
+
   private destroyed = false;
 
   public constructor(context: ChartRenderContext, option: T) {
@@ -72,9 +81,13 @@ export abstract class ChartBase<T extends ChartOption> {
     return this;
   }
 
-  public resize(width: number, height: number): this {
+  public resize(width: number, height: number, dpr?: number): this {
     this.width = Math.max(0, width);
     this.height = Math.max(0, height);
+    // dpr 变化（如窗口跨屏移动）时同步更新，绘制管线按新 dpr 缩放
+    if (dpr !== undefined && Number.isFinite(dpr) && dpr > 0) {
+      this.dpr = dpr;
+    }
     return this;
   }
 
@@ -95,6 +108,7 @@ export abstract class ChartBase<T extends ChartOption> {
     }
 
     const layout = this.computeLayout();
+    this.plot = layout.plot;
     this.drawTitle(layout);
     this.drawLegend(layout);
 
@@ -107,10 +121,39 @@ export abstract class ChartBase<T extends ChartOption> {
 
     this.drawSeries(ctx, layout, this.option);
 
+    // tooltip 浮层最后绘制，保证在最上层
+    if (this.hover) {
+      this.drawTooltip(this.hover);
+    }
+
     ctx.restore();
     return this;
   }
 
+  /* —— 悬浮交互（tooltip）—— */
+
+  /**
+   * 命中测试并显示 tooltip。坐标为逻辑像素（CSS px），由事件层换算后传入。
+   * 未命中任何数据 / tooltip 关闭时不显示。调用后自动重绘。
+   */
+  public setHover(x: number, y: number): this {
+    if (this.option.tooltip?.show === false) {
+      this.hover = null;
+    } else {
+      this.hover = this.hitTestSeries(x, y);
+    }
+    return this.render();
+  }
+
+  /** 清除悬浮状态并重绘。 */
+  public clearHover(): this {
+    this.hover = null;
+    return this.render();
+  }
+
+  /** 子类实现：命中检测——返回 null 表示该位置无数据。 */
+  protected abstract hitTestSeries(x: number, y: number): TooltipParams | null;
+
   public destroy(): void {
     this.destroyed = true;
   }
@@ -319,4 +362,126 @@ export abstract class ChartBase<T extends ChartOption> {
   protected seriesColor(index: number, color?: string): string {
     return color ?? this.palette[index % this.palette.length];
   }
+
+  /* —— tooltip 浮层绘制 —— */
+
+  protected getTooltipOption(): TooltipOption | undefined {
+    return (this.option as { tooltip?: TooltipOption }).tooltip;
+  }
+
+  /** 默认 tooltip 文本：首行标题 + 每行一个数据项。 */
+  protected defaultTooltipLines(params: TooltipParams): string[] {
+    const lines: string[] = [params.name];
+    for (const item of params.items) {
+      lines.push(`${item.name}: ${item.value}`);
+    }
+    return lines;
+  }
+
+  /** 在 canvas 上绘制 tooltip 浮层：跟随触发点，边缘自动翻转。 */
+  protected drawTooltip(params: TooltipParams): void {
+    const option = this.getTooltipOption();
+    if (option?.show === false) {
+      return;
+    }
+    const formatter = option?.formatter;
+    const raw = formatter ? formatter(params) : this.defaultTooltipLines(params);
+    const lines = Array.isArray(raw) ? raw : [raw];
+    if (lines.length === 0) {
+      return;
+    }
+
+    const { ctx } = this;
+    const fontSize = 12;
+    const padX = 10;
+    const padY = 8;
+    const lineH = 18;
+    const dotR = 4;
+    const dotGap = 6;
+
+    applyFont(ctx, fontSize);
+    let maxW = 0;
+    for (const line of lines) {
+      maxW = Math.max(maxW, measureWidth(ctx, line, fontSize));
+    }
+    const boxW = maxW + padX * 2 + dotR * 2 + dotGap;
+    const boxH = lines.length * lineH + padY * 2;
+
+    // 优先将 tooltip 定位在绘图区外，避免遮挡数据元素
+    const plot = this.plot;
+    let bx: number;
+    let by: number;
+
+    if (plot && this.isHorizontal()) {
+      // 横向图：tooltip 定位在绘图区右侧
+      bx = plot.x + plot.width + 8;
+      by = params.y - boxH / 2;
+      // 右侧空间不足时，定位到左侧
+      if (bx + boxW > this.width - 4) {
+        bx = plot.x - boxW - 8;
+      }
+    } else if (plot) {
+      // 纵向图：tooltip 定位在触发点右侧，避免与绘图区重叠
+      bx = params.x + 14;
+      by = params.y - boxH / 2;
+      // 右侧空间不足时，定位到左侧
+      if (bx + boxW > this.width - 4) {
+        bx = params.x - boxW - 14;
+      }
+    } else {
+      // 无绘图区信息（饼图/雷达图）：跟随触发点
+      bx = params.x + 14;
+      by = params.y - boxH / 2;
+      if (bx + boxW > this.width - 4) {
+        bx = params.x - boxW - 14;
+      }
+    }
+
+    bx = Math.max(4, bx);
+    by = Math.max(4, Math.min(by, this.height - boxH - 4));
+
+    ctx.save();
+    // 背景
+    ctx.fillStyle = 'rgba(50, 50, 51, 0.92)';
+    ctx.beginPath();
+    this.roundRectPath(bx, by, boxW, boxH, 6);
+    ctx.fill();
+
+    // 文本行：数据行前画系列色小圆点
+    ctx.textBaseline = 'middle';
+    ctx.textAlign = 'left';
+    lines.forEach((line, i) => {
+      const ty = by + padY + lineH * i + lineH / 2;
+      const dotColor = i > 0 ? params.items[i - 1]?.color : undefined;
+      if (dotColor) {
+        ctx.fillStyle = dotColor;
+        ctx.beginPath();
+        ctx.arc(bx + padX + dotR, ty, dotR, 0, Math.PI * 2);
+        ctx.fill();
+      }
+      ctx.fillStyle = '#ffffff';
+      const tx = bx + padX + (dotColor ? dotR * 2 + dotGap : 0);
+      ctx.fillText(line, tx, ty);
+    });
+    ctx.restore();
+  }
+
+  /** 圆角矩形路径（当前路径），与平台无关。 */
+  private roundRectPath(
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    r: number
+  ): void {
+    const ctx = this.ctx;
+    const radius = Math.min(r, w / 2, h / 2);
+    ctx.moveTo(x + radius, y);
+    ctx.lineTo(x + w - radius, y);
+    ctx.arcTo(x + w, y, x + w, y + h, radius);
+    ctx.arcTo(x + w, y + h, x, y + h, radius);
+    ctx.arcTo(x, y + h, x, y, radius);
+    ctx.arcTo(x, y, x + w, y, radius);
+    ctx.closePath();
+  }
 }

package/lib/core/debounce.ts

@@ -0,0 +1,52 @@
+/**
+ * 零依赖防抖工具。
+ *
+ * 用于高频触发场景（如窗口 / 容器尺寸变化）的合并调度：
+ * 连续调用只会在停止触发 delay 毫秒后执行一次。
+ */
+
+export interface Debounced<T extends (...args: never[]) => unknown> {
+  /** 触发一次；若已有待执行调用则重置计时器（合并连续触发）。 */
+  run: (...args: Parameters<T>) => void;
+  /** 取消尚未执行的调用。 */
+  cancel: () => void;
+  /** 是否已有待执行的调用。 */
+  pending: () => boolean;
+}
+
+type AnyFunction = (...args: any[]) => unknown;
+
+export function debounce<T extends AnyFunction>(
+  fn: T,
+  delay: number
+): Debounced<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let lastArgs: Parameters<T> | null = null;
+
+  return {
+    run(...args: Parameters<T>): void {
+      lastArgs = args;
+      if (timer !== null) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(() => {
+        timer = null;
+        if (lastArgs !== null) {
+          const runArgs = lastArgs;
+          lastArgs = null;
+          fn(...runArgs);
+        }
+      }, delay);
+    },
+    cancel(): void {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      lastArgs = null;
+    },
+    pending(): boolean {
+      return timer !== null;
+    },
+  };
+}

package/lib/index.ts

@@ -30,6 +30,10 @@ export type { LinearScaleOptions, ScaleResult } from './core/scale';
 export { computeLayout } from './core/layout';
 export type { Box, LayoutInput, LayoutResult, Padding } from './core/layout';
 
+// 工具：防抖（自动重绘等高频触发场景）
+export { debounce } from './core/debounce';
+export type { Debounced } from './core/debounce';
+
 // 图表基类
 export { ChartBase } from './core/chart';
 export type { CartesianScales } from './core/chart';

package/lib/types.ts

@@ -81,6 +81,36 @@ export interface CategoryAxisOption {
   showGrid?: boolean;
 }
 
+/** —— Tooltip（悬浮提示）—— */
+
+/** tooltip 中一条数据（一个系列 / 一个扇区）。 */
+export interface TooltipDatum {
+  /** 系列名 / 扇区名。 */
+  name: string;
+  /** 显示值（已格式化）。 */
+  value: number | string;
+  /** 色块颜色，用于 tooltip 前的小圆点。 */
+  color?: string;
+}
+
+/** tooltip 触发时命中的一组数据。 */
+export interface TooltipParams {
+  /** 触发位置（逻辑像素）。 */
+  x: number;
+  y: number;
+  /** 类目名 / 扇区名。 */
+  name: string;
+  /** 该类目 / 扇区下的所有数据项。 */
+  items: readonly TooltipDatum[];
+}
+
+export interface TooltipOption {
+  /** 是否显示 tooltip，默认 true。 */
+  show?: boolean;
+  /** 自定义展示内容；返回文本行数组。缺省自动生成（首行标题 + 每行一个色块数据项）。 */
+  formatter?: (params: TooltipParams) => string | readonly string[];
+}
+
 /** —— 折线图 —— */
 
 export interface LineSeries {
@@ -105,6 +135,8 @@ export interface LineChartOption {
   series: readonly LineSeries[];
   /** 数值轴是否从 0 开始（数据全为正时强制含 0），默认 false（按数据范围紧凑显示）。 */
   startFromZero?: boolean;
+  /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+  tooltip?: TooltipOption;
   /** 背景色（如 'rgba(22,119,255,0.06)'），默认无。 */
   backgroundColor?: string;
 }
@@ -132,6 +164,8 @@ export interface BarChartOption {
   series: readonly BarSeries[];
   /** 横向柱状图（类目轴转纵向、数值轴转横向），默认 false。 */
   horizontal?: boolean;
+  /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+  tooltip?: TooltipOption;
   backgroundColor?: string;
 }
 
@@ -154,10 +188,20 @@ export interface PieChartOption {
   innerRadius?: number | string;
   /** 是否显示扇区标签（名称 + 百分比），默认 true。 */
   showLabel?: boolean;
+  /** 标签位置：'inside' 画在扇区内（默认，白字）；'outside' 画在扇区外并带引线（适合小扇区 / 长名称）。 */
+  labelPosition?: 'inside' | 'outside';
+  /** 外部标签引线沿平分线的长度（px），仅 labelPosition: 'outside' 生效，默认 14。 */
+  labelLineLength?: number;
+  /** 外部标签与引线端点的水平间距（px），仅 labelPosition: 'outside' 生效，默认 6。 */
+  labelGap?: number;
+  /** 外部标签引线颜色，默认 '#c0c4cc'。 */
+  labelLineColor?: string;
   labelFontSize?: number;
   labelColor?: string;
   /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
   startAngle?: number;
+  /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+  tooltip?: TooltipOption;
   backgroundColor?: string;
 }
 
@@ -194,6 +238,8 @@ export interface RadarChartOption {
   radius?: number;
   /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
   startAngle?: number;
+  /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+  tooltip?: TooltipOption;
   backgroundColor?: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transone-chart",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "TransOne 跨端图表库：一份 TypeScript 源码，基于 Canvas 2D 渲染，兼容 Web 与多端小程序，预留原生 App（iOS/Android/鸿蒙）扩展",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "transone": ">=0.3.0"
   },
   "devDependencies": {
-    "transone": "0.3.0"
+    "transone": "0.4.0"
   },
   "keywords": [
     "transone",