套件詳情v4.1.0

numeral

一個用於將數字格式化為美觀字串的 Dart 庫，將數字格式化為美觀、易讀且簡短的字串。

AndroidiOSWebmacOSWindowsLinux

pub.dev API 文件原始碼

近 30 天下載: 2920
喜歡數: 78
Pub 分數: 160

安裝套件

flutter pub add numeral

套件介紹

根據套件公開資料產生的選型評估，僅供參考。

Numeral 是一個 Dart 庫，專門用於將數字格式化為乾淨、易讀且簡潔的字串。它能將大型或複雜的數字轉換為使用者友好的表示方式，例如將 1000000 轉換為 '1M'，或將 1234 轉換為 '1.23K'。非常適合以優雅的方式顯示統計資料、財務數據或社群媒體指標。此庫支援多種格式，並與所有主要平台（包括 Android、iOS、Web、macOS、Windows 和 Linux）相容。它在不犧牲準確性或效能的情況下簡化了數字的呈現。

適用情境

顯示大型統計資訊
格式化財務數值
展示社交媒體計數
提高使用者介面的可讀性
簡化數字資料的顯示
建立緊湊的數字標籤

主要特色

將數字轉換為縮寫形式
支援國際格式化
輕便且快速
跨平台相容性
與 Flutter 的輕鬆整合
可自定義的輸出格式

適合對象

數據可視化應用
社群媒體儀表板
財務追蹤工具
行動和網路應用
UI/UX 設計師與數字打交道
需要乾淨數字格式化的開發人員

使用建議

僅限數字格式化
不直接處理貨幣符號
需要手動處理區域設定相關規則
不支援負數格式化
不適用於數學運算
依賴外部GitHub倉庫進行更新

原始 README

以下為關聯原始碼儲存庫的 README 原文快照，最新內容請造訪原始碼儲存庫。

Numeral

Composable number formatting and parsing for Dart.

Numeral turns application numbers into display strings and back again with reusable codecs for decimals, compact values, percentages, byte sizes, currency text, and locale-aware numerals. Create a codec once, keep it in your app utilities, and use the same object for both formatting and parsing.

Installation

Add Numeral to your pubspec.yaml:

dependencies:
  numeral: ^4.1.0

Usage

Import the codec entrypoint for built-in number display codecs:

import 'package:numeral/codec.dart';
import 'package:numeral/en.dart' as en;

package:numeral/numeral.dart contains the core protocols and shared models: NumeralCodec, NumeralLanguage, NumeralUnitSet, NumeralUnit, and Rounding.

Create reusable codec instances:

final fileSize = BytesCodec.binary(maxFractionDigits: 1);
final compact = en.compact(maxFractionDigits: 1);
final ratio = PercentCodec(maxFractionDigits: 2);

fileSize.format(1536); // 1.5 KiB
fileSize.parse('1.5 KiB'); // 1536
fileSize.encode(1536); // 1.5 KiB
fileSize.decode('1.5 KiB'); // 1536

compact.format(12345); // 12.3K
compact.parse('12.3K'); // 12300

ratio.format(0.1234); // 12.34%
ratio.parse('12.34%'); // 0.1234

For one-off formatting, import the extension entry:

import 'package:numeral/extension.dart';
import 'package:numeral/zh.dart' as zh;

12345.compact(maxFractionDigits: 1); // 12.3K
1536.bytes(binary: true, maxFractionDigits: 1); // 1.5 KiB
1000000.currency('¥', style: zh.compact(maxFractionDigits: 0)); // ¥100万
1000000.formatWith(zh.cardinal()); // 一百万

Codecs

Each codec extends Codec<T, String> from dart:convert.

format and parse are readable aliases for encode and decode, so both styles work:

final bytes = BytesCodec.binary();

bytes.format(1024); // 1 KiB
bytes.encode(1024); // 1 KiB
bytes.parse('1 KiB'); // 1024
bytes.decode('1 KiB'); // 1024

Unit-style codecs such as compact numbers, percentages, byte sizes, and currency can replace their internal number style with another codec. By default, they use a DecimalCodec built from their decimal options.

Decimal

final amount = DecimalCodec(
  minFractionDigits: 2,
  maxFractionDigits: 2,
);

amount.format(1234567.8); // 1,234,567.80
amount.parse('1,234,567.80'); // 1234567.8

Compact

import 'package:numeral/en.dart' as en;

final compact = en.compact(maxFractionDigits: 1);

compact.format(1234); // 1.2K
compact.format(999999); // 1M
compact.parse('3 million'); // 3000000

Custom unit sets use the same NumeralUnit model as byte codecs:

import 'package:numeral/codec.dart';
import 'package:numeral/numeral.dart';

final custom = CompactCodec(
  unitSet: NumeralUnitSet([
    NumeralUnit(1, ''),
    NumeralUnit(1000, 'K', aliases: ['k']),
    NumeralUnit(1000000, 'M', aliases: ['m']),
  ]),
);

