minutool 1.0.26 → 1.0.29

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

@@ -151,7 +151,7 @@ export declare const bindClick: (element: EventTarget | string, payload: (event:
  * @param payload - 事件回调函数
  * @returns 解绑函数
  */
-export declare const bindDomEvent: <E extends Event = Event>(element: EventTarget | string, eventName: string, payload: (event: E) => void) => () => void;
+export declare const bindDomEvent: <E extends Event = Event>(element: EventTarget | string, eventName: string, payload: (event: E) => void, options?: boolean | AddEventListenerOptions) => () => void;
 
 /**
  * 绑定双击事件，并返回一个解绑函数
@@ -165,7 +165,7 @@ export declare const bindDoubleClick: (element: EventTarget | string, payload: (
  * 为 input/textarea 绑定支持 IME 的防抖函数
  * @param element - DOM 元素
  * @param callback - 回调，参数为 { value, event }
- * @param delay - 防抖延迟（ms），默认 300
+ * @param delay - 防抖延迟（ms），默认 50
  * @returns { destroy, cancel, flush }
  */
 export declare const bindInputDebounce: (element: HTMLInputElement | HTMLTextAreaElement, callback: (value: string, event: InputEvent) => void, delay?: number) => (() => void);
@@ -257,6 +257,12 @@ export declare const calcRemainingMSecs: (progress: number, total: number, start
  */
 export declare function camelCase(str: string): string;
 
+/**
+ * 取消 el 上正在进行的滚动动画（若有），并还原 CSS 滚动行为
+ * @param el 要取消滚动动画的元素
+ */
+export declare function cancelScrollAnimation(el: HTMLElement): void;
+
 /**
  * 首字母大写
  * @param str - 输入字符串
@@ -266,6 +272,16 @@ export declare function camelCase(str: string): string;
  */
 export declare function 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 值
  * @param {any} obj - 要清理的对象
@@ -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
@@ -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 文件路径
@@ -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 function 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;
+}
+
 /**
  * 自关闭标签
  */