@base-web-kits/base-tools-ts 0.9.5 → 0.9.8

package/src/ts/number/format.ts

@@ -0,0 +1,253 @@
+import { BigNumber } from './big';
+
+/**
+ * 开头补零
+ * @param n 数字
+ * @param len 总长度，默认 2
+ * @returns 零填充后的字符串
+ * @example
+ * zeroPad(1) // '01'
+ * zeroPad(12) // '12'
+ * zeroPad(12, 4) // '0012'
+ */
+export function zeroPad(n: number | string, len = 2) {
+  return String(n).padStart(len, '0');
+}
+
+/**
+ * 给数字添加指定单位 (支持数字字符串,其他非法字符返回原值)
+ * @param unit 单位
+ * @param num 数字
+ * @example
+ * withUnit(0, 'px') // "0px"
+ * withUnit(1, 'px') // "1px"
+ * withUnit('1', 'rpx') // "1rpx"
+ * withUnit('1', '%') // "1%"
+ * withUnit('auto', 'px') // "auto"
+ * withUnit(null | undefined | '') // ""
+ */
+export function withUnit(num?: number | string, unit = '') {
+  if (num === null || num === undefined || num === '') return ''; // 注意不能排除0
+
+  if (typeof num === 'number') return `${num}${unit}`;
+
+  const str = String(num).trim();
+
+  if (str === '') return '';
+
+  return isNaN(+str) ? str : `${str}${unit}`;
+}
+
+/**
+ * 给数字添加px单位 (支持数字字符串,其他非法字符返回原值)
+ * @example
+ * withUnitPx(10) // "10px"
+ * withUnitPx('10') // "10px"
+ * withUnitPx('10px') // "10px"
+ * withUnitPx("auto") // "auto"
+ * withUnitPx("30%") // "30%"
+ * withUnitPx(null | undefined | '') // ""
+ * withUnitPx(0) // "0px"
+ */
+export function withUnitPx(num?: string | number) {
+  return withUnit(num, 'px');
+}
+
+/**
+ * 给数字添加距离单位：当数值大于等于 1000m 时转换为 km，否则显示 m（最多两位小数、无无意义补零）
+ * @example
+ * withDistance(5); // => '5m'
+ * withDistance(999.456); // => '999.46m'
+ * withDistance(1000); // => '1km'
+ * withDistance('1500'); // => '1.5km'
+ * withDistance('1728'); // => '1.73km'
+ */
+export function withDistance(m: number | string): string {
+  const n = Number(m ?? 0);
+  if (!Number.isFinite(n)) return '0m';
+  return n >= 1000 ? `${+(n / 1000).toFixed(2)}km` : `${+n.toFixed(2)}m`;
+}
+
+/**
+ * 数字转千分位字符串（保留小数与符号）。
+ * @example
+ * toThousandth(1234567); // => '1,234,567'
+ * toThousandth('1234567.89'); // => '1,234,567.89'
+ * toThousandth('-987654'); // => '-987,654'
+ */
+export function toThousandth(str: number | string): string {
+  const v = String(str ?? '').trim();
+  if (v === '') return '';
+
+  // 处理符号
+  let sign = '';
+  let num = v;
+  if (num[0] === '-' || num[0] === '+') {
+    sign = num[0];
+    num = num.slice(1);
+  }
+
+  // 拆分整数与小数部分
+  const [intPart, decPart] = num.split('.');
+
+  // 仅对整数部分进行千分位分组
+  const groupedInt = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+
+  return decPart !== undefined && decPart !== ''
+    ? `${sign}${groupedInt}.${decPart}`
+    : `${sign}${groupedInt}`;
+}
+
+/**
+ * 阿拉伯数字转中文整数（忽略小数；支持负数）。
+ * @param num 输入的数字或数字字符串（小数部分将被丢弃）
+ * @returns 中文数字字符串；非法输入返回空字符串
+ * @example
+ * toChineseNum(123456);   // "十二万三千四百五十六"
+ * toChineseNum(-10008);   // "负一万零八"
+ * `第${toChineseNum(123)}条` // "第一百二十三条"
+ */
+export function toChineseNum(num: number | string) {
+  const numInt = Math.trunc(+num);
+  if (numInt === 0) return '零';
+
+  const digit = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九'];
+  const unit = ['', '十', '百', '千'];
+  const bigUnit = ['', '万', '亿', '兆'];
+
+  const section4 = (n: number) => {
+    let str = '',
+      zeroFlag = false;
+    for (let i = 0; i < 4; i++) {
+      const d = n % 10;
+      n = Math.floor(n / 10);
+      if (d === 0) {
+        zeroFlag = true;
+        continue;
+      }
+      if (zeroFlag) str = digit[0] + str;
+      str = digit[d] + unit[i] + str;
+      zeroFlag = false;
+    }
+    return str;
+  };
+
+  let res = '';
+  let sectionIndex = 0;
+  let n = Math.abs(numInt);
+
+  while (n > 0) {
+    const seg = n % 10000;
+    n = Math.floor(n / 10000);
+    if (seg) {
+      const segStr = section4(seg);
+      res = segStr + (sectionIndex ? bigUnit[sectionIndex] : '') + res;
+    } else if (res && !res.startsWith('零')) {
+      res = `零${res}`;
+    }
+    sectionIndex++;
+  }
+
+  res = res.replace(/^一十/, '十');
+
+  return numInt < 0 ? `负${res}` : res;
+}
+
+/**
+ * 金额转中文大写（支持角/分/厘，精度控制）。
+ * @param amount 金额（支持 number | string），非法或非有限数返回空串
+ * @param opts 配置项
+ * @param opts.precision 保留小数位（0~3），对应：0无小数、1角、2角分、3角分厘；默认 2
+ * @param opts.rm 舍入模式，默认 `BigNumber.ROUND_HALF_UP`（四舍五入）
+ * @param opts.yuanChar 元单位字符（`'元' | '圆'`），默认 `'元'`
+ * @returns 中文大写金额字符串；示例：`壹佰贰拾叁元肆角伍分`
+ * @example
+ * toChineseCurrency(0) // '零元整'
+ * toChineseCurrency(10) // '拾元整'
+ * toChineseCurrency(101) // '壹佰零壹元整'
+ * toChineseCurrency(1001000) // '壹佰万零壹仟元整'
+ * toChineseCurrency(1001.01) // '壹仟零壹元壹分'
+ * toChineseCurrency('1234.5679', { precision: 3 }) // '壹仟贰佰叁拾肆元伍角陆分捌厘'
+ * toChineseCurrency(-1.2) // '负壹元贰角'
+ */
+export function toChineseCurrency(
+  amount: number | string,
+  opts: {
+    precision?: 0 | 1 | 2 | 3;
+    rm?: BigNumber.RoundingMode;
+    yuanChar?: '元' | '圆';
+  } = {},
+): string {
+  const dp = opts.precision ?? 2;
+  const rm = opts.rm ?? BigNumber.ROUND_HALF_UP;
+  const yuan = opts.yuanChar ?? '元';
+
+  // 1. 非法输入直接返回空串
+  if (amount === null || amount === undefined) return '';
+  const bn = new BigNumber(amount);
+  if (!bn.isFinite()) return '';
+
+  // 2. 转字符串并拆分整数/小数
+  const s = bn.toFixed(dp, rm);
+  const sign = s.startsWith('-') ? '负' : '';
+  const [intStr, decStr = ''] = s.replace(/^-/, '').split('.');
+
+  // 3. 数字与大写映射
+  const digit = ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖'];
+  const unit = ['', '拾', '佰', '仟'];
+  const bigUnit = ['', '万', '亿', '兆'];
+  const smallUnit = ['角', '分', '厘'];
+
+  // 4. 四位一段转换整数
+  const section4 = (n: BigNumber): string => {
+    let str = '';
+    let zeroFlag = false;
+    for (let i = 0; i < 4; i++) {
+      const d = n.mod(10).toNumber();
+      n = n.idiv(10);
+      if (d === 0) {
+        zeroFlag = true;
+        continue;
+      }
+      if (zeroFlag) str = digit[0] + str;
+      str = digit[d] + unit[i] + str;
+      zeroFlag = false;
+    }
+    return str.replace(/零+$/g, '');
+  };
+
+  const intNum = new BigNumber(intStr);
+  let res = '';
+  if (intNum.isZero()) {
+    res = digit[0];
+  } else {
+    let n = intNum.abs();
+    let sectionIndex = 0;
+    while (n.gt(0)) {
+      const seg = n.mod(10000);
+      n = n.idiv(10000);
+      if (seg.gt(0)) {
+        const segStr = section4(seg);
+        const needZero =
+          res && !res.startsWith(digit[0]) && (seg.lt(1000) || seg.mod(1000).isZero());
+        const bu = sectionIndex ? bigUnit[sectionIndex] : '';
+        res = segStr + bu + (needZero ? digit[0] : '') + res;
+      } else if (res && !res.startsWith(digit[0])) {
+        res = digit[0] + res;
+      }
+      sectionIndex++;
+    }
+    res = res.replace(/^壹拾/, '拾');
+  }
+
+  // 5. 小数部分（角分厘）
+  let frac = '';
+  for (let i = 0; i < Math.min(3, dp); i++) {
+    const ch = decStr[i] || '0';
+    const d = ch.charCodeAt(0) - 48;
+    if (d > 0) frac += digit[d] + smallUnit[i];
+  }
+
+  // 6. 拼接
+  return frac ? `${sign}${res}${yuan}${frac}` : `${sign}${res}${yuan}整`;
+}

