@libs-ui/pipes-format-number-short

Rút gọn số lớn: 2.380.000.000 → 2,38 Tỷ · 450.000.000 → 450 Triệu. Nhãn bậc khai sẵn cho VI/EN, số chữ số thập phân và ngưỡng rút gọn cấu hình được.

Giới thiệu

Lib gồm một hàm và một pipe là vỏ mỏng của hàm đó:

| Dùng ở đâu | Gọi gì | | --- | --- | | Template | LibsUiPipesFormatNumberShortPipe | | TypeScript — computed, service, config bảng/dropdown | viewDataNumberShortByLanguage |

Pipe chỉ gọi lại hàm, không tự tính gì. Nhờ đó template và TypeScript luôn cho ra cùng một kết quả, và đổi cách rút gọn chỉ phải sửa MỘT chỗ.

Nhãn bậc (Nghìn · Triệu · Tỷ · Nghìn tỷ cho VI, K · M · B · T cho EN) khai sẵn trong lib — nơi dùng không phải tự khai key i18n cho bốn bậc này.

Tính năng

• ✅ Bốn bậc rút gọn: nghìn · triệu · tỷ · nghìn tỷ
• ✅ Nhãn bậc khai sẵn cho vi và en; ngôn ngữ lạ lùi về en
• ✅ Trả về chuỗi đã ghép hoặc object đủ từng phần — chọn bằng tham số
• ✅ Số chữ số thập phân cấu hình qua parseFixed (mặc định 2, bỏ số 0 vô nghĩa)
• ✅ Ngưỡng bắt đầu rút gọn cấu hình qua minThreshold (mặc định 1000)
• ✅ Nhãn bậc riêng của sản phẩm qua scaleLabels, hoặc dùng key i18n của mình
• ✅ Bộ format số thay thế được qua formatNumber
• ✅ Giữ dấu âm — -450.000.000 → -450 Triệu
• ✅ Không throw với null · undefined · NaN · Infinity · chuỗi không phải số
• ✅ Standalone pipe, không phụ thuộc @libs-ui/utils

Khi nào sử dụng

• Cột bảng chật chỗ, số tiền dài làm vỡ layout — cần 24,5 Tỷ thay cho 24.500.000.000
• Thẻ tổng quan (dashboard, KPI) cần con số đọc nhanh thay vì đọc chính xác từng đồng
• Cho người dùng tự chọn giữa hiện đầy đủ và hiện rút gọn trên cùng một trường

Cần con số chính xác từng đơn vị (hoá đơn, đối soát, xuất báo cáo) thì dùng @libs-ui/pipes-format-number, đừng dùng pipe này.

Cài đặt

npm install @libs-ui/pipes-format-number-short

Dùng trên template

import { LibsUiPipesFormatNumberShortPipe } from '@libs-ui/pipes-format-number-short';

@Component({
  imports: [LibsUiPipesFormatNumberShortPipe],
  // ...
})
export class MyComponent {}

<!-- mặc định: chuỗi đã ghép -->
{{ item.amount | LibsUiPipesFormatNumberShortPipe }}
<!-- → 2,38 Tỷ -->

Cần tô màu / bố cục riêng cho phần số và phần bậc thì lấy dạng object:

@let ngan = item.amount | LibsUiPipesFormatNumberShortPipe: 'object';

<span class="libs-ui-font-h3s">{{ ngan.numberText }}</span>
@if (ngan.scaleLabel) {
  <span class="libs-ui-font-h5r text-[#6a7383]">{{ ngan.scaleLabel }}</span>
}

Dùng trong TypeScript

import { viewDataNumberShortByLanguage } from '@libs-ui/pipes-format-number-short';

protected tongTien = computed(() => viewDataNumberShortByLanguage(this.amount()).text);

// config bảng của libs-ui — `parseValue` chạy ở TS, không qua template
parseValue: (row) => viewDataNumberShortByLanguage(row.amount, { parseFixed: 1 }).text,

Kết quả với dữ liệu thật

Locale VI, parseFixed mặc định 2:

| Giá trị vào | number | scale | text | | ---------------- | -------- | ---------- | ------------ | | 999 | 999 | '' | 999 | | 1.000 | 1 | thousand | 1 Nghìn | | 5.000 | 5 | thousand | 5 Nghìn | | 450.000.000 | 450 | million | 450 Triệu | | 2.380.000.000 | 2.38 | billion | 2,38 Tỷ | | 24.500.000.000 | 24.5 | billion | 24,5 Tỷ | | 1.234.567.890 | 1.23 | billion | 1,23 Tỷ | | -450.000.000 | -450 | million | -450 Triệu | | 3.200.000.000.000 | 3.2 | trillion | 3,2 Nghìn tỷ |

Số 0 vô nghĩa bị bỏ, nên 450.000.000 ra 450 chứ không phải 450,00.

