鸿蒙NEXT开发数值工具类（TS）

/**
 * 数值工具类
 *
 * 提供一组静态方法，用于处理和操作数值类型的数据。
 * 包括数值判断、字符串转换、格式化、范围校验等功能。
 *
 * @author CSDN-鸿蒙布道师
 * @since 2025/04/03
 */
export class NumberUtil {

  /**
   * 判断是否是数值
   *
   * 检查给定值是否为有效的 JavaScript 数值（非 NaN）。
   *
   * @param value 需要判断的参数
   * @returns 如果是有效数值，则返回 true；否则返回 false
   */
  static isNumber(value: any): boolean {
    return typeof value === "number" && !isNaN(value);
  }

  /**
   * 将字符串转换为整数。
   *
   * 如果无法转换为整数，则返回默认值。
   *
   * @param value 要转换的字符串
   * @param defaultValue 转换失败时的默认值，默认为 0
   * @returns 转换后的整数值或默认值
   */
  static toInt(value: string, defaultValue: number = 0): number {
    try {
      const parsedValue = parseInt(value, 10); // 明确指定基数为 10
      return isNaN(parsedValue) ? defaultValue : parsedValue;
    } catch (e) {
      return defaultValue;
    }
  }

  /**
   * 将字符串转换为浮点数。
   *
   * 如果无法转换为浮点数，则返回默认值。
   *
   * @param value 要转换的字符串
   * @param defaultValue 转换失败时的默认值，默认为 0
   * @returns 转换后的浮点数值或默认值
   */
  static toFloat(value: string, defaultValue: number = 0): number {
    try {
      const parsedValue = parseFloat(value);
      return isNaN(parsedValue) ? defaultValue : parsedValue;
    } catch (e) {
      return defaultValue;
    }
  }

  /**
   * 格式化数字为固定小数位数。
   *
   * 如果数字超出范围，会自动截断到指定的小数位。
   *
   * @param value 要格式化的数字
   * @param digits 小数位数，默认为 2
   * @returns 格式化后的数字字符串
   */
  static formatFixed(value: number, digits: number = 2): string {
    if (!this.isNumber(value)) {
      throw new Error("Invalid number provided.");
    }
    return value.toFixed(digits);
  }

  /**
   * 校验数字是否在指定范围内。
   *
   * @param value 要校验的数字
   * @param min 最小值
   * @param max 最大值
   * @returns 如果数字在范围内，则返回 true；否则返回 false
   */
  static isInRange(value: number, min: number, max: number): boolean {
    if (!this.isNumber(value) || !this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("All arguments must be valid numbers.");
    }
    return value >= min && value <= max;
  }

  /**
   * 将数字限制在指定范围内。
   *
   * 如果数字小于最小值，则返回最小值；如果大于最大值，则返回最大值。
   *
   * @param value 要限制的数字
   * @param min 最小值
   * @param max 最大值
   * @returns 限制后的数字
   */
  static clamp(value: number, min: number, max: number): number {
    if (!this.isNumber(value) || !this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("All arguments must be valid numbers.");
    }
    return Math.min(Math.max(value, min), max);
  }

  /**
   * 计算两个数字之间的随机数。
   *
   * @param min 最小值（包含）
   * @param max 最大值（包含）
   * @returns 随机生成的数字
   */
  static randomInRange(min: number, max: number): number {
    if (!this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("Both min and max must be valid numbers.");
    }
    return Math.floor(Math.random() * (max - min + 1)) + min;
  }

  /**
   * 将数字四舍五入到指定的小数位。
   *
   * @param value 要四舍五入的数字
   * @param digits 小数位数，默认为 0
   * @returns 四舍五入后的数字
   */
  static roundTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.round(value * factor) / factor;
  }

  /**
   * 将数字向上取整到指定的小数位。
   *
   * @param value 要向上取整的数字
   * @param digits 小数位数，默认为 0
   * @returns 向上取整后的数字
   */
  static ceilTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.ceil(value * factor) / factor;
  }

  /**
   * 将数字向下取整到指定的小数位。
   *
   * @param value 要向下取整的数字
   * @param digits 小数位数，默认为 0
   * @returns 向下取整后的数字
   */
  static floorTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.floor(value * factor) / factor;
  }

  /**
   * 格式化数字为千分位表示法。
   *
   * @param value 要格式化的数字
   * @returns 格式化后的数字字符串
   */
  static formatThousands(value: number): string {
    if (!this.isNumber(value)) {
      throw new Error("Invalid number provided.");
    }
    return value.toLocaleString('en-US');
  }
}

代码如下：

