DateIntervalFormatter — alapok, dátumintervallumok formázása

Mi az a DateIntervalFormatter?

DateIntervalFormatter a Foundation Formatter alosztálya, amely egy DateInterval objektumot (két dátum közötti tartományt) fogad és egy lokalizált sztringet ad vissza a tartomány leírásával. Például a 2024. július 21-től 25-ig tartó tartomány esetén az eredmény „21–25. július 2024.“ lesz a hu_HU és „Jul 21–25, 2024“ az en_US számára. Az osztály intelligensen csoportosítja az ismétlődő elemeket: ha mindkét dátum ugyanabban a hónapban van, a hónap neve egyszer jelenik meg.

A DateIntervalFormatter fő értéke a tartományok nyelvtanának automatikus feldolgozása. Kézi formázásnál a fejlesztőnek össze kellene hasonlítania a kezdet és vég hónapját/évét, ki kellene választania az elválasztót (kötőjel, „től–ig“, „to”, „bis”) és figyelnie kellene a ragozást. A DateIntervalFormatter ezt automatikusan végzi a CLDR (Common Locale Data Repository) adatai alapján, ami csökkenti a hibák számát a nemzetközi alkalmazásokban, különösen az összetett nyelvtanú nyelveknél.

A Unicode CLDR v44 (2024) szerint a dátumtartományok formázási szabályai jelentősen eltérnek a nyelvek között. A német a „bis” előjárót használja (21.–25. Juli 2024), a francia — „au” (du 21 au 25 juillet 2024), a japán — kötőjellel (2024 Jul 21–25). A DateIntervalFormatter mindezeket a változatokat lefedi a fejlesztő részéről többletkód nélkül.

Hogyan működik a DateIntervalFormatter a Foundation-ben?

Működési elv A DateIntervalFormatter a tartományt alkotó két dátum elemzésén és az optimális szöveges megjelenítés kiválasztásán alapul, figyelembe véve a locale-t. Az osztály összehasonlítja a dátumkomponenseket (év, hónap, nap) és dönt a csoportosításról: ha az év azonos — egyszer jelenik meg; ha a hónap azonos — egyszer jelenik meg; ha a napok különböznek — a napok tartománya jelenik meg.

Csoportosítási logika CLDR-minták alapján van megvalósítva. A formázó ellenőrzi az egyes dátumkomponensek (Calendar.Component: year, month, day) egyenlőségét a legnagyobbtól a legkisebbig. Amint egy komponens eltér, az összes kisebb komponens mindkét dátum esetén megjelenik. Például a július 21–25. esetén: az év egyezik, a hónap egyezik, a nap eltér → hónap egyszer, napok — minden dátumhoz külön.

Fontos nuance: A DateIntervalFormatter nem támogatja az elválasztó API-n keresztüli konfigurálását. Az elválasztót a locale határozza meg és nem írható felül. Ha egyéni elválasztóra van szükség (például „–“ helyett „-től -ig”), kézzel kell formáznia a dátumokat a DateFormatter segítségével és összeragasztania a sztringeket az egyéni elválasztóval.

Intervallumformázási stílusok

DateIntervalFormatter két stíluskészletet kínál: dateStyle és timeStyle — a tartomány mindkét végéhez. Ezek a stílusok a DateFormatter-hez hasonlóan működnek: a .none elrejti a komponenst, a .short rövid formátumot ad (21.07.2024), a .medium — közepes (2024. júl. 21.), a .long — hosszú (2024. július 21.), a .full — maximálisan részletes (vasárnap, 2024. július 21.). A dateStyle és timeStyle kombinálásával különböző részletességi szintek érhetők el.

Stíluskombinációk példái

• dateStyle = .medium, timeStyle = .none — csak dátum: „21–25. július 2024.“
• dateStyle = .short, timeStyle = .short — dátum és idő: „21.07.2024, 14:30 – 25.07.2024, 16:45”
• dateStyle = .none, timeStyle = .short — csak idő: „14:30–16:45” (ha a dátumok azonosak)
• dateStyle = .long, timeStyle = .none — hosszú dátum: „21–25. július 2024.“
• dateStyle = .full, timeStyle = .short — teljes formátum: „vasárnap, 2024. július 21. – csütörtök, 2024. július 25.”

