nhanh-pure-function 4.0.0 → 4.2.0

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/Axis/LayerGroup/index.d.ts

@@ -23,7 +23,7 @@ export default class LayerGroup extends EventController {
     /** 删除图层 */
     removeLayer(layers: Layer | Layer[]): void;
     /** 清空图层 */
-    clearLayers(): void;
+    clearLayer(): void;
     /** 收集图层的 canvas */
     fetchCanvas(): [number, HTMLCanvasElement, [[number, number], OverlayType][]][];
 }

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

@@ -34,7 +34,7 @@ export default class OverlayCreator {
     createPolygon(): Polygon;
     finish?: (overlay?: Polygon | Line) => void;
     /** 从创建层中移除指定覆盖物，不传则清空该层全部 */
-    removeOverlays(overlay?: Polygon | Line): void;
+    removeOverlay(overlay?: Polygon | Line): void;
     /** 清空创建层并重置当前创建状态 */
     clear(): void;
     /** 销毁实例：清空覆盖物并移除所有事件监听 */

package/dist/Canvas/Axis/OverlayGroup/billboard.d.ts

@@ -0,0 +1,50 @@
+import { default as Overlay } from './public/overlay';
+import { OverlayType } from './index';
+import { EventHandler } from '../public/eventController';
+import { BillboardStyleType } from '../common.type';
+type ObjectFit = "fill" | "contain" | "cover" | "scale-down";
+type ConstructorOption = ConstructorParameters<typeof Overlay<BillboardStyleType, [number, number][]>>[0] & {
+    url?: string;
+    objectFit?: ObjectFit;
+};
+declare abstract class BillboardBase extends Overlay<BillboardStyleType, [
+    number,
+    number
+][]> {
+    private _ready;
+    get ready(): boolean;
+    set ready(value: boolean);
+    protected image: HTMLImageElement;
+    private _url?;
+    get url(): string | undefined;
+    set url(url: string | undefined);
+    private _objectFit;
+    get objectFit(): ObjectFit;
+    set objectFit(value: ObjectFit);
+    /** 当前广告牌绘制矩形（左上角坐标 + 宽高） */
+    protected get drawRect(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        sx?: number;
+        sy?: number;
+        sw?: number;
+        sh?: number;
+    };
+    private loadImage;
+    protected updateBaseData(): void;
+}
+export default class Billboard extends BillboardBase {
+    constructor(option: ConstructorOption);
+    defaultDragg: EventHandler<"dragg">;
+    protected updateValueScope(): void;
+    isPointInPath(x: number, y: number): boolean;
+    isPointInStroke(x: number, y: number): boolean;
+    /** 设置样式 */
+    protected setOverlayStyles(ctx: CanvasRenderingContext2D): BillboardStyleType;
+    protected get computedValueScopeStyles(): {};
+    draw(ctx: CanvasRenderingContext2D): void;
+    getDraw(): [(ctx: CanvasRenderingContext2D) => void, OverlayType] | void;
+}
+export {};

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

@@ -7,8 +7,9 @@ import { default as Polygon } from './polygon';
 import { default as Custom } from './custom';
 import { default as Arc } from './arc';
 import { default as ArcTo } from './arcTo';
+import { default as Billboard } from './billboard';
 type ConstructorOption = ConstructorParameters<typeof EventController>[0];
-export type OverlayType = Text | Point | Line | Arc | ArcTo | Polygon | Custom<any>;
+export type OverlayType = Text | Point | Line | Arc | ArcTo | Polygon | Billboard | Custom<any>;
 export default class OverlayGroup extends EventController {
     /** 覆盖物集合 */
     overlays: Set<OverlayType>;
@@ -18,13 +19,13 @@ export default class OverlayGroup extends EventController {
     /** 设置覆盖物重新绘制方法 */
     setNotifyReload(notifyReload?: () => void): void;
     /** 添加覆盖物 */
-    addOverlays(overlays: OverlayType[] | OverlayType): void;
+    addOverlay(overlays: OverlayType[] | OverlayType): void;
     /** 是否包含覆盖物 */
     hasOverlay(overlay: OverlayType): boolean;
     /** 移除覆盖物 */
-    removeOverlays(overlays: OverlayType[] | OverlayType): void;
+    removeOverlay(overlays: OverlayType[] | OverlayType): void;
     /** 清空覆盖物 */
-    clearOverlays(): void;
+    clearOverlay(): void;
     /** 获取覆盖物的绘制方法 */
     getOverlaysDrawingMethod(): [number, [(ctx: CanvasRenderingContext2D) => void, OverlayType]][];
 }

package/dist/Canvas/Axis/common.type.d.ts

@@ -93,6 +93,11 @@ export type PolygonStyleType = {
     /** 点位样式 */
     point: PointStyleType;
 };
+/** 广告牌样式 */
+export type BillboardStyleType = {
+    /** 描边 */
+    stroke: BaseLineStyle;
+};
 /** 主题样式 */
 export type StyleItemType = {
     /** 背景色 */
@@ -111,6 +116,8 @@ export type StyleItemType = {
     arcTo: ArcToStyleType;
     /** 面样式 */
     polygon: PolygonStyleType;
+    /** 广告牌样式 */
+    billboard: BillboardStyleType;
 };
 /** 主题样式 */
 export type StyleType = Record<KnownStyleKeys, StyleItemType> & Record<string, StyleItemType>;

package/dist/Canvas/Axis/core/quikmethod.d.ts

@@ -15,6 +15,8 @@ declare class QuickMethod_Get extends Event {
         overlays_line: OverlayGroup | undefined;
         overlays_polygon: OverlayGroup | undefined;
         overlays_custom: OverlayGroup | undefined;
+        overlays_billboard: OverlayGroup | undefined;
+        overlays_other: OverlayGroup | undefined;
     } | undefined;
     /**
      * 获取所有可见的覆盖层（Overlay）

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

@@ -12,6 +12,7 @@ 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';
+import { default as Billboard } from './OverlayGroup/billboard';
 export type * from './index.types';
 type ConstructorOption = ConstructorParameters<typeof QuickMethod>[0] & {
     /** 轴线显示属性 */
@@ -49,6 +50,8 @@ export declare class _Canvas_Axis extends QuickMethod {
     static Arc: typeof Arc;
     /** 圆角 */
     static ArcTo: typeof ArcTo;
+    /** 图片 */
+    static Billboard: typeof Billboard;
     /** 按坐标轴值创建覆盖物（多边形/线）的交互管理 */
     overlayCreator: OverlayCreator;
     constructor(option: ConstructorOption);

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

@@ -13,4 +13,5 @@ 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, OverlayCreatorByAxisValue, ViewFit, EventHandler, };
+import { default as Billboard } from './OverlayGroup/billboard';
+export type { LayerGroup, OverlayGroup, Layer, OverlayType, Overlay, Point, Text, Line, Polygon, Axis, Custom, Arc, ArcTo, Billboard, OverlayCreatorByAxisValue, ViewFit, EventHandler, };

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

@@ -1,3 +1,4 @@
+import { TimeAxisAnimationCurve, TimeAxisFillStyle, TimeAxisMouseTimeInfo } from './type';
 declare class TimeAxisCanvasManager {
     /** Canvas DOM id（用于 `document.getElementById` 定位） */
     private id;
@@ -34,25 +35,6 @@ declare class TimeAxisCanvasManager {
     /** 销毁 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;
@@ -140,6 +122,12 @@ declare class TimeAxisBase {
  * - 提供常用图形绘制方法（如按时间范围画圆角矩形）
  */
 export declare class _Canvas_TimeAxis extends TimeAxisBase {
+    /**
+     * 将填充样式解析为 ctx.fillStyle 可用的值（纯色或线性渐变）
+     * @param rect 矩形区域，用于计算渐变起止点
+     * @param fillStyle 纯色字符串或渐变配置
+     */
+    private resolveFillStyle;
     /**
      * 按时间范围绘制圆角矩形（常用于高亮某段时间区间）
      */
@@ -154,8 +142,8 @@ export declare class _Canvas_TimeAxis extends TimeAxisBase {
         height?: number;
         /** 圆角半径：可为单值或 canvas roundRect 支持的数组（默认 10） */
         radius?: number | number[];
-        /** 填充色：不传则不填充 */
-        fillStyle?: string;
+        /** 填充色：不传则不填充，支持纯色或线性渐变 */
+        fillStyle?: TimeAxisFillStyle;
         /** 描边色：不传则不描边 */
         strokeStyle?: string;
         /** 描边线宽（默认 1） */

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;

package/dist/Element/Runtime/fullscreen.d.ts

@@ -0,0 +1,48 @@
+/** 进入全屏模式 */
+export declare function _Element_EnterFullscreen(element?: HTMLElement | string): Promise<void>;
+/** 退出全屏模式 */
+export declare function _Element_ExitFullscreen(): Promise<void>;
+/** 判断是否处于全屏模式 */
+export declare function _Element_IsFullscreen(element?: HTMLElement | string): boolean;
+/**
+ * 返回一个用于切换全屏模式的函数
+ * @param {HTMLElement} content - 需要进入全屏的元素
+ * 该函数通过检查不同浏览器的特定方法来实现全屏切换
+ */
+export declare function _Element_Fullscreen(element?: HTMLElement | string): (() => void) | undefined;
+/**
+ * 元素全屏状态观察器
+ * 监听元素的全屏状态变化，并通过回调函数通知状态改变
+ * @param notify - 全屏状态变化回调函数，接收一个布尔值参数表示当前是否为全屏状态
+ * @param selectors - 要观察的元素或元素选择器，默认为document.documentElement
+ * @returns 返回一个清理函数，调用后可移除所有事件监听器
+ */
+export declare function _Element_FullscreenObserver(notify: (isFull: boolean) => void, selectors?: HTMLElement | string): (() => void) | undefined;
+/**
+ * 全屏控制：绑定目标元素，提供进入 / 退出 / 切换；在 document 上监听各厂商全屏事件并回调当前是否以该元素全屏。
+ * 构造时即注册监听；务必在不再使用时调用 {@link destroy}，避免泄漏。
+ */
+export declare class _Element_FullscreenController {
+    /** 要全屏展示的目标元素 */
+    private targetElement?;
+    /**
+     * 全屏状态变化回调。参数为 `true` 表示当前全屏元素为本实例的目标元素。
+     */
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+    /** 解除 {@link attachFullscreenChangeListeners} 注册的 document 监听 */
+    private detachFullscreenListeners?;
+    constructor(targetOrSelector?: HTMLElement | string, onFullscreenChange?: (isFullscreen: boolean) => void);
+    /**
+     * 设置或更新目标元素（`HTMLElement` 或 CSS 选择器；未传时内部会回退到 `document.documentElement`）
+     */
+    init(targetOrSelector?: HTMLElement | string): void;
+    /** 使目标元素进入浏览器全屏 */
+    enter(): void;
+    /** 退出浏览器全屏（不区分由哪个元素进入） */
+    exit(): void;
+    /** 若当前已为该目标全屏则退出，否则进入全屏 */
+    toggle(): void;
+    private attachFullscreenChangeListeners;
+    /** 移除全屏事件监听，实例不应再使用 */
+    destroy(): void;
+}

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

@@ -0,0 +1,2 @@
+/** Element 模块内依赖 DOM / 运行时的工具集合（全屏等）；新文件在此 `export *` 即可。 */
+export * from './fullscreen';

package/dist/Element/index.d.ts

@@ -1,4 +1,5 @@
 import { DragOption, LocalDragOptions, UiLibrary } from './type';
+export * from './Runtime';
 /**
  * 滚动结束监听器
  * @param {(trigger: "vertical" | "horizontal") => void} callback
@@ -47,26 +48,6 @@ export declare class _Element_LocalDrag {
     mousemove(event: Event): void;
     mouseup(): void;
 }
-/** 进入全屏模式 */
-export declare function _Element_EnterFullscreen(element?: HTMLElement | string): Promise<void>;
-/** 退出全屏模式 */
-export declare function _Element_ExitFullscreen(): Promise<void>;
-/** 判断是否处于全屏模式 */
-export declare function _Element_IsFullscreen(element?: HTMLElement | string): boolean;
-/**
- * 返回一个用于切换全屏模式的函数
- * @param {HTMLElement} content - 需要进入全屏的元素
- * 该函数通过检查不同浏览器的特定方法来实现全屏切换
- */
-export declare function _Element_Fullscreen(element?: HTMLElement | string): (() => void) | undefined;
-/**
- * 元素全屏状态观察器
- * 监听元素的全屏状态变化，并通过回调函数通知状态改变
- * @param notify - 全屏状态变化回调函数，接收一个布尔值参数表示当前是否为全屏状态
- * @param selectors - 要观察的元素或元素选择器，默认为document.documentElement
- * @returns 返回一个清理函数，调用后可移除所有事件监听器
- */
-export declare function _Element_FullscreenObserver(notify: (isFull: boolean) => void, selectors?: HTMLElement | string): (() => void) | undefined;
 /**
  * 单位转换 12** -> **px
  * @param {string} width