/**
* 数值工具类
*
* 提供一组静态方法，用于处理和操作数值类型的数据。
* 包括数值判断、字符串转换、格式化、范围校验等功能。
*
* @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');
}
}
