nhanh-pure-function 3.0.6 → 4.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 ADMINnhanh
+Copyright (c) 2024 nha-nh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,33 @@
 # nhanh-pure-function
 
-纯函数工具库，提供了一些常用的纯函数工具，帮助您在 JavaScript/TypeScript 项目中更高效地处理数据。
+JavaScript/TypeScript 工具库，提供纯函数、画布、格式化、校验等常用能力，适用于前端项目的数据处理与可视化场景。
 
 ## 安装
 
-您可以通过 npm 安装该库：
-
 ```bash
 npm install nhanh-pure-function
 ```
 
-## 功能介绍
+## 模块概览
+
+| 模块 | 说明 |
+|------|------|
+| **Constant** | 常量：扩展名与 MIME 映射、单位标签、纸张尺寸、窗口目标等 |
+| **Animate** | 动画：进度调度、振荡器、数值过渡 |
+| **Blob** | 数据转图像 URL（Base64、ArrayBuffer、File 等） |
+| **Browser** | 浏览器：帧率、剪贴板、可打印区域、同源标签管理 |
+| **Canvas/Axis** | 数学坐标轴画布 `_Canvas_Axis`：图层、覆盖物（点/线/多边形/圆弧）、视图适配、覆盖物创建交互 |
+| **Canvas/TimeAxis** | 时间轴画布 `_Canvas_TimeAxis`：时间-像素换算、拖拽、缩放、时间范围绘制 |
+| **Element** | DOM：滚动结束监听、点击外部关闭、拖拽等 |
+| **File** | 文件：读取、下载（含进度）、创建并下载 |
+| **Format** | 格式化：首字母大写、百分比、千位分隔符、文件大小、时间戳、链接名等 |
+| **Math** | 数学：经纬度↔平面坐标、点到线段距离、圆弧点、中点、边界交点等 |
+| **Types** | 类型工具：`RequiredBy`、`PartialBy`、`DeepPartial`、`Mutable` |
+| **Utility** | 工具：空闲执行、等待条件、合并对象、防抖节流、UUID 等 |
+| **Valid** | 校验：数组校验、误差范围、点在多边形内、线段与矩形相交、数据类型、安全上下文、文件类型等 |
+| **_Tip** | 提示流：`info`/`success`/`warning`/`error` 链式注册与执行 |
 
-`nhanh-pure-function` 库旨在提供一系列纯函数，这些函数在处理数据时不会产生副作用，确保函数的输入和输出之间的映射关系是确定的。这使得代码更易于测试、维护和复用。
 
 ## 许可证
 
