jalali_date

Persian (Jalali, Shamsi) calendar for Dart. It converts between Gregorian and Jalali dates in both directions, knows leap years and month lengths, does date arithmetic, parses and formats dates with Persian month and weekday names and Persian digits, and has everything a date picker needs: Saturday-first weeks, month anchors, day ranges, and bounds. It reads dates written with a pattern or with month names, writes relative time (3 روز پیش), dates in Persian words, and parts of the day (صبح, عصر), counts whole months and years, and gives the moment of Nowruz (سال تحویل). The conversion is a port of jalaali-js, so century years and leap cycles are handled correctly. It also gives the lunar Hijri date as Iran's official calendar counts it, and writes and reads years in the Shahanshahi numbering when you ask for it. Iranian official holidays are in the companion package iranian_holidays: it calculates them offline on the device, the lunar Hijri ones included, or fetches them from an online source you choose (holidayapi.ir, Calendarific, or Google Calendar), and can fall back from online to offline. It is pure Dart with no dependencies and works on the Web, Flutter, and the Dart VM.

Also known as the Shamsi, Khorshidi, Solar Hijri, Hijri Shamsi, or Iranian calendar. Keywords: تقویم شمسی، تقویم جلالی، تقویم خورشیدی، هجری شمسی، هجری قمری، سال شاهنشاهی، تعطیلات رسمی ایران، تاریخ فارسی، تبدیل تاریخ میلادی به شمسی و شمسی به میلادی.

معرفی به فارسی

jalali_date یک بسته‌ی خالص Dart برای تقویم هجری شمسی (جلالی، خورشیدی) است. تاریخ میلادی را به شمسی و شمسی را به میلادی تبدیل می‌کند، سال کبیسه و طول ماه‌ها را می‌داند و تاریخ را با نام فارسی ماه‌ها و روزهای هفته و ارقام فارسی نمایش می‌دهد. جمع و تفریق روز و ماه و سال، خواندن تاریخ از متن (با ارقام فارسی یا لاتین)، هفته‌ی شنبه تا جمعه و بازه‌ی تاریخ را هم دارد و برای ساختن انتخابگر تاریخ (date picker) آماده است. تاریخ نوشته‌شده با الگو یا نام ماه (مثل ۴ فروردین ۱۴۰۳) را می‌خواند، زمان نسبی (۳ روز پیش)، تاریخ با حروف و بخش‌های روز (صبح، عصر، شب) را می‌نویسد، ماه‌ها و سال‌های کامل (مثلاً سن) را می‌شمارد و لحظه‌ی تحویل سال را می‌دهد. تاریخ هجری قمری را مطابق تقویم رسمی ایران هم می‌دهد و در صورت نیاز سال را به شاهنشاهی می‌نویسد و می‌خواند. تعطیلات رسمی ایران در بسته‌ی همراه iranian_holidays است: آن‌ها را بدون اینترنت روی خود دستگاه محاسبه می‌کند، تعطیلات قمری هم، یا از یک منبع آنلاین به انتخاب شما (holidayapi.ir، Calendarific یا Google Calendar) می‌گیرد، و اگر منبع آنلاین در دسترس نباشد می‌تواند به محاسبه‌ی آفلاین برگردد. الگوریتم تبدیل از jalaali-js گرفته شده و برای سال‌های قرن میلادی و چرخه‌های کبیسه درست کار می‌کند. به Flutter وابسته نیست و روی وب، Flutter و Dart VM اجرا می‌شود.

final date = PersianDate.fromGregorian(2021, 3, 21);
print(date); // 1400/01/01
print(date.format('EEEE d MMMM yyyy')); // یکشنبه 1 فروردین 1400
print(date.toString(persianDigits: true)); // ۱۴۰۰/۰۱/۰۱
print(PersianDate.parse('۱۳۵۷/۱۱/۲۲').toDateTime()); // 1979-02-11 00:00:00.000

Installation

jalali_date is published on pub.dev:

dart pub add jalali_date

Or with Flutter:

flutter pub add jalali_date

Then import the single library:

import 'package:jalali_date/jalali_date.dart';

Quick reference

Everything is exported from package:jalali_date/jalali_date.dart: the immutable PersianDate class, the PersianDateRange class, the HijriDate and IranianHijri classes, the toPersianDigits, toLatinDigits, and toPersianWords functions, the JalaliEra enum, and the DateTime.toPersianDate() and DateTime.toHijriDate() extensions. Every class and member is described in the API reference.

Creating

Member	Description
PersianDate(int year, int month, int day)	From Jalali values, date-only; throws ArgumentError for an invalid date
PersianDate.withTime(year, month, day, [hour, minute, second])	From Jalali values with a local time of day
PersianDate.now()	Current local date and time
PersianDate.fromDateTime(DateTime)	From a DateTime; keeps time of day and time zone
DateTime.toPersianDate()	Extension, the same as fromDateTime
PersianDate.fromGregorian(int year, int month, int day)	From Gregorian values; overflow rolls over like DateTime
PersianDate.fromGregorianString(String)	From an ISO 8601 Gregorian string, via DateTime.parse
PersianDate.parse(String, {era}), tryParse(String, {era})	From a Jalali string such as 1403/01/01 or ۱۴۰۳-۱-۱ ۱۴:۳۰
PersianDate.parseFormat(String, String pattern, {era}), tryParseFormat(...)	From text written with a format pattern, such as ۴ فروردین ۱۴۰۳
PersianDate.fromJson(String), toJson()	yyyy-MM-dd for storage and jsonEncode
PersianDate.min, PersianDate.max	First and last supported day
copyWith({year, month, day})	Copy with fields replaced; validates, never clamps

This is the beginning of the README. Read the rest at the original. Read the full README ↗