sculp-js 0.1.1 → 1.0.0

package/lib/index.d.ts

@@ -1,10 +1,19 @@
+/** 任意函数 */
 type AnyFunc<R = any> = (...args: any[]) => R;
+/** 任意数组 */
 type AnyArray = any[];
+/** 取出数组元素 */
 type ArrayElements<A> = A extends Array<infer R> ? R : never;
+/** 任意对象 */
 type AnyObject = Record<string | number, any>;
 type PartialDeep<T> = {
     [P in keyof T]?: PartialDeep<T[P]>;
 };
+/**
+ * 判断任意值的数据类型
+ * @param {unknown} any
+ * @returns {string}
+ */
 declare const typeIs: (any: unknown) => string;
 declare const isString: (any: unknown) => any is string;
 declare const isBoolean: (any: unknown) => any is boolean;
@@ -16,6 +25,11 @@ declare const isNull: (any: unknown) => any is null;
 declare const isPrimitive: (any: unknown) => boolean;
 declare const isObject: (any: unknown) => any is Record<string, unknown>;
 declare const isArray: (any: unknown) => any is unknown[];
+/**
+ * 判断是否为函数
+ * @param {unknown} any
+ * @returns {boolean}
+ */
 declare const isFunction: (any: unknown) => any is Function;
 declare const isNaN: (any: unknown) => any is number;
 declare const isDate: (any: unknown) => any is Date;
@@ -24,22 +38,25 @@ declare const isRegExp: (any: unknown) => any is RegExp;
 
 /**
  * 判断一个对象是否为类数组
+ *
  * @param any
  * @returns {boolean}
  */
-declare const arrayLike: (any: unknown) => boolean;
+declare function arrayLike(any: unknown): boolean;
 /**
  * 遍历数组，返回 false 中断遍历
+ *
  * @param {ArrayLike<V>} array
  * @param {(val: V, idx: number) => any} iterator
  * @param reverse {boolean} 是否倒序
+ * @returns {*}
  */
-declare const arrayEach: <V>(array: ArrayLike<V>, iterator: (val: V, idx: number, arr: ArrayLike<V>) => any, reverse?: boolean) => void;
+declare function arrayEach<V>(array: ArrayLike<V>, iterator: (val: V, idx: number, arr: ArrayLike<V>) => any, reverse?: boolean): void;
 /**
  * 异步遍历数组，返回 false 中断遍历
- * @param {ArrayLike<V>} array
- * @param {(val: V, idx: number) => Promise<any>} iterator
- * @param {boolean} reverse
+ * @param {ArrayLike<V>} array 数组
+ * @param {(val: V, idx: number) => Promise<any>} iterator  支持Promise类型的回调函数
+ * @param {boolean} reverse  是否反向遍历
  */
 declare function arrayEachAsync<V>(array: ArrayLike<V>, iterator: (val: V, idx: number) => Promise<any> | any, reverse?: boolean): Promise<void>;
 /**
@@ -47,8 +64,9 @@ declare function arrayEachAsync<V>(array: ArrayLike<V>, iterator: (val: V, idx:
  * @param {AnyArray} array
  * @param {number} start
  * @param {number} to
+ * @returns {*}
  */
-declare const arrayInsertBefore: (array: AnyArray, start: number, to: number) => void;
+declare function arrayInsertBefore(array: AnyArray, start: number, to: number): void;
 /**
  * 数组删除指定项目
  * @param {V[]} array
@@ -58,12 +76,13 @@ declare const arrayInsertBefore: (array: AnyArray, start: number, to: number) =>
 declare function arrayRemove<V>(array: V[], expect: (val: V, idx: number) => boolean): V[];
 /**
  * 自定义深度优先遍历函数(支持continue和break操作)
- * @param {array} deepList
- * @param {function} iterator
- * @param {array} children
- * @param {boolean} isReverse 是否反向遍历
+ * @param {ArrayLike<V>} tree  树形数据
+ * @param {Function} iterator  迭代函数
+ * @param {string} children 定制子元素的key
+ * @param {boolean} isReverse  是否反向遍历
+ * @returns {*}
  */
