a2bei4-utils 1.0.3 → 1.0.4

package/types/date.d.ts

@@ -19,60 +19,119 @@ declare function toDate(val: any): Date | null;
  */
 declare function randomDateInRange(date1: Date, date2: Date): Date;
 /**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
- *
- * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
- * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
- * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ * @typedef {Object} DurationObject
+ * @property {number} years - 年数
+ * @property {number} months - 月数（0-11）
+ * @property {number} days - 天数（0-29，取决于 monthDays）
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
  */
-declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
-    days: number;
-    hours: string;
-    minutes: string;
-    seconds: string;
-};
 /**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：1 年=365 天，1 月=30 天。
- *
- * @param {number} totalSeconds - 非负总秒数
- * @param {object} [options] - 格式化选项
- * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
- * @param {boolean} [options.showZero] - 是否强制显示 0 秒
- * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
- * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
- */
-declare function formatDuration(totalSeconds: number, options?: {
-    labels?: Partial<{
-        year: string;
-        month: string;
-        day: string;
-        hour: string;
-        minute: string;
-        second: string;
-    }> | undefined;
-    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    showZero?: boolean | undefined;
-}): string;
+ * 时间持续对象（最大单位为天）
+ * @typedef {Object} DurationMaxDayObject
+ * @property {number} days - 天数
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为小时）
+ * @typedef {Object} DurationMaxHourObject
+ * @property {number} hours - 小时数
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ * 将毫秒转换为时间持续对象。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字
+ * @throws {RangeError} 当 milliseconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+ *
+ * @example
+ * // 基本用法
+ * millisecond2Duration(42070000500);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function millisecond2Duration(milliseconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将毫秒转换为时间持续对象（最大单位为天）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxDay(42070000500);
  */
-declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function millisecond2DurationMaxDay(milliseconds: number): DurationMaxDayObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
+ * 将毫秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxHour(42070000500);
+ */
+declare function millisecond2DurationMaxHour(milliseconds: number): DurationMaxHourObject;
+/**
+ * 将秒转换为时间持续对象。
+ *
+ * @param {number} seconds - 秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字
+ * @throws {RangeError} 当 seconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @example
+ * // 基本用法
+ * second2Duration(42070000.5);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2Duration(seconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为天）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxDay(42070000.5);
+ */
+declare function second2DurationMaxDay(seconds: number): DurationMaxDayObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxHour(42070000.5);
+ */
+declare function second2DurationMaxHour(seconds: number): DurationMaxHourObject;
 /**
  * 根据小时数返回对应的时间段名称。
  *
@@ -132,5 +191,85 @@ declare function formatTimeForLocale(timestamp: number, locales?: {
     } | undefined;
     weekDays?: string[] | undefined;
 }): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ */
+type DurationObject = {
+    /**
+     * - 年数
+     */
+    years: number;
+    /**
+     * - 月数（0-11）
+     */
+    months: number;
+    /**
+     * - 天数（0-29，取决于 monthDays）
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为天）
+ */
+type DurationMaxDayObject = {
+    /**
+     * - 天数
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为小时）
+ */
+type DurationMaxHourObject = {
+    /**
+     * - 小时数
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
 
-export { calcTimeDifference, formatDuration, formatDurationMaxDay, formatDurationMaxHour, formatTimeForLocale, getTimePeriodName, randomDateInRange, toDate };
+export { formatTimeForLocale, getTimePeriodName, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, randomDateInRange, second2Duration, second2DurationMaxDay, second2DurationMaxHour, toDate };
+export type { DurationMaxDayObject, DurationMaxHourObject, DurationObject };

package/types/index.d.ts

@@ -464,60 +464,119 @@ declare function toDate(val: any): Date | null;
  */
 declare function randomDateInRange(date1: Date, date2: Date): Date;
 /**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ * @typedef {Object} DurationObject
+ * @property {number} years - 年数
+ * @property {number} months - 月数（0-11）
+ * @property {number} days - 天数（0-29，取决于 monthDays）
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为天）
+ * @typedef {Object} DurationMaxDayObject
+ * @property {number} days - 天数
+ * @property {number} hours - 小时数（0-23）
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 时间持续对象（最大单位为小时）
+ * @typedef {Object} DurationMaxHourObject
+ * @property {number} hours - 小时数
+ * @property {number} minutes - 分钟数（0-59）
+ * @property {number} seconds - 秒数（0-59）
+ * @property {number} milliseconds - 毫秒数（0-999）
+ */
+/**
+ * 将毫秒转换为时间持续对象。
+ *
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字
+ * @throws {RangeError} 当 milliseconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
  *
- * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
- * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
- * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ * @example
+ * // 基本用法
+ * millisecond2Duration(42070000500);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function millisecond2Duration(milliseconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将毫秒转换为时间持续对象（最大单位为天）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxDay(42070000500);
  */
-declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
-    days: number;
-    hours: string;
-    minutes: string;
-    seconds: string;
-};
+declare function millisecond2DurationMaxDay(milliseconds: number): DurationMaxDayObject;
 /**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：1 年=365 天，1 月=30 天。
- *
- * @param {number} totalSeconds - 非负总秒数
- * @param {object} [options] - 格式化选项
- * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
- * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
- * @param {boolean} [options.showZero] - 是否强制显示 0 秒
- * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
- * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
- */
-declare function formatDuration(totalSeconds: number, options?: {
-    labels?: Partial<{
-        year: string;
-        month: string;
-        day: string;
-        hour: string;
-        minute: string;
-        second: string;
-    }> | undefined;
-    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    showZero?: boolean | undefined;
-}): string;
+ * 将毫秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxHour(42070000500);
+ */
+declare function millisecond2DurationMaxHour(milliseconds: number): DurationMaxHourObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ * 将秒转换为时间持续对象。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @param {number} seconds - 秒数（非负整数）
+ * @param {Object} [options] - 选项对象。
+ * @param {number} [options.yearDays=365] - 一年的天数。
+ * @param {number} [options.monthDays=30] - 一月的天数。
+ * @returns {DurationObject} 时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字
+ * @throws {RangeError} 当 seconds 为负数
+ * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+ *
+ * @example
+ * // 基本用法
+ * second2Duration(42070000.5);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ */
+declare function second2Duration(seconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为天）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxDay(42070000.5);
  */
-declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2DurationMaxDay(seconds: number): DurationMaxDayObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
- *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * 将秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxHour(42070000.5);
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function second2DurationMaxHour(seconds: number): DurationMaxHourObject;
 /**
  * 根据小时数返回对应的时间段名称。
  *
@@ -577,6 +636,85 @@ declare function formatTimeForLocale(timestamp: number, locales?: {
     } | undefined;
     weekDays?: string[] | undefined;
 }): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ */
+type DurationObject = {
+    /**
+     * - 年数
+     */
+    years: number;
+    /**
+     * - 月数（0-11）
+     */
+    months: number;
+    /**
+     * - 天数（0-29，取决于 monthDays）
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为天）
+ */
+type DurationMaxDayObject = {
+    /**
+     * - 天数
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为小时）
+ */
+type DurationMaxHourObject = {
+    /**
+     * - 小时数
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
 
 /**
  * 通过动态创建 `<a>` 标签触发浏览器下载。
@@ -761,4 +899,4 @@ declare function extractFullyCheckedKeys(treeData: any[], selectedKeys: any[], i
 };
 declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
 
-export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
+export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, second2Duration, second2DurationMaxDay, second2DurationMaxHour, shuffle, throttle, toDate };