package/src/ts/number/index.ts

@@ -0,0 +1,3 @@
+export * from './big';
+export * from './format';
+export * from './random';

package/src/ts/number/random.ts

@@ -0,0 +1,65 @@
+/**
+ * 随机生成 `a` 到 `b` 的整数（闭区间，包含两端）。
+ * - 自动交换边界，按从小到大处理。
+ * - 下界向上取整、上界向下取整后再取值。
+ * @param a 边界值。
+ * @param b 边界值。
+ * @returns 闭区间内的随机整数。
+ * @example
+ * randomInt(0, 10); // => 0..10 之间的随机整数（含 0 与 10）
+ * randomInt(10, 0); // => 0..10 之间的随机整数（含 0 与 10）
+ * randomInt(5.2, 10.8); // => 6..10 之间取整随机数（含 6 与 10）
+ */
+export function randomInt(a: number, b: number): number {
+  if (!Number.isFinite(a) || !Number.isFinite(b)) {
+    throw new TypeError('min 和 max 必须是有限数值');
+  }
+
+  const low = Math.min(a, b);
+  const high = Math.max(a, b);
+
+  const minInt = Math.ceil(low);
+  const maxInt = Math.floor(high);
+
+  if (maxInt < minInt) {
+    throw new RangeError('取整后区间为空');
+  }
+
+  if (maxInt === minInt) return minInt;
+
+  return Math.floor(Math.random() * (maxInt - minInt + 1)) + minInt;
+}
+
+/**
+ * 随机生成 `a` 到 `b` 的浮点数（半开区间，包含下界不包含上界）。
+ * - 自动交换边界，按从小到大处理。
+ * @param a 边界值。
+ * @param b 边界值。
+ * @returns 半开区间内的随机浮点数。
+ * @example
+ * randomFloat(0, 10); // => [0, 10) 内的随机浮点数
+ * randomFloat(10, 0); // => [0, 10) 内的随机浮点数
+ * randomFloat(5.2, 10.8); // => [5.2, 10.8) 内的随机浮点数
+ */
+export function randomFloat(a: number, b: number): number {
+  if (!Number.isFinite(a) || !Number.isFinite(b)) {
+    throw new TypeError('min 和 max 必须是有限数值');
+  }
+
+  const low = Math.min(a, b);
+  const high = Math.max(a, b);
+
+  if (high === low) return low;
+
+  return Math.random() * (high - low) + low;
+}
+
+/**
+ * 随机生成一个布尔值。
+ * @returns 随机布尔值。
+ * @example
+ * randomBoolean(); // => 随机返回 true 或 false
+ */
+export function randomBoolean(): boolean {
+  return Math.random() < 0.5;
+}

