chinese-lunar-date 使用手引き

バージョン：1.0.0 | 最終更新：2025-06 Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.

目次

• 1. 概要
• 2. インストールとインポート
• 3. 核心概念
• 4. 日付の生成
• 5. プロパティの読み取り
• 6. 日付変換
• 7. 日付演算
• 8. フォーマット
• 9. 干支
• 10. 生肖
• 11. 24 節気
• 12. 伝統祝日
• 13. 多暦法
• 14. 多言語 / 多地域
• 15. 低レベル API
• 16. 中国語数字
• 17. 型リファレンス
• 18. よくある質問（FAQ）
• 19. アーキテクチャと設計原則
• 20. 更新履歴

1. 概要

chinese-lunar-date は天文アルゴリズムに基づく高精度旧暦ライブラリです。

出力形式： ESM / CJS / IIFE、IIFE 圧縮後わずか ~47 KB（gzip ~16 KB）。

2. インストールとインポート

2.1 インストール

npm install chinese-lunar-date

2.2 ESM インポート

import { ChineseDate, formatGanZhi, PATTERNS } from 'chinese-lunar-date'

2.3 CJS インポート

const { ChineseDate, formatGanZhi, PATTERNS } = require('chinese-lunar-date')

2.4 ブラウザ 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'))  // "甲辰辰年 五月初六"

  const lunar = ChineseDate.gregorianToLunar(ChineseDate.CHINESE_CONFIG, 2024, 6, 21)
</script>

2.5 TypeScript サポート

ネイティブ TypeScript で作成されており、完全な型定義を内蔵しています。

import type { LunarDateValue, GanZhiPair, LocaleCode } from 'chinese-lunar-date'

3. 核心概念

3.1 六十干支周期（cycle / year）

• cycle — 周期番号（1始まり）、何番目の60年周期かを示す
• year — 周期内年番号（1-60）、干支に直接対応
  • year=1 → 甲子年、year=34 → 丁酉年

gregorianYear = epochYear + (cycle - 1) * 60 + (year - 1)

3.2 不変値オブジェクト

すべての日付インスタンスは不変です。変更操作は新しいインスタンスを返します。

3.3 暦設定と地域差異

3.4 言語と地域コード

4. 日付の生成

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 d1 = ChineseDate.fromISO('2024-06-21')
const date4 = ChineseDate.fromTimestamp(Date.now())
const date5 = ChineseDate.fromJDE(2460482.5)

5. プロパティの読み取り

5.1 旧暦日付プロパティ

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

5.2 干支プロパティ

date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"
date.ganZhiInfo      // { year: {gan:0,zhi:4}, month: {gan:6,zhi:6}, day: {gan:0,zhi:2} }

干支インデックス：

• gan（天干）：0=甲, 1=乙, 2=丙, 3=丁, 4=戊, 5=己, 6=庚, 7=辛, 8=壬, 9=癸
• zhi（地支）：0=子, 1=丑, 2=寅, 3=卯, 4=辰, 5=巳, 6=午, 7=未, 8=申, 9=酉, 10=戌, 11=亥

5.3 生肖プロパティ

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

date.getZodiac('ja-JP')  // "辰"
date.getZodiac('ko-KR')  // "용"
date.getZodiac('vi-VN')  // "Thìn"

5.4 西暦と曜日プロパティ

date.weekday           // 5
date.weekdayName       // "金曜日"（ja-JP）
date.weekdayShort      // "金"
date.gregorianYearCn   // "二〇二四"

6. 日付変換

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

7. 日付演算

const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const nextMonth = date.addMonths(1)
const lastYear = date.addYears(-1)
const firstDay = date.with({ day: 1 })

a.equals(b)      // false
a.isAfter(b)     // true
a.diffDays(b)    // 3
date.daysInMonth()  // 29 または 30

8. フォーマット

8.1 内蔵フォーマットメソッド

date.formatFull('ja-JP')   // "甲辰辰年 五月初六"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.formatISO()           // "78-34-5-0-6"

8.2 カスタムパターン

date.format('{Ygz}{Z}年 {Mname}{Dname}', 'ja-JP')   // "甲辰辰年 五月初六"
date.format('{GY}年{GM}月{GD}日', 'ja-JP')           // "2024年6月21日"

8.3 プリセットフォーマット定数 PATTERNS

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

date.format(PATTERNS.LUNAR_FULL)               // "甲辰辰年 九月初九"
date.format(PATTERNS.GREGORIAN_CN_FULL)        // "二〇二五年十月十一日"

8.4 フォーマット Token 完全リファレンス

旧暦関連

西暦関連

曜日関連

8.5 パース

import { parseCompact, parseISO, parseGregorian } from 'chinese-lunar-date'

parseCompact('78/34/5/0/6')    // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseISO('78-34-5-0-6')        // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseGregorian('2025-10-11')   // { year: 2025, month: 10, day: 11 }

9. 干支

import { yearGanZhi, formatGanZhi, parseGanZhi, allGanZhi, ganZhiToCycleIndex } from 'chinese-lunar-date'

