AutoNumeric 数字格式化库使用指南

AutoNumeric 数字格式化库使用指南

【免费下载链接】autoNumeric 项目地址: https://gitcode.com/gh_mirrors/aut/autoNumeric

项目概述

AutoNumeric 是一个专注于数字格式化的 JavaScript 库，它能够自动格式化输入框中的数字，支持多种货币符号、千分位分隔符、小数点格式等国际化需求。本文将详细介绍 AutoNumeric 的核心功能和使用方法。

基本配置方式

AutoNumeric 提供了多种配置方式，开发者可以根据项目需求选择最适合的方式。

1. JavaScript 初始化配置

$(document).ready(function(){
   $(selector).autoNumeric("init", {
        digitGroupSeparator: '.',  // 千分位分隔符
        decimalCharacter: ',',     // 小数点符号
        currencySymbol: '€ '      // 货币符号
    });
});

2. HTML5 数据属性配置

<input type='text' name="price" value="1234.56" 
       data-a-sep="." 
       data-a-dec="," 
       data-a-sign="€ "/>

3. 全局默认配置

$.extend($.fn.autoNumeric.defaults, {
    digitGroupSeparator: ',',
    decimalCharacter: '.',
    currencySymbol: '$'
});

4. 回调函数配置

var getDecimalPlaces = function() {
    return 2; // 返回需要的小数位数
};

$('selector').autoNumeric('init', { 
    decimalPlaces: getDecimalPlaces 
});

输入值处理规则

AutoNumeric 对输入值有严格的验证规则：

输入值示例	是否有效	说明
"123456"	是	纯数字
"123456.78"	是	包含小数点
"123456,78"	是	包含逗号作为小数点
"-123456"	是	带负号前缀
"123456-"	是	带负号后缀
"123,456.78"	否	多个分隔符
"€ 123456.78"	否	包含非数字字符
"2.034E23"	否	科学计数法

特殊场景处理

ASP.NET 回发问题解决方案

在 ASP.NET 应用中，回发可能导致格式化问题，有两种解决方案：

1. 禁用页面加载时格式化

$('selector').autoNumeric('init', {formatOnPageLoad: false});

2. 使用 defaultValueOverride 选项

$('selector').autoNumeric('init', {
    defaultValueOverride: "1234.56"
});

数值范围控制

通过 minimumValue 和 maximumValue 控制输入范围：

{
    minimumValue: '0.00',        // 最小值
    maximumValue: '99999999.99',  // 最大值
    decimalPlaces: 2              // 小数位数
}

核心 API 方法

初始化与销毁

• init - 初始化 AutoNumeric
• destroy - 销毁实例

数据操作

• set - 设置格式化值
• get - 获取原始数值
• unSet - 取消格式化
• reSet - 重新格式化

辅助功能

• update - 更新配置
• getSettings - 获取当前配置
• getArray/getString - 获取序列化数据

直接格式化方法

无需 DOM 元素即可使用格式化功能：

// 直接格式化
$.fn.autoFormat(1234.56, {
    digitGroupSeparator: '.',
    decimalCharacter: ',',
    currencySymbol: ' €'
});

// 直接取消格式化
$.fn.autoUnformat("1.234,56 €", {
    digitGroupSeparator: '.',
    decimalCharacter: ',',
    currencySymbol: ' €'
});

高级配置选项

数字分组设置

• digitalGroupSpacing: '3' - 标准千分位 (1,000,000)
• digitalGroupSpacing: '2' - 印度拉克格式 (10,00,000)
• digitalGroupSpacing: '4' - 亚洲四位数分组 (1,0000,0000)

货币符号位置

• currencySymbolPlacement: 'p' - 前缀 ($100)
• currencySymbolPlacement: 's' - 后缀 (100€)

负号位置

• negativePositiveSignPlacement: 'l' - 货币符号左侧 (-$100)
• negativePositiveSignPlacement: 'r' - 货币符号右侧 ($-100)
• negativePositiveSignPlacement: 's' - 数值后缀 (100-)

舍入方法

AutoNumeric 支持 12 种舍入算法，包括：

• 'S' - 对称四舍五入（默认）
• 'A' - 非对称四舍五入
• 'B' - 银行家舍入法
• 'U' - 向上舍入
• 'D' - 向下舍入
• 'N05' - 舍入到最接近的 0.05

最佳实践建议

1. 移动端优化：启用 showOnlyNumbersOnFocus 选项可改善移动设备输入体验
2. 国际化：根据用户区域设置自动配置分隔符和小数点
3. 表单提交：在提交前使用 unSet 方法取消格式化
4. 性能考虑：避免频繁调用 update 方法
5. 输入验证：结合 minimumValue 和 maximumValue 确保数据有效性

AutoNumeric 提供了强大的数字格式化能力，通过合理配置可以满足各种国际化数字处理需求。开发者应根据具体应用场景选择合适的配置方式和方法组合。

【免费下载链接】autoNumeric 项目地址: https://gitcode.com/gh_mirrors/aut/autoNumeric