# chinese-lunar-date 使用手引き

> バージョン：1.0.0 | 最終更新：2025-06
> Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.
>
> 🌐 言語版：简体中文 · 繁體中文(台) · 繁體中文(港) · **日本語** · 한국어 · Tiếng Việt

---

## 目次

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

---

## 1. 概要

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

| 機能 | 説明 |
|------|------|
| **西暦 ↔ 旧暦変換** | VSOP87 惑星理論に基づく天文級精度 |
| **干支** | 年柱・月柱・日柱、六十干支序号と文字列の相互変換 |
| **生肖** | 12生肖の多言語名称 + Emoji |
| **24節気** | 日単位精度の節気計算、6言語対応 |
| **伝統祝日** | 13種の内蔵祝日、地域別自動フィルタ |
| **フォーマット** | 5種内蔵 + カスタムパターン（17種 Token） |
| **多暦法** | 中国 / 日本 / 韓国 / ベトナム 4種の旧暦バリアント |
| **多言語** | 簡体字中国語 / 繁體字中國語（台灣/香港）/ 日本語 / 한국어 / Tiếng Việt |

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

---

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

### 2.1 インストール

```bash
npm install chinese-lunar-date
```

### 2.2 ESM インポート

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

### 2.3 CJS インポート

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

### 2.4 ブラウザ IIFE インポート

```html
<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 で作成されており、完全な型定義を内蔵しています。

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

---

## 3. 核心概念

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

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

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

### 3.2 不変値オブジェクト

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

### 3.3 暦設定と地域差異

| 暦 | タイムゾーン | 紀元 | 設定定数 |
|---|---|---|---|
| 中国 | UTC+8 | 紀元前 2636 年 | `CHINESE_CONFIG` |
| 日本 | UTC+9 | 紀元前 2636 年 | `JAPANESE_CONFIG` |
| 韓国 | UTC+8:30 / UTC+9 | 紀元前 2333 年（檀君） | `KOREAN_CONFIG` |
| ベトナム | UTC+7 / UTC+8 | 紀元前 2636 年 | `VIETNAMESE_CONFIG` |

### 3.4 言語と地域コード

| コード | 言語 | 説明 |
|--------|------|------|
| `zh-CN` | 簡体字中国語 | 中国大陸 |
| `zh-TW` | 繁體字中國語 | 台灣 |
| `zh-HK` | 繁體字中國語 | 香港 |
| `ja-JP` | 日本語 | 日本 |
| `ko-KR` | 한국어 | 韓国 |
| `vi-VN` | Tiếng Việt | ベトナム |

---

## 4. 日付の生成

```ts
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 旧暦日付プロパティ

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

### 5.2 干支プロパティ

```ts
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 生肖プロパティ

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

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

### 5.4 西暦と曜日プロパティ

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

---

## 6. 日付変換

```ts
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. 日付演算

```ts
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 内蔵フォーマットメソッド

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

### 8.2 カスタムパターン

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

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

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

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

| 定数 | フォーマットパターン | 出力例 |
|------|-------------------|--------|
| `LUNAR_FULL` | `{Ygz}{Z}年 {Mname}{Dname}` | 甲辰辰年 九月初九 |
| `LUNAR_GANZHI` | `{Ygz}年 {Mname}{Dname}` | 甲辰年 九月初九 |
| `GREGORIAN_ISO` | `{GY}-{GM0}-{GD0}` | 2025-10-11 |

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

#### 旧暦関連

| Token | 出力 | 例 |
|-------|------|-----|
| `{CY}` | 周期番号 | `78` |
| `{Y}` | 周期内年番号 | `34` |
| `{Ygz}` | 年干支 | `甲辰` |
| `{Z}` | 生肖 | `辰` |
| `{M}` | 月数字 | `5` |
| `{Mname}` | 月名 | `五月` |
| `{L}` | 閏月マーク | `閏` |
| `{D}` | 日数字 | `6` |
| `{Dname}` | 日名 | `初六` |

#### 西暦関連

| Token | 出力 | 例 |
|-------|------|-----|
| `{GY}` | 西暦年 | `2024` |
| `{GYcn}` | 西暦年中国語（〇版） | `二〇二四` |
| `{GM}` | 西暦月 | `6` |
| `{GD}` | 西暦日 | `21` |

#### 曜日関連

| Token | 出力 | 例 |
|-------|------|-----|
| `{W}` | 曜日数字 (0-6) | `5` |
| `{Wname}` | 曜日フル | `金曜日` |
| `{Wshort}` | 曜日略称 | `金` |

### 8.5 パース

```ts
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. 干支

```ts
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. 生肖

```ts
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 節気日付の取得

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

**節気番号対照表：**

| 番号 | 名称 | 番号 | 名称 | 番号 | 名称 | 番号 | 名称 |
|------|------|------|------|------|------|------|------|
| 1 | 立春 | 7 | 立夏 | 13 | 立秋 | 19 | 立冬 |
| 2 | 雨水 | 8 | 小満 | 14 | 処暑 | 20 | 小雪 |
| 3 | 啓蟄 | 9 | 芒種 | 15 | 白露 | 21 | 大雪 |
| 4 | 春分 | 10 | 夏至 | 16 | 秋分 | 22 | 冬至 |
| 5 | 清明 | 11 | 小暑 | 17 | 寒露 | 23 | 小寒 |
| 6 | 穀雨 | 12 | 大暑 | 18 | 霜降 | 24 | 大寒 |

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

### 11.2 節気名称

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

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

### 11.3 特定日の節気判定

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

### 11.4 年間節気

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

---

## 12. 伝統祝日

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

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

---

## 13. 多暦法

```ts
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. 多言語 / 多地域

```ts
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

```ts
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. 中国語数字

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

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

---

## 17. 型リファレンス

```ts
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 形式の使い方は？

```html
<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）