패키지 상세v4.1.0

numeral

숫자를 아름다운 문자열로 포맷하기 위한 Dart 라이브러리. 숫자를 아름답고 읽기 쉬우며 짧은 문자열로 포맷합니다.

AndroidiOSWebmacOSWindowsLinux

pub.dev API 문서 소스 코드

30일 다운로드: 2.9천
좋아요: 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