-[MIT](https://opensource.org/licenses/MIT)
+[MIT](https://opensource.org/licenses/MIT)

package/dist/Canvas/{LayerGroup → Axis/LayerGroup}/index.d.ts

@@ -1,4 +1,4 @@
-import { default as _Canvas } from '..';
+import { default as _Canvas_Axis } from '..';
 import { OverlayType } from '../OverlayGroup';
 import { default as Layer } from './layer';
 import { EventHandler, default as EventController } from '../public/eventController';
@@ -14,7 +14,7 @@ export default class LayerGroup extends EventController {
     defaultHover: EventHandler<"hover">;
     defaultDragg: EventHandler<"dragg">;
     defaultDown: EventHandler<"down">;
-    setMainCanvas(mainCanvas?: _Canvas): void;
+    setMainCanvas(mainCanvas?: _Canvas_Axis): void;
     setNotifyReload(notifyReload?: () => void): void;
     /** 获取图层 */
     getLayer(name: string): Layer | undefined;

package/dist/Canvas/{LayerGroup → Axis/LayerGroup}/layer.d.ts

@@ -1,7 +1,10 @@
-import { default as _Canvas } from '..';
+import { default as _Canvas_Axis } from '..';
 import { default as OverlayGroup, OverlayType } from '../OverlayGroup';
 import { default as EventController } from '../public/eventController';
-type ConstructorOption = ConstructorParameters<typeof EventController>[0];
+type ConstructorOption = ConstructorParameters<typeof EventController>[0] & {
+    /** 层级 */
+    zIndex?: number;
+};
 /**
  * 图层事件触发机制说明：
  *
@@ -15,15 +18,17 @@ type ConstructorOption = ConstructorParameters<typeof EventController>[0];
  *    事件触发对象就应该是该 图层 中的 覆盖物，这时就不应该再触发其他 图层 的事件了；
  */
 export default class Layer extends EventController {
+    private _zIndex;
     /** 层级 */
-    zIndex: number;
+    get zIndex(): number;
+    set zIndex(zIndex: number);
     protected canvas: HTMLCanvasElement;
     protected ctx: CanvasRenderingContext2D;
     /** 是否需要重新绘制 */
     private isReload;
     groups: Map<string, OverlayGroup>;
     constructor(option: ConstructorOption);
-    setMainCanvas(mainCanvas?: _Canvas): void;
+    setMainCanvas(mainCanvas?: _Canvas_Axis): void;
     setNotifyReload(notifyReload?: () => void): void;
     setGroupNotifyReload(group: OverlayGroup): void;
     /** 获取覆盖物组 */
@@ -34,8 +39,6 @@ export default class Layer extends EventController {
     removeGroup(groups: OverlayGroup | OverlayGroup[]): void;
     /** 清空覆盖物 */
     clearGroup(): void;
-    /** 设置图层的 zIndex 值 */
-    setzIndex(zIndex: number): void;
     /** 本次绘制的覆盖物 */
     private currentDrawOverlays;
     /** 获取画布 */

package/dist/Canvas/Axis/OverlayCreator/index.d.ts

@@ -0,0 +1,52 @@
+import { default as _Canvas_Axis } from '..';
+import { default as Line } from '../OverlayGroup/line';
+import { default as Polygon } from '../OverlayGroup/polygon';
+/**
+ * 管理单次「创建覆盖物」的交互（从开始绘制到完成/取消）。
+ * 覆盖物有两种定位方式：value = 坐标轴上的值 [x,y][]，position = 画布上的位置 px；本类通过 overlay.value 定位。
+ */
+export default class OverlayCreator {
+    /** 绑定的画布实例 */
+    private canvas;
+    private layerGroup;
+    /** 创建中覆盖物的绘制层（置顶以保证可见） */
+    private overlayLayer;
+    /** 该层内的覆盖物分组，便于统一增删 */
+    private overlayGroup;
+    /** 当前正在创建的覆盖物（多边形或线），其顶点通过 overlay.value 即坐标轴上的值表示 */
+    private overlay?;
+    /** 已确定的顶点在坐标轴上的值列表 [x, y][]，对应 overlay.value */
+    private axisValueList?;
+    /** 创建时暂存的其他图层群组的 isInteractive，编辑完成后用于复原 */
+    private savedLayerGroupInteractive;
+    /**
+     * 用户自定义限位器：传入原始 value [x, y]（坐标轴上的值），约束到合法范围后返回。
+     */
+    axisValueLimiter?: (value: [number, number]) => [number, number];
+    constructor(canvas: _Canvas_Axis);
+    /** 按类型开始创建：多边形或线 */
+    create(type: "polygon" | "line"): Line | Polygon | undefined;
+    /** 禁用除创建层外的其他图层群组交互，并记录原始 isInteractive 以便复原 */
+    private disableOtherLayerGroups;
+    /** 复原此前禁用的图层群组的 isInteractive */
+    private restoreLayerGroupsInteractive;
+    createLine(): Line;
+    createPolygon(): Polygon;
+    finish?: (overlay?: Polygon | Line) => void;
+    /** 从创建层中移除指定覆盖物，不传则清空该层全部 */
+    removeOverlays(overlay?: Polygon | Line): void;
+    /** 清空创建层并重置当前创建状态 */
+    clear(): void;
+    /** 销毁实例：清空覆盖物并移除所有事件监听 */
+    destroy(): void;
+    /** 当前类型完成绘制所需的最少顶点数（多边形 3，线 2） */
+    private get minPointCount();
+    /** 从鼠标事件得到坐标轴上的 [x, y]，若设置了限位器则先限位再返回 */
+    private getAxisValueFromEvent;
+    /** 鼠标移动：用已确定顶点 + 当前鼠标的坐标轴值更新 overlay.value 预览（至少有一个确定点后才生效） */
+    private handleMousemove;
+    /** 左键点击：将当前坐标轴值追加为顶点并刷新 overlay.value 预览 */
+    private handleClick;
+    /** 右键：若顶点数达标则写回 overlay.value 并回调完成，否则移除当前覆盖物并取消创建 */
+    private handleContextmenu;
+}

package/dist/Canvas/{OverlayGroup → Axis/OverlayGroup}/index.d.ts

@@ -1,4 +1,4 @@
-import { default as _Canvas } from '..';
+import { default as _Canvas_Axis } from '..';
 import { default as EventController } from '../public/eventController';
 import { default as Text } from './text';
 import { default as Point } from './point';
@@ -14,7 +14,7 @@ export default class OverlayGroup extends EventController {
     overlays: Set<OverlayType>;
     constructor(option: ConstructorOption);
     /** 设置主画布 */
-    setMainCanvas(mainCanvas?: _Canvas): void;
+    setMainCanvas(mainCanvas?: _Canvas_Axis): void;
     /** 设置覆盖物重新绘制方法 */
     setNotifyReload(notifyReload?: () => void): void;
     /** 添加覆盖物 */

package/dist/Canvas/{OverlayGroup → Axis/OverlayGroup}/public/overlay.d.ts

@@ -1,7 +1,7 @@
-import { default as _Canvas } from '../..';
+import { default as _Canvas_Axis } from '../..';
 import { OverlayType } from '../index';
 import { EventHandler, default as EventController } from '../../public/eventController';
-import { _Type_DeepPartial } from '../../..';
+import { _Type_DeepPartial } from '../../../../';
 import { BaseLineStyle, PointStyleType } from '../../common.type';
 type ConstructorOption<T, V> = ConstructorParameters<typeof EventController>[0] & {
     /** 样式 */
@@ -13,7 +13,7 @@ type ConstructorOption<T, V> = ConstructorParameters<typeof EventController>[0]
     /** 动态点位 */
     dynamicPosition?: V;
     /** 坐标轴上的值 */
-    value: V;
+    value?: V;
     /** 偏移 */
     offset?: {
         x: number;
@@ -77,7 +77,7 @@ export default abstract class Overlay<T, V extends [number, number] | [number, n
     redrawOnIsHoverChange: boolean;
     /** 默认 hover  事件 */
     defaultHover: EventHandler<"hover">;
-    setMainCanvas(mainCanvas?: _Canvas): void;
+    setMainCanvas(mainCanvas?: _Canvas_Axis): void;
     setNotifyReload(notifyReload?: () => void): void;
     /** 值范围 */
     private _valueScope?;

package/dist/Canvas/{core → Axis/core}/axis.d.ts

@@ -1,5 +1,5 @@
 import { default as Canvas } from '..';
-import { _Type_DeepPartial } from '../..';
+import { _Type_DeepPartial } from '../../../';
 export default class Axis {
     /** 画布 */
     private canvas;

package/dist/Canvas/{core → Axis/core}/basedata.d.ts

@@ -102,7 +102,7 @@ export default class BaseData extends EventController {
     /** 绘制坐标轴 */
     drawAxis: Axis;
     /** 图层群组 集合 */
-    protected layerGroups: Map<string, LayerGroup>;
+    layerGroups: Map<string, LayerGroup>;
     constructor(option: ConstructorOption);
     setNotifyReload(notifyReload?: () => void): void;
     /** 获取默认中心点位置 */

package/dist/Canvas/{core → Axis/core}/quikmethod.d.ts

@@ -1,4 +1,4 @@
-import { _Type_DeepPartial } from '../..';
+import { _Type_DeepPartial } from '../../../';
 import { default as Axis } from './axis';
 import { default as Event } from './event';
 import { default as OverlayGroup, OverlayType } from '../OverlayGroup';

package/dist/Canvas/{core → Axis/core}/style.d.ts

@@ -1,4 +1,4 @@
-import { _Type_DeepPartial } from '../..';
+import { _Type_DeepPartial } from '../../../';
 import { KnownStyleKeys, StyleType } from '../common.type';
 import { default as BaseData } from './basedata';
 type ConstructorOption = ConstructorParameters<typeof BaseData>[0] & {

package/dist/Canvas/{index.d.ts → Axis/index.d.ts}

@@ -9,11 +9,13 @@ import { default as Polygon } from './OverlayGroup/polygon';
 import { default as Custom } from './OverlayGroup/custom';
 import { default as Arc } from './OverlayGroup/arc';
 import { default as ArcTo } from './OverlayGroup/arcTo';
+import { default as OverlayCreator } from './OverlayCreator';
+import { default as ViewFit } from './public/viewFit';
 import { DeepArray } from './common.type';
 export type * from './index.types';
 type ConstructorOption = ConstructorParameters<typeof QuickMethod>[0] & {
     /** 轴线显示属性 */
-    axisShow?: Parameters<_Canvas["toggleAxis"]>[0];
+    axisShow?: Parameters<_Canvas_Axis["toggleAxis"]>[0];
 };
 /**
  * 你好啊你好的画布工具类
@@ -21,13 +23,12 @@ type ConstructorOption = ConstructorParameters<typeof QuickMethod>[0] & {
  *
  * 使用示例:
  * - GitHub演示:
- *   - 基础画布: https://adminnhanh.github.io/nhanh-frontend-view/#/canvas/_Canvas
- *   - 动态图表(月牙定理): https://adminnhanh.github.io/nhanh-frontend-view/#/math/DynamicDiagram/%E6%9C%88%E7%89%99%E5%AE%9A%E7%90%86
- * - 阿里云演示:
- *   - 基础画布: https://nhanh.xin/#/canvas/_Canvas
- *   - 动态图表(月牙定理): https://nhanh.xin/#/math/DynamicDiagram/%E6%9C%88%E7%89%99%E5%AE%9A%E7%90%86
+ *   - 基础画布: https://nha-nh.github.io/canvas/_Canvas_Axis
+ *   - 动态图表(月牙定理): https://nha-nh.github.io/math/DynamicDiagram/%E6%9C%88%E7%89%99%E5%AE%9A%E7%90%86
  */
-export declare class _Canvas extends QuickMethod {
+export declare class _Canvas_Axis extends QuickMethod {
+    /** 视图适配工具：默认缩放、居中计算 */
+    static ViewFit: typeof ViewFit;
     /** 图层群组 */
     static LayerGroup: typeof LayerGroup;
     /** 图层 */
@@ -48,6 +49,8 @@ export declare class _Canvas extends QuickMethod {
     static Arc: typeof Arc;
     /** 圆角 */
     static ArcTo: typeof ArcTo;
+    /** 按坐标轴值创建覆盖物（多边形/线）的交互管理 */
+    overlayCreator: OverlayCreator;
     constructor(option: ConstructorOption);
     private initLayerGroups;
     /** 获取图层群组 集合 */
@@ -67,4 +70,4 @@ export declare class _Canvas extends QuickMethod {
     /** 销毁 */
     destroy(): void;
 }
-export default _Canvas;
+export default _Canvas_Axis;

package/dist/Canvas/{index.types.d.ts → Axis/index.types.d.ts}

@@ -9,6 +9,8 @@ import { default as Axis } from './core/axis';
 import { default as Custom } from './OverlayGroup/custom';
 import { default as Arc } from './OverlayGroup/arc';
 import { default as ArcTo } from './OverlayGroup/arcTo';
+import { default as OverlayCreatorByAxisValue } from './OverlayCreator';
+import { default as ViewFit } from './public/viewFit';
 import { EventHandler } from './public/eventController';
 import { default as Overlay } from './OverlayGroup/public/overlay';
-export type { LayerGroup, OverlayGroup, Layer, OverlayType, Overlay, Point, Text, Line, Polygon, Axis, Custom, Arc, ArcTo, EventHandler, };
+export type { LayerGroup, OverlayGroup, Layer, OverlayType, Overlay, Point, Text, Line, Polygon, Axis, Custom, Arc, ArcTo, OverlayCreatorByAxisValue, ViewFit, EventHandler, };

package/dist/Canvas/{public → Axis/public}/basedata.d.ts

@@ -1,4 +1,4 @@
-import { default as _Canvas } from '..';
+import { default as _Canvas_Axis } from '..';
 declare abstract class Base<T extends Base<T>> {
     /** 父级 */
     parent?: T;
@@ -7,15 +7,15 @@ declare abstract class Base<T extends Base<T>> {
     /** 自定义扩展数据 */
     extData?: any;
     /** 主画布 */
-    mainCanvas?: _Canvas;
+    mainCanvas?: _Canvas_Axis;
     private _isRecalculate;
     /** 是否需要重新计算坐标 */
     get isRecalculate(): boolean;
     set isRecalculate(isRecalculate: boolean);
     /** 是否是同一个主画布 */
-    equalsMainCanvas(mainCanvas?: _Canvas): boolean;
+    equalsMainCanvas(mainCanvas?: _Canvas_Axis): boolean;
     /** 设置主画布 */
-    setMainCanvas(mainCanvas?: _Canvas): void;
+    setMainCanvas(mainCanvas?: _Canvas_Axis): void;
     /** 通知重新加载 */
     notifyReload?: (needForceExecute?: boolean) => void;
     /** 设置通知重新加载 */
@@ -47,7 +47,7 @@ interface BaseDataOptions {
     /** 自定义扩展数据 */
     extData?: any;
     /** 主画布 */
-    mainCanvas?: _Canvas;
+    mainCanvas?: _Canvas_Axis;
     /** 通知重新加载 */
     notifyReload?: (needForceExecute?: boolean) => void;
     /** 是否显示 */

package/dist/Canvas/Axis/public/viewFit.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 视图适配工具：根据内容尺寸与容器尺寸计算默认缩放与居中位置，供画布/图像适配使用。
+ */
+export default class ViewFit {
+    /**
+     * 计算默认缩放比例，使图像适配视图容器
+     * @param naturalWidth 图像原始宽度
+     * @param naturalHeight 图像原始高度
+     * @param viewWidth 容器宽度
+     * @param viewHeight 容器高度
+     * @param step 缩放步长
+     * @param factor 每翻一倍对应的增量（factor / step = 10）
+     * @returns 缩放比例（步长 0.02），小于1表示缩小，大于1表示放大
+     */
+    static computeDefaultScale(naturalWidth: number, naturalHeight: number, viewWidth: number, viewHeight: number, step?: number, factor?: number): number;
+    /**
+     * 计算默认居中偏移，使内容在视图中居中
+     * @param naturalWidth 图像/内容原始宽度
+     * @param naturalHeight 图像/内容原始高度
+     * @param viewWidth 容器宽度
+     * @param viewHeight 容器高度
+     * @returns 居中时的 left、top 偏移
+     */
+    static computeDefaultCenter(naturalWidth: number, naturalHeight: number, viewWidth: number, viewHeight: number): {
+        left: number;
+        top: number;
+    };
+}

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

@@ -0,0 +1,165 @@
+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;
+}
+/**
+ * 鼠标时间提示：仅负责计算鼠标位置对应的时间
+ * - 监听 canvas 的 mousemove / mouseleave
+ * - 通知外部：显示/隐藏、canvasX、time
+ */
+type TimeAxisMouseTimeInfo = {
+    /** 是否显示指示线/时间提示 */
+    visible: boolean;
+    /** 鼠标在 canvas 内的 x（像素） */
+    canvasX: number;
+    /** 鼠标在 canvas 内的 y（像素） */
+    canvasY: number;
+    /** 鼠标位置对应的时间戳（ms） */
+    time: number;
+};
+/**
+ * 时间轴动画曲线：入参 `t` 为 [0, 1]，返回 eased 后的进度（也应为 [0, 1]）
+ */
+type TimeAxisAnimationCurve = (t: number) => number;
+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 {
+    /**
+     * 按时间范围绘制圆角矩形（常用于高亮某段时间区间）
+     */
+    drawTimeRangeRoundedRect(options: {
+        /** 区间起点时间戳（ms） */
+        startTimeMs: number;
+        /** 区间终点时间戳（ms） */
+        endTimeMs: number;
+        /** 矩形 y 坐标（像素，默认 1） */
+        y?: number;
+        /** 矩形高度（像素，默认使用画布高度 - 1） */
+        height?: number;
+        /** 圆角半径：可为单值或 canvas roundRect 支持的数组（默认 10） */
+        radius?: number | number[];
+        /** 填充色：不传则不填充 */
+        fillStyle?: string;
+        /** 描边色：不传则不描边 */
+        strokeStyle?: string;
+        /** 描边线宽（默认 1） */
+        lineWidth?: number;
+    }): void;
+}
+export default _Canvas_TimeAxis;