nhanh-pure-function 3.0.7 → 4.1.0

package/dist/Canvas/TimeAxis/index.d.ts

@@ -0,0 +1,153 @@
+import { TimeAxisAnimationCurve, TimeAxisFillStyle, TimeAxisMouseTimeInfo } from './type';
+declare class TimeAxisCanvasManager {
+    /** Canvas DOM id（用于 `document.getElementById` 定位） */
+    private id;
+    /** 绑定到的 canvas 元素 */
+    private canvas?;
+    /** Canvas 2D 绘制上下文（可能为 null） */
+    private ctx;
+    /** 当前渲染像素宽度（会随尺寸变化更新） */
+    private width;
+    /** 当前渲染像素高度（会随尺寸变化更新） */
+    private height;
+    /** 尺寸变化监听器，用于驱动重绘 */
+    private resizeObserver?;
+    /** @param id canvas DOM id（通过 getElementById 定位） */
+    constructor(id: string);
+    /**
+     * 初始化 canvas 引用/上下文，并同步画布像素尺寸与注册 resize 监听
+     * @returns true 表示初始化成功；false 表示找不到 canvas 或上下文
+     */
+    init(onResize: () => void): boolean;
+    /** 获取当前 CanvasRenderingContext2D */
+    getContext(): CanvasRenderingContext2D | null;
+    /** 获取当前 canvas DOM 元素 */
+    getCanvas(): HTMLCanvasElement | undefined;
+    /** 获取当前画布像素尺寸 */
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    /** 根据元素在页面中的尺寸同步 canvas.width/canvas.height */
+    syncCanvasSize(): void;
+    /** 注册 ResizeObserver，当尺寸变化时同步尺寸并触发外部重绘 */
+    private setupResizeListener;
+    /** 销毁 ResizeObserver，释放资源 */
+    destroy(): void;
+}
+declare class TimeAxisBase {
+    /** 负责 canvas 引用、2D context 获取与尺寸同步 */
+    protected canvasManager: TimeAxisCanvasManager;
+    /** 鼠标拖拽：把横向像素位移映射到 currentTime 偏移 */
+    private offsetDrag?;
+    /** 鼠标滚轮缩放：调整 timeSpacing，并保持缩放锚点时间不变 */
+    private wheelZoom?;
+    /** 鼠标指示：把鼠标位置映射到时间并通知外部 UI */
+    private mouseTimeReporter?;
+    /** 外部回调：用于更新“鼠标时间提示/指示线”状态 */
+    onMouseTimeChange?: (info: TimeAxisMouseTimeInfo) => void;
+    /** centerTime 动画 runId：用于取消旧动画回调（拖拽开始时立即失效） */
+    private centerTimeAnimationRunId;
+    /** 当前时间轴的“左移/右移”基准时间（与 centerTime、画布 x 共同决定可视区间） */
+    private currentTime;
+    /** 时间轴主刻度间隔：单位 ms */
+    private timeSpacing;
+    /** timeSpacing 对应的像素距离：单位 px */
+    private timeSpacingInPixels;
+    /** 背景与坐标轴绘制样式 */
+    readonly styleConfig: {
+        backgroundColor: string;
+        axisColor: string;
+        textFont: string;
+    };
+    /** 刻度绘制比例与文本基线偏移 */
+    readonly tickConfig: {
+        heightMinor: number;
+        heightMajor: number;
+        labelOffsetY: number;
+        minorTicksPerMajor: number;
+    };
+    /**
+     * 创建时间轴引擎：会在构造后 `requestAnimationFrame` 初始化并开始渲染。
+     * @param id canvas DOM id
+     * @param onMouseTimeChange 鼠标移动时回调（用于显示/更新鼠标时间提示）
+     */
+    constructor(id: string, onMouseTimeChange?: (info: TimeAxisMouseTimeInfo) => void);
+    /**
+     * 用户自定义绘制回调：在绘制背景之后、绘制刻度之前执行
+     * 可用于叠加额外图形（如指示线、事件点等）
+     */
+    onDrawOverlay?: (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+    /** 初始化交互：拖拽平移、滚轮缩放、鼠标时间通知，并触发首次绘制 */
+    private init;
+    /** 重绘：先清理并绘制背景/叠加层，再绘制刻度与文本 */
+    private render;
+    /** 绘制背景（清屏 + 填充背景色） */
+    private renderBackground;
+    /** 绘制刻度与时间标签（按当前可视区间计算 start/end） */
+    private renderAxis;
+    /**
+     * 计算当前视口需要绘制的时间范围与对应像素区间。
+     * 返回值用于 `renderAxis()` 中的刻度循环。
+     */
+    private get axisDrawingRange();
+    /** 获取当前画布中心点对应的时间戳（ms） */
+    private get centerTime();
+    /** 设置中心时间戳，并据此反推 currentTime 以保持时间视图正确 */
+    private set centerTime(value);
+    /** 把画布内 x 像素换算为时间戳（ms） */
+    getTimeAtCanvasX(x: number): number;
+    /** 反向把时间与像素 x 绑定，调整 currentTime 使两者一致 */
+    private setTimeAtCanvasX;
+    /** 把时间戳（ms）换算为画布内 x 像素 */
+    getCanvasXAtTime(time: number): number;
+    /**
+     * 以动画方式把时间轴中心时间移动到目标值。
+     * 用户交互（拖拽/滚轮）会通过 runId 机制取消旧动画回调。
+     */
+    animateCenterTimeTo(targetCenterTime: number, options?: {
+        /** 动画持续的帧数（数值越大越“慢”、越容易感受到快慢） */
+        durationFrames?: number;
+        /** 动画曲线：入参 t∈[0,1]，出参 easedT∈[0,1] */
+        curve?: TimeAxisAnimationCurve;
+    }): void;
+    /** 递增 runId，使正在进行的中心时间动画回调失效 */
+    private stopCenterTimeAnimation;
+    /** 销毁：清理交互监听器与释放 canvas 资源 */
+    destroy(): void;
+}
+/**
+ * 给使用方的绘制辅助类（Overlay 绘制）
+ * - 封装 time <-> x 的换算
+ * - 提供常用图形绘制方法（如按时间范围画圆角矩形）
+ */
+export declare class _Canvas_TimeAxis extends TimeAxisBase {
+    /**
+     * 将填充样式解析为 ctx.fillStyle 可用的值（纯色或线性渐变）
+     * @param rect 矩形区域，用于计算渐变起止点
+     * @param fillStyle 纯色字符串或渐变配置
+     */
+    private resolveFillStyle;
+    /**
+     * 按时间范围绘制圆角矩形（常用于高亮某段时间区间）
+     */
+    drawTimeRangeRoundedRect(options: {
+        /** 区间起点时间戳（ms） */
+        startTimeMs: number;
+        /** 区间终点时间戳（ms） */
+        endTimeMs: number;
+        /** 矩形 y 坐标（像素，默认 1） */
+        y?: number;
+        /** 矩形高度（像素，默认使用画布高度 - 1） */
+        height?: number;
+        /** 圆角半径：可为单值或 canvas roundRect 支持的数组（默认 10） */
+        radius?: number | number[];
+        /** 填充色：不传则不填充，支持纯色或线性渐变 */
+        fillStyle?: TimeAxisFillStyle;
+        /** 描边色：不传则不描边 */
+        strokeStyle?: string;
+        /** 描边线宽（默认 1） */
+        lineWidth?: number;
+    }): void;
+}
+export default _Canvas_TimeAxis;

package/dist/Canvas/TimeAxis/type.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 鼠标时间提示信息
+ */
+export type TimeAxisMouseTimeInfo = {
+    /** 是否显示指示线/时间提示 */
+    visible: boolean;
+    /** 鼠标在 canvas 内的 x（像素） */
+    canvasX: number;
+    /** 鼠标在 canvas 内的 y（像素） */
+    canvasY: number;
+    /** 鼠标位置对应的时间戳（ms） */
+    time: number;
+};
+/** 矩形区域（像素坐标） */
+export type TimeAxisRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** 渐变颜色停靠点 */
+export type TimeAxisGradientColorStop = {
+    color: string;
+    offset: number;
+};
+/** 线性渐变配置：x1/y1/x2/y2 为相对矩形的比例 [0,1]，表示渐变起止方向 */
+export type TimeAxisGradientFillStyle = {
+    x1: number;
+    x2: number;
+    y1: number;
+    y2: number;
+    colorStops: TimeAxisGradientColorStop[];
+};
+/** 填充样式：纯色或线性渐变 */
+export type TimeAxisFillStyle = string | TimeAxisGradientFillStyle;
+/**
+ * 时间轴动画曲线：入参 `t` 为 [0, 1]，返回 eased 后的进度（也应为 [0, 1]）
+ */
+export type TimeAxisAnimationCurve = (t: number) => number;