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('ko-KR'))  // "갑진용년 5월초육"

  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）, 간지에 직접 대응

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} }

5.3 띠 속성

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

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

5.4 양력 및 요일 속성

date.weekday           // 5
date.weekdayName       // "금요일"（ko-KR）
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('ko-KR')   // "갑진용년 5월초육"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.formatISO()           // "78-34-5-0-6"

8.2 커스텀 패턴

date.format('{Ygz}{Z}년 {Mname}{Dname}', 'ko-KR')   // "갑진용년 5월초육"
date.format('{GY}년{GM}월{GD}일', 'ko-KR')           // "2024년6월21일"

8.3 프리셋 포맷 상수 PATTERNS

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

date.format(PATTERNS.LUNAR_FULL)               // "갑진용년 9월초구"
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, 'ko-KR')  // "닭"
zodiacEmoji(value)       // "🐔"
zodiacFromGregorianYear(2024, 'ko-KR')  // "용"
zodiacList('ko-KR')  // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]

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, 'ko-KR')  // "경칩"
solarTermNames('ko-KR')    // ["입춘", "우수", "경칩", ...]

11.3 특정일의 절기 판정

date.getSolarTermName('ko-KR')  // "청명" 또는 null

11.4 연간 절기

ChineseDate.solarTermsInYear(2024, 'ko-KR')
// [{ index: 1, name: "입춘", date: {...}, jde: ... }, ...]

12. 전통 명절

ChineseDate.festivalDate('spring', 2024)       // 춘절
ChineseDate.festivalDate('mid-autumn', 2024)   // 중추절

date.getFestivals('ko-KR')
ChineseDate.festivalsInYear(2024, 'ko-KR')

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

참고: 시간대 차이로 인해 같은 양력 날짜가 다른 역법에서 다른 음력 날짜에 해당할 수 있습니다.

한국 역법의 특수 기원

한국 역법은 단군기원（기원전 2333년）을 사용하므로 cycle과 year가 중국 역법과 다릅니다. 단 gregorianYear는 동일합니다.

14. 다국어 / 다지역

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

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

const loc = getLocale('ko-KR')
loc.zodiac        // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]
loc.solarTerms    // ["입춘", "우수", "경칩", ...]

15. 저수준 API

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

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

16. 중국어 숫자

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

toChineseYear(2025, 'upper')  // "二〇二五"
toChineseNumber(21, 'upper')  // "二十一"
getWeekdayName(6, 'ko-KR')    // "토요일"

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: 한국 음력의 `cycle`이 중국과 다른 이유는？

한국 역법은 단군기원（기원전 2333년）을 사용하여 중국 기원보다 297년 늦기 때문입니다. 단 gregorianYear은 동일합니다.

Q: IIFE 형식 사용법은？

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

피드백 및 협력

사용 중 문제가 발생하거나 기능 제안, 비즈니스 협력 등이 필요하신 경우 이메일로 연락해 주세요：

📧 gyfinjava@163.com

19. 아키텍처 및 설계 원칙

• 불변 값 객체 — 인스턴스 생성 후 변경 불가
• 순수 함수 코어 — 저수준 알고리즘은 모두 순수 함수
• 설정 구동 — 다른 역법을 CalendarConfig로 구분
• 캐시 최적화 — 천문 계산 결과 자동 캐시
• TypeScript 우선 — 네이티브 TypeScript, 완전 타입 정의

20. 업데이트 로그

1.0.0

• 최초 릴리스
• 중국 / 일본 / 한국 / 베트남 4종 음력 변형 지원
• 6개 언어 / 지역 지원
• 간지（연월일 삼주）
• 띠（다국어 + Emoji）
• 24절기 계산
• 13종 전통 명절
• 포맷（5종 내장 + 커스텀 패턴）
• 자체 개발 경량 천문 모듈（VSOP87 절단 데이터）
• IIFE 압축 후 ~47 KB（gzip ~16 KB）