Fontos: A dateStyle és timeStyle egyformán vonatkozik a tartomány mindkét végére. Nem állítható be különböző stílus a kezdet és a vég számára (például .medium a kezdethez és .short a véghez). Ha eltérő stílusra van szükség, minden dátumot külön DateFormatter-rel kell formáznia és az eredményeket összeragasztania.

import Foundation

let formatter = DateIntervalFormatter()

// Különböző stíluskombinációk
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 nap
let interval = DateInterval(start: startDate, end: endDate)

// Csak dátum, közepes formátum
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("Csak dátum: \(formatter.string(from: interval))")

// Rövid formátum idővel
formatter.dateStyle = .short
formatter.timeStyle = .short
print("Rövid idővel: \(formatter.string(from: interval))")

// Teljes formátum
formatter.dateStyle = .full
formatter.timeStyle = .none
print("Teljes dátum: \(formatter.string(from: interval))")

DateIntervalFormatter Swift-ben: példák

Alapvető használat A DateIntervalFormatter létrehozását, a stílusok konfigurálását és a string(from:) meghívását foglalja magában. A metódus egy DateInterval — start és end tulajdonságokkal rendelkező struktúra — fogad. A DateInterval létrehozható két Date-ből, valamint Duration segítségével is (iOS 16+). A formázás után az eredmény további feldolgozás nélkül készen áll a UI-ban való megjelenítésre.

import Foundation

let calendar = Calendar.current
let now = Date()

// Konkrét intervallum példák
let examples: [(title: String, start: Date, end: Date)] = [
    (
        "2-hour event",
        now,
        now.addingTimeInterval(7200)
    ),
    (
        "Week-long vacation",
        now,
        now.addingTimeInterval(604800)
    ),
    (
        "Cross-year period",
        calendar.date(from: DateComponents(
            year: 2024, month: 12, day: 25
        ))!,
        calendar.date(from: DateComponents(
            year: 2025, month: 1, day: 5
        ))!
    )
]

let intervalFormatter = DateIntervalFormatter()
intervalFormatter.dateStyle = .medium
intervalFormatter.timeStyle = .short

for (title, start, end) in examples {
    let interval = DateInterval(start: start, end: end)
    let result = intervalFormatter.string(from: interval)
    print("\(title): \(result)")
}

// Formázás Calendar segítségével (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("Következő 7 nap: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter és Calendar Booking: a foglalási alkalmazásokban (szállodák, jegyek) a dátumtartományok a UI kulcsfontosságú elemei. A DateIntervalFormatter helyesen kezeli az év váltásán átnyúló tartományokat (például december 28-tól január 3-ig), a hónapot és évet minden dátumhoz külön csoportosítva. Az ilyen forgatókönyvekhez ajánlott a dateStyle = .medium és timeStyle = .none használata — a legolvashatóbb formátum az idő nélküli dátumokhoz.

import Foundation

let formatter = DateIntervalFormatter()
formatter.dateStyle = .long
formatter.timeStyle = .none

// Foglalási példák
struct Booking {
    let checkIn: Date
    let checkOut: Date

    var formattedInterval: String {
        let interval = DateInterval(start: checkIn, end: checkOut)
        return formatter.string(from: interval)
    }
}

let booking = Booking(
    checkIn: calendar.date(from: DateComponents(
        year: 2024, month: 7, day: 21
    ))!,
    checkOut: calendar.date(from: DateComponents(
        year: 2024, month: 7, day: 25
    ))!
)
print("Foglalás: \(booking.formattedInterval)")

// Használat különböző locale-okkal
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("Angol: \(enFormatter.string(from: interval))")

DateInterval vs DateIntervalFormatter: DateInterval — egy dátumtartományt reprezentáló struktúra (kezdet és vég). DateIntervalFormatter — a struktúrát sztringgé alakító formázó. A DateInterval emellett támogatja a contains(Date) és intersection(with:) ellenőrzéseket, ami hasznos a foglalási logikához (dátumok átfedésének ellenőrzése).

