### Installation with npm/yarn

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Installs the lunisolar library using either npm or yarn package managers.

```bash
npm install lunisolar
# or
yarn add lunisolar
```

--------------------------------

### Installation

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Provides instructions for installing the lunisolar library for Node.js environments and for direct use in browsers via script tags.

```javascript
// Node.js environment
import lunisolar from 'lunisolar'

// Browser direct script import
// <script src="path/to/lunisolar.js"></script>
// const d = lunisolar('2022/07/18 14:40');

```

--------------------------------

### Lunisolar TheGods Plugin Installation and Usage

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Demonstrates how to install and use the TheGods plugin with the lunisolar library. It shows how to import the plugin, extend lunisolar with it, and then use its methods to retrieve various almanac data like monthly gods, daily gods, twelve gods (Jianchu, Changsheng, Chuangong), auspicious/inauspicious acts, and hourly fortunes.

```typescript
import lunisolar from 'lunisolar'
import theGods from 'lunisolar/plugins/theGods'
lunisolar.extend(theGods)

const lsr = lunisolar('2018-10-04')
// Get gods
lsr.theGods.getGods('M') // Get monthly gods
lsr.theGods.getGods('D') // Get daily gods
lsr.theGods.getGods('MD') // Get monthly and daily gods
lsr.theGods.getDuty12God() // Get Jianchu 12 gods
lsr.theGods.getLife12God('day') // Get Changsheng 12 gods
lsr.theGods.getBy12God('day') // Get Chuangong 12 gods

// Get auspicious/inauspicious acts
lsr.theGods.getActs(0) // Get daily acts {good: string[], bad: string[]}
lsr.theGods.query('this day gods') // Get gods for the day
lsr.theGods.query('good act 1') // Get auspicious acts (60 events)
lsr.theGods.query('bad act 1') // Get inauspicious acts (60 events)
lsr.theGods.query('good act 2') // Get auspicious acts (67 events)
lsr.theGods.query('bad act 2') // Get inauspicious acts (67 events)
lsr.theGods.query('good act 3') // Get auspicious acts (37 events)
lsr.theGods.query('bad act 3') // Get inauspicious acts (37 events)
lsr.theGods.query('good act') // Get all auspicious acts
lsr.theGods.query('bad act') // Get all inauspicious acts

// Get hourly fortunes
lunisolar('2022-10-21').theGods.getLuckHours() // [-1, -1, 1, 1, -1, 1, -1, -1, 1, -1, 1, 1] (1 for good, -1 for bad)

// Get auspicious direction
const [d24, god] = lunisolar('2022-11-25').theGods.getLuckDirection('財神')
d24.direction // 'South'
d24.sign.toString() // '午'
d24.angle // 180
```

--------------------------------

### Custom Plugin Example

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates how to create a custom plugin for lunisolar by adding new properties and methods to the Lunisolar class prototype. This allows for extending the library's functionality.

```typescript
import { PluginFunc, Lunisolar } from 'lunisolar'

// 为新添的属性加上类型声明 
declare module 'lunisolar' {
  interface Lunisolar {
    showExample: string
    exampleMethod(): void
  }
}


const pluginName: PluginFunc = async (options, lsClass, lsFactory) => {
  const lsProto = lsClass.prototype
  // 添加属性
  lsProto.showExample = 'hello'

  // 添加方法
  lsProto.exampleMethod = function () {
    console.log('hello')
  }  
}
export default pluginName
```

--------------------------------

### Lunisolar Date Formatting Examples

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates various ways to format date and time information using the `format()` method of the Lunisolar class, including lunar dates, celestial stems and branches, and zodiac signs.

