Cleave.js 格式化输入库完全指南

什么是 Cleave.js？

Cleave.js 是一个轻量级的 JavaScript 库，专门用于在 Web 表单中实现输入内容的实时格式化。它能够帮助开发者轻松处理各种格式化的输入需求，如信用卡号、电话号码、日期等，极大地提升了表单输入的用户体验。

核心功能特性

1. 实时格式化：在用户输入时即时格式化内容
2. 多场景支持：信用卡号、电话号码、日期等多种格式
3. 跨框架兼容：原生 JavaScript、React 和 Angular 均可使用
4. 高度可定制：通过配置选项满足不同格式化需求
5. 轻量高效：不依赖其他库，性能优异

安装与基本使用

安装方式

可以通过多种方式将 Cleave.js 集成到项目中：

// 通过npm安装
npm install cleave.js --save

// 或者直接引入CDN资源
<script src="path/to/cleave.min.js"></script>

基础示例

// 初始化一个信用卡输入格式化器
var cleave = new Cleave('.input-element', {
    creditCard: true,
    onCreditCardTypeChanged: function(type) {
        // 信用卡类型变化回调
    }
});

主要模块详解

1. JavaScript API

Cleave.js 的核心 API 提供了丰富的配置选项和方法：

构造函数

new Cleave(selector, options)

• selector: 可以是CSS选择器、DOM元素或NodeList
• options: 配置对象，定义格式化规则

常用配置选项

• blocks: 定义输入分段方式（如信用卡号的4-4-4-4格式）
• delimiter: 设置分隔符（如电话号码中的"-"）
• prefix: 添加固定前缀（如货币符号）
• numericOnly: 限制只能输入数字

公共方法

• getRawValue(): 获取未格式化的原始值
• setRawValue(value): 设置原始值
• destroy(): 销毁实例

2. 电话库扩展

Cleave.js 提供了专门的电话格式化扩展，支持：

• 自动国家代码识别
• 根据国家/地区动态调整格式
• 国际电话号码验证

var cleave = new Cleave('.phone-input', {
    phone: true,
    phoneRegionCode: 'US'
});

3. React 组件集成

对于 React 项目，可以使用专门的 React 组件版本：

import Cleave from 'cleave.js/react';

<Cleave
    options={{creditCard: true}}
    onChange={this.onCreditCardChange}
/>

4. Angular 指令支持

Angular 开发者可以通过指令方式使用：

angular.module('app').directive('cleave', function() {
    return {
        restrict: 'A',
        scope: {
            options: '='
        },
        link: function(scope, element) {
            new Cleave(element[0], scope.options);
        }
    };
});

实际应用场景

信用卡输入处理

new Cleave('.credit-card', {
    creditCard: true,
    onCreditCardTypeChanged: function(type) {
        // 根据卡类型更新UI
    }
});

日期输入格式化

new Cleave('.date-input', {
    date: true,
    datePattern: ['Y', 'm', 'd']
});

数字格式化（如货币）

new Cleave('.currency-input', {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

最佳实践建议

1. 合理选择格式化时机：对于复杂格式，考虑在blur时格式化而非实时
2. 提供格式提示：在输入框旁显示预期的格式示例
3. 处理极端情况：考虑粘贴、退格等特殊操作的处理
4. 移动端优化：确保在移动设备上有良好的输入体验
5. 无障碍访问：确保格式化不影响屏幕阅读器的使用

常见问题解答

Q: 如何处理用户粘贴已格式化的内容？ A: Cleave.js 会自动处理粘贴内容，去除已有格式后重新格式化。

Q: 能否自定义格式化规则？ A: 可以通过blocks和delimiter等选项组合实现几乎任何格式化需求。

Q: 格式化会影响表单提交的值吗？ A: 默认会，但可以通过getRawValue()获取原始值用于提交。

Cleave.js 通过简洁的API和强大的格式化能力，成为了处理表单输入格式化的理想解决方案。无论是简单的数字格式化还是复杂的信用卡输入处理，它都能提供优雅的解决方案，值得在前端开发者的工具箱中占有一席之地。