package/src/ts/object/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 获取对象键名数组（类型安全）。
+ * 注：内置 `Object.keys` 与 `lodash-es` 的 `keys` 在 TS 中通常返回 `string[]`，无法精确到 `keyof T`。
+ * @param obj 目标对象
+ * @returns 类型精确的 `Array<keyof T>`
+ * @example
+ * const o = { a: 1, b: 'x' };
+ * const keys = getObjectKeys(o); // type: ('a' | 'b')[], value: ['a','b']
+ */
+export function getObjectKeys<T extends object>(obj: T): Array<keyof T> {
+  return Object.keys(obj) as (keyof T)[];
+}

package/src/ts/string/format.ts

@@ -0,0 +1,52 @@
+/**
+ * 文本脱敏
+ * @param s 原始文本
+ * @param keepLeft 保留左侧字符数（默认 1）
+ * @param keepRight 保留右侧字符数（默认 0）
+ * @param maskChar 脱敏字符（默认 `*`）
+ * @returns 脱敏文本
+ * @example
+ * toMaskText('王小明', 1, 0) // => '王*'
+ * toMaskText('王小明', 1, 1) // => '王*明'
+ * toMaskText('13800138000', 3, 4) // => '138****8000'
+ */
+export function toMaskText(s: string, keepLeft = 1, keepRight = 0, maskChar = '*') {
+  if (!s) return '';
+  const v = String(s);
+  const l = Math.max(0, keepLeft);
+  const r = Math.max(0, keepRight);
+  const len = v.length;
+  const left = Math.min(l, len);
+  const right = Math.min(r, len - left);
+  const mid = len - left - right;
+  if (mid <= 0) return v;
+  const m = maskChar && maskChar.length > 0 ? maskChar : '*';
+  return v.slice(0, left) + m.repeat(mid) + v.slice(len - right);
+}
+
+/**
+ * 手机号中间打星：保留前三位与后四位，中间打 `*`。
+ * @param phone 手机号字符串
+ * @returns 遮蔽后的手机号
+ * @example
+ * toMaskPhone('13800138000') // => '138****8000'
+ */
+export function toMaskPhone(phone: string) {
+  return toMaskText(phone, 3, 4);
+}
+
+/**
+ * 姓名打星：
+ * - 长度 ≤ 2：保留首字，其余打 `*`
+ * - 长度 ≥ 3：保留首尾，各打星中间
+ * @param name 姓名字符串
+ * @returns 遮蔽后的姓名
+ * @example
+ * toMaskName('张三') // => '张*'
+ * toMaskName('王小明') // => '王*明'
+ */
+export function toMaskName(name: string) {
+  if (!name) return '';
+  const v = String(name);
+  return v.length <= 2 ? toMaskText(v, 1, 0) : toMaskText(v, 1, 1);
+}