```javascript
lunisolar('2022/07/18 14:40').format('YYYY/MM/DD HH:mm:ss SSS') // '2022/07/18 14:40:00 000'
lunisolar('2022/07/18 14:40').format('lY年 lMlD lH時') // '二〇二二年 六月二十 未時'
lunisolar('2022/07/18 14:40').format('lY年 lM(lL)lD lH時') // '二〇二二年 六月(大)二十 未時'
lunisolar('2022/07/18 14:40').format('lYn年 農歷lMn月lDn日 第lHn個時辰') // '2022年 農歷6月20日 第8個時辰'
lunisolar('2022/07/18 14:40').format('cY cM cD cH') // '壬寅 丁未 壬申 丁未'
lunisolar('2022/07/18 14:40').format('[八字：] cY cM cD cH') // '八字：壬寅 丁未 壬申 丁未'
lunisolar('2022/03/10').format('cZ年') // '虎年'
lunisolar('2022/03/10').format('cYs-cYb cMs-cMb cDs-cDb cHs-cHb') // ''壬-寅 丁-未 壬-申 丁-未''
```

--------------------------------

### Lunisolar Class Properties and Methods

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

This section details the properties and methods available on a Lunisolar instance. Properties include lunar data, char8 data, and solar terms. Methods allow for getting seasons, converting to Date objects, cloning, getting timestamps, formatting dates, calculating time differences, adding/subtracting time, and managing UTC settings.

```APIDOC
Lunisolar Class:

Properties:
  lunar: Lunar data object. Returns [Lunar](./lunar.md).
  char8: Char8 object. Returns [Char8](./char8.md).
  solarTerm: Returns the solar term object for the current date, or null if not a solar term. Returns [SolarTerm](./solarTerm.md) | null.
  year: Year. Returns number.
  month: Month (1-12). Returns number.
  day: Day (1-31). Returns number.
  dayOfWeek: Day of the week (0-6, 0 is Sunday). Returns number.
  hour: Hour (0-23). Returns number.
  minute: Minute (0-59). Returns number.
  second: Second (0-59). Returns number.
  millis: Milliseconds (0-999). Returns number.

Methods:
  getSeason(): Gets the current season. Returns string.
  getSeasonIndex(): Gets the current season index in the order of Spring, Summer, Autumn, Winter. Returns number.
  toDate(): Returns a Date object. Returns Date.
  clone(): Clones the current Lunisolar object. Returns Lunisolar.
  unix(): Returns the timestamp in seconds. Returns number.
  format(formatStr: string): Formats the time according to the specified format string. Parameters:
    formatStr: string - The format string for the time, e.g., 'YYYY-MM-DD HH:mm:ss'. Returns string.
  diff(date, unit, float): Calculates the time difference. Parameters:
    date: number | string | Date | Lunisolar - The date to compare with the current instance.
    unit: string - The unit of difference, e.g., 'year', 'lunarYear', 'month', 'lunarMonth'.
    float: boolean - Whether to return a floating-point number. Returns number.
  add(value, unit): Adds or subtracts time. Parameters:
    value: number - The value to add or subtract, negative for subtraction.
    unit: string - The unit for addition/subtraction. Returns number.
  utc(): Converts to UTC mode. Returns Lunisolar.
  isUTC(): Checks if the instance is in UTC mode. Returns boolean.
  utcOffset(offset): Gets or sets the UTC offset. Parameters:
    offset: number | undefined - If undefined, gets the UTC offset in minutes. If a number, sets the UTC offset and converts the time to UTC, returning a new Lunisolar instance. If the offset is between [-16, 16], it's in hours; otherwise, it's in minutes. Returns Lunisolar | number.
  local(): Converts to local time. Returns Lunisolar.
  valueOf(): Returns the valueOf() of the Date object, i.e., the timestamp. Returns number.
  toISOString(): Returns the toISOString() of the Date object. Returns string.
  toUTCString(): Returns the toUTCString() of the Date object. Returns string.
  toString(): Returns the toUTCString() of the current Date object plus the formatted lunar date and time, e.g., 'Wed, 24 Aug 2022 14:50:51 GMT (二〇二二年七月廿七亥時)'. Returns string.
```

--------------------------------

### Char8Ex Plugin Integration

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/char8ex.md

Demonstrates how to install and extend lunisolar.js with the char8ex plugin. It also shows how to create a Char8Ex instance for a specific birth date and gender.

