nhanh-pure-function 3.0.7 → 4.1.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/Animate/index.d.ts

@@ -40,6 +40,16 @@ export declare function _Animate_CreateOscillator(initialMin: number, initialMax
  * @param targetValue - 目标值
  * @param stepCount - 动画步数
  * @param callback - 每帧回调函数
- * @param precision - 数值精度（默认2位小数）
+ * @param precision - 数值精度（默认4位小数）
  */
 export declare function _Animate_NumericTransition(startValue: number, targetValue: number, stepCount: number, callback: (currentValue: number) => void, precision?: number): void;
+/**
+ * 三次贝塞尔缓动（与 CSS `cubic-bezier(x1, y1, x2, y2)` 语义一致）
+ * 曲线端点为 (0,0) → (1,1)，控制点为 (x1,y1)、(x2,y2)。
+ * @param x1 第一个控制点 x
+ * @param y1 第一个控制点 y
+ * @param x2 第二个控制点 x
+ * @param y2 第二个控制点 y
+ * @returns 接收归一化时间 `t ∈ [0,1]`，返回缓动后的进度 `∈ [0,1]`（一般情况）
+ */
+export declare function _Animate_CubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number;

package/dist/Browser/Runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './soundEffects';
+export * from './webSocketClient';

package/dist/Browser/Runtime/soundEffects.d.ts

@@ -0,0 +1,47 @@
+/** 资源映射类型 */
+type Resource<T extends string> = Record<T, string>;
+/** 播放配置 */
+interface PlayOptions {
+    /** 是否无限循环播放 */
+    loop?: boolean;
+    /** 循环次数（优先级高于 loop，最少为 1 次） */
+    loopCount?: number;
+}
+/** 构造选项 */
+interface SoundEffectsOptions<T extends string> {
+    /**
+     * 初始化时即 fetch 下载为 Blob，并将 `soundSources` 中对应 key 的地址替换为 blob URL
+     */
+    holdKeys?: readonly T[];
+}
+/**
+ * 音效管理类
+ * 负责音效的加载与播放
+ */
+export declare class _Browser_SoundEffects<T extends string> {
+    /** 音效资源地址映射（preload 成功后对应项会替换为 blob: URL） */
+    private soundSources;
+    /** 各 key 下载任务，避免重复发起 */
+    private readonly preloadTasks;
+    constructor(resource: Resource<T>, options?: SoundEffectsOptions<T>);
+    /**
+     * 下载指定 key 的音频为 Blob，并将 `soundSources[key]` 替换为 `URL.createObjectURL` 结果（与 holdKeys 同一逻辑）
+     */
+    preload(key: T): Promise<void>;
+    preload(keys: readonly T[]): Promise<void>;
+    private fetchAndReplaceSource;
+    /**
+     * 根据 key 播放音效
+     * @param key 资源 key
+     * @param options 播放配置（循环等）
+     */
+    play(key: T, options?: PlayOptions): (() => void) | undefined;
+    /**
+     * 根据 URL 播放音效
+     * @param url 音频地址
+     * @param options 播放配置（循环等）
+     * @returns 停止播放的方法
+     */
+    playUrl(url: string, options?: PlayOptions): (() => void) | undefined;
+}
+export {};

package/dist/Browser/Runtime/webSocketClient.d.ts

@@ -0,0 +1,68 @@
+/** ping 配置 */
+interface WebSocketClientPingConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 间隔（毫秒） */
+    interval?: number;
+    /** 发送内容 */
+    content?: string;
+}
+/** WebSocket 客户端配置 */
+interface WebSocketClientConfig {
+    url?: string;
+    /** true 启用并采用默认参数，或传入具体配置 */
+    ping?: boolean | WebSocketClientPingConfig;
+    /** 最大重试次数，默认 3 */
+    maxRetryCount?: number;
+    /** 重试间隔（毫秒），默认 1000 */
+    retryInterval?: number;
+}
+/** WebSocket客户端 */
+export declare class _Browser_WebSocketClient {
+    /** WebSocket地址 */
+    url?: string;
+    /** WebSocket实例 */
+    private socket?;
+    /** 连接回调 */
+    onopen?: (ev: Event) => any;
+    /** 接收消息回调 */
+    onmessage?: (ev: MessageEvent) => any;
+    /** 错误回调 */
+    onerror?: (ev: Event) => any;
+    /** 关闭回调 */
+    onclose?: (ev: CloseEvent) => any;
+    /** ping 配置 */
+    readonly pingConfig: {
+        /** 是否启用 */
+        enabled: boolean;
+        /** 间隔（毫秒） */
+        interval: number;
+        /** 发送内容 */
+        content: string;
+    };
+    /** ping 定时器 */
+    private pingTimer?;
+    /** 重试配置 */
+    readonly retryConfig: {
+        /** 最大次数 */
+        maxCount: number;
+        /** 当前次数 */
+        currentCount: number;
+        /** 间隔（毫秒） */
+        interval: number;
+    };
+    /** 是否准备完毕 */
+    get ready(): boolean;
+    constructor(config?: WebSocketClientConfig);
+    /** 开始ping */
+    private startPing;
+    /** 开始重试 */
+    private startRetry;
+    /** 开始 */
+    start(url: string): void;
+    /** 停止 */
+    stop(): void;
+    /** 发送信息 */
+    send: WebSocket["send"];
+}
+export {};