custom.format(1234567); // 1.23M
custom.parse('3.5M'); // 3500000

Custom unit scales must be finite, positive, and strictly ascending. Parser tokens are matched case-insensitively, so symbols and aliases should be unique after lowercasing.

Percent

final percent = PercentCodec(maxFractionDigits: 1);

percent.format(0.1234); // 12.3%
percent.parse('12.3%'); // 0.123

Bytes

final decimalBytes = BytesCodec();
final binaryBytes = BytesCodec.binary(maxFractionDigits: 1);

decimalBytes.format(1500); // 1.5 KB
decimalBytes.parse('1.5 MB'); // 1500000

binaryBytes.format(1536); // 1.5 KiB
binaryBytes.parse('1.5 KiB'); // 1536

Currency

Currency formatting is display-oriented. Use a decimal or money type for financial calculation, then use Numeral to render and parse strings.

import 'package:numeral/zh.dart' as zh;

final usd = CurrencyCodec(r'$');
final cny = CurrencyCodec(
  '¥',
  style: zh.compact(maxFractionDigits: 0),
);

usd.format(1234.5); // $1,234.50
usd.parse(r'$1,234.50'); // 1234.5
cny.format(1000000); // ¥100万
cny.parse('¥100万'); // 1000000

Parsing

Every codec has parse and tryParse:

final bytes = BytesCodec.binary();

bytes.parse('1 KiB'); // 1024
bytes.tryParse('bad input'); // null

parse returns the natural numeric type for the codec:

DecimalCodec.parse(...) returns num.
CompactCodec.parse(...) returns num.
PercentCodec.parse(...) returns double.
BytesCodec.parse(...) returns int.
CurrencyCodec.parse(...) returns num.

Language Paths

Built-in language packs live behind separate import paths. This keeps the core API small while allowing locale-specific rules to include code, not only unit data.

import 'package:numeral/zh.dart' as zh;

final compact = zh.compact(maxFractionDigits: 2);
final words = zh.cardinal();
final year = zh.year();
final financial = zh.financial();
final rmb = zh.rmb();

compact.format(1234567); // 123.46万
words.format(1000000); // 一百万
words.format(2000000); // 二百万
words.parse('一百万'); // 1000000
words.parse('两百万'); // 2000000
words.parse('一万零十'); // 10010
words.parse('一万二'); // 12000
year.format(2026); // 二〇二六
financial.format(1000000); // 壹佰万
rmb.format(1000000); // 人民币壹佰万元整
rmb.format(1234567.89); // 人民币壹佰贰拾叁万肆仟伍佰陆拾柒元捌角玖分

Traditional Chinese is available from its own language path:

import 'package:numeral/zh_hant.dart' as zh_hant;

final compact = zh_hant.compact(maxFractionDigits: 2);
final words = zh_hant.cardinal();
final year = zh_hant.year();
final financial = zh_hant.financial();

compact.format(1234567); // 123.46萬
compact.parse('2億'); // 200000000
words.format(1000000); // 一百萬
words.parse('兩百萬'); // 2000000
words.parse('一萬零十'); // 10010
year.format(2026); // 二〇二六
financial.format(1000000); // 壹佰萬

French is available from its own language path:

import 'package:numeral/fr.dart' as fr;

final compact = fr.compact(maxFractionDigits: 1);
final words = fr.cardinal();
final year = fr.year();

compact.format(1500000); // 1,5 M
compact.parse('1,5 M'); // 1500000
words.format(2026); // deux-mille-vingt-six
words.parse('soixante-et-onze'); // 71
year.format(2026); // deux-mille-vingt-six

Korean is available from its own language path:

import 'package:numeral/ko.dart' as ko;

final compact = ko.compact(maxFractionDigits: 2);
final words = ko.cardinal();
final year = ko.year();

compact.format(12345); // 1.23만
compact.parse('2억'); // 200000000
words.format(1000000); // 백만
words.format(123456789); // 일억이천삼백사십오만육천칠백팔십구
words.parse('일억 이천만'); // 120000000
year.format(2026); // 이천이십육

Japanese is available from its own language path:

import 'package:numeral/ja.dart' as ja;

final compact = ja.compact(maxFractionDigits: 2);
final words = ja.cardinal();
final year = ja.year();

compact.format(1234567); // 123.46万
compact.parse('2億'); // 200000000
words.format(1000000); // 百万
words.format(10000001); // 一千万一
words.parse('一万〇一'); // 10001
words.parse('千五百万'); // 15000000
year.format(2026); // 二〇二六

Spanish is available from its own language path:

import 'package:numeral/es.dart' as es;

final compact = es.compact(maxFractionDigits: 2);
final words = es.cardinal();

compact.format(1500000); // 1,5 M
compact.parse('2 millones'); // 2000000
words.format(1000000); // un millón
words.format(1000000000); // mil millones
words.format(1000000000000); // un billón
words.parse('veintiún mil'); // 21000