```javascript
// ---  安装
// 引入lunisolar
import lunisolar from 'lunisolar'
// 引入 theGods 插件
import char8ex from 'lunisolar/plugins/char8ex'
// 加载插件
lunisolar.extend(char8ex)


// ---  使用
// 创建一个Char8Ex实例对象, 该八字为 2023-01-15 12:26出生的男孩
const c8ex =  lunisolar('2023-01-15 12:26').char8ex(1)

console.log(c8ex.toString()) // 乾造: 壬寅 癸丑 癸酉 戊午

// Char8Ex实例可通过year,month,day,hour属性取得四柱实例 Pillar
// 而每个四柱实例（Pillar）又包含纳音、天干、地支、天干十神、地支十神、四柱神煞等功能查询

// 取各柱天干十神, 十神和神煞都是以对象形式存在
console.log(c8ex.year.stemTenGod.name) // 劫財
console.log(c8ex.month.stemTenGod.name) // 比肩
// 注：日主实际并不是十神之一，它位于日柱天干，十神以此推算。
console.log(c8ex.day.stemTenGod.name) // 日主
console.log(c8ex.hour.stemTenGod.name) // 正官

// 取各柱地支藏干十神
// 地支十神通过地支所藏天干推算，所以各柱的地支十神可能存在的个数为1至3个，故以数组形式返回
console.log(c8ex.year.branchTenGod.map(i => i.name)) // [ '傷官', '正財', '正官' ]
console.log(c8ex.month.branchTenGod.map(i => i.name)) // ['七殺', '比肩', '梟神']
console.log(c8ex.day.branchTenGod.map(i => i.name)) // ['梟神']
console.log(c8ex.hour.branchTenGod.map(i => i.name)) // ['偏財', '七殺']

//取年柱纳音
console.log(c8ex.year.takeSound) // 金箔金

//空亡地支 missing属性返回一个元组，该元组包含两个地支实例： [Branch, Branch]
// c8ex.missing 等同于 c8ex.day.missing
console.log(c8ex.missing.map(i => i.name)) //  [ '戌', '亥' ]

// 取得年柱上的神煞,其它柱类似
console.log(c8ex.year.gods.map(item => item.name)) // ['文昌貴人', '金輿', '天廚貴人', '劫煞']

```

--------------------------------

### Customizing Language Packs

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Provides an example of how to customize or override existing language packs in lunisolar. The `defineLocale` function allows modification of specific locale properties or creation of entirely new ones.

```typescript
import lunisolar from 'lunisolar'
const { defineLocale } = lunisolar

// 自定义语言包
const myZh = defineLocale({
  name: 'zh' // 此项必需设置，指定要自义的语言, 可设为任意字符串，如果设为已导入的语言名，后续设置的项将会覆盖原有项
  numerals: '零一二三四五六七八九十'.split(''),
  stems: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']
  branchs: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L']
})

// 载入语言包
lunisolar.locale(myZh)

lunisolar('2022/07/18 14:40').format('lY年 lMlD lH時') //  返回内容变成'二零二二年 六月二十 H時' 原本为 '二〇二二年 六月二十 未時'
lunisolar('2022/07/18 14:40').format('cY') // 返回内容变成'iC' 原本为 '壬寅'
```

--------------------------------

### Get Activities (getActs)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves auspicious and inauspicious activities for a given day. Supports filtering by activity type and returning keys or translated names. Allows for custom replacements in activity descriptions.

```typescript
theGods.getActs(actType?: 0 | 1 | 2 | 3, returnKey?: boolean, replacer?: {}): {good: string[], bad: string[]}

/**
 actType: 0 | 1 | 2 | 3
  宜忌类型
  defalut: 0
  0：所有词条，不会按通书、御用、民事里的词条进行筛选
  1：按`通书六十事`的词条进行筛选，不在此60个词条内者，不会出现
  2：按`御用六十七事`的词条进行筛选
  3: 按`民用三十七事`的词条进行筛选
*/

/**
 returnKey：boolean
  是否返回宜忌key
  defalut: false
  false: 词条将按国际化翻译后返回
  true: 返回宜忌key，（本库宜忌以繁体中文作为key）
*/

/**
 replacer?:  { [key: string]: string }
  宜忌词条替换 
  default: undefined
  例如要把“剃頭”替換成"理髮" 可設定為 {剃頭: "理髮"}
*/
```

