feat: support custom time units

Author: jin-sir

docs/api/functions/formatSecond.md

@@ -2,53 +2,69 @@
 
 # Function: formatSecond()
 
-> **formatSecond**(`secondTime`, `padZero`): `string`
+> **formatSecond**(`secondTime`, `options?`): `string`
 
-Defined in: [formatSecond/index.ts:34](https://github.com/DTStack/dt-utils/blob/master/src/formatSecond/index.ts#L34)
+Defined in: [formatSecond/index.ts:75](https://github.com/DTStack/dt-utils/blob/master/src/formatSecond/index.ts#L75)
 
-将秒数转换为时间格式 (HH[h]mm[m]ss[s])
+将秒数格式化为可读的时间字符串。
+
+支持：
+- 自定义时间单位（h / m / s）
+- 数值补零（padZero）
+- 通过 format 模板输出（如 HH:mm:ss）
 
 ## Parameters
 
 ### secondTime
 
 `number` = `0`
 
-需要转换的秒数
+需要转换的秒数（小于等于 0、NaN、非数字将视为 0）
 
-### padZero
+### options?
 
-`boolean` = `false`
+`FormatSecondOptions` = `{}`
 
-是否使用 HH[h]mm[m]ss[s] 格式
+格式化选项
 
 ## Returns
 
 `string`
 
-格式化后的时间字符串，包含小时(h)、分钟(m)和秒(s)
+格式化后的时间字符串
 
 ## Example
 
-```typescript
+```ts
 import { formatSecond } from 'dt-utils';
 
-// 基本用法
-formatSecond(3661)   // => '1h1m1s'
-formatSecond(59)     // => '59s'
-formatSecond(0)      // => '0s'
+// 基本用法（默认单位：h / m / s）
+formatSecond(3661)  // => '1h1m1s'
+
+formatSecond(59)  // => '59s'
+
+formatSecond(0)  // => '0s'
+
+// 补零
+formatSecond(3661, { padZero: true })  // => '01h01m01s'
+
+formatSecond(60, { padZero: true })  // => '01m'
+
+// 自定义单位（中文）
+formatSecond(1106, {
+  units: { h: '小时', m: '分', s: '秒' },
+})  // => '18分26秒'
+
+// 使用 format 模板（运行时长）
+formatSecond(12078, {
+  format: 'HH:mm:ss',
+  padZero: true,
+})  // => '03:21:18'
 
-// 处理大数字
-formatSecond(7323)   // => '2h2m3s'
-formatSecond(3600)   // => '1h'
+// 边界情况
+formatSecond(-1)  // => '0s'
 
-// 处理边界情况
-formatSecond(-1)     // => '0s'
-formatSecond(NaN)    // => '0s'
-formatSecond()       // => '0s'
+formatSecond(NaN)  // => '0s'
 
-// 使用 HH[h]mm[m]ss[s] 格式
-formatSecond(3661)   // => '01h01m01s'
-formatSecond(60)     // => '01m'
-formatSecond(0)      // => '00s'
+formatSecond()  // => '0s'
 ```

src/formatSecond/__test__/index.test.ts

@@ -62,11 +62,30 @@ describe('formatSecond', () => {
     });
 
     // Test padZero
-    test('should correctly format time with zero-padded hours, minutes and seconds', () => {
-        expect(formatSecond(3661, true)).toBe('01h01m01s');
-        expect(formatSecond(3600, true)).toBe('01h');
-        expect(formatSecond(60, true)).toBe('01m');
-        expect(formatSecond(1, true)).toBe('01s');
-        expect(formatSecond(0, true)).toBe('00s');
+    test('pads hour, minute and second with zero', () => {
+        expect(formatSecond(3661, { padZero: true })).toBe('01h01m01s');
+        expect(formatSecond(60, { padZero: true })).toBe('01m');
+        expect(formatSecond(5, { padZero: true })).toBe('05s');
+    });
+
+    test('pads zero second correctly', () => {
+        expect(formatSecond(0, { padZero: true })).toBe('00s');
+    });
+
+    // Custom units
+    test('supports chinese units', () => {
+        expect(
+            formatSecond(1106, {
+                units: { h: '小时', m: '分', s: '秒' },
+            })
+        ).toBe('18分26秒');
+    });
+
+    test('supports partial units override', () => {
+        expect(
+            formatSecond(61, {
+                units: { m: 'min', s: 'sec' },
+            })
+        ).toBe('1min1sec');
     });
 });

src/formatSecond/index.ts

@@ -1,39 +1,82 @@
+type TimeUnit = 'h' | 'm' | 's';
+
+interface FormatSecondOptions {
+    /** 单位文案映射 */
+    units?: Partial<Record<TimeUnit, string>>;
+    /** 是否补零 */
+    padZero?: boolean;
+}
+
 /**
- * 将秒数转换为时间格式 (HH[h]mm[m]ss[s])
+ * 将秒数格式化为可读的时间字符串。
+ *
+ * 支持：
+ * - 自定义时间单位（h / m / s）
+ * - 数值补零（padZero）
+ * - 通过 format 模板输出（如 HH:mm:ss）
  *
  * @category 格式化
  *
- * @param {number} secondTime - 需要转换的秒数
- * @param {boolean} padZero - 是否使用 HH[h]mm[m]ss[s] 格式
- * @returns {string} 格式化后的时间字符串，包含小时(h)、分钟(m)和秒(s)
+ * @param {number} secondTime
+ *  需要转换的秒数（小于等于 0、NaN、非数字将视为 0）
+ *
+ * @param {Object} [options]
+ *  格式化选项
+ *
+ * @param {boolean} [options.padZero=false]
+ *  是否对小时、分钟、秒进行补零（如 02h、03m、09s）
+ *
+ * @param {Object} [options.units]
+ *  时间单位映射，可自定义 h / m / s 的展示文案
+ *
+ * @param {string} [options.format]
+ *  格式化模板，支持 HH、mm、ss（如 HH:mm:ss）
+ *  若传入 format，则优先使用模板输出
+ *
+ * @returns {string}
+ *  格式化后的时间字符串
  *
  * @example
- * ```typescript
+ * ```ts
  * import { formatSecond } from 'dt-utils';
  *
- * // 基本用法
- * formatSecond(3661)   // => '1h1m1s'
- * formatSecond(59)     // => '59s'
- * formatSecond(0)      // => '0s'
+ * // 基本用法（默认单位：h / m / s）
+ * formatSecond(3661)  // => '1h1m1s'
+ *
  *
- * // 处理大数字
- * formatSecond(7323)   // => '2h2m3s'
- * formatSecond(3600)   // => '1h'
+ * formatSecond(59)  // => '59s'
  *
- * // 处理边界情况
- * formatSecond(-1)     // => '0s'
- * formatSecond(NaN)    // => '0s'
- * formatSecond()       // => '0s'
+ * formatSecond(0)  // => '0s'
  *
- * // 使用 HH[h]mm[m]ss[s] 格式
- * formatSecond(3661)   // => '01h01m01s'
- * formatSecond(60)     // => '01m'
- * formatSecond(0)      // => '00s'
+ * // 补零
+ * formatSecond(3661, { padZero: true })  // => '01h01m01s'
+ *
+ * formatSecond(60, { padZero: true })  // => '01m'
+ *
+ * // 自定义单位（中文）
+ * formatSecond(1106, {
+ *   units: { h: '小时', m: '分', s: '秒' },
+ * })  // => '18分26秒'
+ *
+ * // 使用 format 模板（运行时长）
+ * formatSecond(12078, {
+ *   format: 'HH:mm:ss',
+ *   padZero: true,
+ * })  // => '03:21:18'
+ *
+ * // 边界情况
+ * formatSecond(-1)  // => '0s'
+ *
+ * formatSecond(NaN)  // => '0s'
+ *
+ * formatSecond()  // => '0s'
  * ```
  */
-export const formatSecond = (secondTime = 0, padZero = false): string => {
+export const formatSecond = (secondTime = 0, options: FormatSecondOptions = {}): string => {
+    const { units = { h: 'h', m: 'm', s: 's' }, padZero = false } = options;
+
     if (typeof secondTime !== 'number' || isNaN(secondTime) || secondTime <= 0) {
-        return padZero ? '00s' : '0s';
+        return padZero ? `00${units.s}` : `0${units.s}`;
     }
 
     const totalSeconds = Math.floor(secondTime);
@@ -44,10 +87,11 @@ export const formatSecond = (secondTime = 0, padZero = false): string => {
     const pad = (num: number) => (padZero ? String(num).padStart(2, '0') : String(num));
 
     const parts: string[] = [];
-    if (hours > 0) parts.push(`${pad(hours)}h`);
-    if (minutes > 0) parts.push(`${pad(minutes)}m`);
-    if (seconds > 0 || parts.length === 0) parts.push(`${pad(seconds)}s`);
+    if (hours > 0) parts.push(`${pad(hours)}${units.h}`);
+    if (minutes > 0) parts.push(`${pad(minutes)}${units.m}`);
+    if (seconds > 0 || parts.length === 0) parts.push(`${pad(seconds)}${units.s}`);
 
     return parts.join('');
 };
+
 export default formatSecond;