パッケージ詳細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 などの主要プラットフォームすべてで互換性があります。正確性やパフォーマンスを損なうことなく、数値の表示を簡素化します。

用途

大規模な統計情報を表示する
財務値の書式設定
ソーシャルメディアのカウントを提示する
UIの読みやすさの向上
数値データ表示の簡素化
コンパクトな数値ラベルの作成

主な機能

数値を省略形に変換します
国際的なフォーマットをサポートしています
軽量で高速
クロスプラットフォーム互換性
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