package/src/ts/string/index.ts

@@ -0,0 +1,3 @@
+export * from './format';
+export * from './random';
+export * from './other';

package/src/ts/string/other.ts

@@ -0,0 +1,33 @@
+/**
+ * 计算字符串在 UTF-8 编码下的字节长度。
+ * 使用场景：
+ * 1) 按字节限制表单输入（避免超过后端/数据库字段上限）
+ * 2) 评估网络传输、缓存（Redis/消息队列）开销
+ * 3) 根据字节数截断或提示用户（而非按字符数）
+ * @param str 输入的字符串
+ * @returns 字符串的字节长度
+ * @example
+ * getStringByteLength('abc') // 3
+ * getStringByteLength('中文') // 6
+ * getStringByteLength('😊') // 4
+ */
+export function getStringByteLength(str: string): number {
+  let byteLen = 0;
+
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+
+    if (code <= 0x7f) {
+      byteLen += 1; // （ASCII 基本拉丁）→ 包含数字 0-9、英文字母 A-Z/a-z、常见符号
+    } else if (code <= 0x7ff) {
+      byteLen += 2; // （拉丁扩展）→ 包含拉丁字母（含变音符）、希腊文、俄文/西里尔文、希伯来文、阿拉伯文等
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      byteLen += 4; // （UTF-16 代理项）→ 包含 emoji、稀有汉字（扩展区）、音乐符号等
+      i++;
+    } else {
+      byteLen += 3; // （BMP 绝大部分）→ 包含中文/日文/韩文的大多数字符（CJK 统一汉字）、以及大量其它脚本
+    }
+  }
+
+  return byteLen;
+}

package/src/ts/string/random.ts

