{"id":22001664,"url":"https://github.com/waterbeside/lunisolar","last_synced_at":"2025-05-15T20:02:51.573Z","repository":{"id":37778956,"uuid":"504880420","full_name":"waterbeside/lunisolar","owner":"waterbeside","description":"Typescript农历库，支持阴历公历互转，支持各类黄历数据查询，如八字四柱、阴历、神煞宜忌、建除十二神、胎神占方、吉神方位、五行纳音等。支持自定义插件。","archived":false,"fork":false,"pushed_at":"2025-02-12T03:40:34.000Z","size":1043,"stargazers_count":289,"open_issues_count":15,"forks_count":33,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-08T13:04:39.428Z","etag":null,"topics":["date","javascript","lunar","solar","typescript"],"latest_commit_sha":null,"homepage":"https://lunisolar.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waterbeside.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-18T15:28:13.000Z","updated_at":"2025-05-03T04:05:52.000Z","dependencies_parsed_at":"2023-11-23T01:24:36.310Z","dependency_job_id":"ba0d1136-da62-4182-841f-4a9761c30dc8","html_url":"https://github.com/waterbeside/lunisolar","commit_stats":{"total_commits":625,"total_committers":1,"mean_commits":625.0,"dds":0.0,"last_synced_commit":"f3eff429cc82e0954bfe8d86673d3cc2efd61503"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterbeside%2Flunisolar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterbeside%2Flunisolar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterbeside%2Flunisolar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waterbeside%2Flunisolar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waterbeside","download_url":"https://codeload.github.com/waterbeside/lunisolar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414477,"owners_count":22067270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date","javascript","lunar","solar","typescript"],"created_at":"2024-11-29T23:14:36.780Z","updated_at":"2025-05-15T20:02:50.485Z","avatar_url":"https://github.com/waterbeside.png","language":"TypeScript","funding_links":[],"categories":["📂 按分类"],"sub_categories":["📅 农历日历"],"readme":"\u003c!-- markdownlint-disable --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"120\" src=\"./docs/image/../images/logo.png\" style=\"text-align: center;\" \u003e\n\u003c/div\u003e\n\u003ch1 align=\"center\"\u003eLunisolar\u003c/h1\u003e\n\n![minzip](https://img.shields.io/bundlephobia/minzip/lunisolar)\n![version](https://img.shields.io/npm/v/lunisolar)\n![bulid](https://img.shields.io/github/actions/workflow/status/waterbeside/lunisolar/build.yml)\n\n---\n【[线上文档请点这里](https://lunisolar.js.org)】\n\n---\n\n**lunisolar** 是一个使用`Typescript`编写的专业农历库, 可取得各类农历数据，参考中国中代书籍，数据来源有依有据。支持多语言（可自定义语言包），支持自定义插件。\n\n具体包含以下功能：\n\n- ✅公历-阴历互转\n- ✅阴历查询\n- ✅八字查询\n- ✅节气日期查询\n- ✅Markers（日期备注、节日功能） \n- ✅胎神占方 (插件)\n- ✅五行纳音 (插件)\n- ✅神煞系统 (插件) \u003c基于：协纪辨方书\u003e\n  - ✅建除十二神\n  - ✅神煞宜忌\n  - ✅时辰凶吉\n- ✅八字增强 (插件)\n  - ✅八字十神\n  - ✅四柱神煞\n- ⏳~~紫微斗数~~ (planning)\n- ...更多功能开发中\n  \n-----\n\n- [快速上手](#快速上手)\n- [前言](#前言)\n  - [\\* 为何制作此库](#-为何制作此库)\n  - [\\* 阴历和阳历](#-阴历和阳历)\n  - [\\* 年和岁](#-年和岁)\n  - [\\* 节和气](#-节和气)\n  - [\\* 生肖和换岁](#-生肖和换岁)\n  - [\\* 换日](#-换日)\n  - [\\* 其它](#-其它)\n- [1 安装](#1-安装)\n  - [1.1 Nodejs](#11-nodejs)\n  - [1.2 浏览器直接通过script引入](#12-浏览器直接通过script引入)\n- [2 解释 (创建Lunisolar对象)](#2-解释-创建lunisolar对象)\n  - [2.1 解释 (Parse)](#21-解释-parse)\n  - [2.2 克隆 Lunisolar 实例对象](#22-克隆-lunisolar-实例对象)\n  - [2.3 阴历反查](#23-阴历反查)\n- [3 Lunisolar类](#3-lunisolar类)\n  - [格式化数据 format](#格式化数据-format)\n  - [时间差 diff](#时间差-diff)\n  - [时间加减](#时间加减)\n- [4. 阴历数据](#4-阴历数据)\n  - [4.1 取得阴历](#41-取得阴历)\n  - [4.2 Lunar类](#42-lunar类)\n- [5 八字（天干地支）](#5-八字天干地支)\n  - [5.1 取得数据](#51-取得数据)\n  - [5.2 Char8类](#52-char8类)\n  - [5.3 SB类](#53-sb类)\n  - [5.4 Stem天干类](#54-stem天干类)\n  - [5.5 Branch地支类](#55-branch地支类)\n  - [5.6 Element5五行类](#56-element5五行类)\n  - [5.7 Trigram8 八卦类](#57-trigram8-八卦类)\n  - [5.8 八字增强插件](#58-八字增强插件)\n- [6 节气](#6-节气)\n- [7 胎神](#7-胎神)\n  - [7.1 用法](#71-用法)\n- [8 纳音](#8-纳音)\n- [9 建除十二神](#9-建除十二神)\n- [10 神煞宜忌](#10-神煞宜忌)\n- [11 日期备注 Markers](#11-日期备注-markers)\n- [插件 plugins](#插件-plugins)\n- [国际化](#国际化)\n  - [\\* 加载插件语言包](#-加载插件语言包)\n  - [\\* 对语言包进行自定义](#-对语言包进行自定义)\n- [支持](#支持)\n\n\n\n## 快速上手\n\n```typescript\n// 引入\nimport lunisolar from 'lunisolar'\n\n// 使用\n\nconst d = lunisolar('2022/07/18 14:40')\n\n// --- format ---\n\nd.format('lY年 lM(lL)lD lH時')  // 可取得阴历日期 '二〇二二年 六月(大)二十 未時'\nd.format('cY cM cD cH')  // 可取得八字：'壬寅 丁未 壬申 丁未'\nd.format('YYYY-MM-DD HH:mm:ss') // 2022-07-18 14:40:00\n\n// --- 阴历--- \n\nd.lunar.toString() // 二〇二二年六月二十未時\n`${d.lunar}` // 二〇二二年六月二十未時\nd.lunar.year // 2022\nd.lunar.getYearName() // 二〇二二\nd.lunar.month // 6 （如果是闰六月会返回106）\nd.lunar.getMonthName() // 六月\nd.lunar.day // 20\nd.lunar.getDayName() // 二十\nd.lunar.hour // 7 （返回从0开始算的时辰下标）\nd.lunar.getHourName() // 未\nd.lunar.isLeapMonth // false (是否闰月)\n\n// --- 八字 ----\n\n`${d.char8}` // 壬寅 丁未 壬申 丁未\nd.char8.year.toString() // 壬寅  （取得年柱）\nd.char8.month.toString() // 丁未  （取得月柱）\nd.char8.day.toString() // 壬申 （取得日柱）\nd.char8.hour.toString() // 丁未  （取得时柱）\nd.char8.year.stem.toString() // 壬 (年柱天干)\nd.char8.year.branch.toString() // 寅  (年柱地支)\nd.char8.year.branch.hiddenStems // [甲, 丙, 戊]  （地支藏干的天干对象列表，顺序为本气、中气、余气）\n// ...其它柱类似\n\n// 节气\nlunisolar('2022-07-23').solarTerm?.toString() // 大暑 （返回当天的节气，如果不是节气则solarTerm().solarTerm返回null）\n\n// 阴历反查 （阴历转公历）\nlunisolar.fromLunar({\n  year: 2022,\n  month: 10,\n  day: 25\n}).format('YYYY-MM-DD') // 2022-11-18\n\n```\n\n## 前言\n\n### * 为何制作此库\n\n昔见不同版本日历（包括纸质日历和各类日历软件），其所示宜忌有所不同，更有相矛盾者，不知如何取用，故疑其推算依据是否误，本着宏扬传统文化之精神，离所有职务，查阅各资料文案，以制此库。\n\n### * 阴历和阳历\n\n现所用的中国传统历法，我们常称为农历，农历是阴阳合历，即包含了`阴历`和`阳历`，所以此库命名为`lunisolar`。\n\n农历中，通过月相圆缺纪月，此属于**阴历**范畴，本库会以一个`Lunar`对象记录转换好的阴历数据。\n而公历与阴历的转换没规律可言，故采用查表法进行转换，其数据来自香港天文台【[公历与农历日期对照表](https://www.hko.gov.hk/tc/gts/time/conversion1_text.htm#)】。其可查询年份范围为`[1901,2100]`。数据抓取和压缩的代码见仓库 [lunar-crawler](https://github.com/waterbeside/lunar-crawler)，此处不作详细介绍。\n\n属于阳历范畴的内容比较多，有二十四节气、天干地支等，传统很多术数多以阳历排盘，如八字、奇门遁甲...（也有少数以阴历排盘的，如紫微斗数）。其中二十四节气是阳历中十分重要的部分，其影响天干地支的**换岁**和**换月**。\n\n### * 年和岁\n\n在传统上，年和岁是两个不同的概念。\n\n**年** 是指阴历正月初一到下一个正月初一的一个周期。\n\n**岁** 是指太阳连续两次通过春分点的时间间隔，古人一般用‘冬至点’来观测，现代称作**回归年（tropical year）**，也叫 **太阳年（solar year）**。一个周期结束而开始下一个周期，称为`换岁`。\n\n$$1回归年 = 365.2421990741日 = 365天5小時48分46秒$$\n\n### * 节和气\n\n我们常说的二十四节气，其实分为节和气两种，共十二节和十二气，节和气交替出现。天干地支纪月是以节换月的。\n\n|      |     |     | 节   | 气   |\n| ---  | ---  | ---  | --- | --- |\n|    | 孟春 | 寅月 | 立春 | 雨水 |\n| 春 | 仲春 | 卯月 | 惊蛰 | 春分 |\n|    | 季春 | 辰月 | 清明 | 谷雨 |\n|    | 孟夏 | 巳月 | 立夏 | 小满 |\n| 夏 | 仲夏 | 午月 | 芒种 | 夏至 |\n|    | 季夏 | 未月 | 小暑 | 大暑 |\n|    | 孟秋 | 申月 | 立秋 | 处暑 |\n| 秋 | 仲秋 | 酉月 | 露水 | 秋分 |\n|    | 季秋 | 戌月 | 寒露 | 霜降 |\n|    | 孟冬 | 亥月 | 立冬 | 小雪 |\n| 冬 | 仲冬 | 子月 | 大雪 | 冬至 |\n|    | 季冬 | 丑月 | 小寒 | 大寒 |\n\n实际上，节气是某一个时刻，而这个时刻并不是固定在某天的某个时辰。但由于数据源只精确到日，所以本库的交节（更换八字月柱），也是以日为准。\n\n### * 生肖和换岁\n\n我们知道天干地支是基于二十四节气来定的。在民间，如八字命理这类术数，通常以**立春**换岁，即到了立春，便更换下一个天干地支纪年，例如今年为甲子年，则到下一个立春，则换成乙丑年。\n\n但是，并不是所有术数都是以立春换岁，例如中医的五运六气，则以大寒日换岁。 而奇门遁甲则以冬至换岁，中气换月。\n\n\u003e `lunisolar`默认使用**立春**换岁, 当然你也可以自定义换岁的节气。\n\n**生肖**：生肖与十二地支是对应的，所以实际上生肖也是按节气更换，而不少传统述数系统都是以立春换岁，所以生肖应当也是按立春更换。\n\n但是，跟据 中国大陆国家标准：编号**GB/T 33661-2017 《农历的编算和颁行》**规定,\n\n\u003e “干支纪年的循环参考时间：对应于北京时间公历1984年2月2日0时起到1985年2月19日24时截止的农历年为甲子年。”\n\n如按此标准的话，应该正月初一换岁，即生肖在正月初一更换。\n这与传统术数的计算方式有所冲突，也许是为了方便大众记忆与使用。\n由于大部分术数系统并不以正月初一换岁，所以lunisolar默认并不跟随此标准进行换岁（虽然可以通过配置设置成与国标一致，但不建议）。\n\n### * 换日\n\n传统子时是每一天的开始，子时对应的时间为 [23:00, 01:00), 所以lunisolar会在23:00进行换日。\n\n### * 其它\n\n[moment.js](https://github.com/moment/moment) 和 [dayjs](https://github.com/iamkun/dayjs) 是两个比较出名的时间工具库，为了符合大家的使用习惯，`lunisolar`针对公历的部分操作将会尽量向`dayjs`看齐，并参考了其代码设计。针对公历部分，尽管lunisolar也有类似dayjs的方法，但并不会cover其所有功能，如果你仅仅是对公历进行操作，推荐使用**dayjs**。lunisolar重点在于农历部分，例如`Lunisolar`的`format`方法和`diff`方法包含`dayjs`这两个方法的功能并与之保持一致，同时加入了对农历的处理，具体功能及使用请继续阅读文档。\n\n## 1 安装\n\n### 1.1 Nodejs\n\n```bash\nnpm install lunisolar\n# or\nyarn add lunisolar\n```\n\n引入\n\n```typescript\nimport lunisolar from 'lunisolar'\n```\n\n如果你使用typescript你需要设置：\n\n```json5\n{ //tsconfig.json\n  \"compilerOptions\": {\n    \"esModuleInterop\": true,\n    \"allowSyntheticDefaultImports\": true,\n  }\n}\n```\n\n否则你必需这样引入:\n\n```typescript\nimport * as lunisolar from 'lunisolar'\n```\n\n### 1.2 浏览器直接通过script引入\n\n```html\n\u003cscript src=\"path/to/lunisolar.js\"\u003e\u003c/script\u003e\n\u003c!-- or src from unpkg ( 请根据需求选择版本号 ↓ )--\u003e\n\u003cscript src=\"https://unpkg.com/lunisolar@2.1.12/dist/lunisolar.js\"\u003e\u003c/script\u003e\n```\n\n## 2 解释 (创建Lunisolar对象)\n\n### 2.1 解释 (Parse)\n\n通过lunisolar函数创建一个Lunisolar实例对象：\n\n`lunisolar(param: String | Number | Date | Lunisolar, config?: ConfigType): Lunisolar`\n\n```typescript\n// 传入字符串\nlunisolar('2022-07-18 14:40')\nlunisolar('2022/07/18')\n// 不传入参数时，为当前时间\nlunisolar()\n// 传入时间戳 (毫秒为单位)\nlunisolar(1658289207143)\n// 传入Date对象\nlunisolar(new Date(2022, 6, 20))\n// 传入Lunisolar对象时，将克隆一个Lunisolar对象\nlunisolar(lunisolar())\n\n//\nconst config = {\n  lang: 'en' // 更改用语言，需先加载对应语言包，详见文档 【国际化】的说明\n}\nlunisolar('2022-07-18 14:40', config)\n\n```\n\n### 2.2 克隆 Lunisolar 实例对象\n\n```javascript\nconst lsr1 = lunisolar('2022-07-18 14:40')\nconst lsr2 = lsr1.clone()\n```\n\n### 2.3 阴历反查\n\n通过阴历数据创建一个Lunisolar实例对象，此法可用来阴历转公历:\n\n`lunisolar.fromLunar(lunarData: LunarData, config: ConfigType): Lunisolar`\n\n参数说明\n\n**lunarData**: LunarData\n\n```typescript\ntype LunarData = {\n  year?: number | string \n  // 该年正月初一所在公历年的年份，可以是字符串，默认值为当前日期的年份\n\n  month: number | string \n  // 阴历月份，可以是字符串，必填, 当月份数大于100时，表明时闰月，如闰4月，可输入104\n  \n  day: number | string \n  // 阴历日，可以是字符串，必填\n\n  hour?: number | string \n  // 时辰索引值或时辰名，默认为0, 即子时。设置时辰后，返回的小时为该时辰的中间时间，如寅时，会返回4点正的时间。\n\n  isLeapMonth?: boolean \n  // 指明月份是否闰月，默认为false, 当month设为大于100的数时，会无视此设置\n\n}\n```\n\n示例1\n\n```typescript\nconst lunarData = {\n  year: 2022,\n  month: 10,\n  day: 25\n}\nconst lsr = lunisolar.fromLunar(lunarData) // 成功创建一个个Lunisolar实例对象\n\nconsole.log(lsr.format('YYYY-MM-DD')) // 2022-11-18\n```\n\n示例2\n\n你也可以使用汉字进行阴历反查\n\n```typescript\n// lunisolar默认使用繁体中文语言包，此语言包默认自动加载，可直接使用繁体中文\n// 使用其它语言包参考示例3\nconst lunarData = {\n    year: '二〇二〇',\n    month: '閏四月', \n    day: '廿四'\n  }\nconst lsr = lunisolar.fromLunar(lunarData) // 成功创建一个个Lunisolar实例对象\nconsole.log(lsr.format('YYYY-MM-DD')) // 2020-06-15\n```\n\n示例3\n\n使用简体中文进行阴历反查\n\n```typescript\nimport lunisolar from 'lunisolar'\nimport zhCn from 'lunisolar/locale/zh-cn'\nimport ja from 'lunisolar/locale/ja'\nlunisolar.locale(ja) // 加载日文语言包\nlunisolar.locale(zhCn) // 加载简体中文语言包，最后加载者，会全局默认使用该语言包\n\nconst lunarData = {\n    year: '二〇二〇',\n    month: '闰四月',  // 此时，如果还是使用繁体的“閏”字会报错。\n    day: '廿四'\n  }\nconst lsr = lunisolar.fromLunar(lunarData) // 成功创建一个个Lunisolar实例对象\n\nconsole.log(lsr.format('YYYY-MM-DD')) // 2020-06-15\n\n// lunisolar.locale(zhCn) 加载简体中文语言名后，会全局使用zh-cn语言包\n// 如果个别实例想使用其它语言包可通config进行临时更改，如使用日文，\nconst lsr2 = lunisolar.fromLunar({\n    year: '二〇二〇',\n    month: '睦月', \n    day: '一日'\n  }, {\n  lang: 'ja' // 指正要使用的语言包名\n})\n\nconsole.log(lsr.format('YYYY-MM-DD')) // 2020-01-25\n\n```\n\n## 3 Lunisolar类\n\n通过`lunisolar()`函数获得一个`Lunisolar`实例\n\nLunisolar具有以下属性和方法\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| lunar      | 阴历数据对象 | | [Lunar](./lunar.md) |\n| char8      | 八字对象 | | [Char8](./char8.md) |\n| solarTerm       | 返回当前日期的节气对象，如果不是节气，返回null | | [SolarTerm](./solarTerm.md) \\| null |\n| getSeason()  | 取得当前季节 | | string |\n| getSeasonIndex()  | 以春夏秋冬为顺序取得当前季节索引 | | number |\n| toDate()   | 返回Date对象 | | Date |\n| clone()    | 克隆当前Lunisolar对象 | | Lunisolar |\n| unix()     | 返回以秒为单位的时间戳 | | number |\n| format(formatStr: string) | 按指定格式格式化时间 | **formatStr**: string 时间将以这字符串格式进行格式化，例 'YYYY-MM-DD HH:mm:ss' | string |\n| diff(date, unit, float) | 时间差计算 | **date**: number \\| string \\| Date \\| Lunisolar \u003cbr\u003e 与当前实例的时间进行比较的时间\u003cbr\u003e **unit**: string \u003cbr\u003e单位，如 year, lunarYear, month, lunarMonth 等\u003cbr\u003e **float**: boolean \u003cbr\u003e是否返回浮点数 | number |\n| add(value, unit)  | 时间加减 | **value**: number 时间加减的值，负数为减 \u003cbr/\u003e **unit**: string 加减单位 | number |\n| year     | 年份 | | number |\n| month    | 月份 1 ~ 12 | | number |\n| day      | 日期 1 ~ 31 | | number |\n| dayOfWeek  | 周几，0 ~ 6， 0代表周日 | | number |\n| hour      | 小时 0 ~ 23 | | number |\n| minute    | 分 0 ~ 59 | | number |\n| second    | 秒 0 ~ 59 | | number |\n| millis    | 毫秒 0 ~ 999 | | number |\n| utc()      | 转为utc模式 | | Lunisolar |\n| isUTC()      | 检查是否为UTC模式的实例 | | boolean |\n| utcOffset(offset) | 取得，或设置utc偏移值 | **offset**: number \\| undefined \u003cbr/\u003e · 当为undefined时，为取得utc偏移值, 返回单位为分钟的number值 \u003cbr /\u003e · 当为number类型时，为设置utc偏移值，并把时间转为utc时间，返回一个新的Lunisolar实例。如果设置的offset范围在[-16, 16], 则单位为小时，其它情况为分钟 | Lunisolar \\| number |\n| local()      | 转为本地时间 | | Lunisolar |\n| valueOf()  | 返回Date对象的valueOf(), 即时间戳 | | number |\n| toISOString()  | 返回Date对象的toISOString() | | string |\n| toUTCString()  | 返回Date对象的toUTCString() | | string |\n| toString() | 返回当前 Date对象的toUTCString() + 阴历的格式化后的日期时间: 例“Wed, 24 Aug 2022 14:50:51 GMT (二〇二二年七月廿七亥時)” | | string |\n\n### 格式化数据 format\n\nlunisolar(date).format(formatStr)格式化数据\n\n示例：\n\n```javascript\nlunisolar('2022/07/18 14:40').format('YYYY/MM/DD HH:mm:ss SSS') // '2022/07/18 14:40:00 000'\nlunisolar('2022/07/18 14:40').format('lY年 lMlD lH時') // '二〇二二年 六月二十 未時'\nlunisolar('2022/07/18 14:40').format('lY年 lM(lL)lD lH時') // '二〇二二年 六月(大)二十 未時'\nlunisolar('2022/07/18 14:40').format('lYn年 農歷lMn月lDn日 第lHn個時辰') // '2022年 農歷6月20日 第8個時辰'\nlunisolar('2022/07/18 14:40').format('cY cM cD cH') // '壬寅 丁未 壬申 丁未'\nlunisolar('2022/07/18 14:40').format('[八字：] cY cM cD cH') // '八字：壬寅 丁未 壬申 丁未'\nlunisolar('2022/03/10').format('cZ年') // '虎年'\nlunisolar('2022/03/10').format('cYs-cYb cMs-cMb cDs-cDb cHs-cHb') // ''壬-寅 丁-未 壬-申 丁-未''\n```\n\n根据传入的标识字符串获取格式化的日期。\n\n要对字符进行转义，请将它们括在方括号中(例如 `[cY YY]` )\n\n| 标识 | 示例 | 描述 |\n| ---- | ---- | --- |\n| lY  |  二〇二二 | 当年阴历正月初一所在的公历年 |\n| lYn  |  2022 | 当年阴历正月初一所在的公历年, 数字形式开示 |\n| lM  |  正月-十二月 | 阴历月 |\n| lMn  |  1-12 | 阴历月, 以数字形式表示 |\n| lD  | 初一 | 阴历日 |\n| lDn  | 1 - 30 | 阴历日, 以数字形式表示 |\n| lH  | 子 - 亥 | 时辰 |\n| lHn  | 1 - 12 | 时辰序号，从1开始 |\n| lDn  | 1 - 30 | 阴历日, 以数字形式表示 |\n| lL  | 大 \\| 小  | 阴历月是大月还是小月 |\n| cY  | 甲子 | 八字年柱 |\n| cYs  | 甲 | 八字年柱天干 |\n| cYb  | 子 | 八字年柱地支 |\n| cM  | 甲子 | 八字月柱 |\n| cMs  | 甲 | 八字月柱天干 |\n| cMb  | 子 | 八字月柱地支 |\n| cD  | 甲子 | 八字日柱 |\n| cDs  | 甲 | 八字日柱天干 |\n| cDb  | 子 | 八字日柱地支 |\n| cH | 甲子 | 八字日柱 |\n| cHs  | 甲 | 八字日柱天干 |\n| cHb  | 子 | 八字日柱地支 |\n| cZ  | 鼠 | 生肖 （立春换岁，可通过config设置换岁时机） |\n| t  | 1-24 | 节气，从小寒到冬至的序号，从1开始，如果该日不是节气，返回空字符串 |\n| T  | 小寒-冬至 | 节气字符串，如果该日不是节气，返回空字符串 |\n| YY  |  18 | 年，两位数 |\n| YYYY | 2018 | 年，四位数 |\n| M  | 1-12 | 月，从1开始  |\n| MM | 01-12 | 月，两位数字 |\n| MMM | Jan-Dec | 月，英文缩写 |\n| D | 1-31 | 日 |\n| DD | 01-31 | 日，两位数 |\n| H | 0-23 | 24小时 |\n| HH | 00-23 | 24小时，两位数 |\n| h | 1-12 | 12小时 |\n| hh | 01-12 | 12小时，两位数 |\n| m | 0-59 | 分钟 |\n| mm | 00-59 | 分钟，两位数 |\n| s | 0-59 | 秒 |\n| ss | 00-59 | 秒，两位数 |\n| S | 0-9 | 毫秒（百），一位数 |\n| SS | 00-99 | 毫秒（十），两位数 |\n| SSS | 000-999 | 毫秒，三位数 |\n| Z | -05:00 | UTC偏移 |\n| ZZ | -0500 | UTC偏移，两位数 |\n| A | AM / PM | 上/下午，大写 |\n| a | am / pm | 上/下午，小写 |\n\n### 时间差 diff\n\n`lunisolar(date).diff(date, unit)` 可计算两个日期的时间差。\n\ndiff 方法包含两个参数：`date` 和 `unit`\n\n参数：\n\n- **date**: *string | number | Date | Lunisolar* 为传入作为比较的时间\n- **unit**: *string* 时间单位，单位见下文表格，单位不区分大小写，支持复数和缩写形式。\n\n| 单位 | 缩写 | 描述 |\n| ----| --- | --- |\n| lunarYear | lY | 阴历年 |\n| lunarMonth | lM | 阴历月 |\n| lunarDay | lD | 阴历日 |\n| lunarHour | lH | 时辰 |\n| day | d | 天 |\n| month | M | 月份 |\n| year | y | 年 |\n| hour | h | 小时 |\n| minute | m | 分钟 |\n| second | s | 秒 |\n| millisecond | ms | 毫秒 |\n\n示例:\n\n```javascript\nconst lsr1 = lunisolar('2020/01/01 00:00:00')\nconst lsr2 = lunisolar('2020/01/02 00:00:00')\nlsr1.diff(lsr2, 'ms') // 86400000 \nlsr1.diff(lsr2) // 86400000 默认以毫秒为单位\nlsr1.diff(lsr2, 's') // 86400\nlsr1.diff('2020/02/01 00:00:00', 'M') // 1 第一个参数可接受字符串\n\nconst lsr3 = lunisolar('2018/01/01')\nconst lsr4 = lunisolar('2022/02/02')\nlsr3.diff(lsr4, 'lY') // 5 相差5个阴历年\nlsr3.diff(lsr4, 'lM') // 51 相差51个阴历月\nlunisolar('2018/02/10').diff('2022/02/02', 'lM', true) // 49.233333 相差约49.233个阴历月\nlunisolar('2018/02/10 00:00:00').diff('2018/02/10 00:00:00', 'lM', true) // 49.233333 相差约49.233个阴历月\n\nconst a = '2020/01/02 00:00:00'\nconst b = '2020/01/01 00:00:00'\na.diff(b) // -86400000 a比b大的话将返回负数\n```\n\n\u003e 阴历的时间差计算，如 2018/02/10 （二〇一七年十二月廿五）和 2018/02/16（二〇一八年正月初一）这两个日期，实际只相差五天，但因为两个所在的阴历年不同，所以`date1.diff(date1,'lY')` 计出的结果是1年，如果采用小数`date1.diff(date1,'lY', true)`，会算得 0.016 年。\n\u003e\n\u003e 而公历的diff会与`dayjs.diff`的计算方式一致，两个时间天数不足一年, 其取整数是不会按一年算的。如果你想农历也按此方式取整，可以先取浮点数再取整`parseInt(date1.diff(date1,'lY', true))`\n\n\n### 时间加减\n\n```typescript\n/**\n * @param { number } value 要加减的值，当为负数时即为减\n * @param { DateAddUnit } unit 单位，默认值为 millisecond，即毫秒\n * @return { Lunisolar } 返回一个新的Lunisolar实例\n */\nlunisolar().add(value: number, unit?: DateAddUnit): Lunisolar\n\n```\n\n```typescript\nlunisolar().add(1, 'd') // 加一天\nlunisolar().add(-2, 'M') // 减两个月\nlunisolar().add(-2, 'm') // 减两分钟\n```\n\n单位说明\n\n```typescript\n\ntype DateAddUnit = \n  | 'millisecond'\n  | 'second' \n  | 'minute' \n  | 'hour' \n  | 'day' \n  | 'month' \n  | 'year' \n  | 'ms' \n  | 's' \n  | 'm' \n  | 'h' \n  | 'd'\n  | 'M' \n  | 'y'\n```\n\n| 单位 | 缩写 | 描述 |\n| ----| --- | --- |\n| day | d | 天 |\n| month | M | 月份 |\n| year | y | 年 |\n| hour | h | 小时 |\n| minute | m | 分钟 |\n| second | s | 秒 |\n| millisecond | ms | 毫秒 |\n\n\n## 4. 阴历数据\n\n### 4.1 取得阴历\n\n```javascript\nconst lsr = lunisolar('2022-07-18 14:40')\nconsole.log(lsr.lunar.toString()) // 二〇二二年六月二十未時\nconsole.log(lsr.lunar.month) // 6\nconsole.log(lsr.lunar.day) // 20\nconsole.log(lsr.lunar.hour) // 7\nconsole.log(lsr.lunar.getMonthName()) // 六月\nconsole.log(lsr.lunar.getDayName()) // 二十\nconsole.log(lsr.lunar.getHourName()) // 未\nconsole.log(lsr.format('lY年 lM(lL)lD lH時')) // 二〇二二年 六月(大)二十 未時\n```\n\n### 4.2 Lunar类\n\n通过`lunisolar().lunar`取得`Lunar`对象实例\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| leapMonth      | 当年农历的闰月，返回月份的数字， 如果没有闰月，返回0 | | number |\n| leapMonthIsBig | 当年农历闰月是否大月 如果有闰月并且为大月，返回true || boolean |\n| year           | 取得该阴历年正月初一所在的公历年 || number |\n| month          | 取得当前阴历月的月号数字 | | number |\n| day            | 取得当前阴历日号数字 | | number |\n| hour           | 取得当前时辰下标 0 ~ 11 | | number |\n| isLeapMonth    | 当前阴历月是否为闰月 |  | boolean |\n| isBigMonth     | 当前所在阴历月是否为大月 | | boolean |\n| lunarNewYearDay | 取得当年正月初一对应的公历日期 |  | Date |\n| lastDayOfYear | 取得当年的最后一天 |  | Date |\n| getYearName()  | 取得该阴历年正月初一所在的公历年, 返回汉字字符串 | | string |\n| phaseOfTheMoon | 取得当天月相，如朔、弦、望、晦等，不在上述其中之一者，返回空字符串 || string |\n| getMonthName() | 取得当前阴历月, 返回汉字字符串 | | string |\n| getDayName()   | 取得当前阴历日, 返回汉字字符串 | | string |\n| getHourName()  | 取得当前时辰 | | string |\n| valueOf()      | 返回Date对象的valueOf(), 即时间戳 | | number |\n| toString()     | 返回当前阴历的格式化后的日期时间 如“二〇二二年六月二十未時” | | string |\n| getLunarNewYearDay(year?: number) | 取得当年正月初一对应的公历日期 | year?: number\u003cbr\u003e year为指定的年份，为空时则为Lunisolar已设定的年份 | Date |\n\n## 5 八字（天干地支）\n\n### 5.1 取得数据\n\n```javascript\nconst lsr = lunisolar('2022-07-18 14:40')\nconsole.log(lsr.char8.toString()) // '壬寅 丁未 壬申 丁未'\nconsole.log(lsr.char8.year.name) // 壬寅\nconsole.log(lsr.char8.year.stem.toString()) // 壬\nconsole.log(lsr.char8.year.branch.toString()) // 寅\nconsole.log(lsr.char8.month.toString()) // 丁未\nconsole.log(lsr.char8.day.toString()) // 壬申\nconsole.log(lsr.char8.hour.toString()) // 丁未\n\nconsole.log(lsr.format('cY cM cD cH')) // '壬寅 丁未 壬申 丁未'\n```\n\n### 5.2 Char8类\n\n通过`lunisolar().char8`取得`Char8`实例\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| list           | 取得八字四柱的天干地支对象列表 | | [[SB](#53-sb类),SB,SB,SB] |\n| year           | 年柱的干支对象 | | SB |\n| month          | 月柱的干支对象 | | SB |\n| day            | 日柱的干支对象 | | SB |\n| hour           | 时柱的干支对象 | | SB |\n| me             | 日主，即日柱的天干对象 |  | Stem |\n| valueOf()      | 返回一个8位10进程数字，每两位分别表时年月日时的天干地支序号 | | number |\n| toString()     | 返回格式化后的八字 如“壬寅 丁未 壬申 丁未” | | string |\n\n### 5.3 SB类\n\nSB干支对象, 为StemBranch的缩写\n\nChar8的年月日时四柱为四个SB对象，参见4.2 Char8对象，list, year, month, day, hour的返回类型\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value | 取得60干支顺序索引值  | | number |\n| name | 天干地支组合名，如‘甲子’  | | string |\n| stem | 天干对象 | | [Stem](#54-stem天干类) |\n| branch | 地支对象 | | [Branch](#55-branch地支类)  |\n| valueOf()      | 返回60干支顺序索引值 | | number |\n| toString()     | 返回格式化后天干地支字符串如 “壬寅” | | string |\n| missing | 取得旬空的地支 | | [Branch, Branch] |\n| takeSound | 五行纳音，需加载`takeSound`插件, 参考 [#8 纳音](#8-纳音) | | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 取得六十干支符串列表 | | string[] |\n\n### 5.4 Stem天干类\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value | 天干索引值，范围[0, 9]  | | number |\n| name | 天干名  | | string |\n| e5 | 五行属性对象 | | [Element5](#56-element5五行类) |\n| trigram8 | 纳甲配卦 | | [Trigram8](#57-trigram8-八卦类)\n| valueOf()      | 返回天干索引值 | | number |\n| toString()     | 返回天干字符串| | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 返回所有天干字符串列表| | string[] |\n\n### 5.5 Branch地支类\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value | 地支索引值，范围[0, 11]  | | number |\n| name | 地支名  | | string |\n| e5 | 五行属性对象 | | [Element5](#56-element5五行类) |\n| hiddenStems | 取得地支所藏的天干对象列表，长度最多3个，分别为 `[本气, 中 气, 余气]` | | Stem[] |\n| triad | 三合地支, 返回当前地支的另外两个与之三合的地支 | | [Branch, Branch] |\n| triadE5 | 三合的五行属性 | | Element5 |\n| group6 | 六合地支 | | Branch |\n| group6E5 | 六合五行属性 | | Element5 |\n| punishing | 相刑地支 | | Branch |\n| punishBy | 被什么地支所刑 | | Branch |\n| conflict | 相冲的地支 | | Branch |\n| destroying | 相破的地支 | | Branch |\n| harming | 相害的地支 | | Branch |\n| valueOf()      | 返回地支索引值 | | number |\n| toString()     | 返回地支字符串| | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 返回所有地支字符串列表| | string[] |\n\n### 5.6 Element5五行类\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value | 五行属性索引值，其顺序为`['木', '火', '土', '金', '水']`  | | number |\n| name | 五行名  | | string |\n| generating() | 取得**相生**（我生者）的五行，如实例为`木`，则返回实例为`火`的Element5对象 | |Element5 |\n| overcoming() | 取得**相克**（我克者）的五行，如实例为`木`，则返回实例为`土`的Element5对象 | |Element5 |\n| weakening() | 取得**相泄**（生我者）的五行，如实例为`木`，则返回实例为`水`的Element5对象 | |Element5 |\n| counteracting() | 取得**相侮**（克我者）的五行，如实例为`木`，则返回实例为`金`的Element5对象 | |Element5 |\n| valueOf()      | 返回五行属性索引值 | | number |\n| toString()     | 返回五行属性字符串| | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 返回天干字符串列表| | string[] |\n\n### 5.7 Trigram8 八卦类\n\n八卦中每卦都三爻，阴爻用0表示，阳爻用1表示。\n\n所以每个卦可以用3位2进程表示：\n\n| 卦名  | 符号 | 二进制  | 10进制 |\n| --- | ---  | --- | --- |\n| 乾  | ☰ | 111  | 7 |\n| 坤  | ☷ | 000  | 0 |\n| 坎  | ☵ | 010  | 2 |\n| 离  | ☲ | 101  | 5 |\n| 震  | ☳ | 001  | 1 |\n| 巽  | ☴ | 110  | 6 |\n| 艮  | ☶ | 100  | 4 |\n| 兑  | ☱ | 011  | 3 |\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value      | 八卦数值 | | number |\n| name     | 八卦名 | | string |\n| valueOf()      | 返回八卦数值 | | number |\n| toString()     | 返回八卦字符串| | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 返回八卦字符串列表| | string[] |\n\n### 5.8 八字增强插件\n\n如果你需要用到**八字十神**，**四柱神煞**等功能，需加载八字增强插件 **char8ex**, 具体请点击[**【本连接】**](https://lunisolar.js.org/guide/plugins/char8ex.html)查看插件文档\n\n## 6 节气\n\n6.1 通过`lunisolar().solarTerm` 取得当前日期节气对象，如果当前日期不是节气，返回null\n\n6.2 通过 `lunisolar().recentSolarTerm(nodeFlag:number)` 取得当前日期之前的最近的节气点\n\n参数:\n  nodeFlag : number\n  nodeFlag = 0： 取得最近的节\n  nodeFlag = 1:  取得最近的气\n  nodeFlag = 2:  节和气哪个近就取哪个\n\n6.3 通过 `lunisolar.SolarTerm` 取得`SolarTerm`类以调用静态方法\n\n6.4 节气类 SolarTerm\n\n| 属性或方法  | 描述 | 参数  | 返回类型 |\n| --- | ---  | --- | --- |\n| value | 取得节气索引值  | | number |\n| name | 取得节气名称  | | string |\n| valueOf()      | 返回节气索引值 | | number |\n| toString()     | 返回节气字符串| | string |\n| **静态方法**   static method| | |  |\n| getNames()     | 返回节气字符串列表| | string[] |\n| getYearTermDayList(year)   | 取得某年的节气日期列表| -  **year**: *number* \u003cbr\u003e 指定某年 | number[] |\n| getMonthTerms(year, month)   | 取得某年某月的两个节气的日期 | - **year**: *number* \u003cbr\u003e 指定某年\u003cbr\u003e - **month**: *number*\u003cbr\u003e 某月 (1 ~ 12) | [number,number] |\n| findDate(year, termValue, config)   | 取得某年指定节气的日期 | - **year**: number \u003cbr\u003e 指定某年 \u003cbr\u003e - **termValue**: number \\| string \\| SolarTerm  \u003cbr\u003e 指定的节气 \u003cbr\u003e  - **config**: {\u003cbr\u003e  \u0026nbsp;\u0026nbsp; \u0026nbsp;\u0026nbsp;**lang**  \u003cbr\u003e}| [number, number, number] 分别为[year, month, day] |\n| findNode(date, config)   | 查出指定日期属于哪个节气之后，并返回该节气及该节气日期 | - **date**: *number* \u003cbr\u003e 指定日期\u003cbr\u003e - **config**: {\u003cbr\u003e  \u0026nbsp;\u0026nbsp; \u0026nbsp;\u0026nbsp;**lang**?: *string*, \u003cbr\u003e\u0026nbsp;\u0026nbsp; \u0026nbsp;\u0026nbsp;**returnValue**?: *boolean* 返回值的第一个元素是返回SolarTerm对象，还是返回节气索引，默认为`ture`, 即返回节气索引。\u003cbr\u003e\u0026nbsp;\u0026nbsp;  \u0026nbsp;\u0026nbsp;**nodeFlag**: *number* 0,1,2三个值可选，默认0，`0`返回`节`之后，`1`返回`气`之后，`2`返回最近的`节气`之后} | [`SolarTerm \\| number`, `Date`] 分别为 [`节气或节气索引`，`该节气对应的日期`] |\n\n## 7 胎神\n\n古人认为怀孕以及孕期胎儿的好坏都与胎神有关。所以民间传统习俗里，家里一旦有孕妇，便有各种禁忌，以免惊动胎神。\n\n胎神每日都会出现在不同的位置，参考《胎神逐日所占游方定局》。\n\n![fetalGod](./docs/images/fetalGod.jpg)\n\n其中天干地支与胎神位置的规律可用以下口诀记忆：\n\n```text\n  ----天干六甲胎神歌----\n  甲己之日占在門，乙庚碓磨休移动。\n  丙辛廚灶莫相干，丁壬倉庫忌修弄。\n  戊癸房床若移整，犯之孕妇堕孩童。\n\n  ----地支六甲胎神歌----\n  子午二日碓须忌，丑未廁道莫修移。\n  寅申火爐休要动，卯酉大門修当避。\n  辰戌雞棲巳亥床，犯着六甲身堕胎。\n```\n\n### 7.1 用法\n\n胎神占方插件请参考文档：[【胎神占方】](https://lunisolar.js.org/guide/plugins/fetalGod.html)\n\n查询胎神要先导入 fetalGod 插件，\n\n之后可使用lunisolar().fetalGod 取得胎神描述，\n\n也可以使用lunisolar().fetalGodData 取得胎神数据。\n\n```sh\nnpm install @lunisolar/plugin-fetalgod\n```\n\n示例：\n\n```typescript\nimport { fetalGod } from '@lunisolar/plugin-fetalgod'\nimport lunisolar from 'lunisolar'\n\nlunisolar.extend(fetalGod)\n\nconst lsr = lunisolar('2022-07-08')\nlsr.fetalGod // 倉庫棲外東南\nlsr.fetalGodData.stemPlace // 倉庫\nlsr.fetalGodData.branchPlace // 雞棲\nlsr.fetalGodData.direction // 外東南\nlsr.fetalGodData.description // 倉庫棲外東南\n```\n\nfetalGodData 包含以下属性\n\n| 属性  | 描述   | 返回类型 |\n| --- | ---  | --- |\n| stemPlace | 根据天干推算的胎神位置，有以下五种： ['門', '碓磨', '廚灶', '倉庫', '房床'] | string |\n| branchPlace  | 根据地支推算的胎神位置，有以下六种：['碓', '廁', '爐', '門', '雞棲', '床']| string |\n| direction | 胎神的方向，如'外东南'、'外西'、'内中' 等 | string |\n| description | 胎神占方的完整描述，如：\"占門碓外東南\" | string |\n\n## 8 纳音\n\n查询胎神要先导入 takeSound 插件，文档请参考 \n\n```sh\nnpm install @lunisolar/plugin-takesound\n```\n\n- `lunisolar().takeSound` 属性返回纳音描述字符串\n- `lunisolar().takeSoundE5` 属性返回**纳音五行**的Element5实例\n\n示例：\n\n```typescript\nimport { takeSound } from '@lunisolar/plugin-takesound'\nimport lunisolar from 'lunisolar'\n\nlunisolar.extend(takeSound)\n\n/**\n  加载takeSound插件后，\n  SB对象（天干地支对象）会添加一个takeSound属性，\n */\nconst lsr = lunisolar('2022-07-08')\nlsr.char8.year.takeSound // 金箔金 （取得年干支的纳音）\nlsr.char8.year.takeSoundE5.toString() // 金 （取得年干支的纳音五行）\n// ...\nlsr.char8.day.takeSound // 大海水 （取得日干支的纳音）\nlsr.takeSound // 大海水 （取得日干支的纳音 等同于 lsr.char8.day.takeSound）\n\n```\n\n## 9 建除十二神\n\n**建除十二神**，又称**十二值神**。即 “`建、除、满、平、定、执、破、危、成、收、开、闭`”共十二位神，每日轮值，周而复始，观所值以定吉凶。\n\n十二值神已归到神煞类之下，请参考[神煞宜忌](https://lunisolar.js.org/guide/plugins/theGods.html)\n\n## 10 神煞宜忌\n\n神煞宜忌的所有内容，主要基于 **《协纪辨方书》**\n\n因其数据内容较多，故作为一个插件单独介绍，请点击跳转到[【神煞宜忌】](https://lunisolar.js.org/guide/plugins/theGods.html)查看介绍和使用说明\n\n## 11 日期备注 Markers\n\n从2.3.0版本开始，可以通过Markers类，添加日期备注，如添加节日、备忘等。\n\nlunisolar内置了中国的各类节日列表，全局加载后，可通过lunisolar().markers实例取得该天的节日。 你也可以自定义添加日期节日、备忘等。 通过以下几个列子，可快速上手。\n\n更详细的使用请移步至文档 -\u003e [节日、日期备注 https://lunisolar.js.org/guide/functional/markers.html](https://lunisolar.js.org/guide/functional/markers.html)\n\n例: 全局添加内置的节日列表\n\n```typescript\nimport lunisolar from 'lunisolar'\n// 载入节日列表\nimport festivals from 'lunisolar/markers/festivals.zh'  // 繁体版\n// import festivals from 'lunisolar/markers/festivals.zh-cn' // 简体版\n\n// 全局加载节日列表\nlunisolar.Markers.add(festivals)\n\n// lunisolar('2023-10-01')实例下\nconst markersList = lunisolar('2023-10-01').markers.list \nconsole.log(markersList.map(v =\u003e v.name).join(',')) // 國際音樂節,國慶節\n\n```\n\n例：全局添加自定义的节日和日期备注\n\n```typescript\nimport lunisolar from 'lunisolar'\nimport type { MarkersSetting } from 'lunisolar'\n\n// 编写自定义的节日列表\nconst markersSetting: MarkersSetting = [{\n  format: 'MMDD',  // 将会使用lunisolar().format('MMDD')方法格式化日期\n  markers: {\n    '1019': { // 如果format方法返回值与此key匹配，则为当前日期会取得此marker\n      tag: '生日',\n      name: '我的生日'\n    },\n    '0919': {\n      tag: ['生日', '吐槽'], // tag可以是数组\n      name: '假的生日',\n      data: { // 可以通过data，设定任何信息以便取用\n        desc: '身份证是的生日写早了一个月, 所以公司都提早一个月给我庆生',\n        color: '#aa0000'\n      }\n    }\n  }\n}, {\n  format: 'lMn,lDn', // 农历月日\n  markers: {\n    '4,14': { // 农历四月十四\n      tag: '生日',\n      name: '吕洞宾诞辰',\n      data: {\n        desc: '西樵山大仙诞交通管制',\n        color: '#00cccc'\n      }\n    }\n  }\n}]\n\n\n// 再编写自定义的日期备注列表\nconst markersSetting2: MarkersSetting = [{\n  format: 'MMDD',  // 将会使用lunisolar().format('MMDD')方法格式化日期\n  markers: {\n    '1003': [{ //同一日期可以设定多个marker\n      tag: '任务',\n      name: '带家人出去吃饭'\n    }, {\n      tag: ['任务', '保险'],\n      name: '交汽车保险'\n    }]\n  }\n}]\n\n// 加载自定义的节日\n// Markers类add静态方法支持链式操作，add方法的第二参数可为节日列表全补打一个标签\nlunisolar.Markers.add(markersSetting, '自定义节日').add(markersSetting2, '自定义备忘')\n\n// lunisolar()实例的markers实例，可以取得对应日期marker数据\n\nconst lsr1003 = lunisolar('2023-10-03').markers.list // markers.list 取得markers数据列表\nconsole.log(lsr1003.map(v =\u003e v.name)) // ['带家人出去吃饭', '交汽车保险']\n\nconst lsr0919 = lunisolar('2023-09-19')\nconsole.log(lsr0919.markers.toString()) // '假的生日'\nconsole.log(lsr0919.markers.find({name:'假的生日'})?.data?.desc) // '身份证是的生日写早了一个月, 所以公司都提早一个月给我庆生'\n\n\n// 全局删除指定tag的marker\nlunisolar.Markers.removeByTag('吐槽')\n\nconsole.log(lunisolar('2023-09-19').markers.toString()) // 没有marker，输出空字符串\n\n// 但是原来已生成的实例并不会移除marker\nconsole.log(lsr0919.markers.toString()) // '假的生日'\n// 可在markers实例上使用reset方法重置该实例上的全局marker\nlsr0919.markers.reset()\nconsole.log(lsr0919.markers.toString()) // 没有marker，输出空字符串\n\n\n```\n\n例：直接在lunisolar()实例上添加日期备注\n\n```typescript\nimport lunisolar from 'lunisolar'\n\n// 可直接在指定的lunisolar().markers实例上添加该日的marker\nconst lsr = lunisolar('2023-10-30')\nlsr.markers.add({name: '买电烙铁', tag: '买东西'})\n\n// 多个markers可以以数组形式传入，或者以链式操作添加\nlsr.markers.add([{name: '练习多宝塔碑'}, {name: '临摹经飞经'}], '学习').add({name: '补充lunisolar.Markers相关文档', tag: '任务'})\n\n\nconsole.log(lsr.markers.toString()) // '买电烙铁,练习多宝塔碑,临摹经飞经,补充lunisolar.Markers相关文档'\n\n// 因为不是全局添加，其它实例即使日期相同，也取不到上边设置的这些marker\nconsole.log(lunisolar('2023-10-30').markers.list) // []\n\n```\n\n\n## 插件 plugins\n\nlunisolar支持自定义插件以扩展功能\n\n1，自定义插件\n\n```typescript\nimport { PluginFunc, Lunisolar } from 'lunisolar'\n\n// 为新添的属性加上类型声明 \ndeclare module 'lunisolar' {\n  interface Lunisolar {\n    showExample: string\n    exampleMethod(): void\n  }\n}\n\n\nconst pluginName: PluginFunc = async (options, lsClass, lsFactory) =\u003e {\n  const lsProto = lsClass.prototype\n  // 添加属性\n  lsProto.showExample = 'hello'\n\n  // 添加方法\n  lsProto.exampleMethod = function () {\n    console.log('hello')\n  }  \n}\nexport default pluginName\n```\n\n2 使用插件\n\n```typescript\nimport plugin from 'your/plugin/path/pluginName'\nimport lunisolar from 'lunisolar'\n\nlunisolar.extend(plugin)\n\nlunisolar().showExample // 'hello'\n```\n\n## 国际化\n\n`lunisolar`返回数据默认用`繁体中文`，主要考虑到这类使用人群往往有繁体需求，而且繁体也易于直接翻译成简体（由于一简对多繁，繁体可直接转为简体，但简体不能直接转为繁体）。\n\n尽管如此，lunisolar还是支持更改语言包。方法如下：\n\n```javascript\nimport lunisolar from 'lunisolar'\n// 加载英文语言包\nimport en from 'lunisolar/locale/en' \nlunisolar.locale(en)\n// 此时，lunisolar将全属使用en作为默认语言\nlunisolar('2017-12-01').char8.month.toString() // Xin-Hai\n\n// 如果locale方法第二参数设为true，加载语言包时不会变更默认使用的语言包\nlunisolar.locale(en, true)\n\n\n// --------------------------------------\n// 如果不想使用en作为全局默认语言，可通以下方法更改全局配置\nlunisolar.config({\n  lang: 'zh' // 设换默认语言为繁体中文\n})\n\n\nlunisolar('2017-12-01').char8.month.toString() // 辛亥\n\n// 局部使用指定语言 （须已先以lunisolar.locale()方法加载对应语言包）\nlunisolar('2017-12-01', { lang: 'en' }).char8.month.toString() // Xin-Hai\n\n```\n\nlunisolar内置的语言包有：\n\n```typescript\n// 繁体中文 (默认自动加载，请勿重复加载)\n// 语言包名：zh \nimport zh from 'lunisolar/locale/zh' \n\n// 简体中文\n// 语言包名：zh-cn \nimport zhCn from 'lunisolar/locale/zh-cn' \n\n// 英文\n// 语言包名：en \nimport en from 'lunisolar/locale/en' \n\n// 日文\n// 语言包名：ja \nimport ja from 'lunisolar/locale/ja'\n```\n\n### * 加载插件语言包\n\n使用内置插件时，需要另外加载插件的语言包 （**默认使用的繁体中文无需手动加载**）\n\n```typescript\nimport lunisolar from 'lunisolar'\nimport en from 'lunisolar/locale/en'\nimport takeSound from 'lunisolar/plugins/takeSound'\nimport takeSoundEn from 'lunisolar/plugins/takeSound/locale/en'\n\nlunisolar.locale(en).locale(takeSoundEn)\n\n```\n\n### * 对语言包进行自定义\n\n你可以对载入后的语言包进行修改，或者自定义一个语言包对原有的进行覆盖\n\n例如:\n\n```typescript\nimport lunisolar from 'lunisolar'\nconst { defineLocale } = lunisolar\n\n// 自定义语言包\nconst myZh = defineLocale({\n  name: 'zh' // 此项必需设置，指定要自义的语言, 可设为任意字符串，如果设为已导入的语言名，后续设置的项将会覆盖原有项\n  numerals: '零一二三四五六七八九十'.split(''),\n  stems: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']\n  branchs: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L']\n})\n\n// 载入语言包\nlunisolar.locale(myZh)\n\nlunisolar('2022/07/18 14:40').format('lY年 lMlD lH時') //  返回内容变成'二零二二年 六月二十 H時' 原本为 '二〇二二年 六月二十 未時'\nlunisolar('2022/07/18 14:40').format('cY') // 返回内容变成'iC' 原本为 '壬寅'\n```\n\n\u003e 具体设置项可参考项目中的语言包， `/src/locale/zh.ts`\n\u003e\n\u003e 自定义语言包时，并非所有项都是必填的，未配置的项会默认使用zh语言包所设置的数据。\n\n## 支持\n\n如果你喜欢本项目，给个Star是对作者最大的支持。\n\n如果你在使用中发现本程序有任何问题，或者对本程序的运算结果有什么任何异议，欢迎发布Issue。\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterbeside%2Flunisolar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaterbeside%2Flunisolar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaterbeside%2Flunisolar/lists"}