--------------------------------

### Creating Lunisolar from Lunar Data

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Shows how to create a Lunisolar instance from lunar calendar data, effectively converting lunar dates to Gregorian dates. It details the `LunarData` structure and provides examples using both numeric and Chinese character inputs for year, month, and day.

```typescript
// lunisolar.fromLunar(lunarData: LunarData, config: ConfigType): Lunisolar

// LunarData structure:
type LunarData = {
  year?: number | string
  month: number | string
  day: number | string
  hour?: number | string
  isLeapMonth?: boolean
}

// Example 1: Numeric lunar data
const lunarData = {
  year: 2022,
  month: 10,
  day: 25
}
const lsr = lunisolar.fromLunar(lunarData)
console.log(lsr.format('YYYY-MM-DD')) // Output: 2022-11-18

// Example 2: Using Chinese characters for lunar data (default Traditional Chinese)
const lunarDataChinese = {
    year: '二〇二〇',
    month: '閏四月', 
    day: '廿四'
  }
const lsrChinese = lunisolar.fromLunar(lunarDataChinese)
console.log(lsrChinese.format('YYYY-MM-DD')) // Output: 2020-06-15
```

```typescript
// Example 3: Loading and using different language packs (Simplified Chinese and Japanese)
import lunisolar from 'lunisolar'
import zhCn from 'lunisolar/locale/zh-cn'
import ja from 'lunisolar/locale/ja'

lunisolar.locale(ja) // Load Japanese locale
lunisolar.locale(zhCn) // Load Simplified Chinese locale (becomes the global default)

const lunarDataSimplified = {
    year: '二〇二〇',
    month: '闰四月',  // Note: Using '闰' from Simplified Chinese
    day: '廿四'
  }
const lsrSimplified = lunisolar.fromLunar(lunarDataSimplified)
console.log(lsrSimplified.format('YYYY-MM-DD')) // Output: 2020-06-15

// Using a specific locale for an instance
const lsrJapanese = lunisolar.fromLunar({
    year: '二〇二〇',
    month: '睦月', 
    day: '一日'
  }, {
  lang: 'ja' // Specify Japanese locale for this instance
})

console.log(lsrJapanese.format('YYYY-MM-DD')) // Output: 2020-01-25
```

--------------------------------

### Loading Plugin Language Packs

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Shows how to load language packs for plugins, specifically for the `takeSound` plugin. It demonstrates loading both the general English locale and the plugin-specific English locale.

```typescript
import lunisolar from 'lunisolar'
import en from 'lunisolar/locale/en'
import takeSound from 'lunisolar/plugins/takeSound'
import takeSoundEn from 'lunisolar/plugins/takeSound/locale/en'

lunisolar.locale(en).locale(takeSoundEn)
```

--------------------------------

### Creating a Lunisolar Instance

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Explains how to create a Lunisolar object using various input types such as strings, numbers (timestamps), Date objects, or other Lunisolar instances. It also shows how to pass a configuration object for language settings.

```typescript
// Creating a Lunisolar instance
// lunisolar(param: String | Number | Date | Lunisolar, config?: ConfigType): Lunisolar

// Using a string
lunisolar('2022-07-18 14:40')
lunisolar('2022/07/18')

// Without parameters (current time)
lunisolar()

// Using a timestamp (milliseconds)
lunisolar(1658289207143)

// Using a Date object
lunisolar(new Date(2022, 6, 20))

// Cloning another Lunisolar object
lunisolar(lunisolar())

// With configuration (e.g., language)
const config = {
  lang: 'en' // Requires loading the corresponding language pack
}
lunisolar('2022-07-18 14:40', config)
```

--------------------------------

### TheGods: Get Chuangong 12 Gods (Yellow/Black Path)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves the 'Chuangong 12 Gods' (串宫十二神), also known as the 'Yellow and Black Path Gods' (黄道黑道十二神). These include gods like Qinglong, Mingtang, Tianxing, etc. The function `getBy12God` takes a 'dh' parameter to specify whether to get the gods for the day ('day') or the hour ('hour').

