minutool 1.0.27 → 1.0.30

package/README.md

@@ -109,6 +109,27 @@ const cloned = deepClone(obj)
 - `arraySortByKey<T>(obj: T): T` - Sort object by keys
 - `arrayChunk<T>(list: T[], size: number): T[][]` - Split array into chunks
 
+### Animate Utilities
+
+**Types:**
+- `EasingFn` - Easing function type `(t: number) => number`
+
+**Functions:**
+- `linear(t: number): number` - Linear easing (no easing)
+- `easeInQuad(t) / easeOutQuad(t) / easeInOutQuad(t)` - Quadratic easing
+- `easeInCubic(t) / easeOutCubic(t) / easeInOutCubic(t)` - Cubic easing
+- `easeInQuart(t) / easeOutQuart(t) / easeInOutQuart(t)` - Quartic easing
+- `easeInQuint(t) / easeOutQuint(t) / easeInOutQuint(t)` - Quintic easing
+- `easeInSine(t) / easeOutSine(t) / easeInOutSine(t)` - Sine easing
+- `easeInExpo(t) / easeOutExpo(t) / easeInOutExpo(t)` - Exponential easing
+- `easeInCirc(t) / easeOutCirc(t) / easeInOutCirc(t)` - Circular easing
+- `easeInBack(t, s?) / easeOutBack(t, s?) / easeInOutBack(t, s?)` - Back easing (with overshoot)
+- `easeInElastic(t) / easeOutElastic(t) / easeInOutElastic(t)` - Elastic easing
+- `easeInBounce(t) / easeOutBounce(t) / easeInOutBounce(t)` - Bounce easing
+- `clamp01(t: number): number` - Clamp value into [0, 1]
+- `lerp(from: number, to: number, t: number): number` - Linear interpolation
+- `easeValue(from: number, to: number, t: number, easing?: EasingFn): number` - Interpolate with easing applied
+
 ### Math Utilities
 
 **Constants:**

package/dist/index.d.ts