Dátumintervallumok lokalizálása

DateIntervalFormatter a locale tulajdonságon keresztül lokalizálja a kimenetet. Alapértelmezett Locale.current — a készülék locale-ja. Az intervallumok más nyelven való megjelenítéséhez (például angol tartalom magyar felületen) állítsa be explicit a locale-t. Ellentétben a DateFormatter-rel, a DateIntervalFormatter nem igényli a Locale beállítását a szerveradatokhoz — mindig a saját, CLDR-alapú belső csoportosítási logikáját használja.

A dátumtartományok formázásának nyelvi különbségei jelentősen bonyolultabbak, mint az egyes dátumoké. Az angol egyszerű kötőjelet használ: Jul 21–25. A magyar — a „től–ig” előjárót: július 21-től 25-ig. A francia — „au”: du 21 au 25 juillet. A német — pont a szám után és kötőjel: 21.–25. Juli. A japán — kötőjellel előjáró nélkül: Jul 21–25. A DateIntervalFormatter mindezeket a változatokat lefedi.

import Foundation

let formatter = DateIntervalFormatter()
formatter.dateStyle = .medium
formatter.timeStyle = .none

let start = Date()
let end = Date().addingTimeInterval(259200) // +3 nap
let interval = DateInterval(start: start, end: end)

// Különböző locale-ok bemutatása
let localeIds = ["ru_RU", "en_US", "de_DE", "fr_FR", "ja_JP", "zh_CN"]
for localeId in localeIds {
    formatter.locale = Locale(identifier: localeId)
    print("\(localeId): \(formatter.string(from: interval))")
}

// Lokalizáció időintervallumokhoz
formatter.dateStyle = .none
formatter.timeStyle = .short

let todayStart = Date()
let todayEnd = Date().addingTimeInterval(3600)
let timeInterval = DateInterval(start: todayStart, end: todayEnd)

for localeId in ["ru_RU", "en_US", "de_DE"] {
    formatter.locale = Locale(identifier: localeId)
    print("\(localeId) idő: \(formatter.string(from: timeInterval))")
}

Lokalizációs jellemzők: a magyar nyelv esetén a DateIntervalFormatter a „től” és „ig” előjárókat használja a hosszú dátumformátumokhoz. A rövid (short) formátumhoz — csak kötőjel: 21.07–25.07.2024. A teljes formátumhoz (full) — a hét napjának megjelölésével. A formátum kiválasztása a kontextustól függ: foglalási listához használjon .medium, részletes nézethez .long vagy .full értéket.

Összehasonlítás más dátumformázókkal

DateIntervalFormatter betölti a dátumtartományok formázásának rést, amelyet más Foundation osztályok nem fednek le. A DateFormatter egyes dátumokat, a RelativeDateTimeFormatter relatív dátumokat (ezelőtt/múlva), a DateComponentsFormatter időtartamot (2 óra 30 perc) formáz. Ezen osztályok mindegyike a saját feladatát oldja meg és nem cserélhetők fel.

Mikor használja a DateIntervalFormatter-t: dátumtartományok UI-ban való megjelenítéséhez — szállodafoglalás, események, szűrés dátum szerint, művelettörténet. A dátumok közötti időtartam kiszámításához használja a DateComponentsFormatter-t, ne a DateIntervalFormatter-t — az utóbbi nem időtartam megjelenítésére való. A DateFormatter-t csak egyes dátumokhoz használja, ne két formázott dátum sztring-összefűzéssel történő összeragasztásához — ez az elválasztó lokalizációjának elvesztéséhez vezet.

Határeset: A DateIntervalFormatter nem támogatja a nyitott tartományok (végdátum nélkül) megjelenítését. Ha a tartomány vége ismeretlen (például „július 21-től”), használja a DateFormatter-t a „-től” előjáróval a magyar nyelvhez vagy „from” az angolhoz. A DateIntervalFormatter emellett nem támogatja a különböző napokhoz időt rendelő tartományokat — az idő minden dátumra külön vonatkozik, ami rövid tartományok esetén túlzó lehet.