Flutter字符串格式化插件 string_mask 的使用

string_mask 是一个基于掩码的字符串格式化和验证工具，它最初是为 JavaScript 编写的，后来被移植到了 Dart。这个插件可以帮助你轻松地格式化输入数据，如电话号码、日期、货币等。

特性和问题报告

如果你有任何功能请求或发现了任何 bug，请在 [issue tracker][tracker] 上提交。

安装

通过 pub.dartlang.org 来安装 string_mask 插件：

dependencies:
  string_mask: "^0.0.1"

特殊掩码字符

以下是一些特殊的掩码字符及其用途：

特殊字符类型

• 可选字符：用于解析源字符串中可能存在也可能不存在的字符。例如日期和时间。
• 递归字符：用于解析源字符串开头或结尾重复出现的模式。例如带有千位分隔符的两位小数数字。

注意：递归字符之后的所有字符都将被视为非特殊字符。

使用方法

创建实例

你可以通过创建 StringMask 实例来使用该插件：

/**
 * - optionsObject 参数在构造函数中是可选的
 * - apply 方法返回一个格式化的字符串值
 * - validate 方法返回布尔值，表示字符串是否符合掩码规则
 */
var mask = new StringMask('some mask', options: new MaskOptions()); // optionsObject 是可选的
var maskedValue = mask.apply('some value string');
var isValid = mask.validate('some value string to validate');

静态接口

也可以通过静态接口来使用：

/**
 * - optionsObject 参数在所有方法中都是可选的
 * - apply 方法返回一个格式化的字符串值
 * - validate 方法返回布尔值，表示字符串是否符合掩码规则
 * - process 方法返回一个对象：{result: <maskedValue>, valid: <isValid>}
 */
var maskedValue = StringMask.apply_('some value string', 'some mask', optionsObject); 
var isValid = StringMask.validate_('some value string', 'some mask', optionsObject);
var result = StringMask.process_('some value string', 'some mask', optionsObject);

示例代码

以下是一些常见的格式化示例：

数字格式化

var maskOptions = new MaskOptions()
  ..reverse = true;

var formatter = new StringMask("#0", options: maskOptions);
var result = formatter.apply('123'); // 123

带有千位分隔符的两位小数数字

var maskOptions = new MaskOptions()
  ..reverse = true;

var formatter = new StringMask('#.##0,00', options: maskOptions);
var result = formatter.apply('100123456'); // 1.001.234,56
var result2 = formatter.apply('6'); // 0,06

电话号码格式化

var formatter = new StringMask('+00 (00) 0000-0000');
var result = formatter.apply('553122222222'); // +55 (31) 2222-2222

百分比格式化

var maskOptions = new MaskOptions()
  ..reverse = true;

var formatter = new StringMask('#.##0,00', options: maskOptions);
var result = formatter.apply('001'); // 0,01%

巴西 CPF 号码格式化

var formatter = new StringMask('000.000.000-00');
var result = formatter.apply('12965815620'); // 129.658.156-20

日期和时间格式化

var formatter = new StringMask('90/90/9900');
var result = formatter.apply('1187'); // 1/1/87

大小写转换

var formatter = new StringMask('UUUUUUUUUUUUU');
var result = formatter.apply('To Upper Case'); // TO UPPER CASE

var formatter = new StringMask('LLLLLLLLLLLLL');
var result = formatter.apply('To Lower Case'); // to lower case

国际银行账号格式化

var formatter = new StringMask('UUAA AAAA AAAA AAAA AAAA AAAA AAA');
var result = formatter.apply('FR761111BBBB69410000AA33222');
// 结果: FR76 1111 BBBB 6941 0000 AA33 222

完整示例 Demo

以下是一个完整的 Flutter 示例，演示如何使用 string_mask 插件来格式化用户输入：

import 'package:flutter/material.dart';
import 'package:string_mask/string_mask.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'String Mask Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  [@override](/user/override)
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final TextEditingController _controller = TextEditingController();
  String _formattedText = '';

  void _onTextChanged(String text) {
    var mask = StringMask('+00 (00) 0000-0000');
    setState(() {
      _formattedText = mask.apply(text);
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('String Mask Example'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            TextField(
              controller: _controller,
              onChanged: _onTextChanged,
              decoration: InputDecoration(
                labelText: 'Enter phone number',
              ),
            ),
            SizedBox(height: 20),
            Text('Formatted Phone Number: $_formattedText'),
          ],
        ),
      ),
    );
  }
}