Flutter伊斯兰历日历插件hijri_calendar的使用

欢迎来到 Hijri Calendar 库！这个Dart库可以帮助你轻松地处理回历日期。无论你是想创建、验证还是转换回历日期，这个库都能满足你的需求！🎉

功能 ✨

• 创建回历日期：使用不同的构造函数创建回历日期：

  • HijriCalendarConfig.now() - 获取当前回历日期
  • HijriCalendarConfig.fromGregorian() - 将公历转换为回历
  • HijriCalendarConfig.fromHijri() - 创建特定回历日期

• 日期转换：

  • 使用 hijriToGregorian(year, month, day) 将回历日期转换为公历
  • 使用 fromGregorian() 将公历日期转换为回历

• 日历配置：

  • 设置语言偏好（例如，‘ar’ 表示阿拉伯语）
  • 支持通过构造函数或 setAdjustments() 方法进行自定义日期调整

• 日期工具：

  • 使用 getDaysInMonth(year, month) 获取特定回历月份的天数
  • 使用 formatDate(year, month, day, pattern) 格式化回历日期

• 验证：

  • 内置回历日期验证
  • 公历日期范围验证（1937-2076）

调整的理解 🔧

回历中的调整用于根据当地月球观测或特定区域差异来微调日期。以下是它们的工作原理：

调整格式

• 调整以 Map<int, int> 的形式提供
• 键：儒略日编号（JDN）
• 值：调整值（-1、0 或 1）

如何计算JDN

// 示例：计算2023年5月17日的JDN
DateTime date = DateTime(2023, 5, 17);
int jdn = (date.millisecondsSinceEpoch / 86400000).floor() + 2440588;

设置调整

// 方法1：通过构造函数
var calendar = HijriCalendarConfig(adjustments: {
  16800: 1,  // 当JDN为16800时加一天
  16801: -1, // 当JDN为16801时减一天
});

// 方法2：使用setAdjustments方法
calendar.setAdjustments({
  16802: 1,
  16803: -1,
});

设置调整

• 1：将计算出的日期加一天
• -1：将计算出的日期减一天
• 0：无需调整

特定月份、日期、年份的调整

要对特定月份、日期和年份设置调整，首先需要计算该特定回历日期的JDN。以下是一个示例：

// 示例：调整1444年斋月1日
int year = 1444;
int month = 9; // 斋月
int day = 1;

// 计算特定回历日期的JDN
DateTime gregorianDate = HijriCalendarConfig.hijriToGregorian(year, month, day);
int jdn = (gregorianDate.millisecondsSinceEpoch / 86400000).floor() + 2440588;

// 为该JDN设置调整
calendar.setAdjustments({
  jdn: 1, // 为1444年斋月1日加一天
});

使用场景

• 地区月球观测差异
• 与当地伊斯兰教历法机构保持一致
• 根据实际观察纠正计算出的日期

安装 📦

要在项目中使用回历库，请将其添加到 pubspec.yaml 文件中：

dependencies:
  hijri_calendar: ^1.0.0

使用 🚀

以下是使用回历库的一个简单示例：

基本用法

import 'package:hijri_calendar/hijri_calendar.dart';

void main() {
  // 创建一个当前日期的回历配置实例
  var hijriCalendar = HijriCalendarConfig.now();
  print(hijriCalendar); // 打印当前回历日期

  // 将特定公历日期转换为回历
  var specificDate = HijriCalendarConfig.fromGregorian(DateTime(2023, 5, 17));
  print(specificDate); // 打印相应的回历日期

  // 直接创建一个回历日期
  var hijriDate = HijriCalendarConfig.fromHijri(1444, 10, 27);
  print(hijriDate); // 打印指定的回历日期

  // 将回历转换为公历
  DateTime gregorianDate = hijriDate.hijriToGregorian(1444, 10, 27);
  print(gregorianDate); // 打印相应的公历日期
}

高级用法

// 设置语言为阿拉伯语
HijriCalendarConfig.language = 'ar';

// 创建具有自定义调整的日历
var customCalendar = HijriCalendarConfig(adjustments: {16800: 1, 16801: -1});

// 初始化后设置调整
var calendar = HijriCalendarConfig.now();
calendar.setAdjustments({16802: 1, 16803: -1});

// 获取特定回历月份的天数
int daysInMonth = calendar.getDaysInMonth(1444, 10);
print('Days in Shawwal 1444: $daysInMonth');

// 格式化特定日期
String formattedDate = calendar.formatDate(1444, 10, 27, "dd/mm/yyyy");
print('Formatted date: $formattedDate');

// 新增兼容性API
// 桥接方法添加一个月
var nextMonth = HijriCalendarConfig.bridgeAddMonth(1444, 11);
print('Next month: ${nextMonth.fullDate()}');

// 从DateTime创建
var fromDate = HijriCalendarConfig.bridgeFromDate(DateTime.now());
print('Current date: ${fromDate.fullDate()}');

// 用特定模式格式化回历日期
var hijriDate = HijriCalendarConfig.fromHijri(1444, 10, 27);
print('Formatted: ${hijriDate.toFormat("DDDD, MMMM dd, yyyy")}');

// 获取月份和日期名称
print('Month name: ${hijriDate.getLongMonthName()}');
print('Short month: ${hijriDate.getShortMonthName()}');
print('Day name: ${hijriDate.getDayName()}');

// 日期比较方法
var compareDate = HijriCalendarConfig.fromHijri(1444, 11, 1);
print('Is before: ${hijriDate.isBefore(1444, 11, 1)}');
print('Is after: ${hijriDate.isAfter(1444, 9, 1)}');
print('Same moment: ${hijriDate.isAtSameMomentAs(1444, 10, 27)}');

// 获取日历信息
var months = hijriDate.getMonths();
print('All months: $months');

// 获取特定月份的天数
var monthDays = hijriDate.getMonthDays(1444, 10);
print('Days in month: $monthDays');

// 转换为列表格式
List<int?> dateList = hijriDate.toList();
print('Date as list: $dateList'); // [1444, 10, 27]

// 获取年长度
int yearLength = hijriDate.lengthOfYear();
print('Days in year: $yearLength');

// 验证日期
print('Is valid date: ${hijriDate.isValid()}');

// 添加新本地化
HijriCalendarConfig.addLocale('fr', {
  'long': {1: 'Mouharram', 2: 'Safar', /* ... */},
  'short': {1: 'Mou', 2: 'Saf', /* ... */},
  'days': {1: 'Lundi', /* ... */},
  'short_days': {1: 'Lun', /* ... */}
});