@@ -191,7 +191,7 @@ export declare const bindKeyUp: (element: EventTarget | string, payload: (event:
  * @param element - 要移动的元素
  * @param handle - 拖动句柄，默认为元素本身
  */
-export declare function bindNodeMove(element: HTMLElement | string, handle?: HTMLElement | string | null): () => void;
+export declare const bindNodeMove: (element: HTMLElement | string, handle?: HTMLElement | string | null) => () => void;
 
 /**
  * 转换 Blob 数据到 Base64 Data URL
@@ -255,7 +255,13 @@ export declare const calcRemainingMSecs: (progress: number, total: number, start
  * camelCase('hello-world') // 'helloWorld'
  * camelCase('hello_world') // 'helloWorld'
  */
-export declare function camelCase(str: string): string;
+export declare const camelCase: (str: string) => string;
+
+/**
+ * 取消 el 上正在进行的滚动动画（若有），并还原 CSS 滚动行为
+ * @param el 要取消滚动动画的元素
+ */
+export declare const cancelScrollAnimation: (el: HTMLElement) => void;
 
 /**
  * 首字母大写
@@ -264,7 +270,17 @@ export declare function camelCase(str: string): string;
  * @example
  * capitalize('hello') // 'Hello'
  */
-export declare function capitalize(str: string): string;
+export declare const capitalize: (str: string) => string;
+
+/**
+ * 将任意数值限制到 [0, 1] 区间，常用于保证动画进度合法
+ * @param t - 进度值
+ * @returns 限制后的进度
+ * @example
+ * clamp01(-0.5) // 0
+ * clamp01(1.5) // 1
+ */
+export declare const clamp01: (t: number) => number;
 
 /**
  * 清理对象中的 null 值
@@ -359,7 +375,7 @@ export declare const decodeHTMLEntities: (str: string) => string;
  * @example
  * deepClone({ a: 1, b: { c: 2 } })
  */
-export declare function deepClone<T>(obj: T): T;
+export declare const deepClone: <T>(obj: T) => T;
 
 /**
  * 删除 Cookie
@@ -437,6 +453,135 @@ export { dispatchEvent_2 as dispatchEvent }
  */
 export declare const downloadFile: (uri: string, fileName: string) => void;
 
+/**
+ * 回退缓入：先向后蓄力再前进
+ * @param t - 时间进度，范围 [0, 1]
+ * @param s - 过冲系数，默认为 1.70158
+ * @returns 缓动后的值
+ */
+export declare const easeInBack: (t: number, s?: number) => number;
+
+/** 弹跳缓入 */
+export declare const easeInBounce: (t: number) => number;
+
+/** 圆形缓入 */
+export declare const easeInCirc: (t: number) => number;
+
+/** 三次方缓入：由慢到快 */
+export declare const easeInCubic: (t: number) => number;
+
+/** 弹性缓入 */
+export declare const easeInElastic: (t: number) => number;
+
+/** 指数缓入 */
+export declare const easeInExpo: (t: number) => number;
+
+/**
+ * 回退缓入缓出
+ * @param t - 时间进度，范围 [0, 1]
+ * @param s - 过冲系数，默认为 1.70158
+ * @returns 缓动后的值
+ */
+export declare const easeInOutBack: (t: number, s?: number) => number;
+
+/** 弹跳缓入缓出 */
+export declare const easeInOutBounce: (t: number) => number;
+
+/** 圆形缓入缓出 */
+export declare const easeInOutCirc: (t: number) => number;
+
+/**
+ * 三次方缓入缓出
+ * @param t - 时间进度，范围 [0, 1]
+ * @returns 缓动后的值，范围 [0, 1]
+ * @example
+ * easeInOutCubic(0.25) // 0.0625
+ */
+export declare const easeInOutCubic: (t: number) => number;
+
+/** 弹性缓入缓出 */
+export declare const easeInOutElastic: (t: number) => number;
+
+/** 指数缓入缓出 */
+export declare const easeInOutExpo: (t: number) => number;
+
+/** 二次方缓入缓出 */
+export declare const easeInOutQuad: (t: number) => number;
+
+/** 四次方缓入缓出 */
+export declare const easeInOutQuart: (t: number) => number;
+
+/** 五次方缓入缓出 */
+export declare const easeInOutQuint: (t: number) => number;
+
+/** 正弦缓入缓出 */
+export declare const easeInOutSine: (t: number) => number;
+
+/** 二次方缓入：由慢到快 */
+export declare const easeInQuad: (t: number) => number;
+
+/** 四次方缓入 */
+export declare const easeInQuart: (t: number) => number;
+
+/** 五次方缓入 */
+export declare const easeInQuint: (t: number) => number;
+
+/** 正弦缓入 */
+export declare const easeInSine: (t: number) => number;
+
+/**
+ * 回退缓出：超过终点再回弹到终点
+ * @param t - 时间进度，范围 [0, 1]
+ * @param s - 过冲系数，默认为 1.70158
+ * @returns 缓动后的值
+ */
+export declare const easeOutBack: (t: number, s?: number) => number;
+
+/** 弹跳缓出：落地点弹跳衰减 */
+export declare const easeOutBounce: (t: number) => number;
+
+/** 圆形缓出 */
+export declare const easeOutCirc: (t: number) => number;
+
+/** 三次方缓出：由快到慢 */
+export declare const easeOutCubic: (t: number) => number;
+
+/** 弹性缓出：终点前反复振荡 */
+export declare const easeOutElastic: (t: number) => number;
+
+/** 指数缓出 */
+export declare const easeOutExpo: (t: number) => number;
+
+/** 二次方缓出：由快到慢 */
+export declare const easeOutQuad: (t: number) => number;
+
+/** 四次方缓出 */
+export declare const easeOutQuart: (t: number) => number;
+
+/** 五次方缓出 */
+export declare const easeOutQuint: (t: number) => number;
+
+/** 正弦缓出 */
+export declare const easeOutSine: (t: number) => number;
+
+/**
+ * 按缓动函数计算 from 到 to 之间某一进度的插值
+ * @param from - 起始值
+ * @param to - 结束值
+ * @param t - 原始时间进度，范围 [0, 1]
+ * @param easing - 缓动函数，默认为 linear
+ * @returns 缓动后的插值结果
+ * @example
+ * easeValue(0, 100, 0.5, easeOutCubic) // 87.5
+ */
+export declare const easeValue: (from: number, to: number, t: number, easing?: EasingFn) => number;
+
+/**
+ * 缓动函数类型：接收时间进度 t（范围 [0, 1]），返回缓动后的进度
+ * 注意：部分缓动（如 back / elastic）中间过程可能超出 [0, 1]，但起点与终点仍是 0 和 1
+ */
+export declare type EasingFn = (t: number) => number;
+
 /**
  * 启用元素（允许交互，移除disabled）
  * @param {String|Node} el
@@ -748,7 +893,7 @@ export declare const isChinese: (str: string) => boolean;
  * isEmptyObject({}) // true
  * isEmptyObject({ a: 1 }) // false
  */
-export declare function isEmptyObject(obj: object): boolean;
+export declare const isEmptyObject: (obj: object) => boolean;
 
 /**
  * 检测是否为 Firefox 浏览器
@@ -854,7 +999,7 @@ export declare const isUrl: (str: string) => boolean;
  * kebabCase('helloWorld') // 'hello-world'
  * kebabCase('HelloWorld') // 'hello-world'
  */
-export declare function kebabCase(str: string): string;
+export declare const kebabCase: (str: string) => string;
 
 /**
  * 保持对象尽量在容器内部，优先保证上边、左边显示
@@ -875,6 +1020,17 @@ export declare const keepRectInContainer: (objDim: Dimension, ctnDim?: Dimension
     top: number;
 };
 
+/**
+ * 线性插值：根据进度 t 在 from 与 to 之间取值
+ * @param from - 起始值
+ * @param to - 结束值
+ * @param t - 进度，范围 [0, 1]
+ * @returns 插值结果
+ * @example
+ * lerp(0, 100, 0.5) // 50
+ */
+export declare const lerp: (from: number, to: number, t: number) => number;
+
 /**
  * 限制数值在指定范围内
  * @param {number} num - 要限制的数值
@@ -886,6 +1042,15 @@ export declare const keepRectInContainer: (objDim: Dimension, ctnDim?: Dimension
  */
 export declare const limit: (num: number, min: number, max: number) => number;
 
+/**
+ * 线性缓动：匀速运动，无加减速
+ * @param t - 时间进度，范围 [0, 1]
+ * @returns 缓动后的值，恒等于 t
+ * @example
+ * linear(0.5) // 0.5
+ */
+export declare const linear: (t: number) => number;
+
 /**
  * 挂载 CSS 文件
  * @param {string} file - CSS 文件路径
@@ -1340,7 +1505,7 @@ export declare const objectFromEntries: <T extends Record<string | number | symb
  * get({ a: { b: { c: 1 } } }, 'a.b.c') // 1
  * get({ a: { b: 1 } }, 'a.b.c', 0) // 0
  */
-export declare function objectGet<T = any>(obj: object, path: string, defaultValue?: T): T;
+export declare const objectGet: <T = any>(obj: object, path: string, defaultValue?: T) => T;
 
 /**
  * 根据映射关系替换对象的键
@@ -1360,7 +1525,7 @@ export declare const objectKeyReplace: (obj: Record<string, any>, mapping: Recor
  * @example
  * merge({ a: 1 }, { b: 2 }, { c: 3 }) // { a: 1, b: 2, c: 3 }
  */
-export declare function objectMerge<T extends object>(target: T, ...sources: Partial<T>[]): T;
+export declare const objectMerge: <T extends object>(target: T, ...sources: Partial<T>[]) => T;
 
 /**
  * 设置对象指定路径的值
@@ -1370,7 +1535,7 @@ export declare function objectMerge<T extends object>(target: T, ...sources: Par
  * @example
  * set({}, 'a.b.c', 1) // { a: { b: { c: 1 } } }
  */
-export declare function objectSet(obj: any, path: string, value: any): void;
+export declare const objectSet: (obj: any, path: string, value: any) => void;
 
 /**
  * 交换对象中的键值对
@@ -1447,7 +1612,7 @@ export declare const onEvents: (events: (string | symbol)[], handler: EventListe
  * @param onHoverOut - 鼠标离开回调函数
  * @returns 返回解绑函数
  */
-export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void, onHoverOut: () => void) => () => void;
+export declare const onHover: (el: HTMLElement | string, onHoverIn: () => void, onHoverOut: () => void) => (() => void);
 
 /**
  * 非自关闭标签
@@ -1655,6 +1820,27 @@ export declare const sanitizeFileName: (name: string) => string;
 
 export declare const SCREEN_DPI: number;
 
+export declare type ScrollAxis = "scrollLeft" | "scrollTop";
+
+/**
+ * 用 rAF + 缓动把 el 平滑滚动到 target（自动夹取在合法滚动范围内）
+ * @param el 要滚动的元素
+ * @param target 目标滚动位置
+ * @param options 动画选项
+ */
+export declare const scrollToAnimated: (el: HTMLElement, target: number, options?: ScrollToAnimatedOptions) => void;
+
+export declare interface ScrollToAnimatedOptions {
+    /** 动画时长(ms)，默认 380 */
+    duration?: number;
+    /** 滚动的属性，默认横向 'scrollLeft' */
+    axis?: ScrollAxis;
+    /** 缓动函数，默认 easeInOutCubic */
+    easingFn?: (t: number) => number;
+    /** 动画自然结束（或被取消/被新动画取代）时回调 */
+    onEnd?: () => void;
+}
+
 /**
  * 自关闭标签
  */
@@ -1870,7 +2056,7 @@ export declare const TRIM_RIGHT = 2;
  * @example
  * truncate('hello world', 5) // 'hello...'
  */
-export declare function truncate(str: string, length: number, suffix?: string): string;
+export declare const truncate: (str: string, length: number, suffix?: string) => string;
 
 /**
  * 反转义 HTML（将 HTML 实体转换为字符）