Flutter文本格式化插件flutter_masked_text的使用

flutter_masked_text 是一个用于 Flutter 的文本格式化插件，可以帮助开发者轻松实现输入框的格式化功能。无论是电话号码、身份证号还是货币金额，都可以通过简单的配置实现。

安装

在 pubspec.yaml 文件中添加以下依赖：

dependencies:
  flutter_masked_text: ^2.0.0

然后运行以下命令安装：

flutter pub get

使用

导入库

首先，在 Dart 文件中导入 flutter_masked_text 库：

import 'package:flutter_masked_text/flutter_masked_text.dart';

MaskedText 示例

创建掩码控制器

创建一个掩码控制器并设置掩码格式：

var controller = new MaskedTextController(mask: '000.000.000-00');

设置到文本字段

将控制器绑定到 TextField 中：

return new MaterialApp(
    title: 'Flutter Demo',
    theme: new ThemeData(
        primarySwatch: Colors.blue,
    ),
    home: new SafeArea(
        child: new Scaffold(
            body: new Column(
                children: <Widget>[
                    new TextField(
                        controller: controller, // 绑定控制器
                        decoration: InputDecoration(hintText: "请输入身份证号"),
                    )
                ],
            ),
        ),
    ),
);

运行效果如下：

掩码选项

掩码支持以下字符：

• 0: 仅接受数字。
• A: 仅接受字母。
• @: 接受数字和字母。
• *: 接受任意字符。

初始值

可以通过 text 属性设置初始值：

var controller = new MaskedTextController(mask: '000-000', text: '123456');

动态更新文本

如果需要动态更新文本，可以使用 updateText 方法：

var controller = new MaskedTextController(text: '', mask: '000-000');
controller.updateText('123456');

print(controller.text); // 输出: 123-456

自定义翻译器

可以通过自定义翻译器来限制输入规则：

const translator = {
    '#': new RegExp(r'^[a-zA-Z0-9]+$') // 仅允许字母和数字
};

var controller = new MaskedTextController(mask: '####', translator: translator);

或者覆盖默认翻译器的部分规则：

var translator = MaskedTextController.getDefaultTranslator();
translator.remove('*'); // 移除通配符翻译器

var controller = new MaskedTextController(mask: '0000 **** **** 0000', translator: translator);
controller.updateText('12345678');

print(controller.text); // 输出: 1234 **** **** 5678

动态更改掩码

可以通过 updateMask 方法在运行时更改掩码：

var cpfController = new MaskedTextController(text: '12345678901', mask: '000.000.000-00');

print(cpfController.text); // 输出: 123.456.789-01

cpfController.updateMask('000.000.0000-0');

print(cpfController.text); // 输出: 123.456.7890-1

钩子函数

beforeChange 钩子（v0.7.0+）

在某些情况下，你可能需要验证用户输入是否符合掩码规则。可以使用 beforeChange 钩子：

var controller = new MaskedTextController(mask: '(00) 0000-0000');
controller.beforeChange = (String previous, String next) {
    // 自定义逻辑
    return next.length <= 14; // 允许最大长度为14
};

afterChange 钩子（v0.7.0+）

当文本发生变化时，可以监听 afterChange 钩子：

var controller = new MaskedTextController(mask: '(00) 0000-0000');
controller.afterChange = (String previous, String next) {
    print("$previous | $next");
};

Money Mask 示例

创建货币掩码控制器

var controller = new MoneyMaskedTextController();

使用 TextField

new TextField(
    controller: controller,
    keyboardType: TextInputType.number,
    decoration: InputDecoration(hintText: "请输入金额")
)

自定义分隔符

可以自定义小数点和千位分隔符：

var controller = new MoneyMaskedTextController(
    decimalSeparator: '.', 
    thousandSeparator: ','
);

动态设置值

通过 updateValue 方法动态设置值：

controller.updateValue(1234.56);

获取原始数值

可以通过 numberValue 属性获取原始数值：

double val = controller.numberValue;

使用装饰符号

可以在货币前或后添加符号：

// 左侧符号
var controller = new MoneyMaskedTextController(leftSymbol: 'R\$ ');
controller.updateValue(123.45);

print(controller.text); // 输出: R$ 123,45

// 右侧符号
var controller = new MoneyMaskedTextController(rightSymbol: ' US\$');
controller.updateValue(99.99);

print(controller.text); // 输出: 99,99 US$

// 两侧符号
var controller = new MoneyMaskedTextController(leftSymbol: 'to pay:', rightSymbol: ' US\$');
controller.updateValue(123.45);

print(controller.text); // 输出: to pay: 123,45 US$

监听变化

可以通过 afterChange 钩子监听掩码和原始值的变化：

var controller = new MoneyMaskedTextController();

controller.afterChange = (String masked, double raw) {
    print("$masked | $raw");
};

定义小数位数（v0.8.0+）

可以设置小数位数：

var controller = new MoneyMaskedTextController(precision: 3);
controller.updateValue(123.45);

print(controller.text); // 输出: 123,450

使用默认的 TextEditingController

MaskedTextController 和 MoneyMaskedTextController 都继承自 TextEditingController，因此可以使用所有默认的方法。

示例代码

以下是一个完整的示例代码，展示了如何结合 flutter_masked_text 实现身份证号输入框和货币输入框：

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

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

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

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

class _MyHomePageState extends State<MyHomePage> {
  final cpfController = MaskedTextController(mask: '000.000.000-00');
  final moneyController = MoneyMaskedTextController(
    decimalSeparator: '.',
    thousandSeparator: ',',
  );

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Flutter Masked Text'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextField(
              controller: cpfController,
              decoration: InputDecoration(
                labelText: '身份证号',
                hintText: '请输入身份证号',
              ),
            ),
            SizedBox(height: 20),
            TextField(
              controller: moneyController,
              keyboardType: TextInputType.number,
              decoration: InputDecoration(
                labelText: '金额',
                hintText: '请输入金额',
              ),
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: () {
                print("身份证号: ${cpfController.text}");
                print("金额: ${moneyController.text} (${moneyController.numberValue})");
              },
              child: Text('提交'),
            ),
          ],
        ),
      ),
    );
  }
}