package/dist/Browser/index.d.ts

@@ -1,4 +1,5 @@
 import { PaperType, WindowTarget } from '../Constant';
+export * from './Runtime';
 /**
  * 获取帧率
  * @param {(fps , frameTime)=>void} callback callback( 帧率 , 每帧时间 )
@@ -66,3 +67,36 @@ export declare class _Browser_SameOriginTabManager {
     /** 获取所有已经打开的标签页 */
     static getAllWindows(): Promise<string[]>;
 }
+/**
+ * 无操作（闲置）检测类
+ * 监听用户键盘、鼠标操作，更新用户活跃状态
+ * 支持注册/触发活跃/闲置状态的回调通知
+ */
+export declare class _Browser_IdleDetection {
+    /** 用户状态：active(活跃) / idle(闲置) */
+    status: "active" | "idle";
+    /** 活跃状态回调通知集合（key: 回调标识，value: 回调函数） */
+    readonly activeCallbacks: Map<string, () => void>;
+    /** 闲置状态回调通知集合（key: 回调标识，value: 回调函数） */
+    readonly idleCallbacks: Map<string, () => void>;
+    /** 闲置时间（分钟） */
+    idleTime: number;
+    /** 闲置判定定时器（5分钟无操作触发闲置状态） */
+    private timeoutTimer?;
+    constructor();
+    /**
+     * 重置闲置判定定时器
+     * 每次用户操作时重置，重新开始5分钟计时
+     */
+    resetTimeoutTimer(): void;
+    /**
+     * 激活为活跃状态
+     * 触发活跃回调，并重置定时器
+     */
+    private activate;
+    /**
+     * 标记为闲置状态
+     * 触发闲置回调，并清除定时器
+     */
+    private markAsIdle;
+}

package/dist/Browser/type.d.ts

@@ -0,0 +1,16 @@
+/** 定义消息类型枚举，避免硬编码字符串 */
+export declare enum ChannelMessageType {
+    /** 回执消息 */
+    RESPONSE = "response",
+    /** 询问消息 */
+    QUERY = "query"
+}
+/** 基础消息结构 */
+export interface ChannelMessage {
+    /** 消息类型 */
+    type: ChannelMessageType;
+    /** 消息关联的标识键 */
+    responseKey: string;
+    /** 标签页名称 "*" 表示所有标签页 */
+    name: string;
+}

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] & {
     /** 样式 */
@@ -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;
+    };
+}