nhanh-pure-function 4.5.0 → 4.6.0

package/dist/Browser/index.d.ts

@@ -1,5 +1,5 @@
 import { PaperType, WindowTarget } from '../Constant';
-export * from './Runtime';
+export * from './modules';
 /**
  * 获取帧率
  * @param {(fps , frameTime)=>void} callback callback( 帧率 , 每帧时间 )

package/dist/Element/index.d.ts

@@ -1,5 +1,5 @@
 import { DragOption, LocalDragOptions, UiLibrary } from './type';
-export * from './Runtime';
+export * from './modules';
 /**
  * 滚动结束监听器
  * @param {(trigger: "vertical" | "horizontal") => void} callback

package/dist/Math/index.d.ts

@@ -32,6 +32,19 @@ export declare function _Math_PointToLineDistance(point: [number, number], lineS
  * @returns [起点坐标[x,y], 终点坐标[x,y]]
  */
 export declare function _Math_GetArcPoints(x: number, y: number, radius: number, startAngle: number, endAngle: number, axisX?: number, axisY?: number): [[number, number], [number, number]];
+/**
+ * 计算两个经纬度坐标之间的直线距离（单位：米）。
+ *
+ * 先将经纬度通过 Mercator 投影转换为平面坐标（米），
+ * 再计算二维平面欧几里得距离，适用于短距离近似计算。
+ *
+ * @param lng1 第一个点的经度（度），范围 [-180, 180]
+ * @param lat1 第一个点的纬度（度），范围 [-85.05, 85.05]
+ * @param lng2 第二个点的经度（度），范围 [-180, 180]
+ * @param lat2 第二个点的纬度（度），范围 [-85.05, 85.05]
+ * @returns 两点间的距离（米）
+ */
+export declare function _Math_CalculateDistanceLngLat(lng1: number, lat1: number, lng2: number, lat2: number): number;
 /** 计算平面直角坐标系中两点的距离 */
 export declare function _Math_CalculateDistance2D(x1: number, y1: number, x2: number, y2: number): number;
 /** 获取两点的中点 */