/**
 * 数值工具类
 *
 * 提供一组静态方法，用于处理和操作数值类型的数据。
 * 包括数值判断、字符串转换、格式化、范围校验等功能。
 *
 * @author CSDN-鸿蒙布道师
 * @since 2025/04/03
 */
export class NumberUtil {

  /**
   * 判断是否是数值
   *
   * 检查给定值是否为有效的 JavaScript 数值（非 NaN）。
   *
   * @param value 需要判断的参数
   * @returns 如果是有效数值，则返回 true；否则返回 false
   */
  static isNumber(value: any): boolean {
    return typeof value === "number" && !isNaN(value);
  }

  /**
   * 将字符串转换为整数。
   *
   * 如果无法转换为整数，则返回默认值。
   *
   * @param value 要转换的字符串
   * @param defaultValue 转换失败时的默认值，默认为 0
   * @returns 转换后的整数值或默认值
   */
  static toInt(value: string, defaultValue: number = 0): number {
    try {
      const parsedValue = parseInt(value, 10); // 明确指定基数为 10
      return isNaN(parsedValue) ? defaultValue : parsedValue;
    } catch (e) {
      return defaultValue;
    }
  }

  /**
   * 将字符串转换为浮点数。
   *
   * 如果无法转换为浮点数，则返回默认值。
   *
   * @param value 要转换的字符串
   * @param defaultValue 转换失败时的默认值，默认为 0
   * @returns 转换后的浮点数值或默认值
   */
  static toFloat(value: string, defaultValue: number = 0): number {
    try {
      const parsedValue = parseFloat(value);
      return isNaN(parsedValue) ? defaultValue : parsedValue;
    } catch (e) {
      return defaultValue;
    }
  }

  /**
   * 格式化数字为固定小数位数。
   *
   * 如果数字超出范围，会自动截断到指定的小数位。
   *
   * @param value 要格式化的数字
   * @param digits 小数位数，默认为 2
   * @returns 格式化后的数字字符串
   */
  static formatFixed(value: number, digits: number = 2): string {
    if (!this.isNumber(value)) {
      throw new Error("Invalid number provided.");
    }
    return value.toFixed(digits);
  }

  /**
   * 校验数字是否在指定范围内。
   *
   * @param value 要校验的数字
   * @param min 最小值
   * @param max 最大值
   * @returns 如果数字在范围内，则返回 true；否则返回 false
   */
  static isInRange(value: number, min: number, max: number): boolean {
    if (!this.isNumber(value) || !this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("All arguments must be valid numbers.");
    }
    return value >= min && value <= max;
  }

  /**
   * 将数字限制在指定范围内。
   *
   * 如果数字小于最小值，则返回最小值；如果大于最大值，则返回最大值。
   *
   * @param value 要限制的数字
   * @param min 最小值
   * @param max 最大值
   * @returns 限制后的数字
   */
  static clamp(value: number, min: number, max: number): number {
    if (!this.isNumber(value) || !this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("All arguments must be valid numbers.");
    }
    return Math.min(Math.max(value, min), max);
  }

  /**
   * 计算两个数字之间的随机数。
   *
   * @param min 最小值（包含）
   * @param max 最大值（包含）
   * @returns 随机生成的数字
   */
  static randomInRange(min: number, max: number): number {
    if (!this.isNumber(min) || !this.isNumber(max)) {
      throw new Error("Both min and max must be valid numbers.");
    }
    return Math.floor(Math.random() * (max - min + 1)) + min;
  }

  /**
   * 将数字四舍五入到指定的小数位。
   *
   * @param value 要四舍五入的数字
   * @param digits 小数位数，默认为 0
   * @returns 四舍五入后的数字
   */
  static roundTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.round(value * factor) / factor;
  }

  /**
   * 将数字向上取整到指定的小数位。
   *
   * @param value 要向上取整的数字
   * @param digits 小数位数，默认为 0
   * @returns 向上取整后的数字
   */
  static ceilTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.ceil(value * factor) / factor;
  }

  /**
   * 将数字向下取整到指定的小数位。
   *
   * @param value 要向下取整的数字
   * @param digits 小数位数，默认为 0
   * @returns 向下取整后的数字
   */
  static floorTo(value: number, digits: number = 0): number {
    if (!this.isNumber(value) || !this.isNumber(digits)) {
      throw new Error("Both value and digits must be valid numbers.");
    }
    const factor = Math.pow(10, digits);
    return Math.floor(value * factor) / factor;
  }

  /**
   * 格式化数字为千分位表示法。
   *
   * @param value 要格式化的数字
   * @returns 格式化后的数字字符串
   */
  static formatThousands(value: number): string {
    if (!this.isNumber(value)) {
      throw new Error("Invalid number provided.");
    }
    return value.toLocaleString('en-US');
  }
}