```typescript
theGods.getBy12God(dh: 'day' | 'hour'): God
```

--------------------------------

### Including Lunisolar via Script Tag

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Shows how to include the lunisolar library in an HTML file using a script tag, either from a local path or a CDN like unpkg.

```html
<script src="path/to/lunisolar.js"></script>
<!-- or src from unpkg ( 请根据需求选择版本号 ↓ )-->
<script src="https://unpkg.com/lunisolar@2.1.12/dist/lunisolar.js"></script>
```

--------------------------------

### 安装和使用纳音插件

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

展示如何安装 `@lunisolar/plugin-takesound` 插件，并将其扩展到 lunisolar 实例。提供了获取纳音描述和纳音五行数据的代码示例。

```sh
npm install @lunisolar/plugin-takesound
```

```typescript
import { takeSound } from '@lunisolar/plugin-takesound'
import lunisolar from 'lunisolar'

lunisolar.extend(takeSound)

/**
  加载takeSound插件后，
  SB对象（天干地支对象）会添加一个takeSound属性，
 */
const lsr = lunisolar('2022-07-08')
lsr.char8.year.takeSound // 金箔金 （取得年干支的纳音）
lsr.char8.year.takeSoundE5.toString() // 金 （取得年干支的纳音五行）
// ...
lsr.char8.day.takeSound // 大海水 （取得日干支的纳音）
lunisolar('2022-07-08').takeSound // 大海水 （取得日干支的纳音 等同于 lsr.char8.day.takeSound）
```

--------------------------------

### Get Auspicious Activities (getGoodActs)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves only the auspicious activities for the current day. This method is an alias for `getActs` filtering for 'good' activities.

```typescript
theGods.getGoodActs(actType?: 0 | 1 | 2 | 3, returnKey?: boolean, replacer?: {}): string[]

// 參數與getActs相同
// 此方法等同于:
theGods.getActs(actType, returnKey, replacer).good
```

--------------------------------

### Basic Usage and Formatting

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates how to create a Lunisolar instance, format dates in lunar and solar formats, and access lunar properties like year, month, day, and hour.

```typescript
import lunisolar from 'lunisolar'

// Using a date string
const d = lunisolar('2022/07/18 14:40')

// --- format ---

d.format('lY年 lM(lL)lD lH時')  // Output: 二〇二二年 六月(大)二十 未時
d.format('cY cM cD cH')  // Output: 壬寅 丁未 壬申 丁未
d.format('YYYY-MM-DD HH:mm:ss') // Output: 2022-07-18 14:40:00

// --- Lunar --- 

d.lunar.toString() // Output: 二〇二二年六月二十未時
`${d.lunar}` // Output: 二〇二二年六月二十未時
d.lunar.year // 2022
d.lunar.getYearName() // Output: 二〇二二
d.lunar.month // 6 (returns 106 for a leap month)
d.lunar.getMonthName() // Output: 六月
d.lunar.day // 20
d.lunar.getDayName() // Output: 二十
d.lunar.hour // 7 (index of the hour, starting from 0)
d.lunar.getHourName() // Output: 未
d.lunar.isLeapMonth // false (indicates if it's a leap month)

// --- Bazi (Four Pillars of Destiny) ----

`${d.char8}` // Output: 壬寅 丁未 壬申 丁未
d.char8.year.toString() // Output: 壬寅 (Year Pillar)
d.char8.month.toString() // Output: 丁未 (Month Pillar)
d.char8.day.toString() // Output: 壬申 (Day Pillar)
d.char8.hour.toString() // Output: 丁未 (Hour Pillar)
d.char8.year.stem.toString() // Output: 壬 (Heavenly Stem of Year Pillar)
d.char8.year.branch.toString() // Output: 寅 (Earthly Branch of Year Pillar)
d.char8.year.branch.hiddenStems // [甲, 丙, 戊] (List of Heavenly Stems hidden in the Earthly Branch, in order: principal, secondary, tertiary)
// ... other pillars are similar

// Solar Terms
lunisolar('2022-07-23').solarTerm?.toString() // Output: 大暑 (Returns the solar term for the day, or null if it's not a solar term day)

// Lunar to Solar Conversion (Reverse Lookup)
lunisolar.fromLunar({
  year: 2022,
  month: 10,
  day: 25
}).format('YYYY-MM-DD') // Output: 2022-11-18

```