-declare const deepTraversal: <V>(deepList: ArrayLike<V>, iterator: (val: V, i: number, arr: ArrayLike<V>, parent: V | null, level: number) => any, children?: string, isReverse?: boolean) => void;
+declare function deepTraversal<V>(tree: ArrayLike<V>, iterator: (val: V, i: number, arr: ArrayLike<V>, parent: V | null, level: number) => any, children?: string, isReverse?: boolean): void;
 type IdLike = number | string;
 interface ITreeConf {
     id: string | number;
@@ -71,10 +90,11 @@ interface ITreeConf {
 }
 /**
  * 在树中找到 id 为某个值的节点，并返回上游的所有父级节点
- * @param {ArrayLike<T>} tree
- * @param {IdLike} nodeId
- * @param {ITreeConf} config
- * @return {[IdLike[], ITreeItem<V>[]]}
+ *
+ * @param {ArrayLike<T>} tree - 树形数据
+ * @param {IdLike} nodeId - 元素ID
+ * @param {ITreeConf} config - 迭代配置项
+ * @returns {[IdLike[], ITreeItem<V>[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
  */
 declare function getTreeIds<V>(tree: ArrayLike<V>, nodeId: IdLike, config?: ITreeConf): [IdLike[], ArrayLike<V>[]];
 
@@ -82,27 +102,38 @@ declare function getTreeIds<V>(tree: ArrayLike<V>, nodeId: IdLike, config?: ITre
  * 复制文本
  * @param {string} text
  */
-declare const copyText: (text: string) => void;
+declare function copyText(text: string): void;
 
 /**
  * 获取cookie
  * @param {string} name
  * @returns {string}
  */
-declare const cookieGet: (name: string) => string;
+declare function cookieGet(name: string): string;
 /**
  * 设置 cookie
  * @param {string} name
  * @param {string} value
  * @param {number | Date} [maxAge]
  */
-declare const cookieSet: (name: string, value: string, maxAge?: number | Date) => void;
+declare function cookieSet(name: string, value: string, maxAge?: number | Date): void;
 /**
  * 删除单个 cookie
  * @param name cookie 名称
  */
 declare const cookieDel: (name: string) => void;
 
+declare const isValidDate: (any: unknown) => any is Date;
+interface DateObj {
+    [propName: string]: string;
+}
+type DateValue = number | string | Date;
+/**
+ * 解析为Date对象
+ * @param {DateValue} value - 可以是数值、字符串或 Date 对象
+ * @returns {Date} - 转换后的目标Date
+ */
+declare function dateParse(value: DateValue): Date;
 /**
  * 格式化为日期对象(带自定义格式化模板)
  * @param {DateValue} value 可以是数值、字符串或 Date 对象
@@ -117,24 +148,52 @@ declare const cookieDel: (name: string) => void;
  * - mm：分
  * - ss：秒
  * - SSS：毫秒
- * - ww: 周
  * @returns {string}
  */
-declare const formatDate: (date?: Date, format?: string) => string;
+/**
+ * 将日期转换为一天的开始时间，即0点0分0秒0毫秒
+ * @param {DateValue} value
+ * @returns {Date}
+ */
+declare function dateToStart(value: DateValue): Date;
+/**
+ * 将日期转换为一天的结束时间，即23点59分59秒999毫秒
+ * @param {DateValue} value
+ * @returns {Date}
+ */
+declare function dateToEnd(value: DateValue): Date;
+/**
+ * 格式化为日期对象(带自定义格式化模板)
+ * @param {Date} value - 可以是数值、字符串或 Date 对象
+ * @param {string} [format] - 模板，默认是 YYYY-MM-DD HH:mm:ss，模板字符：
+ * - YYYY：年
+ * - yyyy: 年
+ * - MM：月
+ * - DD：日
+ * - dd: 日
+ * - HH：时（24 小时制）
+ * - hh：时（12 小时制）
+ * - mm：分
+ * - ss：秒
+ * - SSS：毫秒
+ * - ww: 周
+ * @returns {string}  格式化后的日期字符串
+ */
+declare function formatDate(value: DateValue, format?: string): string;
 /**
  * 计算向前或向后N天的具体日期
- * @param {string} strDate 参考日期
- * @param {number} n 正数：向后推算；负数：向前推算
- * @param {string} sep 日期格式的分隔符
- * @return {*} 目标日期
+ * @param {string} strDate - 参考日期
+ * @param {number} n - 正数：向后推算；负数：向前推算
+ * @param {string} sep - 日期格式的分隔符
+ * @returns {string} 计算后的目标日期
  */
 declare function calculateDate(strDate: string, n: number, sep?: string): string;
 /**
  * 计算向前或向后N天的具体时间日期
- * @param {number} n 正数：向后推算；负数：向前推算
- * @param {string} dateSep 日期分隔符
- * @param {string} timeSep 时间分隔符
- * @return {*}
+ * @param {number} n - 正数：向后推算；负数：向前推算
+ * @param {string} dateSep - 日期分隔符
+ * @param {string} timeSep - 时间分隔符
+ * @returns {string} 转换后的目标日期时间
  */
 declare function calculateDateTime(n: number, dateSep?: string, timeSep?: string): string;
 
@@ -149,19 +208,19 @@ interface Style {
  * @param {string} className
  * @returns {boolean}
  */
-declare const hasClass: (el: HTMLElement, className: string) => boolean;
+declare function hasClass(el: HTMLElement, className: string): boolean;
 /**
  * 给元素增加样式名
  * @param {HTMLElement} el
  * @param {string} classNames
  */
-declare const addClass: (el: HTMLElement, classNames: string) => void;
+declare function addClass(el: HTMLElement, classNames: string): void;
 /**
  * 给元素移除样式名
  * @param {HTMLElement} el
  * @param {string} classNames
  */
-declare const removeClass: (el: HTMLElement, classNames: string) => void;
+declare function removeClass(el: HTMLElement, classNames: string): void;
 interface SetStyle {
     (el: HTMLElement, key: string, val: string): void;
     (el: HTMLElement, style: Style): void;
@@ -175,11 +234,11 @@ interface SetStyle {
 declare const setStyle: SetStyle;
 /**
  * 获取元素样式
- * @param {HTMLElement} el
+ * @param {HTMLElement} el 元素
  * @param {string} key
  * @returns {string}
  */
-declare const getStyle: (el: HTMLElement, key: string) => string;
+declare function getStyle(el: HTMLElement, key: string): string;
 type ScrollElement = HTMLElement | Document | Window;
 interface SmoothScrollOptions {
     el: ScrollElement;
@@ -196,7 +255,7 @@ declare function onDomReady(callback: ReadyCallback): void;
  * @param {HTMLElement} el
  * @param {string} property
  * @param {boolean} reNumber
- * @return {string|number}
+ * @returns {string|number}
  */
 declare function getComputedCssVal(el: HTMLElement, property: string, reNumber?: boolean): string | number;
 
@@ -208,7 +267,7 @@ interface Params<T = string | number> {
  * @param {string} queryString
  * @returns {Params}
  */
-declare const qsParse: (queryString: string) => Params;
+declare function qsParse(queryString: string): Params;
 type LooseParamValue = string | number | boolean | Date | null | undefined;
 interface LooseParams<T = LooseParamValue> {
     [key: string]: T | Array<T>;
@@ -220,26 +279,26 @@ type Replacer = (value: LooseParamValue) => string | null;
  * @param {Replacer} replacer
  * @returns {string}
  */
-declare const qsStringify: (query: LooseParams, replacer?: Replacer) => string;
+declare function qsStringify(query: LooseParams, replacer?: Replacer): string;
 
 /**
  * 通过打开新窗口的方式下载
  * @param {string} url
  * @param {LooseParams} params
  */
-declare const downloadURL: (url: string, params?: LooseParams) => void;
+declare function downloadURL(url: string, params?: LooseParams): void;
 /**
  * 通过 A 链接的方式下载
  * @param {string} href
  * @param {string} filename
  */
-declare const downloadHref: (href: string, filename: string) => void;
+declare function downloadHref(href: string, filename: string): void;
 /**
  * 将大文件对象通过 A 链接的方式下载
  * @param {Blob} blob
  * @param {string} filename
  */
-declare const downloadBlob: (blob: Blob, filename: string) => void;
+declare function downloadBlob(blob: Blob, filename: string): void;
 type FileType = 'json' | 'csv' | 'xls' | 'xlsx';
 /**
  * 将指定数据格式通过 A 链接的方式下载
@@ -248,7 +307,7 @@ type FileType = 'json' | 'csv' | 'xls' | 'xlsx';
  * @param {string} filename
  * @param {string[]} [headers]
  */
-declare const downloadData: (data: AnyObject | AnyObject[], fileType: FileType, filename: string, headers?: string[]) => void;
+declare function downloadData(data: AnyObject | AnyObject[], fileType: FileType, filename: string, headers?: string[]): void;
 
 /**
  * 判断对象是否为纯对象
@@ -262,13 +321,13 @@ declare const isPlainObject: (obj: unknown) => boolean;
  * @param {string} key
  * @returns {boolean}
  */
-declare const objectHas: <T extends AnyObject>(obj: T, key: keyof T) => boolean;
+declare function objectHas<T extends AnyObject>(obj: T, key: keyof T): boolean;
 /**
  * 遍历对象，返回 false 中断遍历
  * @param {O} obj
  * @param {(val: O[keyof O], key: keyof O) => (boolean | void)} iterator
  */
-declare const objectEach: <O extends AnyObject>(obj: O, iterator: (val: O[keyof O], key: Extract<keyof O, string>) => any) => void;
+declare function objectEach<O extends AnyObject>(obj: O, iterator: (val: O[keyof O], key: Extract<keyof O, string>) => any): void;
 /**
  * 异步遍历对象，返回 false 中断遍历
  * @param {O} obj
@@ -303,7 +362,7 @@ type ObjectAssignItem = AnyObject | AnyArray;
  * @param {ObjectAssignItem | undefined} targets
  * @returns {R}
  */
-declare const objectAssign: <R = AnyObject | AnyArray>(source: ObjectAssignItem, ...targets: (ObjectAssignItem | undefined)[]) => R;
+declare function objectAssign<R = AnyObject | AnyArray>(source: ObjectAssignItem, ...targets: (ObjectAssignItem | undefined)[]): R;
 
 /**
  * 对象填充
@@ -312,7 +371,7 @@ declare const objectAssign: <R = AnyObject | AnyArray>(source: ObjectAssignItem,
  * @param {(s: Partial<R>, t: Partial<R>, key: keyof R) => boolean} fillable
  * @returns {R}
  */
-declare const objectFill: <R extends AnyObject = AnyObject>(source: Partial<R>, target: Partial<R>, fillable?: ((s: Partial<R>, t: Partial<R>, key: keyof R) => boolean) | undefined) => R;
+declare function objectFill<R extends AnyObject = AnyObject>(source: Partial<R>, target: Partial<R>, fillable?: (s: typeof source, t: typeof target, key: keyof R) => boolean): R;
 declare function objectGet(obj: AnyObject, path: string, strict?: boolean): {
     p: any | undefined;
     k: string | undefined;
@@ -322,9 +381,9 @@ declare function objectGet(obj: AnyObject, path: string, strict?: boolean): {
  * 深拷贝堪称完全体 即：任何类型的数据都会被深拷贝
  * @param {AnyObject | AnyArray} obj
  * @param {WeakMap} map
- * @return {AnyObject | AnyArray}
+ * @returns {AnyObject | AnyArray}
  */
-declare function cloneDeep(obj: Object, map?: WeakMap<WeakKey, any>): Object;
+declare function cloneDeep(obj: Object, map?: WeakMap<object, any>): Object;
 
 /**
  * 标准化路径
@@ -346,14 +405,14 @@ declare const pathJoin: (from: string, ...to: string[]) => string;
  * @param {boolean} [bigger] 是否大写第一个字母
  * @returns {string}
  */
-declare const stringCamelCase: (string: string, bigger?: boolean) => string;
+declare function stringCamelCase(string: string, bigger?: boolean): string;
 /**
  * 将字符串转换为连字格式
  * @param {string} string
  * @param {string} [separator] 分隔符，默认是"-"（短横线）
  * @returns {string}
  */
-declare const stringKebabCase: (string: string, separator?: string) => string;
+declare function stringKebabCase(string: string, separator?: string): string;
 declare const STRING_ARABIC_NUMERALS = "0123456789";
 declare const STRING_LOWERCASE_ALPHA = "abcdefghijklmnopqrstuvwxyz";
 declare const STRING_UPPERCASE_ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -368,7 +427,7 @@ declare const STRING_UPPERCASE_ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
  * @param args
  * @returns {string}
  */
-declare const stringFormat: (string: string, ...args: Array<unknown>) => string;
+declare function stringFormat(string: string, ...args: Array<unknown>): string;
 /**
  * 字符串赋值
  * @example
@@ -404,7 +463,7 @@ declare const stringFill: (length: number, value?: string) => string;
  * @param {string} str 目标字符串
  * @param {number} fontSize 字符串字体大小
  * @param {boolean} isRemoveDom 计算后是否移除中间dom元素
- * @return {*}
+ * @returns {*}
  */
 declare function getStrWidthPx(str: string, fontSize?: number, isRemoveDom?: boolean): number;
 
@@ -470,12 +529,11 @@ declare function asyncMap<T, R>(list: Array<T>, mapper: (val: T, idx: number, li
 
 /**
  * 选择本地文件
- * @param {function} changeCb 选择文件回调
- * @return {*}
+ * @param {string} accept 上传的文件类型，用于过滤
+ * @param {Function} changeCb 选择文件回调
+ * @returns {HTMLInputElement}
  */
-declare function chooseLocalFile({ accept }: {
-    accept: any;
-}, changeCb: (FileList: any) => any): HTMLInputElement;
+declare function chooseLocalFile(accept: string, changeCb: (FileList: any) => any): HTMLInputElement;
 
 interface ICanvasWM {
     container: HTMLElement;
@@ -490,10 +548,11 @@ interface ICanvasWM {
     zIndex: number;
 }
 /**
- * canvas 实现 watermark
+ * canvas 实现 水印, 具备防删除功能
  * @param {ICanvasWM} canvasWM
+ * @example genCanvasWM({ content: 'QQMusicFE' })
  */
-declare const genCanvasWM: (canvasWM: ICanvasWM) => void;
+declare function genCanvasWM(canvasWM: ICanvasWM): void;
 
 interface DebounceFunc<F extends AnyFunc> {
     (...args: Parameters<F>): void;
@@ -551,7 +610,7 @@ declare function getGlobal<T>(key: string | number | symbol): T | void;
  * @returns {number}
  */
 declare const randomNumber: (min: number, max: number) => number;
-declare const STRING_POOL = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+declare const STRING_POOL: string;
 interface RandomString {
     (length: number, pool: string): string;
     (length: number): string;
@@ -571,14 +630,14 @@ declare const randomString: RandomString;
  */
 declare function randomUuid(): string;
 
-declare const HEX_POOL = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+declare const HEX_POOL: string;
 /**
  * 将十进制转换成任意进制
  * @param {number | string} decimal 十进制数值或字符串，可以是任意长度，会使用大数进行计算
  * @param {string} [hexPool] 进制池，默认 62 进制
  * @returns {string}
  */
-declare const numberToHex: (decimal: number | string, hexPool?: string) => string;
+declare function numberToHex(decimal: number | string, hexPool?: string): string;
 /**
  * 缩写
  * @param {number | string} num
@@ -592,7 +651,7 @@ declare const numberAbbr: (num: number | string, units: Array<string>, ratio?: n
  * 将数字格式化成千位分隔符显示的字符串
  * @param {number} val 数字
  * @param {'int' | 'float'} type 展示分段显示的类型 int:整型 | float:浮点型
- * @return {string}
+ * @returns {string}
  */
 declare function formatNumber(val: number, type?: string): string;
 
@@ -617,4 +676,4 @@ interface UniqueString {
  */
 declare const uniqueString: UniqueString;
 
-export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, HEX_POOL, type LooseParamValue, type LooseParams, type Params, type PartialDeep, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, UNIQUE_NUMBER_SAFE_LENGTH, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, cookieDel, cookieGet, cookieSet, copyText, debounce, deepTraversal, downloadBlob, downloadData, downloadHref, downloadURL, formatDate, formatNumber, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, getTreeIds, hasClass, isArray, isBigInt, isBoolean, isDate, isDomReady, isError, isFunction, isNaN, isNull, isNumber, isObject, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, onDomReady, once, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, throttle, typeIs, uniqueNumber, uniqueString, urlDelParams, urlParse, urlSetParams, urlStringify, wait };
+export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, type DateObj, type DateValue, type DebounceFunc, type FileType, HEX_POOL, type ICanvasWM, type ITreeConf, type IdLike, type LooseParamValue, type LooseParams, type ObjectAssignItem, type OnceFunc, type Params, type PartialDeep, type RandomString, type ReadyCallback, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, type SetStyle, type SmoothScrollOptions, type Style, type ThrottleFunc, UNIQUE_NUMBER_SAFE_LENGTH, type UniqueString, type Url, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, cookieDel, cookieGet, cookieSet, copyText, dateParse, dateToEnd, dateToStart, debounce, deepTraversal, downloadBlob, downloadData, downloadHref, downloadURL, formatDate, formatNumber, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, getTreeIds, hasClass, isArray, isBigInt, isBoolean, isDate, isDomReady, isError, isFunction, isNaN, isNull, isNumber, isObject, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, isValidDate, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, onDomReady, once, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, throttle, typeIs, uniqueNumber, uniqueString, urlDelParams, urlParse, urlSetParams, urlStringify, wait };