transone-chart 0.1.2 → 0.1.4

package/dist/types.d.ts

@@ -126,6 +126,14 @@ 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 点方向），顺时针。 */

package/lib/charts/bar.ts

@@ -9,6 +9,7 @@
 
 import type { ICanvas2D } from '../core/canvas';
 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';
@@ -154,20 +155,25 @@ export class BarChart extends ChartBase<BarChartOption> {
   }
 
   private computeSlot(
-    category: { bandStart(index: number): number; innerWidth(): number },
+    category: CategoryScale,
     groupCount: number,
     explicitWidth?: number
   ): Slot {
+    const band = category.bandWidth;
+    const inner = category.innerWidth();
     if (explicitWidth !== undefined) {
-      // 显式柱宽：组内居中
+      // 显式柱宽：整组在类目带内居中
       return {
-        offset: (category.innerWidth() - explicitWidth) / 2,
+        offset: (band - explicitWidth * groupCount) / 2,
         size: explicitWidth,
       };
     }
-    const size = category.innerWidth() / Math.max(1, groupCount) * 0.8;
-    const gap = (category.innerWidth() - size * groupCount) / 2;
-    return { offset: gap, size };
+    const size = (inner / Math.max(1, groupCount)) * 0.8;
+    // 柱区（size × groupCount）先在 inner 内居中，再随 inner 在类目带内居中，
+    // 保证整组柱中心落在类目中心（与轴标签 center(i) 对齐）。
+    const bandSide = (band - inner) / 2;
+    const innerSide = (inner - size * groupCount) / 2;
+    return { offset: bandSide + innerSide, size };
   }
 
   private drawBar(

package/lib/charts/pie.ts

@@ -77,19 +77,56 @@ export class PieChart extends ChartBase<PieChartOption> {
       ctx.stroke();
       ctx.restore();
 
-      // 扇区标签：名称 + 百分比，画在扇区角平分线上
+      // 扇区标签：名称 + 百分比
+      // - inside（默认）：画在扇区角平分线上（白字）
+      // - outside：引线把文字引到扇区外（右半区左对齐、左半区右对齐，避免文字跨越中线）
       if (option.showLabel !== false) {
         const midAngle = angle + sweep / 2;
-        const labelRadius = (outerRadius + (innerRadius > 0 ? innerRadius : 0)) / 2 * 0.85;
-        const labelX = centerX + Math.cos(midAngle) * labelRadius;
-        const labelY = centerY + Math.sin(midAngle) * labelRadius;
         const percent = total > 0 ? Math.round((d.value / total) * 100) : 0;
+        const text = `${d.name} ${percent}%`;
 
-        applyFont(ctx, option.labelFontSize ?? 10);
-        ctx.fillStyle = option.labelColor ?? '#ffffff';
-        ctx.textAlign = 'center';
-        ctx.textBaseline = 'middle';
-        ctx.fillText(`${d.name} ${percent}%`, labelX, labelY);
+        if (option.labelPosition === 'outside') {
+          const lineLength = option.labelLineLength ?? 14;
+          const gap = option.labelGap ?? 6;
+          const dirX = Math.cos(midAngle);
+          const dirY = Math.sin(midAngle);
+          // 引线第一段：扇区边缘沿平分线向外
+          const edgeX = centerX + dirX * outerRadius;
+          const edgeY = centerY + dirY * outerRadius;
+          const bendX = centerX + dirX * (outerRadius + lineLength);
+          const bendY = centerY + dirY * (outerRadius + lineLength);
+          // 第二段：水平延伸到文字锚点（右半向右、左半向左）
+          const horizontal = dirX >= 0 ? 1 : -1;
+          const textX = bendX + horizontal * gap;
+          const textY = bendY;
+
+          ctx.save();
+          ctx.strokeStyle = option.labelLineColor ?? '#c0c4cc';
+          ctx.lineWidth = 1;
+          ctx.beginPath();
+          ctx.moveTo(edgeX, edgeY);
+          ctx.lineTo(bendX, bendY);
+          ctx.lineTo(textX, textY);
+          ctx.stroke();
+          ctx.restore();
+
+          applyFont(ctx, option.labelFontSize ?? 10);
+          ctx.fillStyle = option.labelColor ?? '#323233';
+          ctx.textAlign = horizontal > 0 ? 'left' : 'right';
+          ctx.textBaseline = 'middle';
+          ctx.fillText(text, textX, textY);
+        } else {
+          const labelRadius =
+            ((outerRadius + (innerRadius > 0 ? innerRadius : 0)) / 2) * 0.85;
+          const labelX = centerX + Math.cos(midAngle) * labelRadius;
+          const labelY = centerY + Math.sin(midAngle) * labelRadius;
+
+          applyFont(ctx, option.labelFontSize ?? 10);
+          ctx.fillStyle = option.labelColor ?? '#ffffff';
+          ctx.textAlign = 'center';
+          ctx.textBaseline = 'middle';
+          ctx.fillText(text, labelX, labelY);
+        }
       }
 
       angle += sweep;

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,20 @@ 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;
 
   protected initState(): TcChartState {
     return { canvasId: CANVAS_ID };
@@ -71,6 +88,7 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
 
   protected onMounted(): void {
     this.attachChart();
+    this.setupAutoResize();
   }
 
   protected onUpdated(): void {
@@ -82,6 +100,7 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
   }
 
   protected onUnmounted(): void {
+    this.teardownAutoResize();
     this.destroyed = true;
     this.chart?.destroy();
     this.chart = null;
@@ -98,7 +117,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);
@@ -114,7 +134,88 @@ export class TcChart extends Component<TcChartProps, TcChartState> {
     return super.getElement() as HTMLCanvasElement | null;
   }
 
-  private resolveContext(): Promise<ChartRenderContext> {
+  /* —— 自动重绘：容器 / 窗口尺寸变化时防抖重绘 —— */
+
+  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();
+    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 | null> {
     if (this.props.resolve) {
       return Promise.resolve(this.props.resolve(this.getElement()));
     }
@@ -141,9 +242,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

@@ -72,9 +72,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;
   }
 

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

@@ -154,6 +154,14 @@ 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 点方向），顺时针。 */

package/package.json

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