--------------------------------

### Get Inauspicious Activities (getBadActs)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves only the inauspicious activities for the current day. This method is an alias for `getActs` filtering for 'bad' activities.

```typescript
theGods.getBadActs(actType?: 0 | 1 | 2 | 3, returnKey?: boolean, replacer?: {}): string[]

// 參數與getActs相同
// 此方法等同于:
theGods.getActs(actType, returnKey, replacer).bad
```

--------------------------------

### Importing Lunisolar in TypeScript

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates how to import the lunisolar library in a TypeScript project, including necessary tsconfig.json settings for default imports.

```typescript
import lunisolar from 'lunisolar'

// If using TypeScript, ensure your tsconfig.json includes:
// {
//   "compilerOptions": {
//     "esModuleInterop": true,
//     "allowSyntheticDefaultImports": true,
//   }
// }
```

```typescript
import * as lunisolar from 'lunisolar'
```

--------------------------------

### Get All Day Hour Deities (getAllDayHourGods)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves all deities for each hour of the day. The result is a 2D array where each inner array represents an hour (from 子时 to 亥时) and contains deity objects.

```typescript
theGods.getAllDayHourGods(): God[][]

// 返回结果为二维数组：
[
  [God, God, ...], // 子时
  [God, God, God, ...], // 丑时
  [God, God, God, ...], // 寅时
  [God, God, ...], // 卯时
  [God, ...], // 辰时
  [God, ...], // 巳时
  ...
  ...
  [God, ...], //亥时
]
```

--------------------------------

### Get All Lucky Directions (getAllLuckDirection)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves the lucky directions for all deities of the day. It returns a list of tuples, where each tuple contains a '二十四山' object and a deity object, indicating the direction of auspicious deities.

```typescript
// 示例：
const lsr = lunisolar('2022-11-25')
const allDirections = lsr.theGods.getAllLuckDirection()
for (let i = 0; i < allDirections.length; i++) {
  const [d24, god] = allDirections[i]
  console.log(d24.direction, god.name)
}
// 南 喜神
// 東南 福神
// 南 財神
// 東 陽貴
// 東南 陰貴

// 取得当日所有神煞吉方

//  করিবে返回元素为`[二十四山对象, 神煞对象]`元组的列表

// 二十四山对象说明参考[本连接](./%E4%BA%8C%E5%8D%81%E5%9B%9B%E5%B1%B1.md)
```

--------------------------------

### Cloning a Lunisolar Instance

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates how to create a copy of an existing Lunisolar object using the `clone()` method.

```javascript
const lsr1 = lunisolar('2022-07-18 14:40')
const lsr2 = lsr1.clone()
```

--------------------------------

### 在lunisolar实例上直接添加日期备注

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

演示如何直接在特定的 `lunisolar()` 实例的 `markers` 属性上添加日期备注，这些备注仅对该实例生效，不会影响全局或其他实例。

```typescript
import lunisolar from 'lunisolar'

// 可直接在指定的lunisolar().markers实例上添加该日的marker
const lsr = lunisolar('2023-10-30')
lrs.markers.add({name: '买电烙铁', tag: '买东西'})

// 多个markers可以以数组形式传入，或者以链式操作添加
lrs.markers.add([{name: '练习多宝塔碑'}, {name: '临摹经飞经'}], '学习').add({name: '补充lunisolar.Markers相关文档', tag: '任务'})


console.log(lsr.markers.toString()) // '买电烙铁,练习多宝塔碑,临摹经飞经,补充lunisolar.Markers相关文档'

// 因为不是全局添加，其它实例即使日期相同，也取不到上边设置的这些marker
console.log(lunisolar('2023-10-30').markers.list) // []
```

--------------------------------

