@tindoaneiu/vietnamese-lunar-calendar

v0.1.0

Published

13 days ago

Thư viện chuyển đổi âm lịch Việt Nam cho các dự án npm.

0High
0Medium
0Low

tindoaneiu

vietnamese lunar-calendar am-lich duong-lich tet ngay-nghi-le

Vietnamese Lunar Calendar

Thư viện TypeScript/NPM để chuyển đổi âm lịch Việt Nam, tính ngày nghỉ lễ âm lịch theo năm dương, và gộp danh sách ngày lễ âm + dương cho các hệ thống HR, timesheet, payroll hoặc calendar nội bộ.

Tính năng

Chuyển ngày dương sang ngày âm.
Chuyển ngày âm sang ngày dương.
Hỗ trợ tháng nhuận âm lịch.
Sinh toàn bộ lịch âm tương ứng với một năm dương.
Sinh ngày nghỉ lễ âm rơi trong một năm dương.
Gộp ngày lễ dương cố định và ngày lễ âm đã convert sang ngày dương.
Hỗ trợ TypeScript type definitions, ESM và CommonJS.

Cài đặt

npm install @tindoaneiu/vietnamese-lunar-calendar

Định dạng dữ liệu

Input ngày hỗ trợ:

dd/MM/yyyy, ví dụ 17/02/2026
dd/MM/yy, ví dụ 26/04/26
Date

Năm 2 chữ số được hiểu là 20yy.

Output ngày luôn dùng định dạng:

dd/MM/yyyy

Phạm vi dữ liệu âm lịch hiện hỗ trợ từ năm 1900 đến 2100.

Import

import {
  VIETNAM_LUNAR_HOLIDAYS,
  VIETNAM_SOLAR_HOLIDAYS,
  getHolidaysBySolarYear,
  getLeapMonth,
  getLunarCalendarBySolarYear,
  getLunarHolidaysBySolarYear,
  getLunarHolidaysForYear,
  getSolarHolidaysByYear,
  lunarToSolar,
  solarToLunar,
} from '@tindoaneiu/vietnamese-lunar-calendar';

API

`solarToLunar(input)`

Chuyển ngày dương sang ngày âm.

Input:

solarToLunar('17/02/2026');

Output:

{
  "solarDate": "17/02/2026",
  "lunarDate": "01/01/2026",
  "isLeapMonth": false
}

Field:

| Field | Type | Ý nghĩa | | --- | --- | --- | | solarDate | string | Ngày dương đã chuẩn hóa | | lunarDate | string | Ngày âm tương ứng | | isLeapMonth | boolean | true nếu ngày âm nằm trong tháng nhuận |

`lunarToSolar(input, options?)`

Chuyển ngày âm sang ngày dương.

Input:

lunarToSolar('01/01/2026');

Output:

{
  "date": "17/02/2026"
}

Khi tháng âm có tháng nhuận, một ngày âm có thể có 2 ngày dương:

lunarToSolar('05/04/2001');

{
  "date": "27/04/2001",
  "leapMonthDate": "27/05/2001"
}

Nếu muốn lấy đúng ngày của tháng nhuận:

lunarToSolar('05/04/2001', { isLeapMonth: true });

{
  "date": "27/05/2001"
}

`getLeapMonth(year)`

Lấy thông tin tháng nhuận của một năm âm lịch.

Input:

getLeapMonth(2001);

Output:

{
  "year": 2001,
  "leapMonth": 4,
  "days": 29
}

Nếu năm không có tháng nhuận:

{
  "year": 2026,
  "days": 0
}

`getLunarCalendarBySolarYear(year)`

Sinh toàn bộ ngày trong một năm dương, kèm ngày âm tương ứng.

Input:

getLunarCalendarBySolarYear(2027);

Output rút gọn:

[
  {
    "solarDate": "01/01/2027",
    "lunarDate": "24/11/2026",
    "isLeapMonth": false
  },
  {
    "solarDate": "02/01/2027",
    "lunarDate": "25/11/2026",
    "isLeapMonth": false
  }
]

`getLunarHolidaysForYear(year, holidays)`

Sinh ngày dương của các ngày lễ âm theo một năm âm lịch.

Input:

getLunarHolidaysForYear(2026, VIETNAM_LUNAR_HOLIDAYS);

Output rút gọn:

[
  {
    "name": "Giỗ Tổ Hùng Vương",
    "lunarDate": "10/03/2026",
    "solarDate": "26/04/2026"
  }
]

`getLunarHolidaysBySolarYear(year, holidays?)`

Sinh các ngày lễ âm có ngày dương rơi trong một năm dương.

Input:

getLunarHolidaysBySolarYear(2027);

Output:

[
  {
    "name": "Tết Nguyên đán",
    "lunarDate": "29/12/2026",
    "solarDate": "05/02/2027"
  },
  {
    "name": "Tết Nguyên đán",
    "lunarDate": "01/01/2027",
    "solarDate": "06/02/2027"
  },
  {
    "name": "Giỗ Tổ Hùng Vương",
    "lunarDate": "10/03/2027",
    "solarDate": "16/04/2027"
  }
]

`getSolarHolidaysByYear(year, holidays?)`

Sinh các ngày lễ dương cố định theo năm dương.

