transone-chart 0.1.4 → 0.2.0

package/dist/types.d.ts

@@ -61,6 +61,32 @@ export interface CategoryAxisOption {
     /** 是否显示类目网格竖线，默认 false。 */
     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 {
     name?: string;
@@ -83,6 +109,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;
 }
@@ -107,6 +135,8 @@ export interface BarChartOption {
     series: readonly BarSeries[];
     /** 横向柱状图（类目轴转纵向、数值轴转横向），默认 false。 */
     horizontal?: boolean;
+    /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+    tooltip?: TooltipOption;
     backgroundColor?: string;
 }
 /** —— 饼图 —— */
@@ -138,6 +168,8 @@ export interface PieChartOption {
     labelColor?: string;
     /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
     startAngle?: number;
+    /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+    tooltip?: TooltipOption;
     backgroundColor?: string;
 }
 /** —— 雷达图 —— */
@@ -170,6 +202,8 @@ export interface RadarChartOption {
     radius?: number;
     /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
     startAngle?: number;
+    /** 悬浮提示配置；默认开启，可 tooltip: { show: false } 关闭。 */
+    tooltip?: TooltipOption;
     backgroundColor?: string;
 }
 export type ChartOption = LineChartOption | BarChartOption | PieChartOption | RadarChartOption;

package/lib/charts/bar.ts

@@ -12,7 +12,7 @@ import { ChartBase } from '../core/chart';
 import type { CategoryScale } from '../core/scale';
 import type { LayoutResult } from '../core/layout';
 import type { LegendItem } from '../core/legend';
-import type { BarChartOption, BarSeries } from '../types';
+import type { BarChartOption, BarSeries, TooltipParams } from '../types';
 
 /** 柱体在类目带内的水平偏移与宽度（纵向）或垂直偏移与高度（横向）。 */
 interface Slot {
@@ -95,6 +95,7 @@ export class BarChart extends ChartBase<BarChartOption> {
 
     const stackGroups = groupStacks(option.series);
     const categoryCount = option.xAxis.labels.length;
+    const hoverIndex = this.getHoverCategoryIndex();
 
     for (let i = 0; i < categoryCount; i += 1) {
       // 每个类目带内：无堆叠时按系列分组并排；有堆叠时按 stack 组并排
@@ -104,6 +105,7 @@ export class BarChart extends ChartBase<BarChartOption> {
         .map((s) => s.barWidth)
         .find((w) => w !== undefined && w > 0);
       const slot = this.computeSlot(category, seriesCount, explicitWidth);
+      const isHovered = hoverIndex === i;
 
       groups.forEach((group, groupIndex) => {
         const slotOffset = slot.offset + groupIndex * slot.size;
@@ -111,10 +113,11 @@ export class BarChart extends ChartBase<BarChartOption> {
 
         group.forEach((series) => {
           const raw = series.data[i] ?? 0;
-          const color = this.seriesColor(
+          const baseColor = this.seriesColor(
             option.series.indexOf(series),
             series.color
           );
+          const color = isHovered ? lightenColor(baseColor, 0.25) : baseColor;
 
           if (horizontal) {
             const x0 = value.scale(0);
@@ -154,6 +157,46 @@ export class BarChart extends ChartBase<BarChartOption> {
     }
   }
 
+  /** 命中检测：点落在某类目的柱体带内即显示该类目所有系列值。 */
+  protected hitTestSeries(x: number, y: number): TooltipParams | null {
+    const scales = this.cartesian;
+    if (!scales) {
+      return null;
+    }
+    const horizontal = this.option.horizontal ?? false;
+    const labels = this.getCategoryLabels();
+
+    // 命中整个类目带（含柱间间隙）：鼠标在类目带内即命中，避免间隙处 tooltip 消失
+    for (let i = 0; i < labels.length; i += 1) {
+      const start = scales.category.bandStart(i);
+      const band = scales.category.bandWidth;
+      const hit = horizontal
+        ? y >= start && y <= start + band
+        : x >= start && x <= start + band;
+      if (!hit) {
+        continue;
+      }
+      // 该类目下所有系列（堆叠时为各段值）
+      const items = this.option.series.map((s, si) => ({
+        name: s.name ?? `系列${si + 1}`,
+        value: s.data[i] ?? 0,
+        color: this.seriesColor(si, s.color),
+      }));
+      return { x, y, name: labels[i], items };
+    }
+    return null;
+  }
+
+  /** 从 hover 状态解析命中的类目索引，未命中返回 -1。 */
+  private getHoverCategoryIndex(): number {
+    const hover = this.hover;
+    if (!hover) {
+      return -1;
+    }
+    const labels = this.getCategoryLabels();
+    return labels.indexOf(hover.name);
+  }
+
   private computeSlot(
     category: CategoryScale,
     groupCount: number,
@@ -274,3 +317,41 @@ function roundRectPath(
   }
   ctx.closePath();
 }
+
+/** 将颜色向白色方向混合 amount（0~1），支持 #rrggbb 与 rgba()。 */
+function lightenColor(color: string, amount: number): string {
+  const a = Math.max(0, Math.min(1, amount));
+
+  // #rrggbb / #rgb
+  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
+  if (hex) {
+    let r: number;
+    let g: number;
+    let b: number;
+    const h = hex[1];
+    if (h.length === 3) {
+      r = parseInt(h[0] + h[0], 16);
+      g = parseInt(h[1] + h[1], 16);
+      b = parseInt(h[2] + h[2], 16);
+    } else {
+      r = parseInt(h.slice(0, 2), 16);
+      g = parseInt(h.slice(2, 4), 16);
+      b = parseInt(h.slice(4, 6), 16);
+    }
+    r = Math.round(r + (255 - r) * a);
+    g = Math.round(g + (255 - g) * a);
+    b = Math.round(b + (255 - b) * a);
+    return `rgb(${r}, ${g}, ${b})`;
+  }
+
+  // rgba(r, g, b, a?) / rgb(r, g, b)
+  const rgba = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgba) {
+    const r = Math.round(parseInt(rgba[1]) + (255 - parseInt(rgba[1])) * a);
+    const g = Math.round(parseInt(rgba[2]) + (255 - parseInt(rgba[2])) * a);
+    const b = Math.round(parseInt(rgba[3]) + (255 - parseInt(rgba[3])) * a);
+    return `rgb(${r}, ${g}, ${b})`;
+  }
+
+  return color;
+}

package/lib/charts/line.ts

@@ -7,7 +7,7 @@ import type { ICanvas2D } from '../core/canvas';
 import { ChartBase } from '../core/chart';
 import type { LayoutResult } from '../core/layout';
 import type { LegendItem } from '../core/legend';
-import type { LineChartOption } from '../types';
+import type { LineChartOption, TooltipParams } from '../types';
 
 interface Point {
   x: number;
@@ -68,6 +68,7 @@ export class LineChart extends ChartBase<LineChartOption> {
     }
     const { plot } = layout;
     const { value, category } = scales;
+    const hoverIndex = this.getHoverCategoryIndex();
 
     const pointsPerSeries: Point[][] = option.series.map((series) =>
       series.data.map((d, i) => ({
@@ -76,6 +77,20 @@ export class LineChart extends ChartBase<LineChartOption> {
       }))
     );
 
+    // 悬浮参考线：在命中类目中心画一条纵向虚线
+    if (hoverIndex >= 0) {
+      const hx = category.center(hoverIndex);
+      ctx.save();
+      ctx.strokeStyle = '#c8c9cc';
+      ctx.lineWidth = 1;
+      ctx.setLineDash([4, 3]);
+      ctx.beginPath();
+      ctx.moveTo(hx, plot.y);
+      ctx.lineTo(hx, plot.y + plot.height);
+      ctx.stroke();
+      ctx.restore();
+    }
+
     option.series.forEach((series, index) => {
       const points = pointsPerSeries[index];
       if (points.length === 0) {
@@ -111,11 +126,14 @@ export class LineChart extends ChartBase<LineChartOption> {
 
       // 数据点标记
       if (series.showSymbol !== false) {
+        const baseR = Math.max(2.5, lineWidth + 0.5);
         ctx.save();
         ctx.fillStyle = color;
-        for (const p of points) {
+        for (let i = 0; i < points.length; i += 1) {
+          const p = points[i];
+          const r = i === hoverIndex ? baseR * 1.6 : baseR;
           ctx.beginPath();
-          ctx.arc(p.x, p.y, Math.max(2.5, lineWidth + 0.5), 0, Math.PI * 2);
+          ctx.arc(p.x, p.y, r, 0, Math.PI * 2);
           ctx.fill();
         }
         ctx.restore();
@@ -123,6 +141,47 @@ export class LineChart extends ChartBase<LineChartOption> {
     });
   }
 
+  /** 命中检测：x 落在某类目带内即显示该类目所有系列值（y 在绘图区内即可）。 */
+  protected hitTestSeries(x: number, y: number): TooltipParams | null {
+    const scales = this.cartesian;
+    const plot = this.plot;
+    if (!scales || !plot) {
+      return null;
+    }
+    if (y < plot.y || y > plot.y + plot.height) {
+      return null;
+    }
+    const labels = this.option.xAxis.labels;
+    let best = -1;
+    let bestDist = Infinity;
+    for (let i = 0; i < labels.length; i += 1) {
+      const d = Math.abs(scales.category.center(i) - x);
+      if (d < bestDist) {
+        bestDist = d;
+        best = i;
+      }
+    }
+    if (best < 0 || bestDist > scales.category.bandWidth / 2) {
+      return null;
+    }
+    const items = this.option.series.map((s, i) => ({
+      name: s.name ?? `系列${i + 1}`,
+      value: s.data[best] ?? 0,
+      color: this.seriesColor(i, s.color),
+    }));
+    return { x, y, name: labels[best], items };
+  }
+
+  /** 从 hover 状态解析命中的类目索引，未命中返回 -1。 */
+  private getHoverCategoryIndex(): number {
+    const hover = this.hover;
+    if (!hover) {
+      return -1;
+    }
+    const labels = this.option.xAxis.labels;
+    return labels.indexOf(hover.name);
+  }
+
   /** 折线路径：直线或 Catmull-Rom 平滑插值（三次贝塞尔）。 */
   private tracePath(ctx: ICanvas2D, points: readonly Point[], smooth: boolean): void {
     if (points.length === 0) {

package/lib/charts/pie.ts

@@ -8,7 +8,7 @@ import { ChartBase } from '../core/chart';
 import type { LayoutResult } from '../core/layout';
 import type { LegendItem } from '../core/legend';
 import { applyFont } from '../core/text';
-import type { PieChartOption } from '../types';
+import type { PieChartOption, TooltipParams } from '../types';
 
 const TWO_PI = Math.PI * 2;
 
@@ -24,6 +24,61 @@ export class PieChart extends ChartBase<PieChartOption> {
     }));
   }
 
+  /** 命中检测：点落在某扇区（环形环带内）即显示该扇区名与数值占比。 */
+  protected hitTestSeries(x: number, y: number): TooltipParams | null {
+    const plot = this.plot;
+    if (!plot) {
+      return null;
+    }
+    const centerX = plot.x + plot.width / 2;
+    const centerY = plot.y + plot.height / 2;
+    const maxRadius = Math.min(plot.width, plot.height) / 2;
+    const outerRadius = resolveRadius(this.option.radius ?? '60%', maxRadius);
+    const innerRadius = resolveRadius(this.option.innerRadius ?? 0, maxRadius);
+    const startAngle = this.option.startAngle ?? -Math.PI / 2;
+
+    const dx = x - centerX;
+    const dy = y - centerY;
+    const dist = Math.hypot(dx, dy);
+    if (dist < innerRadius || dist > outerRadius) {
+      return null;
+    }
+
+    const data = this.option.data.filter((d) => d.value > 0);
+    const total = data.reduce((sum, d) => sum + d.value, 0);
+    if (total <= 0) {
+      return null;
+    }
+
+    // 命中角（canvas 系 y 向下，与绘制时角度递增方向一致）
+    let a = Math.atan2(dy, dx);
+    while (a < startAngle) {
+      a += TWO_PI;
+    }
+    let cur = startAngle;
+    for (let i = 0; i < data.length; i += 1) {
+      const d = data[i]!;
+      const sweep = (d.value / total) * TWO_PI;
+      if (a >= cur && a <= cur + sweep) {
+        const percent = Math.round((d.value / total) * 100);
+        return {
+          x,
+          y,
+          name: d.name,
+          items: [
+            {
+              name: d.name,
+              value: `${percent}%`,
+              color: d.color ?? this.seriesColor(i),
+            },
+          ],
+        };
+      }
+      cur += sweep;
+    }
+    return null;
+  }
+
   protected drawSeries(
     ctx: ICanvas2D,
     layout: LayoutResult,

package/lib/charts/radar.ts

@@ -8,7 +8,7 @@ import { ChartBase } from '../core/chart';
 import type { LayoutResult } from '../core/layout';
 import type { LegendItem } from '../core/legend';
 import { applyFont } from '../core/text';
-import type { RadarChartOption } from '../types';
+import type { RadarChartOption, TooltipParams } from '../types';
 
 interface PolarPoint {
   x: number;
@@ -141,6 +141,57 @@ export class RadarChart extends ChartBase<RadarChartOption> {
     });
   }
 
+  /** 命中检测：靠近任一数据顶点（阈值 24px）即显示该指标下所有系列值。 */
+  protected hitTestSeries(x: number, y: number): TooltipParams | null {
+    const plot = this.plot;
+    if (!plot) {
+      return null;
+    }
+    const centerX = plot.x + plot.width / 2;
+    const centerY = plot.y + plot.height / 2;
+    const radius =
+      this.option.radius ?? (Math.min(plot.width, plot.height) / 2) * 0.6;
+    const count = this.option.indicators.length;
+    if (count === 0) {
+      return null;
+    }
+    const startAngle = this.option.startAngle ?? -Math.PI / 2;
+    const step = TWO_PI / count;
+
+    let best = -1;
+    let bestDist = 24; // 命中阈值（px）
+    for (let i = 0; i < count; i += 1) {
+      const max =
+        this.option.indicators[i].max ?? this.indicatorMax(this.option, i);
+      const angle = startAngle + i * step;
+      for (let si = 0; si < this.option.series.length; si += 1) {
+        const value = this.option.series[si].data[i] ?? 0;
+        const ratio = max > 0 ? Math.max(0, Math.min(1, value / max)) : 0;
+        const px = centerX + Math.cos(angle) * radius * ratio;
+        const py = centerY + Math.sin(angle) * radius * ratio;
+        const d = Math.hypot(x - px, y - py);
+        if (d < bestDist) {
+          bestDist = d;
+          best = i;
+        }
+      }
+    }
+    if (best < 0) {
+      return null;
+    }
+    const items = this.option.series.map((s, si) => ({
+      name: s.name ?? `系列${si + 1}`,
+      value: s.data[best] ?? 0,
+      color: this.seriesColor(si, s.color),
+    }));
+    return {
+      x,
+      y,
+      name: this.option.indicators[best]!.name,
+      items,
+    };
+  }
+
   private indicatorMax(option: RadarChartOption, index: number): number {
     let max = 0;
     for (const series of option.series) {

package/lib/component.ts

@@ -62,6 +62,8 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
   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 };
@@ -89,6 +91,7 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
   protected onMounted(): void {
     this.attachChart();
     this.setupAutoResize();
+    this.setupHoverEvents();
   }
 
   protected onUpdated(): void {
@@ -101,6 +104,7 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
 
   protected onUnmounted(): void {
     this.teardownAutoResize();
+    this.teardownHoverEvents();
     this.destroyed = true;
     this.chart?.destroy();
     this.chart = null;
@@ -129,9 +133,67 @@ 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 = [];
   }
 
   /* —— 自动重绘：容器 / 窗口尺寸变化时防抖重绘 —— */
@@ -155,7 +217,7 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
 
     // Web：ResizeObserver 观察 canvas 自身（CSS 宽高 100%，容器变化即触发）。
     // SSR / 构建期无真实元素与 ResizeObserver，跳过。
-    const element = this.getElement();
+    const element = this.getElement() as HTMLCanvasElement | null;
     if (
       element &&
       typeof element.getContext === 'function' &&