transone-chart 0.1.2

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * transone-chart 公共类型定义。
+ *
+ * 所有图表共用一份 Option 风格配置（对齐 ECharts 心智：xAxis / yAxis /
+ * series / legend / title），但实现零依赖、纯 Canvas 2D 绘制。
+ */
+/** 一期支持的图表类型。 */
+export type ChartType = 'line' | 'bar' | 'pie' | 'radar';
+/** 默认主题色板（与 transone-ui 主色一致，可按需覆盖）。 */
+export declare const DEFAULT_PALETTE: readonly string[];
+export declare const DEFAULT_TEXT_COLOR = "#323233";
+export declare const DEFAULT_AXIS_COLOR = "#c8c9cc";
+export declare const DEFAULT_GRID_COLOR = "#ebedf0";
+export declare const DEFAULT_FONT_FAMILY = "-apple-system, BlinkMacSystemFont, 'Helvetica Neue', 'PingFang SC', 'Microsoft YaHei', sans-serif";
+/** 标题配置。 */
+export interface TitleOption {
+    text: string;
+    fontSize?: number;
+    color?: string;
+    /** 标题与绘图区之间的留白，默认 16。 */
+    padding?: number;
+}
+/** 图例配置。 */
+export interface LegendOption {
+    show?: boolean;
+    /** 图例位置：顶部横向 / 底部横向 / 右侧纵向。 */
+    position?: 'top' | 'bottom' | 'right';
+    fontSize?: number;
+    color?: string;
+    /** 图例色块边长（正方形），默认 12。 */
+    markerSize?: number;
+    /** 图例项之间的水平间距，默认 16。 */
+    itemGap?: number;
+}
+/** 数值轴（y 轴/雷达数值）配置。 */
+export interface ValueAxisOption {
+    /** 显式最小值；缺省自动 nice。 */
+    min?: number;
+    /** 显式最大值；缺省自动 nice。 */
+    max?: number;
+    /** 刻度分段数，默认 5。 */
+    splitCount?: number;
+    labelFontSize?: number;
+    labelColor?: string;
+    gridColor?: string;
+    gridLineWidth?: number;
+    /** 网格虚线，如 [4, 4]；默认实线。 */
+    gridLineDash?: number[];
+    /** 是否显示网格，默认 true。 */
+    showGrid?: boolean;
+    /** 刻度标签格式化。 */
+    format?: (value: number) => string;
+}
+/** 类目轴（x 轴/雷达指标）配置。 */
+export interface CategoryAxisOption {
+    labels: readonly string[];
+    labelFontSize?: number;
+    labelColor?: string;
+    gridColor?: string;
+    gridLineWidth?: number;
+    /** 是否显示类目网格竖线，默认 false。 */
+    showGrid?: boolean;
+}
+/** —— 折线图 —— */
+export interface LineSeries {
+    name?: string;
+    data: readonly number[];
+    color?: string;
+    /** 平滑曲线（三次贝塞尔插值），默认 false。 */
+    smooth?: boolean;
+    /** 是否填充系列与数值轴之间的面积，默认 false。 */
+    area?: boolean;
+    /** 是否绘制数据点标记，默认 true。 */
+    showSymbol?: boolean;
+    lineWidth?: number;
+}
+export interface LineChartOption {
+    type: 'line';
+    title?: TitleOption;
+    legend?: LegendOption;
+    xAxis: CategoryAxisOption;
+    yAxis?: ValueAxisOption;
+    series: readonly LineSeries[];
+    /** 数值轴是否从 0 开始（数据全为正时强制含 0），默认 false（按数据范围紧凑显示）。 */
+    startFromZero?: boolean;
+    /** 背景色（如 'rgba(22,119,255,0.06)'），默认无。 */
+    backgroundColor?: string;
+}
+/** —— 柱状图 —— */
+export interface BarSeries {
+    name?: string;
+    data: readonly number[];
+    color?: string;
+    /** 堆叠组名；同名系列纵向堆叠。 */
+    stack?: string;
+    /** 柱体宽度（px），缺省按类目带自动计算。 */
+    barWidth?: number;
+    /** 柱体圆角，默认 0。 */
+    borderRadius?: number;
+}
+export interface BarChartOption {
+    type: 'bar';
+    title?: TitleOption;
+    legend?: LegendOption;
+    xAxis: CategoryAxisOption;
+    yAxis?: ValueAxisOption;
+    series: readonly BarSeries[];
+    /** 横向柱状图（类目轴转纵向、数值轴转横向），默认 false。 */
+    horizontal?: boolean;
+    backgroundColor?: string;
+}
+/** —— 饼图 —— */
+export interface PieDatum {
+    name: string;
+    value: number;
+    color?: string;
+}
+export interface PieChartOption {
+    type: 'pie';
+    data: readonly PieDatum[];
+    title?: TitleOption;
+    legend?: LegendOption;
+    /** 外半径：数字（px）或百分比字符串（相对 min(width, height) / 2），默认 '60%'。 */
+    radius?: number | string;
+    /** 内半径：0 为饼图；>0 为环形图，默认 0。 */
+    innerRadius?: number | string;
+    /** 是否显示扇区标签（名称 + 百分比），默认 true。 */
+    showLabel?: boolean;
+    labelFontSize?: number;
+    labelColor?: string;
+    /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
+    startAngle?: number;
+    backgroundColor?: string;
+}
+/** —— 雷达图 —— */
+export interface RadarIndicator {
+    name: string;
+    /** 指标最大值；缺省取所有系列该指标的最大值。 */
+    max?: number;
+}
+export interface RadarSeries {
+    name?: string;
+    data: readonly number[];
+    color?: string;
+    /** 是否填充多边形区域，默认 true。 */
+    area?: boolean;
+    lineWidth?: number;
+}
+export interface RadarChartOption {
+    type: 'radar';
+    indicators: readonly RadarIndicator[];
+    series: readonly RadarSeries[];
+    title?: TitleOption;
+    legend?: LegendOption;
+    /** 网格层数，默认 5。 */
+    splitCount?: number;
+    gridColor?: string;
+    gridLineWidth?: number;
+    labelFontSize?: number;
+    labelColor?: string;
+    /** 雷达中心半径（px），缺省取 min(width, height) / 2 的 60%。 */
+    radius?: number;
+    /** 起始角（弧度），默认 -Math.PI / 2（12 点方向），顺时针。 */
+    startAngle?: number;
+    backgroundColor?: string;
+}
+export type ChartOption = LineChartOption | BarChartOption | PieChartOption | RadarChartOption;
+/** 图表渲染上下文（适配器解析后的产物）。 */
+export interface ChartRenderContext {
+    /** 跨端 Canvas 2D 上下文。 */
+    ctx: import('./core/canvas').ICanvas2D;
+    /** 逻辑宽度（CSS px）。 */
+    width: number;
+    /** 逻辑高度（CSS px）。 */
+    height: number;
+    /** 设备像素比。 */
+    dpr: number;
+    /** 自定义色板，缺省使用 DEFAULT_PALETTE。 */
+    palette?: readonly string[];
+}

