Emoji Moons

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

特性

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

安装

使用 npm 安装：

npm install emoji-moons

使用 yarn 安装：

yarn add emoji-moons

快速开始

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
}
*/

使用方法

基本使用

import { moon } from 'emoji-moons';

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

指定日期

// 使用日期字符串
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 类型支持

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 | 🌘 | 接近新月，只有一小部分月亮可见 |

错误处理

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

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

使用场景

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

许可证

MIT

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