a2bei4-utils 1.0.2 → 1.0.4

package/types/index.d.ts

@@ -464,60 +464,257 @@ 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 second2DurationMaxHour(seconds: number): DurationMaxHourObject;
+/**
+ * 根据小时数返回对应的时间段名称。
+ *
+ * @param {number} hour - 24 小时制的小时（0-23）
+ * @param {object} [locales] - 自定义时段文案
+ * @param {string} [locales.earlyMorning="凌晨"] - 00-05
+ * @param {string} [locales.morning="上午"] - 06-11
+ * @param {string} [locales.noon="中午"] - 12-13
+ * @param {string} [locales.afternoon="下午"] - 14-17
+ * @param {string} [locales.evening="晚上"] - 18-23
+ * @returns {string} 时段名称
+ * @throws {RangeError} 当 hour 不在 0-23 范围时抛出
+ */
+declare function getTimePeriodName(hour: number, locales?: {
+    earlyMorning?: string | undefined;
+    morning?: string | undefined;
+    noon?: string | undefined;
+    afternoon?: string | undefined;
+    evening?: string | undefined;
+}): string;
+/**
+ * 格式化时间戳为本地化的时间字符串。
+ *
+ * @param {number} timestamp - 要格式化的时间戳（毫秒）。
+ * @param {Object} [locales] - 本地化配置对象，包含时间相关的本地化字符串。
+ * @param {string} [locales.justNow='刚刚'] - 表示刚刚过去的时间。
+ * @param {string} [locales.today='今天'] - 表示今天。
+ * @param {string} [locales.yesterday='昨天'] - 表示昨天。
+ * @param {string} [locales.beforeYesterday='前天'] - 表示前天。
+ * @param {string} [locales.year='年'] - 年的单位。
+ * @param {string} [locales.month='月'] - 月的单位。
+ * @param {string} [locales.day='日'] - 日的单位。
+ * @param {Object} [locales.timePeriod] - 一天中不同时间段的本地化字符串。
+ * @param {string} [locales.timePeriod.earlyMorning='凌晨'] - 凌晨。
+ * @param {string} [locales.timePeriod.morning='上午'] - 上午。
+ * @param {string} [locales.timePeriod.noon='中午'] - 中午。
+ * @param {string} [locales.timePeriod.afternoon='下午'] - 下午。
+ * @param {string} [locales.timePeriod.evening='晚上'] - 晚上。
+ * @param {Array<string>} [locales.weekDays=['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六']] - 星期几的本地化字符串数组。
+ *
+ * @returns {string} - 格式化后的时间字符串。
+ */
+declare function formatTimeForLocale(timestamp: number, locales?: {
+    justNow?: string | undefined;
+    today?: string | undefined;
+    yesterday?: string | undefined;
+    beforeYesterday?: string | undefined;
+    year?: string | undefined;
+    month?: string | undefined;
+    day?: string | undefined;
+    timePeriod?: {
+        earlyMorning?: string | undefined;
+        morning?: string | undefined;
+        noon?: string | undefined;
+        afternoon?: string | undefined;
+        evening?: string | undefined;
+    } | undefined;
+    weekDays?: string[] | undefined;
+}): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): 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>` 标签触发浏览器下载。
@@ -702,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, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, 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 };