### Get Specific Lucky Direction (getLuckDirection)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves the direction of a specific deity. Accepts the deity's key name or translated name and returns a tuple containing the '二十四山' object and the deity object.

```typescript
// 示例：
const lsr = lunisolar('2022-11-25')
const [d24, god] = lsr.theGods.getLuckDirection('財神')
console.log(d24.direction) // 南

/**
 godKeyOrName:string
  吉方神煞名称，一般为 '喜神' | '福神' | '財神' | '陽貴' | '陰貴'
  可以是国际化翻译后的名称
  不在此范围内者，将返回null
*/
```

--------------------------------

### Configuring Default Language

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Demonstrates how to configure the default language for lunisolar using the `config` method. This sets the global default language for all instances.

```javascript
lunisolar.config({
  lang: 'zh' // 设换默认语言为繁体中文
})

lunisolar('2017-12-01').char8.month.toString() // 辛亥
```

--------------------------------

### Using Specific Language Locally

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Illustrates how to use a specific language for a single lunisolar instance without affecting the global default. This requires the desired locale to be loaded beforehand.

```javascript
// 局部使用指定语言 （须已先以lunisolar.locale()方法加载对应语言包）
lunisolar('2017-12-01', { lang: 'en' }).char8.month.toString() // Xin-Hai
```

--------------------------------

### Loading Language Packs

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Explains how to change the default language of lunisolar by loading different locale files. It also shows how to load a locale without changing the global default.

```javascript
import lunisolar from 'lunisolar'
// 加载英文语言包
import en from 'lunisolar/locale/en' 
lunisolar.locale(en)
// 此时，lunisolar将全属使用en作为默认语言
lunisolar('2017-12-01').char8.month.toString() // Xin-Hai

// 如果locale方法第二参数设为true，加载语言包时不会变更默认使用的语言包
lunisolar.locale(en, true)
```

--------------------------------

### Get Luck Hours (getLuckHours)

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves the luck status for each hour of the day. Returns an array of numbers where positive values indicate good luck and negative values indicate bad luck. The luck calculation can be based on different criteria.

```typescript
theGods.getLuckHours(luckType: 0 | 1 = 1): number[]
// 返回数组表示各时辰，数组元素指示吉凶，大于0为吉，小于0为凶
[1, 1, -1, 1, -1, -1, -1, -1, 1, 1, -1, -1]

/**
 luckeType: 0 | 1
  选择吉凶取法
  default: 0
  0: 按黄黑道十二神（即青龙明堂等）决定吉凶
  1：按黄黑道十二神（即青龙明堂等）决定吉凶
*/
```

--------------------------------

### 全局添加自定义节日和日期备注

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

展示如何定义自定义的节日和日期备注数据结构，并使用 `lunisolar.Markers.add()` 方法全局加载。包括如何按不同日期格式（MMDD, lMn,lDn）添加标记，以及如何使用 `tag` 和 `data` 属性。还演示了如何通过 `removeByTag` 删除标记以及 `reset` 方法。