Tuỳ chọn

parseFixed — số chữ số thập phân

| parseFixed | 1.234.567.890 ra | | ------------ | ------------------ | | 0 | 1 Tỷ | | 1 | 1,2 Tỷ | | 2 (mặc định) | 1,23 Tỷ | | 3 | 1,235 Tỷ |

minThreshold — ngưỡng bắt đầu rút gọn

Mặc định gọn từ bậc nghìn. Muốn dưới 1 triệu vẫn hiện số đầy đủ:

| minThreshold | 500.000 ra | 1.500.000 ra | | -------------- | ------------ | -------------- | | 1000 (mặc định) | 500 Nghìn | 1,5 Triệu | | 1000000 | 500.000 | 1,5 Triệu |

{{ item.amount | LibsUiPipesFormatNumberShortPipe: 'text' : { minThreshold: 1000000 } }}

lang — ngôn ngữ nhãn bậc

| lang | 2.380.000.000 ra | | ------ | ------------------ | | 'vi' (mặc định) | 2,38 Tỷ | | 'en' | 2.38 B |

Ngôn ngữ chưa có bảng nhãn thì lùi về en.

scaleLabels — nhãn bậc riêng của sản phẩm

viewDataNumberShortByLanguage(2_380_000_000, { scaleLabels: { billion: 'tỉ' } }).text;
// → '2,38 tỉ'

Muốn tự quản chữ qua file ngôn ngữ của sản phẩm thì lấy key sẵn có rồi truyền chữ đã dịch vào:

import { libsUiFormatNumberShortI18nKeys } from '@libs-ui/pipes-format-number-short';

// { thousand: 'i18n_libs_ui_number_short_thousand', million: 'i18n_libs_ui_number_short_million', … }

formatNumber — bộ format số thay thế

Lib cố tình không phụ thuộc @libs-ui/utils; mặc định dùng Intl.NumberFormat. Cần khớp tuyệt đối cách format số của phần còn lại trong sản phẩm:

import { viewDataNumberByLanguage } from '@libs-ui/utils';

viewDataNumberShortByLanguage(value, {
  formatNumber: (num, fixed, lang) => `${viewDataNumberByLanguage(num, true, fixed, true, false, lang)}`,
});

API

// Hàm — điểm vào duy nhất
viewDataNumberShortByLanguage(
  value: number | string,
  options?: T_libsUiFormatNumberShort_options,
): T_libsUiFormatNumberShort_result

// Pipe — vỏ mỏng của hàm trên
transform(
  value: number | string,
  output?: 'text' | 'object',           // mặc định 'text'
  options?: T_libsUiFormatNumberShort_options,
): string | T_libsUiFormatNumberShort_result

T_libsUiFormatNumberShort_options

| Trường | Kiểu | Mặc định | Ý nghĩa | | --- | --- | --- | --- | | parseFixed | number | 2 | Số chữ số thập phân sau khi chia bậc | | minThreshold | number | 1_000 | Chỉ rút gọn khi trị tuyệt đối đạt ngưỡng này | | lang | string | 'vi' | Ngôn ngữ nhãn bậc và dấu phân cách | | scaleLabels | Partial<Record<scale, string>> | — | Nhãn bậc riêng, ghi đè nhãn sẵn có | | formatNumber | (value, parseFixed, lang) => string | Intl.NumberFormat | Bộ format phần số |

T_libsUiFormatNumberShort_result

| Trường | Kiểu | Ví dụ với 2.380.000.000 | | --- | --- | --- | | number | number | 2.38 — số thô, chưa có dấu phân cách | | numberText | string | '2,38' — số đã format theo locale | | scale | E_libsUiFormatNumberShort_scale_string | 'billion' | | scaleLabel | string | 'Tỷ' — nhãn đã dịch | | text | string | '2,38 Tỷ' — chuỗi hoàn chỉnh |

Export khác

| Tên | Dùng để | | --- | --- | | libsUiFormatNumberShortScales() | bảng bậc + ngưỡng, khi cần dựng chú thích | | libsUiFormatNumberShortLabels() | bảng nhãn sẵn có theo ngôn ngữ | | libsUiFormatNumberShortI18nKeys() | key i18n của bốn bậc, khi sản phẩm tự quản chữ | | E_libsUiFormatNumberShort_scale_string | so sánh bậc trong code | | E_libsUiFormatNumberShort_output_string | chọn dạng trả về của pipe |

Lưu ý

• Số dưới ngưỡng trả về giá trị gốc kèm scale/scaleLabel rỗng — nơi dùng vẽ được bằng cùng một khối template, không cần nhánh riêng.
• null · undefined · NaN · Infinity · chuỗi không phải số đều trả về 0, không throw.
• parseFixed âm được coi như 0.