transone-chart 0.1.4 → 0.2.0

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) {
@@ -99,6 +108,7 @@ export abstract class ChartBase<T extends ChartOption> {
     }
 
     const layout = this.computeLayout();
+    this.plot = layout.plot;
     this.drawTitle(layout);
     this.drawLegend(layout);
 
@@ -111,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;
   }
@@ -323,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/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;
 }
 
@@ -166,6 +200,8 @@ export interface PieChartOption {
   labelColor?: string;
   /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
   startAngle?: number;
+  /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+  tooltip?: TooltipOption;
   backgroundColor?: string;
 }
 
@@ -202,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.4",
+  "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",