package/lib/adapters/index.ts

@@ -0,0 +1,18 @@
+export type {
+  ResolveCanvasOptions,
+  ResolvedCanvas,
+} from './types';
+export { detectPixelRatio } from './types';
+
+export { resolveWebCanvas } from './web';
+
+export {
+  getMiniProgramCanvasNode,
+  getMiniProgramGlobal,
+  resolveMiniProgramCanvas,
+  detectMiniProgramPixelRatio,
+} from './miniprogram';
+export type { MiniProgramCanvasNode, MiniProgramGlobal } from './miniprogram';
+
+export { resolveNativeCanvas } from './native';
+export type { NativeCanvasHost } from './native';

package/lib/adapters/miniprogram.ts

@@ -0,0 +1,146 @@
+/**
+ * 小程序适配器：微信 / 阿里 / 字节的 Canvas 2D 节点 → ChartRenderContext。
+ *
+ * 获取流程（各端一致，仅全局名不同）：
+ *   canvas type="2d" → 节点 node → node.getContext('2d') → ICanvas2D
+ *
+ * 节点获取依赖 SelectorQuery，属于组件生命周期职责，由
+ * getMiniProgramCanvasNode() 提供；本文件只负责「节点 → 上下文」，
+ * 以及 DPR 探测（pixelRatio 从各端系统信息接口读取）。
+ */
+
+import type { ChartRenderContext } from '../types';
+import type { ICanvas2D } from '../core/canvas';
+import { detectPixelRatio, type ResolveCanvasOptions } from './types';
+
+/** 小程序 Canvas 2D 节点（各端 node 的公共形状）。 */
+export interface MiniProgramCanvasNode {
+  getContext(type: '2d'): unknown;
+  width: number;
+  height: number;
+}
+
+export type MiniProgramGlobal = 'wx' | 'my' | 'tt';
+
+/** 安全读取小程序全局（避免与官方类型定义冲突，模式同 transone request）。 */
+export function getMiniProgramGlobal(
+  name: MiniProgramGlobal
+): Record<string, unknown> | null {
+  const host = getHost();
+  const api = host[name];
+  return typeof api === 'object' && api !== null
+    ? (api as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * 通过 SelectorQuery 获取 Canvas 2D 节点（组件/页面内调用）。
+ * 各端 API 形状一致：createSelectorQuery().in(instance).select(selector)
+ *   .fields({ node: true, size: true }).exec(callback)
+ */
+export function getMiniProgramCanvasNode(options: {
+  /** 端标识，缺省自动探测（wx → my → tt）。 */
+  platform?: MiniProgramGlobal;
+  /** 组件/页面实例（.in() 入参）。 */
+  instance?: unknown;
+  /** canvas 选择器，如 '#chart'。 */
+  selector: string;
+}): Promise<MiniProgramCanvasNode> {
+  const platform =
+    options.platform ?? detectMiniProgramGlobal() ?? 'wx';
+  const api = getMiniProgramGlobal(platform);
+  const queryFn = api?.createSelectorQuery;
+  if (typeof queryFn !== 'function') {
+    return Promise.reject(
+      new Error(`getMiniProgramCanvasNode: ${platform}.createSelectorQuery is not available`)
+    );
+  }
+
+  return new Promise((resolve, reject) => {
+    let query = queryFn.call(api);
+    if (options.instance && typeof query.in === 'function') {
+      query = query.in(options.instance);
+    }
+    if (typeof query.select !== 'function') {
+      reject(new Error(`${platform}.createSelectorQuery().select is not available`));
+      return;
+    }
+    query
+      .select(options.selector)
+      .fields({ node: true, size: true })
+      .exec((res: unknown) => {
+        const first = Array.isArray(res) ? res[0] : undefined;
+        const node = first?.node as MiniProgramCanvasNode | undefined;
+        if (!node || typeof node.getContext !== 'function') {
+          reject(
+            new Error(
+              `getMiniProgramCanvasNode: canvas node not found for "${options.selector}"`
+            )
+          );
+          return;
+        }
+        resolve(node);
+      });
+  });
+}
+
+/** 探测当前小程序全局（wx → my → tt），均不存在返回 null。 */
+export function detectMiniProgramGlobal(): MiniProgramGlobal | null {
+  if (getMiniProgramGlobal('wx')) {
+    return 'wx';
+  }
+  if (getMiniProgramGlobal('my')) {
+    return 'my';
+  }
+  if (getMiniProgramGlobal('tt')) {
+    return 'tt';
+  }
+  return null;
+}
+
+/** 读取各端设备像素比（wx.getSystemInfoSync / my.getSystemInfoSync / tt.getSystemInfoSync）。 */
+export function detectMiniProgramPixelRatio(platform?: MiniProgramGlobal): number {
+  const name = platform ?? detectMiniProgramGlobal() ?? 'wx';
+  const api = getMiniProgramGlobal(name);
+  const sync = api?.getSystemInfoSync;
+  if (typeof sync === 'function') {
+    try {
+      const info = sync.call(api) as { pixelRatio?: number };
+      if (typeof info.pixelRatio === 'number' && info.pixelRatio > 0) {
+        return info.pixelRatio;
+      }
+    } catch {
+      // 探测失败回退通用探测
+    }
+  }
+  return detectPixelRatio();
+}
+
+/**
+ * 从 Canvas 2D 节点解析渲染上下文。
+ * 物理画布尺寸由节点自身管理（width/height 已在平台侧按像素比设置），
+ * 此处只做归一化返回。
+ */
+export function resolveMiniProgramCanvas(
+  node: MiniProgramCanvasNode,
+  options: ResolveCanvasOptions = {}
+): ChartRenderContext {
+  const ctx2d = node.getContext('2d');
+  if (!ctx2d) {
+    throw new Error('resolveMiniProgramCanvas: 2d context is not available');
+  }
+
+  const dpr = options.dpr ?? detectMiniProgramPixelRatio();
+  const width = options.width ?? node.width;
+  const height = options.height ?? node.height;
+  const ctx = ctx2d as unknown as ICanvas2D;
+
+  return { ctx, width, height, dpr, palette: options.palette };
+}
+
+function getHost(): Record<string, unknown> {
+  if (typeof globalThis !== 'undefined') {
+    return globalThis as unknown as Record<string, unknown>;
+  }
+  return {};
+}

package/lib/adapters/native.ts

@@ -0,0 +1,39 @@
+/**
+ * 原生 App 适配器（占位 / 契约声明）。
+ *
+ * 未来 iOS / Android / 鸿蒙 原生端接入路径：
+ * 1. 宿主提供原生 canvas 能力（Skia / ArkUI Canvas / WebView 桥），
+ *    把原生绘制 API 实现为 ICanvas2D（见 core/canvas.ts 契约）
+ * 2. 实现 resolveNativeCanvas()，返回 ChartRenderContext（含 DPR 与逻辑尺寸）
+ * 3. 之后引擎与四种图表零改动运行
+ *
+ * 本文件当前不导出可运行实现，仅保留类型契约与接入文档，防止
+ * 平台差异悄悄渗入引擎。
+ */
+
+import type { ChartRenderContext } from '../types';
+
+/** 未来原生端需实现的最小宿主接口。 */
+export interface NativeCanvasHost {
+  /** 逻辑尺寸（CSS px）。 */
+  width: number;
+  height: number;
+  /** 设备像素比。 */
+  pixelRatio: number;
+  /** 原生绘图上下文（宿主实现为 ICanvas2D 契约）。 */
+  getContext(type: '2d'): unknown;
+}
+
+/**
+ * 未来实现：原生 canvas 节点 → ChartRenderContext。
+ * 当前未接入任何原生端，调用会明确报错，避免静默降级。
+ */
+export function resolveNativeCanvas(
+  _host: NativeCanvasHost
+): ChartRenderContext {
+  throw new Error(
+    'resolveNativeCanvas is not implemented yet. ' +
+      'Native app support (iOS/Android/HarmonyOS) is planned for a future phase; ' +
+      'implement ICanvas2D on the host side and fill in this resolver.'
+  );
+}

package/lib/adapters/types.ts

@@ -0,0 +1,44 @@
+/**
+ * 平台适配层：把各端 Canvas 2D 上下文解析为统一渲染上下文
+ * （ICanvas2D + 逻辑尺寸 + DPR）。
+ *
+ * 适配器只负责三件事：
+ * 1. 拿到上下文（HTMLCanvasElement / 小程序 canvas node / 未来原生 canvas）
+ * 2. 计算设备像素比并设置物理画布尺寸
+ * 3. 返回引擎需要的 ChartRenderContext
+ *
+ * 引擎代码永远不直接接触 DOM / wx / native API。
+ */
+
+import type { ChartRenderContext } from '../types';
+
+export interface ResolveCanvasOptions {
+  /** 逻辑宽度（CSS px）；缺省取节点实际尺寸。 */
+  width?: number;
+  /** 逻辑高度（CSS px）；缺省取节点实际尺寸。 */
+  height?: number;
+  /** 设备像素比；缺省自动探测。 */
+  dpr?: number;
+  /** 自定义色板。 */
+  palette?: readonly string[];
+}
+
+export interface ResolvedCanvas {
+  context: ChartRenderContext;
+}
+
+/** 通用探测设备像素比（web 与小程序可用 globalThis 访问）。 */
+export function detectPixelRatio(): number {
+  const host = getHost();
+  if (typeof host.devicePixelRatio === 'number' && host.devicePixelRatio > 0) {
+    return host.devicePixelRatio;
+  }
+  return 1;
+}
+
+function getHost(): Record<string, unknown> {
+  if (typeof globalThis !== 'undefined') {
+    return globalThis as unknown as Record<string, unknown>;
+  }
+  return {};
+}

package/lib/adapters/web.ts

@@ -0,0 +1,41 @@
+/**
+ * Web 适配器：HTMLCanvasElement → ChartRenderContext。
+ *
+ * - 把物理画布尺寸设为 逻辑尺寸 × DPR，保证高分屏清晰
+ * - 上下文为标准 CanvasRenderingContext2D，天然满足 ICanvas2D 契约
+ */
+
+import type { ChartRenderContext } from '../types';
+import type { ICanvas2D } from '../core/canvas';
+import { detectPixelRatio, type ResolveCanvasOptions } from './types';
+
+/**
+ * 从 HTMLCanvasElement 解析渲染上下文。
+ * 会就地修改 canvas.width / canvas.height 为物理像素尺寸。
+ */
+export function resolveWebCanvas(
+  canvas: HTMLCanvasElement,
+  options: ResolveCanvasOptions = {}
+): ChartRenderContext {
+  if (!canvas) {
+    throw new Error('resolveWebCanvas: canvas element is required');
+  }
+
+  const ctx2d = canvas.getContext('2d');
+  if (!ctx2d) {
+    throw new Error('resolveWebCanvas: 2d context is not available');
+  }
+
+  const dpr = options.dpr ?? detectPixelRatio();
+  const width = options.width ?? (canvas.clientWidth || canvas.width);
+  const height = options.height ?? (canvas.clientHeight || canvas.height);
+
+  // 物理像素 = 逻辑像素 × DPR
+  canvas.width = Math.round(width * dpr);
+  canvas.height = Math.round(height * dpr);
+
+  // 标准 CanvasRenderingContext2D 已满足 ICanvas2D 全部成员
+  const ctx = ctx2d as unknown as ICanvas2D;
+
+  return { ctx, width, height, dpr, palette: options.palette };
+}