chinese-number-format

Chinese Number Format

強大且輕量的中文數字轉換函式庫。支援繁體/簡體中文、金融大寫、貨幣格式化、日期轉換、數字縮寫等多種場景。

A powerful and lightweight library for converting numbers to Chinese numerals. Supports Traditional/Simplified Chinese, financial uppercase, currency formatting, date conversion, and number approximation.

✨ 特色 (Features)

• 🚀 全方位轉換：支援一般數字、金融大寫、貨幣、日期、年份、分數、百分比。
• 💡 智慧解析：支援將中文數字（包含口語縮寫如「一萬二」）反向解析為數值。
• 🌏 繁簡支援：完整支援 zh-TW (繁體) 與 zh-CN (簡體)，無論輸入或輸出。
• 🛡️ 安全設計：提供 ChineseNumberFormat 類別，可建立獨立設定的實例，完美支援 SSR 與多語系環境。
• ⚡ 高效輕量：零依賴 (Zero Dependency)。
• 🛠️ 通用支援：
  • TypeScript: 內建完整型別定義。
  • Node.js: 支援 CommonJS (require) 與 ES Modules (import)。
  • Browser: 支援原生 ES Modules，可直接在瀏覽器使用。
  • Frameworks: 完美支援 React, Vue, Next.js, Angular, Svelte 等。

📦 安裝 (Installation)

npm install chinese-number-format
# 或
yarn add chinese-number-format
# 或
pnpm add chinese-number-format

💻 使用方式 (Usage)

1. 基礎函式 (Functional API)

適合簡單、無狀態的使用場景。

import { numberToChinese, numberToCurrency } from 'chinese-number-format';

console.log(numberToChinese(12345));
// Output: "一萬二千三百四十五"

console.log(numberToCurrency(1234.5, { locale: 'zh-CN' }));
// Output: "壹仟贰佰叁拾肆元伍角"

2. 類別實例 (Class API) - 推薦 ⭐

適合需要統一設定、多語系切換或 SSR 環境。

import { ChineseNumberFormat } from 'chinese-number-format';

// 建立一個簡體中文的格式化器
const cnFormatter = new ChineseNumberFormat({ locale: 'zh-CN' });

console.log(cnFormatter.toChinese(123));
// Output: "一百二十三" (簡體)

console.log(cnFormatter.toCurrency(100));
// Output: "壹佰元整" (簡體)

// 建立一個繁體中文的格式化器
const twFormatter = new ChineseNumberFormat({ locale: 'zh-TW', finance: true });
console.log(twFormatter.toChinese(123));
// Output: "壹佰貳拾參"

3. 瀏覽器原生 (Browser Native)

可以直接透過 CDN 引入 (使用 ES Modules 版本)：

<script type="module">
    import { ChineseNumberFormat } from 'https://unpkg.com/chinese-number-format@^2.0.0/dist/esm/index.js';

    const formatter = new ChineseNumberFormat();
</script>

📚 API 文件 (API Documentation)

ChineseNumberFormat Class

獨立函式 (Functional Exports)

numberToChinese(num, options?)

將數字轉換為中文讀法。

numberToChinese(10010); // "一萬零一十"
numberToChinese(123, { locale: 'zh-CN' }); // "一百二十三"
numberToChinese(123, { finance: true }); // "壹佰貳拾參"
numberToChinese(10); // "十"
numberToChinese(10, { tenMin: false }); // "一十"
numberToChinese(2024, { units: false }); // "二零二四"

numberToCurrency(num, options?)

將數字轉換為中文貨幣格式（自動四捨五入至小數第二位）。

numberToCurrency(1000); // "壹仟元整"
numberToCurrency(1234.56, { currencyUnit: '圓' }); // "壹仟貳佰參拾肆圓伍角陸分"
numberToCurrency(500, { useIntUnit: false }); // "伍佰元"

chineseToNumber(str)

將中文數字字串解析為數值。

chineseToNumber('一萬二'); // 12000
chineseToNumber('參佰伍拾'); // 350
chineseToNumber('三點一四'); // 3.14

numberToChineseApproximate(num, options?)

將大數字轉換為簡短的近似值（如觀看次數）。

numberToChineseApproximate(12345); // "1.2萬"
numberToChineseApproximate(12345, { precision: 2 }); // "1.23萬"
numberToChineseApproximate(12345, { locale: 'zh-CN' }); // "1.2万"

numberToYear(year, locale?)

將年份數字轉換為中文讀法（逐字讀出）。

numberToYear(2024); // "二零二四"
numberToYear(2024, 'zh-CN'); // "二零二四" (簡體)

dateToChinese(date, options?)

將 Date 物件轉換為中文日期表示。

const d = new Date('2024-01-22T12:30:00');
dateToChinese(d); // "二零二四年一月二十二日"
dateToChinese(d, { locale: 'zh-CN', format: 'day' }); // "二零二四年一月二十二日 星期一"
dateToChinese(d, { format: 'time' }); // "二零二四年一月二十二日 十二點三十分"

numberToFraction(val, options?)

分數或百分比轉換。

numberToFraction('1/2'); // "二分之一"
numberToFraction('75%', { locale: 'zh-CN' }); // "百分之七十五"
numberToFraction(0.5, { type: 'percentage' }); // "百分之五十"

🤝 貢獻 (Contributing)

歡迎提交 Issue 或 Pull Request！

1. Fork 本專案
2. 建立您的 Feature 分支 (git checkout -b feature/AmazingFeature)
3. 提交變更 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

📄 授權 (License)

MIT © GaryLin