```typescript
import lunisolar from 'lunisolar'
import type { MarkersSetting } from 'lunisolar'

// 编写自定义的节日列表
const markersSetting: MarkersSetting = [{
  format: 'MMDD',  // 将会使用lunisolar().format('MMDD')方法格式化日期
  markers: {
    '1019': { // 如果format方法返回值与此key匹配，则为当前日期会取得此marker
      tag: '生日',
      name: '我的生日'
    },
    '0919': {
      tag: ['生日', '吐槽'], // tag可以是数组
      name: '假的生日',
      data: { // 可以通过data，设定任何信息以便取用
        desc: '身份证是的生日写早了一个月, 所以公司都提早一个月给我庆生',
        color: '#aa0000'
      }
    }
  }
}, {
  format: 'lMn,lDn', // 农历月日
  markers: {
    '4,14': { // 农历四月十四
      tag: '生日',
      name: '吕洞宾诞辰',
      data: {
        desc: '西樵山大仙诞交通管制',
        color: '#00cccc'
      }
    }
  }
}]


// 再编写自定义的日期备注列表
const markersSetting2: MarkersSetting = [{
  format: 'MMDD',  // 将会使用lunisolar().format('MMDD')方法格式化日期
  markers: {
    '1003': [{
      tag: '任务',
      name: '带家人出去吃饭'
    }, {
      tag: ['任务', '保险'],
      name: '交汽车保险'
    }]
  }
}]

// 加载自定义的节日
// Markers类add静态方法支持链式操作，add方法的第二参数可为节日列表全补打一个标签
lunisolar.Markers.add(markersSetting, '自定义节日').add(markersSetting2, '自定义备忘')

// lunisolar()实例的markers实例，可以取得对应日期marker数据

const lsr1003 = lunisolar('2023-10-03').markers.list 
console.log(lsr1003.map(v => v.name)) // ['带家人出去吃饭', '交汽车保险']

const lsr0919 = lunisolar('2023-09-19')
console.log(lsr0919.markers.toString()) // '假的生日'
console.log(lsr0919.markers.find({name:'假的生日'})?.data?.desc) // '身份证是的生日写早了一个月, 所以公司都提早一个月给我庆生'


// 全局删除指定tag的marker
lunisolar.Markers.removeByTag('吐槽')

console.log(lunisolar('2023-09-19').markers.toString()) // 没有marker，输出空字符串

// 但是原来已生成的实例并不会移除marker
console.log(lsr0919.markers.toString()) // '假的生日'
// 可在markers实例上使用reset方法重置该实例上的全局marker
lsr0919.markers.reset()
console.log(lsr0919.markers.toString()) // 没有marker，输出空字符串
```

--------------------------------

### TheGods: Get Auspicious Gods

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves auspicious gods (吉神) for a given year, month, day, or hour. The `getGoodGods` method functions similarly to `getGods`, accepting 'Y', 'M', 'D', 'H', or combinations as the `ymdh` parameter. The default is 'MD'.

```typescript
theGods.getGoodGods(ymdh: 'Y' | 'M' | 'D' | 'H' | string): God[]
```

--------------------------------

### 全局添加内置节日列表

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

演示如何导入并全局加载 Lunisolar 内置的中国节日列表，并通过 `lunisolar().markers.list` 获取当天的节日信息。

```typescript
import lunisolar from 'lunisolar'
// 载入节日列表
import festivals from 'lunisolar/markers/festivals.zh'  // 繁体版
// import festivals from 'lunisolar/markers/festivals.zh-cn' // 简体版

// 全局加载节日列表
lunisolar.Markers.add(festivals)

// lunisolar('2023-10-01')实例下
const markersList = lunisolar('2023-10-01').markers.list 
console.log(markersList.map(v => v.name).join(',')) // 國際音樂節,國慶節
```

--------------------------------

### TheGods: Get Hourly Fortunes

Source: https://github.com/waterbeside/lunisolar/blob/main/docs/theGods.md

Retrieves the auspiciousness of each hour of the day. The `getLuckHours` method returns an array of numbers, where a positive number indicates a lucky hour and a negative number indicates an unlucky hour. This is useful for determining the best times for activities.

```typescript
theGods.getLuckHours(): number[]
```

--------------------------------

### SB (StemBranch) Class Documentation

Source: https://github.com/waterbeside/lunisolar/blob/main/README.md

Documentation for the SB class, representing StemBranch. It details properties like value, name, stem, branch, and methods such as valueOf(), toString(), missing, and takeSound. Static methods like getNames() are also included.

```APIDOC
SB (StemBranch):
  value: Get the 60-stem-branch sequence index value. (number)
  name: The combined name of the stem and branch, e.g., '甲子'. (string)
  stem: The Stem object. ([Stem](#54-stem天干类))
  branch: The Branch object. ([Branch](#55-branch地支类))
  valueOf(): Returns the 60-stem-branch sequence index value. (number)
  toString(): Returns the formatted stem-branch string, e.g., "壬寅". (string)
  missing: Gets the earthly branches that are in旬空 (Xun Kong). ([Branch, Branch])
  takeSound: Gets the five-element sound, requires loading the `takeSound` plugin. (string)

  Static Methods:
  getNames(): Gets a list of 60-stem-branch strings. (string[])
```