@@ -0,0 +1,42 @@
+/**
+ * 生成UUID
+ * @returns UUID字符串
+ * @example
+ * const uuid = createUUID() // '7982fcfe-5721-4632-bede-6000885be57d'
+ */
+export function createUUID() {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+    const r = (Math.random() * 16) | 0,
+      v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * 生成随机字符串id
+ * - 常用于生成元素标签的id (默认加上'id_'前缀, 避免小程序中数字开头的id导致查询节点信息失败)
+ * @param prefix 前缀, 默认 'id_'
+ * @returns 随机字符串
+ * @example
+ * const id = createRandId(); // 'id_0rjuuuqv60xi'
+ * const id = createRandId('canvas_'); // 'canvas_v82a7ctm09q'
+ */
+export function createRandId(prefix = 'id_') {
+  return `${prefix}${Math.random().toString(36).substring(2, 16)}`;
+}
+
+/**
+ * 时间+固定位数的随机数字字符串
+ * @param digits 随机部分的位数，默认 6
+ * @returns 时间+随机数字字符串
+ * @example
+ * const traceId = createTimeRandId(); // '1763002648039123456'
+ * const traceId = createTimeRandId(8); // '176300264803912345678'
+ */
+export function createTimeRandId(digits: number = 6) {
+  const base = 10 ** (digits - 1);
+  const range = 9 * base;
+  const randomInt = Math.floor(Math.random() * range) + base;
+
+  return `${Date.now()}${randomInt}`;
+}

package/src/ts/typing/index.ts

@@ -0,0 +1,161 @@
+/**
+ * 将指定属性设为必填（不改变其他属性）。
+ * - 所有属性必填请使用内置的Required<T>
+ * @example
+ * type User = { id?: number; name?: string; age?: number };
+ * type U1 = SetRequired<User, 'id' | 'name'>; // { id: number; name: string; age?: number }
+ */
+export type SetRequired<T, K extends keyof T> = {
+  [P in K]-?: T[P];
+} & Omit<T, K>;
+
+/**
+ * 将指定属性设为可选（不改变其他属性）。
+ * - 所有属性可选请使用内置的Partial<T>
+ * @example
+ * type User = { id: number; name: string; age: number };
+ * type U2 = SetOptional<User, 'age'>; // { id: number; name: string; age?: number }
+ */
+export type SetOptional<T, K extends keyof T> = {
+  [P in K]+?: T[P];
+} & Omit<T, K>;
+
+/**
+ * 深度可选（递归将所有属性设为可选）。
+ * @example
+ * type T = { a: { b: number }; list: Array<{ id: string }> };
+ * type R = DeepPartial<T>;
+ */
+export type DeepPartial<T> = T extends (infer U)[]
+  ? DeepPartial<U>[]
+  : T extends (...args: unknown[]) => unknown
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T;
+
+/**
+ * 深度必填（递归移除所有可选标记）。
+ * @example
+ * type T = { a?: { b?: number } };
+ * type R = DeepRequired<T>; // { a: { b: number } }
+ */
+export type DeepRequired<T> = T extends (infer U)[]
+  ? DeepRequired<U>[]
+  : T extends (...args: unknown[]) => unknown
+    ? T
+    : T extends object
+      ? { [K in keyof T]-?: DeepRequired<T[K]> }
+      : T;
+
+/**
+ * 取消只读（顶层移除 `readonly`）。
+ * @example
+ * type R = Mutable<Readonly<{ a: number }>>; // { a: number }
+ */
+export type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+/**
+ * 深度只读（递归添加 `readonly`）。
+ * @example
+ * type R = ReadonlyDeep<{ a: { b: number }; list: { id: string }[] }>;
+ */
+export type ReadonlyDeep<T> = T extends (infer U)[]
+  ? ReadonlyArray<ReadonlyDeep<U>>
+  : T extends (...args: unknown[]) => unknown
+    ? T
+    : T extends object
+      ? { readonly [K in keyof T]: ReadonlyDeep<T[K]> }
+      : T;
+
+/**
+ * 对象值联合类型。
+ * @example
+ * type V = ValueOf<{ a: 1; b: 'x' }>; // 1 | 'x'
+ */
+export type ValueOf<T> = T[keyof T];
+
+/**
+ * 根据值类型获取键名联合。
+ * @example
+ * type Keys = KeysOfType<{ a: string; b: number; c: string }, string>; // 'a' | 'c'
+ */
+export type KeysOfType<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];
+
+/**
+ * 按值类型挑选属性。
+ * @example
+ * type R = PickByType<{ a: string; b: number; c: string }, string>; // { a: string; c: string }
+ */
+export type PickByType<T, V> = Pick<T, KeysOfType<T, V>>;
+
+/**
+ * 可选键名联合。
+ * @example
+ * type K = OptionalKeys<{ a?: number; b: string }>; // 'a'
+ */
+export type OptionalKeys<T> = {
+  [K in keyof T]-?: Pick<T, K> extends Required<Pick<T, K>> ? never : K;
+}[keyof T];
+
+/**
+ * 必填键名联合。
+ * @example
+ * type K = RequiredKeys<{ a?: number; b: string }>; // 'b'
+ */
+export type RequiredKeys<T> = {
+  [K in keyof T]-?: Pick<T, K> extends Required<Pick<T, K>> ? K : never;
+}[keyof T];
+
+/**
+ * 联合类型转交叉类型。
+ * @example
+ * type I = UnionToIntersection<{ a: 1 } | { b: 2 }>; // { a: 1 } & { b: 2 }
+ */
+export type UnionToIntersection<U> = (U extends unknown ? (x: U) => unknown : never) extends (
+  x: infer I,
+) => unknown
+  ? I
+  : never;
+
+/**
+ * 合并属性（以 `U` 覆盖 `T` 的同名属性）。
+ * @example
+ * type R = Merge<{ a: 1; b: 2 }, { b: 3; c: 4 }>; // { a: 1; b: 3; c: 4 }
+ */
+export type Merge<T, U> = Omit<T, keyof U> & U;
+
+/**
+ * 名义类型（品牌化）。
+ * @example
+ * type UserId = Brand<number, 'UserId'>;
+ */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+
+/**
+ * 可空（包含 `null | undefined`）。
+ * @example
+ * type R = Nullable<string>; // string | null | undefined
+ */
+export type Nullable<T> = T | null | undefined;
+
+/**
+ * 可序列化为 JSON 的值类型。
+ */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonObject = { [k: string]: JsonValue };
+export type JsonArray = Array<JsonValue>;
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/**
+ * 精确匹配形状（不允许多余属性）。
+ * @example
+ * type Shape = { a: number };
+ * type OK = Exact<{ a: number }, Shape>; // { a: number }
+ * type NG = Exact<{ a: number; b: 1 }, Shape>; // never
+ */
+export type Exact<T, Shape> = T extends Shape
+  ? Exclude<keyof T, keyof Shape> extends never
+    ? T
+    : never
+  : never;