yearGanZhi(value)   // { gan: 3, zhi: 9 }  → 丁酉
formatGanZhi({ gan: 3, zhi: 9 })  // "丁酉"
parseGanZhi('甲子')  // { gan: 0, zhi: 0 }
allGanZhi()  // ["甲子", "乙丑", ..., "癸亥"]

10. 生肖

import { zodiac, zodiacEmoji, zodiacFromGregorianYear, zodiacList } from 'chinese-lunar-date'

zodiac(value, 'ja-JP')  // "鶏"
zodiacEmoji(value)       // "🐔"
zodiacFromGregorianYear(2024, 'ja-JP')  // "辰"
zodiacList('ja-JP')  // ["鼠", "牛", "虎", "兔", "竜", "蛇", "馬", "羊", "猿", "鶏", "犬", "猪"]

11. 24 節気

11.1 節気日付の取得

ChineseDate.solarTerm(1, 2024)   // 立春
ChineseDate.solarTerm(5, 2024)   // 清明
ChineseDate.qingming(2024)       // 同上

節気番号対照表：

奇数番号は節気（節）、偶数番号は中気（気）。

11.2 節気名称

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

solarTermName(3, 'ja-JP')  // "啓蟄"
solarTermNames('ja-JP')    // ["立春", "雨水", "啓蟄", ...]

11.3 特定日の節気判定

date.getSolarTermName('ja-JP')  // "清明" または null

11.4 年間節気

ChineseDate.solarTermsInYear(2024, 'ja-JP')
// [{ index: 1, name: "立春", date: {...}, jde: ... }, ...]

12. 伝統祝日

ChineseDate.festivalDate('spring', 2024)       // 春節
ChineseDate.festivalDate('mid-autumn', 2024)   // 中秋節

date.getFestivals('ja-JP')
ChineseDate.festivalsInYear(2024, 'ja-JP')

13. 多暦法

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

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

14. 多言語 / 多地域

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

availableLocales()  // ["zh-CN", "zh-TW", "zh-HK", "ja-JP", "ko-KR", "vi-VN"]

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

15. 低レベル API

import {
  gregorianToLunar, lunarToGregorian,
  CHINESE_CONFIG, JAPANESE_CONFIG, KOREAN_CONFIG, VIETNAMESE_CONFIG
} from 'chinese-lunar-date'

const lunar = gregorianToLunar(JAPANESE_CONFIG, 2024, 6, 21)
const greg = lunarToGregorian(JAPANESE_CONFIG, lunar)

16. 中国語数字

import { toChineseYear, toChineseNumber, getWeekdayName } from 'chinese-lunar-date'

toChineseYear(2025, 'upper')  // "二〇二五"
toChineseNumber(21, 'upper')  // "二十一"
getWeekdayName(6, 'ja-JP')    // "土曜日"

17. 型リファレンス

interface LunarDateValue {
  cycle: number
  year: number
  month: number
  leap: boolean
  day: number
}

interface GregorianDate {
  year: number
  month: number
  day: number
}

type CalendarType = 'chinese' | 'korean' | 'japanese' | 'vietnamese'

interface GanZhiPair {
  gan: number
  zhi: number
}

type LocaleCode = 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'vi-VN'

18. よくある質問（FAQ）

Q: `cycle` と `year` の違いは？

cycle は何番目の60年周期か、year は周期内の年番号（1-60）です。ほとんどの場合、date.gregorianYear を使えば十分です。

Q: 同じ西暦日付で `ChineseDate` と `JapaneseDate` の旧暦が異なるのはなぜ？

タイムゾーンの違いによるものです。新月が UTC+8 の深夜付近に発生すると、日本（UTC+9）では既に翌日に入っている場合があります。

Q: IIFE 形式の使い方は？

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
</script>

Q: 精度は？

VSOP87 惑星理論に基づく天文アルゴリズムを使用しており、天文台が発表する暦表と同等の精度（誤差は秒レベル）です。

フィードバック・ご協力

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

📧 gyfinjava@163.com

19. アーキテクチャと設計原則

• 不変値オブジェクト — インスタンス生成後は変更不可
• 純関数コア — 低レベルアルゴリズムはすべて純関数
• 設定駆動 — 異なる暦を CalendarConfig で区別
• キャッシュ最適化 — 天文計算結果を自動キャッシュ
• TypeScript 優先 — ネイティブ TypeScript、完全な型定義

20. 更新履歴

1.0.0

• 初回リリース
• 中国 / 日本 / 韓国 / ベトナム 4種の旧暦バリアント対応
• 6言語 / 地域対応
• 干支（年月日三柱）
• 生肖（多言語 + Emoji）
• 24節気計算
• 13種の伝統祝日
• フォーマット（5種内蔵 + カスタムパターン）
• 自社開発軽量天文モジュール（VSOP87 切り詰めデータ）
• IIFE 圧縮後 ~47 KB（gzip ~16 KB）