Input:

getSolarHolidaysByYear(2027);

Output:

[
  {
    "name": "Tết Dương lịch",
    "month": 1,
    "day": 1,
    "type": "solar",
    "solarDate": "01/01/2027"
  },
  {
    "name": "Ngày Giải phóng miền Nam",
    "month": 4,
    "day": 30,
    "type": "solar",
    "solarDate": "30/04/2027"
  }
]

`getHolidaysBySolarYear(year, options?)`

Gộp ngày lễ dương cố định và ngày lễ âm đã đổi sang ngày dương.

Input:

getHolidaysBySolarYear(2027);

Output:

[
  {
    "name": "Tết Dương lịch",
    "month": 1,
    "day": 1,
    "type": "solar",
    "solarDate": "01/01/2027"
  },
  {
    "name": "Tết Nguyên đán",
    "lunarDate": "29/12/2026",
    "solarDate": "05/02/2027",
    "type": "lunar"
  },
  {
    "name": "Giỗ Tổ Hùng Vương",
    "lunarDate": "10/03/2027",
    "solarDate": "16/04/2027",
    "type": "lunar"
  },
  {
    "name": "Ngày Quốc khánh",
    "month": 9,
    "day": 2,
    "type": "solar",
    "solarDate": "02/09/2027"
  }
]

Field:

| Field | Type | Ý nghĩa | | --- | --- | --- | | name | string | Tên ngày lễ | | type | 'solar' \| 'lunar' | Nguồn ngày lễ | | solarDate | string | Ngày dương thực tế | | lunarDate | string \| undefined | Ngày âm, chỉ có với type: 'lunar' | | month | number \| undefined | Tháng dương, chỉ có với type: 'solar' | | day | number \| undefined | Ngày dương, chỉ có với type: 'solar' |

Ngày lễ mặc định

`VIETNAM_SOLAR_HOLIDAYS`

Danh sách ngày dương cố định:

| Tên | Ngày | | --- | --- | | Tết Dương lịch | 01/01 | | Ngày Giải phóng miền Nam | 30/04 | | Ngày Quốc tế Lao động | 01/05 | | Ngày Quốc khánh | 02/09 |

Ngày nghỉ liền kề dịp Quốc khánh có thể là 01/09 hoặc 03/09 theo từng năm, nên thư viện chưa hard-code ngày này vào mặc định.

`VIETNAM_LUNAR_HOLIDAYS`

Danh sách ngày âm mặc định:

| Tên | Ngày âm | | --- | --- | | Tết Nguyên đán | 29 tháng Chạp | | Tết Nguyên đán | 30 tháng Chạp | | Tết Nguyên đán | Mùng 1 | | Tết Nguyên đán (Mùng 2) | Mùng 2 | | Tết Nguyên đán (Mùng 3) | Mùng 3 | | Giỗ Tổ Hùng Vương | 10/03 âm lịch |

Nếu tháng Chạp của năm đó không có ngày 30, ngày 30 tháng Chạp sẽ được bỏ qua.

Custom holidays

Bạn có thể truyền danh sách ngày lễ riêng.

getHolidaysBySolarYear(2027, {
  solarHolidays: [
    { name: 'Ngày thành lập công ty', month: 6, day: 15 },
  ],
  lunarHolidays: [
    { name: 'Ngày giỗ nội bộ', lunarMonth: 8, lunarDay: 15 },
  ],
});

Lưu ý nghiệp vụ

Thư viện này trả ngày lễ theo lịch, chưa tự tính nghỉ bù cuối tuần.
Tết Nguyên đán mặc định tính từ 29 tháng Chạp đến Mùng 3 theo yêu cầu nghiệp vụ.
Các ngày nghỉ theo quyết định từng năm, ví dụ ngày nghỉ thêm dịp Quốc khánh, nên được cấu hình thêm bằng custom holidays.
Bảng dữ liệu âm lịch hiện dựa trên dữ liệu mã hóa sẵn, không phải phép tính thiên văn realtime.

Scripts

npm test
npm run typecheck
npm run build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Vietnamese Lunar Calendar

Tính năng

Cài đặt

Định dạng dữ liệu

Import

API

solarToLunar(input)

lunarToSolar(input, options?)

getLeapMonth(year)

getLunarCalendarBySolarYear(year)

getLunarHolidaysForYear(year, holidays)

getLunarHolidaysBySolarYear(year, holidays?)

getSolarHolidaysByYear(year, holidays?)

getHolidaysBySolarYear(year, options?)

Ngày lễ mặc định

VIETNAM_SOLAR_HOLIDAYS

VIETNAM_LUNAR_HOLIDAYS

Custom holidays

Lưu ý nghiệp vụ

Scripts

`solarToLunar(input)`

`lunarToSolar(input, options?)`

`getLeapMonth(year)`

`getLunarCalendarBySolarYear(year)`

`getLunarHolidaysForYear(year, holidays)`

`getLunarHolidaysBySolarYear(year, holidays?)`

`getSolarHolidaysByYear(year, holidays?)`

`getHolidaysBySolarYear(year, options?)`

`VIETNAM_SOLAR_HOLIDAYS`

`VIETNAM_LUNAR_HOLIDAYS`