tinylunar

本库采用 16 位位字段打包（Bit-packing）协议，将 1901 年至 2100 年的农历数据存储为 143KB 的二进制格式（经 Deflate 压缩嵌入代码后约 50KB）。数据内置于包内，提供同步查询接口，具备 O(1)时间复杂度的检索性能。

核心特性

• 数据压缩：采用二进制位域编码，显著减小数据体积。
• 零运行时依赖：自包含解压逻辑，无需安装额外的运行库。
• 同步 API：数据随代码加载，无需执行异步网络请求，引入即可调用。

数据来源

• 原始数据：历法原始数据来源于 香港天文台 (Hong Kong Observatory)。
• 数据解析：本项目采用了由 traditional-chinese-calendar-database 项目提供的 JSON 数据作为构建源，在此表示感谢。
• 使用规范：请在遵守香港天文台相关数据公开使用协议的前提下使用本库。

安装

npm install tinylunar
# 或
pnpm add tinylunar

浏览器 CDN 引入

<script type="module">
  import { lunisolar } from 'https://unpkg.com/tinylunar/dist/index.js';
  const info = lunisolar.query('2026-02-17');
  console.log(info);
</script>

根据重构后的显式接口设计，我为您更新了 README.md 的接口说明部分。新的文档结构更加直观，详细列出了每个方法的职责、参数以及返回类型。

接口说明 (API Reference)

本库默认导出单例对象 lunisolar，所有查询均为同步操作。

1. 核心查询接口

lunisolar.query()

查询指定日期的详细农历信息。具备严格的日期合法性校验（如拦截非闰年的 2 月 29 日）。

方法签名

query(date?: Date | string | number, lang?: 'SC' | 'TC'): LunarInfo | null

参数说明

| 参数名 | 是否必选 | 说明 | | ------ | -------- | ------------------------------------------------------------ | | date | 否 | 支持 Date 对象、ISO 字符串（YYYY-MM-DD）或时间戳，默认为当前系统时间 | | lang | 否 | 输出语言：SC（简体），TC（繁体），默认 SC |

lunisolar.queryMonth()

批量查询指定公历月份的整月数据，适用于日历月视图渲染。

方法签名

queryMonth(year: number, month: number, lang?: 'SC' | 'TC'): (LunarInfo | null)[]

参数说明

| 参数名 | 是否必选 | 说明 | | ------ | -------- | ----------------------- | | year | 是 | 公历年份（1901 - 2100） | | month | 是 | 公历月份（1 - 12） | | lang | 否 | 输出语言，默认 SC |

返回值说明

• 返回数组长度等于当月天数
• 数组索引 i 对应公历 i + 1 日

lunisolar.queryYear()

批量查询指定公历年份的整年数据。

方法签名

queryYear(year: number, lang?: 'SC' | 'TC'): (LunarInfo | null)[]

参数说明

| 参数名 | 是否必选 | 说明 | | ------ | -------- | ----------------------- | | year | 是 | 公历年份（1901 - 2100） | | lang | 否 | 输出语言，默认 SC |

2. 工具接口

lunisolar.getSolarTerms()

获取指定公历年份全年的 24 节气列表。

方法签名

getSolarTerms(year: number, lang?: 'SC' | 'TC'): SolarTermItem[]

SolarTermItem 结构

{
  name: string;
  date: { year: number; month: number; day: number };
  lunar: string;
}

lunisolar.getSupportRange()

获取当前数据文件支持的公历年份范围。

方法签名

getSupportRange(): { start: number; end: number }

3. 代码示例

单日查询

import { lunisolar } from 'tinylunar';

const info = lunisolar.query('2026-02-17', 'TC');
console.log(info?.lunar.month); // "正月"

月度批量查询

import { lunisolar } from 'tinylunar';

const days = lunisolar.queryMonth(2026, 1);
console.log(days[0]?.lunar.date); // "十三" (对应 1月1日)

获取节气列表

const terms = lunisolar.getSolarTerms(2025);
const lichun = terms.find(t => t.name === '立春');
// lichun.date -> { year: 2025, month: 2, day: 3 }

数据结构 (LunarInfo)

interface LunarInfo {
  day: string;          // 星期。例："星期五"
  gregorian: {
    year: number;       // 公历年
    month: number;      // 公历月 (1-12)
    date: number;       // 公历日
  };
  lunar: {
    year: string;       // 农历干支年。例："戊寅"
    month: string;      // 农历月。例："正月" 或 "闰六月"
    date: string;       // 农历日。例："初八"
    leapMonth: boolean; // 是否为闰月
  };
  zodiac: string;       // 生肖。例："虎"
  solarTerm: string;    // 24节气。无节气则为空字符串 ""
}

存储协议 (Binary Layout)

数据由 12 字节 Header 开头，随后是每单元 2 字节（16-bit）的每日数据块。

Bit | 15 | 14 13 12 11 10 | 9 |  8  7  6  5  4 |  3  2  1  0 |
    +----+----------------+---+----------------+-------------+
    |  R |     Solar      | L |      Date      |    Month    |
    +----+----------------+---+----------------+-------------+

| 位段 (Bits) | 缩写 | 含义 | 说明 | | :---------- | :---- | :-------- | :------------------------------- | | 15 | R | Reserved | 预留位，固定填充 0。 | | 14 - 10 | Solar | 节气索引 | 取值 0-24。0 代表当天无节气。 | | 9 | L | Leap Flag | 闰月标志。1 为闰月，0 为正常月。 | | 8 - 4 | Date | 农历日期 | 取值 1-30。对应初一至三十。 | | 3 - 0 | Month | 农历月份 | 取值 1-12。对应正月至腊月。 |

许可证

MIT