@@ -75,3 +88,77 @@ export declare function _Math_GetBezierCurveNodes(nodes: [number, number][], pro
  * @returns 椭圆上的点 [x, y]
  */
 export declare function _Math_GetEllipsePoints(aspectRatio: number, progress: number, normalizeToUnitSquare?: boolean): [number, number];
+/**
+ * 将数值钳制在指定区间内。
+ * @param value 输入值
+ * @param min 下限
+ * @param max 上限
+ * @returns 钳制后的值
+ */
+export declare function _Math_Clamp(value: number, min: number, max: number): number;
+/**
+ * 线性插值。
+ * @param a 起始值
+ * @param b 结束值
+ * @param t 插值参数，[0, 1]
+ * @returns 插值结果
+ */
+export declare function _Math_Lerp(a: number, b: number, t: number): number;
+/**
+ * 逆线性插值：计算 value 在 [a, b] 区间的位置比例。
+ * @param a 区间下限
+ * @param b 区间上限
+ * @param value 当前值
+ * @returns 比例 t，0 表示在 a，1 表示在 b
+ */
+export declare function _Math_InverseLerp(a: number, b: number, value: number): number;
+/**
+ * 将 value 从 [fromMin, fromMax] 区间映射到 [toMin, toMax] 区间。
+ * @param value 输入值
+ * @param fromMin 源区间下限
+ * @param fromMax 源区间上限
+ * @param toMin 目标区间下限
+ * @param toMax 目标区间上限
+ * @returns 映射后的值
+ */
+export declare function _Math_Remap(value: number, fromMin: number, fromMax: number, toMin: number, toMax: number): number;
+/**
+ * 角度转弧度。
+ * @param deg 角度（度）
+ * @returns 弧度
+ */
+export declare function _Math_DegToRad(deg: number): number;
+/**
+ * 弧度转角度。
+ * @param rad 弧度
+ * @returns 角度（度）
+ */
+export declare function _Math_RadToDeg(rad: number): number;
+/**
+ * 将角度归一化到指定范围。
+ * @param angle 输入角度（度）
+ * @param signed 为 true 时归一化到 [-180, 180)，默认 false 归一化到 [0, 360)
+ * @returns 归一化后的角度
+ */
+export declare function _Math_NormalizeAngle(angle: number, signed?: boolean): number;
+/**
+ * 判断点是否在矩形内（含边界）。
+ * @param px 点 X 坐标
+ * @param py 点 Y 坐标
+ * @param rx 矩形左上角 X
+ * @param ry 矩形左上角 Y
+ * @param rw 矩形宽度
+ * @param rh 矩形高度
+ * @returns true 表示点在矩形内
+ */
+export declare function _Math_IsPointInRect(px: number, py: number, rx: number, ry: number, rw: number, rh: number): boolean;
+/**
+ * 判断点是否在圆形内（含边界）。
+ * @param px 点 X 坐标
+ * @param py 点 Y 坐标
+ * @param cx 圆心 X
+ * @param cy 圆心 Y
+ * @param radius 圆半径
+ * @returns true 表示点在圆内
+ */
+export declare function _Math_IsPointInCircle(px: number, py: number, cx: number, cy: number, radius: number): boolean;

package/dist/Types/index.d.ts

@@ -37,3 +37,12 @@ export type _Type_DeepPartial<T> = {
 export type _Type_Mutable<T> = {
     -readonly [P in keyof T]: T[P];
 };
+/**
+ * 递归地将类型中的所有只读（readonly）属性转换为可写（writable）属性
+ * @template T - 要处理的基础类型
+ * @description 与TypeScript内置的Writable不同，DeepWritable会对嵌套对象进行递归处理，
+ *              使所有层级的属性都变为可写。适用于需要修改对象属性的场景，但需要确保对象不会被其他地方引用。
+ */
+export type _Type_DeepWritable<T> = {
+    -readonly [P in keyof T]: _Type_DeepWritable<T[P]>;
+};

package/dist/Utility/index.d.ts

@@ -1,4 +1,5 @@
-export * from './Runtime';
+import { _Type_DeepWritable } from '../Types';
+export * from './modules';
 /**
  * 寻找空闲时机执行传入方法
  * @param callback  需执行的方法
@@ -73,7 +74,7 @@ export declare function _Utility_RotateList<T>(list: T[]): T[][];
  * @param {any} val - 需要克隆的值
  * @returns {any} - 克隆后的值
  */
-export declare function _Utility_Clone<T>(val: T): T;
+export declare function _Utility_Clone<T>(val: T): _Type_DeepWritable<T>;
 /**
  * 函数装饰器：精准测量并记录目标函数的执行耗时（单位：毫秒）
  *
@@ -100,86 +101,3 @@ export declare function _Utility_TimeConsumption<T extends Function>(func: T, co
  * @returns 实际暂停的毫秒数
  */
 export declare function _Utility_Sleep(ms: number): number;
-/**
- * 颜色转换工具。
- * 支持输入：hex/rgb/hsl/hsv，统一解析后输出指定格式。
- */
-export declare class _Utility_ColorConverter {
-    private constructor();
-    private static readonly DEFAULT_ALPHA;
-    /**
-     * 数值钳制，确保在合法区间内。
-     */
-    private static clamp;
-    private static normalizeHue;
-    /**
-     * 根据色相分段与色度参数生成 RGB（0-255）。
-     */
-    private static chromaToRgb;
-    private static resolveAlpha;
-    private static toRoundedRgbString;
-    /**
-     * HSL 转 RGB。
-     * h: 0-360, s/l: 0-100
-     */
-    private static hslToRgb;
-    /**
-     * HSV 转 RGB。
-     * h: 0-360, s/v: 0-100
-     */
-    private static hsvToRgb;
-    /**
-     * 解析任意受支持的颜色格式并标准化为 RGBA。
-     */
-    private static parseColor;
-    /**
-     * 十进制颜色分量转两位十六进制字符串。
-     */
-    private static toHexPart;
-    /**
-     * RGB 转 HSL。
-     * 返回 h:0-360, s/l:0-100
-     */
-    private static rgbToHsl;
-    /**
-     * RGB 转 HSV。
-     * 返回 h:0-360, s/v:0-100
-     */
-    private static rgbToHsv;
-    /**
-     * 转换为 HEX（#RRGGBB）。
-     */
-    static toHex(color: string): string;
-    /**
-     * 转换为 HEXA（#RRGGBBAA）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHexa(color: string, alpha?: number): string;
-    /**
-     * 转换为 RGB（rgb(r, g, b)）。
-     */
-    static toRgb(color: string): string;
-    /**
-     * 转换为 RGBA（rgba(r, g, b, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toRgba(color: string, alpha?: number): string;
-    /**
-     * 转换为 HSL（hsl(h, s%, l%)）。
-     */
-    static toHsl(color: string): string;
-    /**
-     * 转换为 HSLA（hsla(h, s%, l%, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHsla(color: string, alpha?: number): string;
-    /**
-     * 转换为 HSV（hsv(h, s%, v%)）。
-     */
-    static toHsv(color: string): string;
-    /**
-     * 转换为 HSVA（hsva(h, s%, v%, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHsva(color: string, alpha?: number): string;
-}

package/dist/Utility/modules/colorConverter.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 颜色转换工具。
+ * 支持输入：hex/rgb/hsl/hsv，统一解析后输出指定格式。
+ */
+export declare class _Utility_ColorConverter {
+    private constructor();
+    private static readonly DEFAULT_ALPHA;
+    /**
+     * 数值钳制，确保在合法区间内。
+     */
+    private static clamp;
+    private static normalizeHue;
+    /**
+     * 根据色相分段与色度参数生成 RGB（0-255）。
+     */
+    private static chromaToRgb;
+    private static resolveAlpha;
+    private static toRoundedRgbString;
+    /**
+     * HSL 转 RGB。
+     * h: 0-360, s/l: 0-100
+     */
+    private static hslToRgb;
+    /**
+     * HSV 转 RGB。
+     * h: 0-360, s/v: 0-100
+     */
+    private static hsvToRgb;
+    /**
+     * 解析任意受支持的颜色格式并标准化为 RGBA。
+     */
+    private static parseColor;
+    /**
+     * 十进制颜色分量转两位十六进制字符串。
+     */
+    private static toHexPart;
+    /**
+     * RGB 转 HSL。
+     * 返回 h:0-360, s/l:0-100
+     */
+    private static rgbToHsl;
+    /**
+     * RGB 转 HSV。
+     * 返回 h:0-360, s/v:0-100
+     */
+    private static rgbToHsv;
+    /**
+     * 转换为 HEX（#RRGGBB）。
+     */
+    static toHex(color: string): string;
+    /**
+     * 转换为 HEXA（#RRGGBBAA）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHexa(color: string, alpha?: number): string;
+    /**
+     * 转换为 RGB（rgb(r, g, b)）。
+     */
+    static toRgb(color: string): string;
+    /**
+     * 转换为 RGBA（rgba(r, g, b, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toRgba(color: string, alpha?: number): string;
+    /**
+     * 转换为 HSL（hsl(h, s%, l%)）。
+     */
+    static toHsl(color: string): string;
+    /**
+     * 转换为 HSLA（hsla(h, s%, l%, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHsla(color: string, alpha?: number): string;
+    /**
+     * 转换为 HSV（hsv(h, s%, v%)）。
+     */
+    static toHsv(color: string): string;
+    /**
+     * 转换为 HSVA（hsva(h, s%, v%, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHsva(color: string, alpha?: number): string;
+    /**
+     * 返回解析后的 RGBA 对象。
+     * @param color 任意受支持的颜色字符串（hex/rgb/hsl/hsv）
+     * @returns {{ r: number; g: number; b: number; a: number }} RGBA 分量，r/g/b 范围 0-255，a 范围 0-1
+     */
+    static toRgbaObject(color: string): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * 判断两个颜色是否在允许的色差范围内（基于 RGB 欧几里得距离）。
+     * @param colorA 第一个颜色字符串
+     * @param colorB 第二个颜色字符串
+     * @param threshold 允许的最大色差值，范围约 0（完全相同）到 442（黑白最大距离），含 alpha 时上限约 510
+     * @param includeAlpha 是否将 alpha 差值纳入计算，默认 true；启用时 alpha 差值会缩放到 0-255 参与距离
+     * @returns true 表示在允许色差内
+     */
+    static isWithinColorDifference(colorA: string, colorB: string, threshold: number, includeAlpha?: boolean): boolean;
+    /**
+     * 混合两个颜色（在 RGBA 空间线性插值）。
+     * @param colorA 起始颜色
+     * @param colorB 终点颜色
+     * @param ratio 混合比例，0 = 完全 A，1 = 完全 B
+     * @returns 混合后的 rgba 字符串
+     */
+    static mix(colorA: string, colorB: string, ratio: number): string;
+    /**
+     * 转换为灰度（基于 ITU-R BT.709 权重）。
+     * @param color 任意受支持的颜色字符串
+     * @returns 灰度 rgb 字符串
+     */
+    static toGrayscale(color: string): string;
+    /**
+     * 计算 WCAG 2.0 相对亮度。
+     * @param color 任意受支持的颜色字符串
+     * @returns 相对亮度值，范围 [0, 1]
+     */
+    static luminance(color: string): number;
+    /**
+     * 计算 WCAG 2.0 对比度。
+     * @param colorA 第一个颜色
+     * @param colorB 第二个颜色
+     * @returns 对比度值，范围 [1, 21]
+     */
+    static contrastRatio(colorA: string, colorB: string): number;
+    /**
+     * 设置透明度并返回 rgba 字符串。
+     * @param color 任意受支持的颜色字符串
+     * @param alpha 目标透明度，范围 [0, 1]
+     * @returns rgba 字符串
+     */
+    static withAlpha(color: string, alpha: number): string;
+}

package/dist/Utility/{Runtime → modules}/index.d.ts

@@ -1,2 +1,3 @@
 export * from './undoRedoHistory';
 export * from './shortcutKey';
+export * from './colorConverter';