JavaScript函数声明生成器

函数声明

/**
 * 将数值金额格式化为本地化的货币或千分位数字字符串。
 * - 使用 Intl.NumberFormat 实现本地化格式化与千分位分隔。
 * - 支持自定义货币代码、小数最小/最大小数位数。
 * - 严格处理边界：NaN/Infinity/非法参数会抛出错误；规范化 -0 为 0。
 *
 * 适用场景：
 * - 价格展示（页面 UI）
 * - 报表导出（稳定的小数位与千分位格式）
 *
 * @param {number|string} amount - 要格式化的金额；支持 number 或可被 Number() 正确解析的字符串。
 * @param {string|string[]} [locale] - BCP-47 语言标记（如 "zh-CN"、"en-US"），或其数组；省略时使用运行环境默认区域。
 * @param {string} [currency] - 3 位 ISO 4217 货币代码（如 "CNY"、"USD"）。省略则输出为普通带千分位的十进制数字。
 * @param {number} [minFraction] - 最小小数位（0-20）。未传时使用该区域/货币的默认值。
 * @param {number} [maxFraction] - 最大小数位（0-20），需不小于 minFraction。未传时使用该区域/货币的默认值。
 * @returns {string} 已格式化的字符串。
 *
 * @throws {TypeError} 当 amount 非有限数值（NaN/Infinity）或类型不合法时抛出。
 * @throws {RangeError} 当 locale/currency 非法，或小数位参数越界/相互矛盾时抛出。
 */
function formatCurrency(amount, locale, currency, minFraction, maxFraction) {
  // 将输入转换为有限数值
  const toFiniteNumber = (val) => {
    if (typeof val === 'number') {
      return val;
    }
    if (typeof val === 'string') {
      const n = Number(val.trim());
      return n;
    }
    throw new TypeError('formatCurrency: "amount" must be a number or a numeric string.');
  };

  let num = toFiniteNumber(amount);
  if (!Number.isFinite(num)) {
    throw new TypeError('formatCurrency: "amount" must be a finite number (not NaN/Infinity).');
  }

  // 规范化 -0 为 0，避免显示 "-0.00" 等
  if (Object.is(num, -0)) {
    num = 0;
  }

  // 处理货币代码：允许未提供；若提供则必须是 3 位字母
  let upperCurrency;
  if (currency != null) {
    if (typeof currency !== 'string') {
      throw new TypeError('formatCurrency: "currency" must be a string ISO 4217 code, e.g., "USD".');
    }
    upperCurrency = currency.trim().toUpperCase();
    if (!/^[A-Z]{3}$/.test(upperCurrency)) {
      throw new RangeError('formatCurrency: "currency" must be a 3-letter ISO 4217 code (e.g., "CNY", "USD").');
    }
  }

  // 先用默认分组与样式创建一个格式化器，以获取该区域/货币的默认小数位
  const style = upperCurrency ? 'currency' : 'decimal';
  let defaultsNf;
  try {
    defaultsNf = new Intl.NumberFormat(locale, {
      style,
      currency: upperCurrency,
    });
  } catch (err) {
    throw new RangeError(`formatCurrency: Invalid locale or currency. ${err.message}`);
  }

  const { minimumFractionDigits: defMin, maximumFractionDigits: defMax } =
    defaultsNf.resolvedOptions();

  // 归一化小数位参数
  const normalizeDigits = (name, value) => {
    if (value === undefined || value === null) return undefined;
    const n = Number(value);
    if (!Number.isFinite(n) || !Number.isInteger(n)) {
      throw new RangeError(`formatCurrency: "${name}" must be an integer between 0 and 20.`);
    }
    if (n < 0 || n > 20) {
      throw new RangeError(`formatCurrency: "${name}" must be between 0 and 20.`);
    }
    return n;
  };

  const min = normalizeDigits('minFraction', minFraction);
  const max = normalizeDigits('maxFraction', maxFraction);

  let finalMin;
  let finalMax;

  if (min === undefined && max === undefined) {
    finalMin = defMin;
    finalMax = defMax;
  } else if (min !== undefined && max === undefined) {
    finalMin = min;
    finalMax = Math.max(min, defMax);
  } else if (min === undefined && max !== undefined) {
    finalMax = max;
    finalMin = Math.min(defMin, max);
  } else {
    if (min > max) {
      throw new RangeError('formatCurrency: "minFraction" cannot be greater than "maxFraction".');
    }
    finalMin = min;
    finalMax = max;
  }

  // 创建最终格式化器
  let formatter;
  try {
    formatter = new Intl.NumberFormat(locale, {
      style,
      currency: upperCurrency,
      useGrouping: true,
      minimumFractionDigits: finalMin,
      maximumFractionDigits: finalMax,
      // currencyDisplay 默认 "symbol"；如报表需要 "code"，可在注意事项中参考调整
    });
  } catch (err) {
    throw new RangeError(`formatCurrency: Failed to create formatter. ${err.message}`);
  }

  return formatter.format(num);
}

