# emoji-moons

**Repository Path**: nodets/emoji-moons

## Basic Information

- **Project Name**: emoji-moons
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-21
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Emoji Moons

一个轻量级 TypeScript 库，用于获取指定日期的月亮信息，包括月相、月龄和对应的 emoji 符号。

[![NPM](https://img.shields.io/npm/v/emoji-moons.svg)](https://www.npmjs.com/package/emoji-moons)
[![License](https://img.shields.io/npm/l/emoji-moons.svg)](LICENSE)
[![Types](https://img.shields.io/npm/types/emoji-moons.svg)](https://www.typescriptlang.org/)

## 特性

- 🌕 获取任意日期的月相信息
- 🚀 轻量级实现，零依赖
- 📝 完整的 TypeScript 类型支持
- 🌍 国际化支持（中文描述）
- ⚡ 简单易用的 API

## 安装

使用 npm 安装：

```bash
npm install emoji-moons
```

使用 yarn 安装：

```bash
yarn add emoji-moons
```

## 快速开始

```typescript
import { moon } from 'emoji-moons';

// 获取今天的月亮信息
const todayMoon = moon();
console.log(todayMoon);
/*
{
  date: 2024-05-20T00:00:00.000Z,
  phase: 'full-moon',
  emoji: '🌕',
  description: '满月 - 整个月亮可见，地球位于太阳和月亮之间',
  age: 15.2
}
*/
```

## 使用方法

### 基本使用

```typescript
import { moon } from 'emoji-moons';

// 获取今天的月亮信息
const todayMoon = moon();
console.log(todayMoon.emoji); // 🌕
```

### 指定日期

```typescript
// 使用日期字符串
const moonInfo1 = moon('2023-12-25');

// 使用不同格式的日期字符串
const moonInfo2 = moon('January 1, 2024');

// 使用Date对象
const moonInfo3 = moon(new Date(2024, 0, 1));

// 输出示例
console.log(moonInfo1);
/*
{
  date: 2023-12-25T00:00:00.000Z,
  phase: 'waning-crescent',
  emoji: '🌘',
  description: '残月 - 接近新月，只有一小部分月亮可见',
  age: 27.3
}
*/
```

### TypeScript 类型支持

```typescript
import { moon, MoonInfo, MoonPhase } from 'emoji-moons';

const moonInfo: MoonInfo = moon();
const phase: MoonPhase = moonInfo.phase;

// MoonPhase 类型包括:
// 'new-moon' | 'waxing-crescent' | 'first-quarter' | 'waxing-gibbous' 
// 'full-moon' | 'waning-gibbous' | 'last-quarter' | 'waning-crescent'
```

## API 参考

### `moon(date?: string | Date): MoonInfo`

获取指定日期的月亮信息。

#### 参数

- `date` (可选): 可以是日期字符串（如 `'2023-10-17'`）、Date 对象，或不提供（默认使用当前日期）

#### 返回值

返回一个包含以下属性的对象：

| 属性 | 类型 | 描述 |
|------|------|------|
| `date` | Date | 计算使用的日期（UTC 时间） |
| `phase` | MoonPhase | 月相标识符 |
| `emoji` | string | 对应的月亮 emoji |
| `description` | string | 月相的中文描述 |
| `age` | number | 月龄（月亮从新月开始的天数，0-30 之间） |

#### 月相类型

| 月相 | 标识符 | Emoji | 描述 |
|------|--------|-------|------|
| 新月 | `new-moon` | 🌑 | 月亮不可见，月球位于地球和太阳之间 |
| 眉月 | `waxing-crescent` | 🌒 | 新月之后，可看到一小部分月亮 |
| 上弦月 | `first-quarter` | 🌓 | 月亮右半部可见，呈半圆形 |
| 盈凸月 | `waxing-gibbous` | 🌔 | 超过一半的月亮可见，正在接近满月 |
| 满月 | `full-moon` | 🌕 | 整个月亮可见，地球位于月球和太阳之间 |
| 亏凸月 | `waning-gibbous` | 🌖 | 满月之后，超过一半的月亮可见但正在变小 |
| 下弦月 | `last-quarter` | 🌗 | 月亮左半部可见，呈半圆形 |
| 残月 | `waning-crescent` | 🌘 | 接近新月，只有一小部分月亮可见 |

## 错误处理

当传入无效的日期时，函数会抛出错误：

```typescript
try {
  const invalidMoon = moon('invalid-date');
} catch (error) {
  console.error(error.message); // "无效的日期字符串: invalid-date"
}
```

## 使用场景

- 📅 日历应用中的月相显示
- 🌿 农业应用中的农历信息
- 🎨 设计项目中的天文元素
- 📚 教育应用中的天文知识展示
- 📱 移动应用中的日期装饰元素

## 许可证

[MIT](LICENSE)

---

**注意**：月龄计算使用简化算法，可能存在 ±1 天的误差。如需更高精度，请参考专业的天文计算库。