chinese-lunar-date

高精度旧暦ライブラリ — 干支 · 生肖 · 節気 · 祝日 · フォーマット · 多言語

天文アルゴリズムに基づく旧暦計算。中国・日本・韓国・ベトナムの4種類の旧暦バリアント、および簡体字中国語・繁體字中國語（台灣/香港）・日本語・한국어・Tiếng Việt の6言語に対応。

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.yearGanZhi    // "甲辰"
date.zodiac        // "辰"
date.zodiacEmoji   // "🐉"
date.formatFull()  // "甲辰辰年 五月初六"

本プロジェクトの独自性

• 自社開発軽量天文モジュール — VSOP87 惑星理論の切り詰めデータ（1e-7 閾値、220/2564 項のみ保持）に基づき、重い astronomia ライブラリを代替。IIFE サイズを ~350 KB から ~47 KB（gzip ~16 KB）に削減しつつ精度は無損
• 4種類の暦の統一アーキテクチャ — 中/日/韓/越の4種類の旧暦バリアントを CalendarConfig で設定駆動。異なる紀元とタイムゾーン履歴に同じアルゴリズムで対応
• 不変値オブジェクト + 純関数デュアルモード — 高レベル API（ChineseDate 等）は不変値オブジェクト、低レベルアルゴリズムはすべて純関数。2つのモードを独立して使用可能
• 繁體字中國語の地域差異化 — zh-TW と zh-HK は文字だけでなく祝日名も区別（例：「春節/農曆新年」）。単なる繁簡変換ではない

なぜ chinese-lunar-date を選ぶのか？

特徴

• 天文級精度 — VSOP87 惑星理論に基づく自社開発軽量天文モジュール
• 不変値オブジェクト — インスタンス生成後は変更不可。with() / addDays() は新インスタンスを返す
• 干支 — 年柱・月柱・日柱、六十干支序号と文字列の相互変換
• 生肖 — 12生肖の多言語名称 + Emoji
• 24節気 — 日単位の精度で節気を計算、中気と節気を区別
• 伝統祝日 — 13種の内蔵祝日、地域別自動フィルタ
• 多言語 / 多地域 — zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / vi-VN
• フォーマット — 5種内蔵 + カスタムパターン文字列
• 多暦法 — 中 / 日 / 韓 / 越の4種の暦設定（異なる紀元、異なるタイムゾーン履歴）
• TypeScript 優先 — 完全な型定義、ESM / CJS / IIFE 出力
• 軽量 — IIFE 圧縮後わずか ~47 KB（gzip ~16 KB）

インストール

npm install chinese-lunar-date

クイックスタート

日付の生成

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)
const date2 = ChineseDate.fromDate(new Date(2024, 5, 21))
const today = ChineseDate.today()
const date3 = ChineseDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })

プロパティの読み取り

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.cycle           // 78
date.year            // 34
date.month           // 5
date.leap            // false
date.day             // 6
date.gregorianYear   // 2024

date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"

date.zodiac          // "辰"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

フォーマット

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.formatFull('ja-JP')   // "甲辰辰年 五月初六"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.format('{Ygz}{Z}年 {Mname}{Dname}', 'ja-JP')  // "甲辰辰年 五月初六"

日付演算

const date = ChineseDate.fromGregorian(2024, 6, 21)

const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const firstDay = date.with({ day: 1 })
tomorrow.isAfter(date)     // true

変換

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.toGregorian()  // { year: 2024, month: 6, day: 21 }
date.toDate()       // Date object
date.toJSON()       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }

多暦法

import { ChineseDate, JapaneseDate, KoreanDate, VietnameseDate } from 'chinese-lunar-date'

const cn = ChineseDate.fromGregorian(2024, 6, 21)    // UTC+8
const jp = JapaneseDate.fromGregorian(2024, 6, 21)   // UTC+9
const kr = KoreanDate.fromGregorian(2024, 6, 21)     // UTC+8:30/9
const vn = VietnameseDate.fromGregorian(2024, 6, 21) // UTC+7/8

注意：タイムゾーンの違いにより、同じ西暦日付でも異なる暦では異なる旧暦日付に対応する場合があります。

24 節気

import { ChineseDate, solarTermName } from 'chinese-lunar-date'

ChineseDate.solarTerm(5, 2024)   // 清明
solarTermName(3, 'ja-JP')       // "啓蟄"

const date = ChineseDate.fromGregorian(2024, 4, 4)
date.getSolarTermName('ja-JP')  // "清明"

伝統祝日

import { ChineseDate } from 'chinese-lunar-date'

ChineseDate.festivalDate('spring', 2024)
ChineseDate.festivalsInYear(2024, 'ja-JP')

多言語 / 多地域

import { getLocale, availableLocales } from 'chinese-lunar-date'

const loc = getLocale('ja-JP')
loc.gan           // ["甲", "乙", "丙", ...]
loc.zhi           // ["子", "丑", "寅", ...]
loc.zodiac        // ["鼠", "牛", "虎", "兔", "竜", "蛇", "馬", "羊", "猿", "鶏", "犬", "猪"]
loc.monthNames(12, false)  // "師走"
loc.solarTerms    // ["立春", "雨水", "啓蟄", ...]

フォーマット Token

完全な Token リストは使用手引きを参照してください。

ブラウザ使用（IIFE）

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
  console.log(date.formatFull('ja-JP'))  // "甲辰辰年 五月初六"
</script>

ビルド

npm install chinese-lunar-date
npm run build        # ESM + CJS + IIFE をコンパイル
npm run build:types  # .d.ts 型宣言を生成
npm run test         # テストを実行

フィードバック・ご協力

ご利用中の問題、機能リクエスト、ビジネス協力などがございましたら、メールにてお気軽にお問い合わせください：

📧 gyfinjava@163.com

License

MIT License

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼)