Konwersja kalendarzy w JavaScript Temporal: Opanowanie mapowania dat między kalendarzami

Świat funkcjonuje w oparciu o więcej niż tylko kalendarz gregoriański. Firmy rozwijające się globalnie muszą uwzględniać różnorodne święta kulturowe i religijne, z których każde jest powiązane z określonymi systemami kalendarzowymi. Nowoczesne API Temporal w JavaScript dostarcza potężnych narzędzi do radzenia sobie z tymi złożonościami, pozwalając programistom na płynne mapowanie dat między kalendarzami i zapewnienie dokładnego planowania, obliczeń oraz prezentacji danych. Ten kompleksowy przewodnik zgłębia możliwości konwersji kalendarzy w API Temporal, oferując praktyczne przykłady i najlepsze praktyki tworzenia aplikacji świadomych globalnie.

Zrozumienie potrzeby mapowania dat między kalendarzami

Tradycyjne obiekty `Date` w JavaScript mają ograniczenia w obsłudze kalendarzy innych niż gregoriański. API Temporal rozwiązuje ten problem, zapewniając ustandaryzowany i solidny sposób pracy z różnymi systemami kalendarzowymi. Rozważmy następujące scenariusze:

• Planowanie spotkań międzynarodowych: Dokładne określenie równoważnej daty w kalendarzu islamskim (Hidżry) lub hebrajskim dla wydarzenia zaplanowanego w kalendarzu gregoriańskim jest kluczowe dla poszanowania świąt religijnych i wrażliwości kulturowej.
• Obliczanie odsetek od pożyczek w różnych regionach: Niektóre instytucje finansowe używają określonych kalendarzy do obliczania odsetek. Temporal pozwala na precyzyjną arytmetykę dat w tych systemach.
• Wyświetlanie dat w formatach preferowanych przez użytkownika: Dostosowanie wyświetlania dat do lokalizacji i preferencji kalendarza użytkownika poprawia doświadczenie użytkownika, szczególnie w aplikacjach skierowanych do zróżnicowanych populacji.
• Analiza danych historycznych: Podczas pracy z historycznymi zbiorami danych, zrozumienie i konwersja dat zapisanych w starszych lub mniej popularnych kalendarzach staje się niezbędne do ich prawidłowej interpretacji.

Wprowadzenie do API Temporal i kalendarzy

API Temporal, obecnie szeroko wspierane w nowoczesnych środowiskach JavaScript, oferuje bardziej intuicyjny i potężny sposób pracy z datami, czasem i strefami czasowymi. W jego rdzeniu obiekt `Temporal.Calendar` reprezentuje określony system kalendarzowy. Temporal.PlainDate, Temporal.PlainDateTime i inne typy Temporal mogą być powiązane z instancją `Temporal.Calendar`.

API Temporal obecnie obsługuje następujące kalendarze (w momencie pisania tego tekstu):

• `iso8601` (gregoriański - domyślny)
• `gregory` (alias dla `iso8601`)
• `islamic`
• `islamic-umalqura`
• `islamic-tbla`
• `islamic-rgsa`
• `islamic-civil`
• `hebrew`
• `buddhist`
• `roc` (Republika Chińska)
• `japanese`
• `persian`

Przyszłe wersje mogą wprowadzić więcej kalendarzy lub pozwolić na niestandardowe implementacje kalendarzy.

Podstawowa konwersja kalendarzy z Temporal.PlainDate

Obiekt `Temporal.PlainDate` reprezentuje datę bez strefy czasowej. Możesz utworzyć `Temporal.PlainDate` powiązany z określonym kalendarzem:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = Temporal.PlainDate.from({ year: 1445, month: 6, day: 8, calendar: islamicCalendar });

console.log(gregorianDate.toString()); // Wynik: 2024-01-20
console.log(islamicDate.toString());   // Wynik: 1445-06-08[u-ca=islamic]

Metoda `toString()` wyświetli datę z adnotacją kalendarza `[u-ca=islamic]`. Wskazuje to, że data jest powiązana z kalendarzem islamskim.

Konwersja między kalendarzami

Kluczem do konwersji między kalendarzami jest utworzenie obiektów `Temporal.PlainDate` powiązanych z każdym kalendarzem, a następnie wyodrębnienie odpowiednich składników daty. Oto jak przekonwertować datę gregoriańską na jej odpowiednik w kalendarzu islamskim:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');

// Wyodrębnij składniki daty w kalendarzu islamskim
const islamicYear = gregorianDate.toPlainDate(islamicCalendar).year;
const islamicMonth = gregorianDate.toPlainDate(islamicCalendar).month;
const islamicDay = gregorianDate.toPlainDate(islamicCalendar).day;

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic: ${islamicYear}-${islamicMonth}-${islamicDay}`); // Wynik: Islamic: 1445-6-8

Przeanalizujmy ten przykład:

1. Zaczynamy od `gregorianDate` reprezentowanej jako obiekt `Temporal.PlainDate`.
2. Tworzymy obiekt `islamicCalendar` za pomocą `Temporal.Calendar.from('islamic')`.
3. Główna konwersja odbywa się za pomocą `gregorianDate.toPlainDate(islamicCalendar)`. Tworzy to nowy obiekt `Temporal.PlainDate` reprezentujący ten sam punkt w czasie, ale teraz powiązany z kalendarzem islamskim.
4. Wyodrębniamy składniki `year`, `month` i `day` z przekonwertowanego obiektu `Temporal.PlainDate`.

Możesz dostosować ten wzorzec do konwersji między dowolnymi dwoma kalendarzami obsługiwanymi przez API Temporal.

Zaawansowana obsługa kalendarzy: Kalendarze islamskie

Kalendarz islamski ma kilka odmian. API Temporal obsługuje następujące:

• `islamic`: Ogólny kalendarz islamski (implementacja może się różnić).
• `islamic-umalqura`: Oparty na kalendarzu Umm al-Qura z Arabii Saudyjskiej.
• `islamic-tbla`: Oparty na obliczeniach tabelarycznych.
• `islamic-rgsa`: Oparty na Religijnym Generalnym Sekretariacie Awqaf (Egipt).
• `islamic-civil`: Czysto arytmetyczna wersja kalendarza islamskiego, używana głównie do obliczeń.

Pracując z kalendarzem islamskim, kluczowe jest zrozumienie, która odmiana jest odpowiednia dla Twojego przypadku użycia. Na przykład, w przypadku świąt religijnych w Arabii Saudyjskiej, prawdopodobnie będziesz chciał użyć `islamic-umalqura`. Do obliczeń finansowych, `islamic-civil` może być bardziej odpowiedni ze względu na jego przewidywalną naturę.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const islamicUmalquraCalendar = Temporal.Calendar.from('islamic-umalqura');
const islamicCivilCalendar = Temporal.Calendar.from('islamic-civil');

const islamicUmalquraDate = gregorianDate.toPlainDate(islamicUmalquraCalendar);
const islamicCivilDate = gregorianDate.toPlainDate(islamicCivilCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic (Umm al-Qura): ${islamicUmalquraDate.year}-${islamicUmalquraDate.month}-${islamicUmalquraDate.day}`);
console.log(`Islamic (Civil): ${islamicCivilDate.year}-${islamicCivilDate.month}-${islamicCivilDate.day}`);

Ważne uwagi dotyczące kalendarzy islamskich:

• Początek nowego miesiąca w kalendarzu islamskim opiera się na obserwacji nowego sierpa księżyca. Kalendarz `islamic-umalqura` ma na celu dostosowanie się do faktycznych obserwacji księżyca w Arabii Saudyjskiej, ale nadal mogą występować rozbieżności.
• Kalendarz `islamic-civil` jest matematycznym przybliżeniem i nie odzwierciedla rzeczywistych obserwacji księżyca.
• Zawsze konsultuj się z odpowiednimi władzami religijnymi lub wiarygodnymi źródłami w celu uzyskania dokładnych dat świąt islamskich.

Praca z kalendarzem hebrajskim

Kalendarz hebrajski to kalendarz księżycowo-słoneczny używany do żydowskich obrzędów religijnych oraz jako oficjalny kalendarz w Izraelu. Zawiera miesiące przestępne, aby zachować zgodność z porami roku.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');

const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Hebrew: ${hebrewDate.year}-${hebrewDate.month}-${hebrewDate.day}`);

Kluczowe cechy kalendarza hebrajskiego i Temporal:

• Miesiące przestępne są automatycznie obsługiwane przez API Temporal. Nie musisz implementować niestandardowej logiki do określania lat przestępnych ani dodawania dodatkowych miesięcy.
• Numeracja lat zaczyna się od tradycyjnej epoki żydowskiej (stworzenia świata).
• Nazwy miesięcy w kalendarzu hebrajskim różnią się od kalendarza gregoriańskiego. Możesz uzyskać dostęp do tych nazw miesięcy za pomocą bibliotek internacjonalizacji (i18n) lub niestandardowych mapowań.

Obsługa kalendarzy buddyjskiego, ROC, japońskiego i perskiego

API Temporal obsługuje również inne kalendarze, z których każdy ma swoje własne osobliwości. Oto kilka uwag:

• Kalendarz buddyjski: Kalendarz buddyjski to kalendarz księżycowo-słoneczny używany w wielu krajach Azji Południowo-Wschodniej. Numeracja lat zazwyczaj zaczyna się od śmierci Buddy.
• Kalendarz ROC (Republika Chińska): Ten kalendarz jest używany na Tajwanie i numeruje lata od założenia Republiki Chińskiej w 1912 roku.
• Kalendarz japoński: Kalendarz japoński opiera się na kalendarzu gregoriańskim, ale używa japońskich nazw er (nengō) do oznaczania lat.
• Kalendarz perski: Kalendarz perski to kalendarz słoneczny używany głównie w Iranie i Afganistanie.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const buddhistCalendar = Temporal.Calendar.from('buddhist');
const rocCalendar = Temporal.Calendar.from('roc');
const japaneseCalendar = Temporal.Calendar.from('japanese');
const persianCalendar = Temporal.Calendar.from('persian');

const buddhistDate = gregorianDate.toPlainDate(buddhistCalendar);
const rocDate = gregorianDate.toPlainDate(rocCalendar);
const japaneseDate = gregorianDate.toPlainDate(japaneseCalendar);
const persianDate = gregorianDate.toPlainDate(persianCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Buddhist: ${buddhistDate.year}-${buddhistDate.month}-${buddhistDate.day}`);
console.log(`ROC: ${rocDate.year}-${rocDate.month}-${rocDate.day}`);
console.log(`Japanese: ${japaneseDate.year}-${japaneseDate.month}-${japaneseDate.day}`);
console.log(`Persian: ${persianDate.year}-${persianDate.month}-${persianDate.day}`);

Podczas korzystania z tych kalendarzy, bądź świadomy ich specyficznej epoki (roku początkowego) i wszelkich niuansów kulturowych związanych z reprezentacją dat.

Temporal.Now a kwestie związane z kalendarzem

Chociaż `Temporal.Now` może być używane do uzyskania bieżącej daty i czasu, ważne jest, aby zrozumieć, że domyślnie zwraca bieżącą datę i czas w kalendarzu ISO 8601. Jeśli potrzebujesz bieżącej daty w innym kalendarzu, musisz ją przekonwertować:

const islamicCalendar = Temporal.Calendar.from('islamic');
const now = Temporal.Now.plainDateISO(); // Bieżąca data w kalendarzu ISO 8601
const islamicNow = now.toPlainDate(islamicCalendar);

console.log(`Current Gregorian Date: ${now.toString()}`);
console.log(`Current Islamic Date: ${islamicNow.year}-${islamicNow.month}-${islamicNow.day}`);

Formatowanie dat i internacjonalizacja (i18n)

Konwersja dat to tylko część równania. Musisz je również poprawnie sformatować do wyświetlenia. API `Intl.DateTimeFormat` w JavaScript zapewnia potężne możliwości internacjonalizacji. Możesz go używać w połączeniu z API Temporal do formatowania dat w sposób uwzględniający ustawienia regionalne, biorąc pod uwagę powiązany kalendarz.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

const formatter = new Intl.DateTimeFormat('ar-SA-u-ca-islamic', { // Arabski (Arabia Saudyjska) z kalendarzem islamskim
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(islamicDate)); // Przykładowy wynik: ٢٠ رجب، ١٤٤٥ هـ

Przeanalizujmy kod:

• `'ar-SA-u-ca-islamic'` to ciąg znaków lokalizacji. `ar-SA` określa język arabski (Arabia Saudyjska), a `u-ca-islamic` jawnie żąda kalendarza islamskiego.
• Opcje `Intl.DateTimeFormat` kontrolują sposób formatowania daty (rok, miesiąc, dzień).
• Metoda `format()` przyjmuje obiekt `Temporal.PlainDate` (w tym przypadku `islamicDate`) i zwraca sformatowany ciąg znaków zgodnie z określoną lokalizacją i kalendarzem.

Możesz dostosować ciąg znaków lokalizacji i opcje formatowania do swoich specyficznych potrzeb. Na przykład, aby sformatować datę w języku hebrajskim:

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');
const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

const formatter = new Intl.DateTimeFormat('he-IL-u-ca-hebrew', { // Hebrajski (Izrael) z kalendarzem hebrajskim
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(hebrewDate));

Wskazówki dotyczące efektywnego formatowania dat:

• Używaj ciągów znaków lokalizacji, które dokładnie odzwierciedlają preferowany język i region użytkownika.
• Wybieraj opcje formatowania odpowiednie dla kontekstu (np. krótkie formaty dat dla kompaktowych wyświetlaczy, długie formaty dat dla szczegółowych prezentacji).
• Testuj swoje formatowanie w różnych lokalizacjach, aby zapewnić dokładność i czytelność.

Wykonywanie arytmetyki dat między kalendarzami

API Temporal doskonale radzi sobie z arytmetyką dat. Możesz dodawać lub odejmować dni, miesiące lub lata od obiektu `Temporal.PlainDate`, nawet pracując z kalendarzami innymi niż gregoriański.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

// Dodaj 30 dni do daty islamskiej
const futureIslamicDate = islamicDate.add({ days: 30 });

console.log(`Original Islamic Date: ${islamicDate.year}-${islamicDate.month}-${islamicDate.day}`);
console.log(`Islamic Date + 30 days: ${futureIslamicDate.year}-${futureIslamicDate.month}-${futureIslamicDate.day}`);

// Przekonwertuj przyszłą datę islamską z powrotem na gregoriańską
const futureGregorianDate = futureIslamicDate.toPlainDate('iso8601');
console.log(`Equivalent Gregorian Date: ${futureGregorianDate.toString()}`);

Kluczowe uwagi dotyczące arytmetyki dat:

• Metody `add()` i `subtract()` zwracają nowe obiekty `Temporal.PlainDate`; nie modyfikują one oryginalnego obiektu.
• Podczas dodawania lub odejmowania miesięcy lub lat, API Temporal obsługuje specyficzne dla kalendarza zasady dotyczące lat przestępnych i długości miesięcy.
• Należy pamiętać o potencjalnych przepełnieniach lub niedopełnieniach daty podczas wykonywania operacji arytmetycznych. API Temporal zazwyczaj dostosuje datę do najbliższej prawidłowej daty w danym kalendarzu.

Obsługa niejednoznacznych dat

W niektórych przypadkach data może być niejednoznaczna podczas konwersji między kalendarzami. Może się to zdarzyć, gdy dana data nie istnieje w kalendarzu docelowym lub gdy wiele dat w kalendarzu docelowym może odpowiadać dacie źródłowej. Temporal radzi sobie z takimi sytuacjami z wdziękiem, zazwyczaj zwracając najbliższą prawidłową datę.

Na przykład, rozważ konwersję daty gregoriańskiej blisko końca miesiąca gregoriańskiego na kalendarz islamski, gdzie odpowiadający mu miesiąc islamski może być krótszy. Temporal automatycznie dostosuje wynikową datę islamską do ostatniego dnia tego miesiąca.

Obsługa błędów i walidacja

Chociaż API Temporal jest solidne, niezbędne jest wdrożenie odpowiedniej obsługi błędów i walidacji, aby zapobiec nieoczekiwanemu zachowaniu. Oto kilka typowych scenariuszy do rozważenia:

• Nieprawidłowe nazwy kalendarzy: Jeśli podasz nieprawidłową nazwę kalendarza do `Temporal.Calendar.from()`, rzuci to błąd `RangeError`. Złap ten błąd i przekaż przyjazny dla użytkownika komunikat.
• Nieprawidłowe formaty dat: Jeśli spróbujesz utworzyć `Temporal.PlainDate` z nieprawidłowego ciągu znaków daty, rzuci to błąd `RangeError`. Waliduj ciągi znaków daty przed przekazaniem ich do `Temporal.PlainDate.from()`.
• Nieobsługiwane operacje: Niektóre operacje specyficzne dla kalendarza mogą nie być obsługiwane przez API Temporal. Sprawdź dokumentację dla konkretnego kalendarza, którego używasz.

Dobre praktyki mapowania dat między kalendarzami

Aby zapewnić dokładność i łatwość w utrzymaniu podczas pracy z mapowaniem dat między kalendarzami, postępuj zgodnie z poniższymi dobrymi praktykami:

• Używaj API Temporal: API Temporal zapewnia ustandaryzowany i solidny sposób obsługi konwersji kalendarzy. Unikaj używania do tego celu przestarzałych obiektów `Date` z JavaScript.
• Określaj kalendarze jawnie: Zawsze jawnie określaj kalendarz podczas tworzenia obiektów `Temporal.PlainDate`. Zapobiega to niejednoznaczności i zapewnia zastosowanie poprawnych reguł kalendarzowych.
• Wybierz odpowiednią odmianę kalendarza islamskiego: Zrozum różnice między różnymi implementacjami kalendarza islamskiego i wybierz tę, która jest najbardziej odpowiednia dla Twojego przypadku użycia.
• Używaj internacjonalizacji (i18n): Wykorzystaj API `Intl.DateTimeFormat` do formatowania dat w sposób uwzględniający ustawienia regionalne.
• Wdróż obsługę błędów: Wdróż solidną obsługę błędów, aby wyłapywać nieprawidłowe nazwy kalendarzy, formaty dat i inne potencjalne problemy.
• Testuj dokładnie: Testuj swój kod z różnymi datami i lokalizacjami, aby zapewnić dokładność i kompatybilność.
• Bądź na bieżąco: API Temporal wciąż ewoluuje. Bądź na bieżąco z najnowszymi specyfikacjami i implementacjami w przeglądarkach.

Podsumowanie

API Temporal w JavaScript rewolucjonizuje sposób, w jaki obchodzimy się z datami i kalendarzami, zapewniając potężny i ustandaryzowany sposób na mapowanie dat między kalendarzami. Rozumiejąc niuanse różnych systemów kalendarzowych i efektywnie wykorzystując API Temporal, programiści mogą tworzyć aplikacje świadome globalnie, które odpowiadają na różnorodne potrzeby kulturowe i religijne. Wykorzystaj API Temporal, aby tworzyć bardziej inkluzywne i dokładne rozwiązania do obsługi dat w swoich projektach.

Ten przewodnik przedstawił kompleksowy przegląd konwersji kalendarzy za pomocą API Temporal w JavaScript. Pamiętaj, aby konsultować się z oficjalną dokumentacją API Temporal w celu uzyskania najbardziej aktualnych informacji i szczegółowych specyfikacji.