简介

精准、易用的 Flutter 金额处理工具库，支持多方式初始化、高精度运算、格式化与序列化。

开始使用

import 'package:moneykit/moneykit.dart';

final money = Money.fromYuan(100);

核心特性说明

多方式初始化

// 1. 从分初始化（无精度损失，推荐）
final money1 = Money.fromCents(12345); // 123.45元

// 2. 从元初始化（支持int/double）
final money2 = Money.fromYuan(100); // 100元
final money3 = Money.fromYuan(99.99); // 99.99元
final money4 = Money.fromYuan(123.456); // 自动四舍五入为123.46元

// 3. 从字符串初始化（支持常见金额格式）
final money5 = Money.fromString("50"); // 50元
final money6 = Money.fromString("33.33"); // 33.33元
final money7 = Money.fromString("123.456"); // 123.46元

灵活的类型转换

 final money = Money.fromYuan(123.45);

// 转换为分（int）
int cents = money.toCents(); // 12345

// 转换为元（double）
double yuan = money.toYuan(); // 123.45

// 转换为元字符串
String yuanStr = money.toYuanString(); // "123.45"

// 转换为int（元为单位，向下取整）
int intYuan = money.toInt(); // 123

// 转换为JSON格式
Map<String, dynamic> json = money.toJson(); // {"amount": 123.45, "precisionMode": 0}

金额运算（Money 与 Money / 数值类型 绝对值、相反数、取模）

final a = Money.fromYuan(100); // 100元
final b = Money.fromYuan(50.50); // 50.5元

// Money ± Money
final sum = a + b; // 150.5元
final difference = a - b; // 49.5元

// Money × int/double（四舍五入到分）
final multiply1 = a * 2; // 200元
final multiply2 = b * 1.5; // 75.75元（50.5 × 1.5 = 75.75）
final multiply3 = a * 0.333; // 33.30元（100 × 0.333 = 33.3 → 3330分）

// Money ÷ int/double（四舍五入到分）
final divide1 = a / 2; // 50元
final divide2 = b / 3; // 16.83元（50.50 ÷ 3 ≈ 16.833... → 1683分）

final money = Money.fromYuan(-100.50);

// 相反数
final opposite = -money; // "100.5"

// 绝对值
final absMoney = money.abs(); // "100.5"

// 取模（100.50 元 % 3 → 1.50 元）
final mod = money.abs() % 3;// "1.50"

比较操作（== 和大小判断）

final x = Money.fromYuan(100);
final y = Money.fromCents(10000);
final z = Money.fromYuan(99.99);

// == 比较（基于分的精确比较）
print(x == y); // true（100元 == 100元）
print(x == z); // false

// 大小比较（支持 >、<、>=、<=）
print(x > z); // true
print(y >= x); // true
print(z < x); // true

// 比较方法
print(x.compareTo(z)); // 1（x > z）
print(z.compareTo(x)); // -1（z < x）
print(x.compareTo(y)); // 0（x == y）

// 辅助判断
print(x.isPositive); // true
print(z.isZero); // false
print(y.isNegative); // false

格式化与序列化

final money = Money.fromYuan(1234.56);

// 格式化输出（默认最多2位小数）
print(money.toYuanString()); // "1234.56"
print(money.toYuanString(maxDigits: 0, keepFixedDigits: false)); // "1235"（四舍五入）
print(money.toYuanString(maxDigits: 2, keepFixedDigits: false)); // "1234.56"（四舍五入）
print(money.toYuanString(maxDigits: 3, keepFixedDigits: true)); // "1234.560"（四舍五入）

// 序列化/反序列化
Map<String, dynamic> json = money.toJson(); // {amount: 1234.56, precisionMode: 0}
Money fromJson = Money.fromJson(json); // 1234.56元

精度模式配置

// 向下取整（123.456 元 → 123.45 元）
final money1 = Money.fromYuan(123.456, precisionMode: PrecisionMode.floor);
print(money1.toYuanString()); // "123.45"

// 向上取整（123.451 元 → 123.46 元）
final money2 = Money.fromYuan(123.451, precisionMode: PrecisionMode.ceil);
print(money2.toYuanString()); // "123.46"

空值与异常处理

// 空字符串 → 返回 0 元（默认）
final money1 = Money.fromString("");
print(money1.isZero); // true

// null 值 → 抛出异常（配置后）
try {
    final money2 = Money.fromYuan(null, nullValueHandling: NullValueHandling.throwError);
} catch (e) {
    print(e); // "yuan 不能为 null"
}

// 非法字符串 → 抛出格式化异常
try {
    final money3 = Money.fromString("abc123");
} catch (e) {
    print(e); // "无法解析金额字符串：abc123"
}