package/src/ts/url/file/index.ts

@@ -0,0 +1,57 @@
+import { getObjectKeys } from '../../object';
+
+/**
+ * 跨端 100% 原生可解码文件后缀表
+ * 覆盖：iOS 14+ / Android 5+ WebView、Chrome/Edge/Safari/Firefox
+ * 剔除：所有需要 polyfill 或转码的容器/编码
+ */
+const FILE_TYPE = {
+  img: ['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp'],
+  video: ['mp4', 'mov', 'm4v'],
+  voice: ['mp3', 'wav', 'm4a'],
+  excel: ['csv', 'xls', 'xlsx', 'xlsm', 'ods'],
+  word: ['txt', 'doc', 'docx', 'pdf', 'md', 'wps'],
+  zip: ['zip', 'gz', 'tar', 'rar', '7z'],
+  ppt: ['ppt', 'pptx', 'odp'],
+  app: ['apk', 'ipa'],
+};
+
+/**
+ * 获取文件后缀（不含点，返回小写）。
+ * 当文件名不包含点（'.'）时，返回空字符串。
+ * @param fileName 文件名，例如 `avatar.PNG`
+ * @returns 后缀字符串，例如 `png`
+ * @example getFileSuffix('avatar.PNG') // 'png'
+ * @example getFileSuffix('a.tar.gz') // 'gz'
+ * @example getFileSuffix('.ignore') // ''
+ * @example getFileSuffix('abc') // ''
+ */
+export function getFileSuffix(fileName: string) {
+  if (fileName.startsWith('.')) return ''; // 隐藏文件，返回空串
+
+  const idx = fileName.lastIndexOf('.');
+  return idx > 0 ? fileName.slice(idx + 1).toLowerCase() : '';
+}
+
+/**
+ * 根据文件后缀判断文件类型。
+ * 会将后缀转换为小写后与 `FILE_TYPE` 映射匹配；若未匹配到则返回 `'unknown'`。
+ * @param fileName 文件名
+ * @returns 文件类型字符串（如 'img' | 'video' | 'voice' | 'excel' | 'word' | 'zip' | 'ppt' | 'app' | 'unknown'）
+ * @example getFileType('avatar.PNG') // 'img'
+ * @example getFileType('archive.tar') // 'zip'
+ * @example getFileType('abc') // 'unknown'
+ */
+export function getFileType(fileName: string) {
+  const suffix = getFileSuffix(fileName);
+  if (!suffix) return 'unknown';
+
+  const keys = getObjectKeys(FILE_TYPE);
+  for (const key of keys) {
+    if (FILE_TYPE[key].includes(suffix)) {
+      return key;
+    }
+  }
+
+  return 'unknown';
+}

package/src/ts/url/index.ts

@@ -0,0 +1,4 @@
+export * from './file';
+export * from './oss';
+export * from './param';
+export * from './qn';