功能说明

• 函数用途：

  • 将金额数值格式化为符合本地化规则的货币或十进制字符串，包含千分位分隔与可控小数位数。
  • 支持指定 locale 与货币代码，适用于 UI 价格展示与对小数位有严格要求的报表导出。

• 参数说明：

  • amount (number|string)：要格式化的金额；支持 number 或可被 Number() 正确解析的字符串。必须为有限数值。
  • locale (string|string[]，可选)：BCP-47 语言标记或数组，例如 "zh-CN"、"en-US"；省略时使用运行环境默认区域。
  • currency (string，可选)：3 位 ISO 4217 货币代码，如 "CNY"、"USD"、"JPY"。未提供时按十进制数字格式化（不显示货币符号）。
  • minFraction (number，可选)：最小小数位（0-20），未提供时使用该区域/货币默认值。
  • maxFraction (number，可选)：最大小数位（0-20），未提供时使用该区域/货币默认值；若与 minFraction 同时提供，则必须 >= minFraction。

• 返回值：

  • string：格式化后的字符串。

• 使用示例：

  • 基本货币格式化（UI 展示）
    • formatCurrency(1234567.89, 'zh-CN', 'CNY') => "¥1,234,567.89"
    • formatCurrency(1234567.89, 'en-US', 'USD') => "$1,234,567.89"
  • 报表导出（固定两位小数）
    • formatCurrency(1234.5, 'zh-CN', 'CNY', 2, 2) => "¥1,234.50"
    • formatCurrency('9876', 'en-GB', 'GBP', 2, 2) => "£9,876.00"
  • 无货币代码时作为十进制数字输出（仍含千分位）
    • formatCurrency(1234567.89, 'de-DE') => "1.234.567,89"
  • 处理日元（默认 0 位，强制两位）
    • formatCurrency(1234, 'ja-JP', 'JPY') => "￥1,234"
    • formatCurrency(1234, 'ja-JP', 'JPY', 2, 2) => "￥1,234.00"

注意事项

• 代码兼容性：
  • 依赖 Intl.NumberFormat。现代浏览器与 Node.js 均已支持；在老旧环境或 Node 打包裁剪 ICU 数据的场景，请确保完整的 ICU 支持，否则部分 locale/currency 可能不可用。
• 特殊使用场景提示：
  • 报表导出通常需要稳定的小数位，建议将 minFraction 与 maxFraction 设为相同值（例如 2）。
  • 若需要在报表中显示货币代码而非符号（如 "USD 1,234.56"），可将 formatter 的 currencyDisplay 由默认 "symbol" 改为 "code"；或在函数内根据需求扩展一个参数。
  • 若需要在高频循环中大量格式化，考虑在业务层缓存 Intl.NumberFormat 实例（按 locale/currency/小数位作为缓存键）以减少实例化开销。
• 可能的错误处理建议：
  • 函数对非法 amount（NaN/Infinity）或参数越界会抛出错误；在 UI 中建议使用 try/catch 包裹并提供降级回退（例如显示 "--" 或原始数值）。
  • 过大数值（超过 Number 安全整数范围）可能存在精度风险；如需处理超大金额，建议在数据层使用十进制库（如 decimal.js）先做精度运算，再传入本函数进行展示格式化。