DateFormatter: əsas anlayışlar, tarix formatlaşdırma və lokalizasiya

DateFormatter nədir?

DateFormatter — Foundation çərçivəsindən Date ilə mətn arasında ikitərəfli çevirməni həyata keçirən sinifdir. O, OpenStep-də NSDateFormatter kimi ortaya çıxmışdır və o vaxtdan bəri Apple platformalarında tarixlərin formatlaşdırılması üçün əsas alət olaraq qalır. Sinif Formatter-dən miras alır və lokalizasiya olunmuş tarix göstərimi üçün rahat API təmin edir.

DateFormatter-in iş prinsipi Unicode LDML şablonlarına əsaslanır — eyni ICU (International Components for Unicode) da istifadə olunur. Şablon dateFormat xüsusiyyəti vasitəsilə təyin edilir, burada y, M, d, H, m, s simvolları müvafiq olaraq il, ay, gün, saat, dəqiqə və saniyəyə uyğun gəlir. Simvolun təkrarlanması formatı müyyənləşdirir: “y” — iki rəqəmli il, “yyyy” — dörd rəqəmli.

DateFormatter yaratmaq bahalı əməliyyatdır, çünki işə salma zamanı lokal və təqvim məlumatları yüklənir. Apple hər formatlaşdırma növü üçün formatlayıcını bir dəfə yaratmağı və onu təkrar istifadə etməyi tövsiyə edir. SwiftUI və UIKit-də formatlayıcılar tez-tez statik xüsusiyyətlərdə keşlənir və ya ilk müraciətdə tənbələşərək yaradılır.

iOS SDK-da DateFormatter

DateFormatter iOS-un bir çox sistem komponentlərində tətbiq olunur. UIDatePicker countDownTimer rejimində tarixləri göstərmək üçün daxilində DateFormatter istifadə edir. Girişdə formatlayıcı olan TextField istifadəçi tərəfindən daxil edilən tarixi avtomatik olaraq yoxlaya bilər. Core Data Date tipli atributları dəstəkləyir, lakin onların mətn göstərimi həmişə DateFormatter vasitəsilə həyata keçirilir.

Thread Safety — DateFormatter iplik təhlükəsiz deyil. Formatlayıcının xüsusiyyətlərini müxtəlif iplərdən dəyişdirmək qeyri-müəyyən davranışa səbəb olur. Çoxiplikli istifadə üçün hər iplik üçün ayrı formatlayıcı instansiyaları yaradın və ya NSLock və ya serial queue vasitəsilə sinxronizasiyadan istifadə edin.

DateFormatter formatlaşdırma stilləri

dateStyle və timeStyle — tarixin göstərilməsini qurmağın ən sadə yollarıdır. Hər stilin dörd variantı var: .short, .medium, .long, .full. dateStyle və timeStyle kombinasiyası tarix və vaxt formatını müstəqil şəkildə konfiqurasiya etməyə imkan verir, .none xüsusiyyəti isə müvafiq hissəni söndürür.

ABŞ lokalı üçün .short stili tarixi “7/21/26” kimi, Azərbaycan lokalı üçün isə “21.07.2026” kimi formatlaşdırır. .long stili Azərbaycan lokalı üçün “21 iyul 2026”, .full isə “çərşənbə axşamı, 21 iyul 2026” şəklində göstərir. Bütün dörd stil avtomatik olaraq regional standartlara, o cümlədən komponentlərin sırasına və ayırıcılara uyğunlaşır.

RelativeDateFormatter iOS 15+-də RelativeDateFormatter və DateIntervalFormatter vasitəsilə alternativ yanaşma təklif edir. RelativeDateFormatter cari kontekst üçün “bu gün”, “dünən”, “3 gün sonra” kimi göstərir. DateIntervalFormatter tarix diapazonlarını göstərir: “21–25 iyul 2026” — rezervasiya və planlaşdırma üçün.

Stilləri birləşdirərkən DateFormatter avtomatik olaraq ayırıcı seçir: .short.date + .short.time üçün nəticə “21.07.2026, 14:30” ola bilər. .full.date + .full.time üçün — “çərşənbə axşamı, 21 iyul 2026, 14:30:00 MSK”. Ayırıcı lokal tərəfindən idarə olunur, proqramçı tərəfindən yox — bu, istifadəçinin regional gözləntilərinə uyğunluğu təmin edir.

dateFormat vasitəsilə fərdi formatlar

dateFormat Unicode LDML spesifikasiya simvollarından istifadə edərək ixtiyari formatlaşdırma şablonu təyin etməyə imkan verir. Bu, göstərim üzərində tam nəzarət verir: yalnız il və ayı, ədədsiz həftə günü və ya saniyəsiz vaxtı göstərə bilərsiniz. Fərdi format dizaynın xüsusi tələbləri üçün əvəzolunmazdır.

Əsas simvollar — yyyy (il: 2026), MM (ay: 07), dd (gün: 21), HH (saat: 14), mm (dəqiqə: 30), ss (saniyə: 00). Tam ay adı üçün MMMM (iyul), qısaldılmış üçün MMM (iyl) istifadə edin. Həftə günü — EEEE (çərşənbə axşamı), qısaldılmış — E (ça).

dateFormat istifadə edərkən formatlayıcının locale-ini təyin etmək vacibdir. Əgər locale təyin edilməyibsə, formatlayıcı sistem lokalından istifadə edir, bu da API-də sabit format üçün arzuolunmaz ola bilər. Apple sabit regionlararası format üçün locale = Locale(identifier: “en_US_POSIX”) təyin etməyi tövsiyə edir, xüsusilə server cavablarından tarixləri təhlil edərkən.

let formatter = DateFormatter()
formatter.locale = Locale(identifier: "ru_RU")
formatter.dateFormat = "d MMMM yyyy"
let customString = formatter.string(from: Date())
// "21 July 2026"

// Xüsusi sətri təhlil etmə
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
let date = formatter.date(from: "2026-07-21 14:30:00")!

dateFormat səhvi — tətbiqin çökməsinin tez-tez rast gəlinən səbəblərindən biridir. Format sətrə uyğun gəlməzsə, date(from:) metodu nil qaytarır. Opsional dəyəri təhlükəsiz çıxarmaq üçün guard let və ya ?? istifadə edin. Formatı yoxlamaq üçün bütün dəstəklənən dillərdə test edin — bəzi LDML simvolları müxtəlif lokallarda fərqli işləyir.

Lokalizasiya və TimeZone

Locale ayların, həftə günlərinin adlarının necə göstəriləcəyini və hansı ayırıcıların istifadə ediləcəyini müyyənləşdirir. DateFormatter susmaya görə Locale.current istifadə edir, lakin bəzi ssenarilərdə konkret lokal göstərmək tələb olunur: jurnallarda sabit format üçün en_US_POSIX, server tarixləri üçün serverə uyğun lokal istifadə edin.

TimeZone xüsusiyyəti göstərmə üçün saat qurşağını müyyənləşdirir. Susmaya görə sistem saat qurşağı istifadə olunur, lakin beynəlmiləl auditoriyası olan tətbiqlərdə tarixləri istifadəçinin saat qurşağında və ya UTC-də göstərmək tələb olunur. timeZone dəyişikliyi yalnız göstərimə təsir edir — Date dəyəri dəyişməz qalır.

Vacib xüsusiyyət: əgər DateFormatter sətri təhlil etmək üçün istifadə olunursa və sətrdə saat qurşağı göstəricisi varsa (məs. “2026-07-21T14:30:00Z” UTC üçün Z ilə), timeZone xüsusiyyəti nəzərə alınmır — formatlayıcı sətrdən saat qurşağını istifadə edir. Əgər sətrdə saat qurşağı yoxdursa, formatlayıcının timeZone-u tətbiq olunur.

let formatter = DateFormatter()
formatter.locale = Locale(identifier: "ru_RU")
formatter.timeZone = TimeZone(identifier: "Europe/Moscow")
formatter.dateStyle = .long
formatter.timeStyle = .short

let moscowTime = formatter.string(from: Date())
// "21 July 2026, 14:30"

// Sətrdə saat qurşağı olmadan təhlil
formatter.timeZone = TimeZone(secondsFromGMT: 0)
formatter.dateFormat = "yyyy-MM-dd HH:mm"
let utcDate = formatter.date(from: "2026-07-21 10:30")!

AutoupdatingCurrentLocale — istifadəçinin sistem parametrləri dəyişərkən avtomatik yenilənən xüsusi lokal növüdür. DateFormatter onu susmaya görə dəstəkləyir. Əgər tətbiq fonda işləyirsə və istifadəçi sistem dilini dəyişirsə, dəyişiklikdən əvvəl yaradılmış formatlayıcı köhnə lokaldan istifadə etməyə davam edəcək — yeniləmə üçün yeni instansiya yaratmaq lazımdır.

ISO8601DateFormatter və alternativlər

ISO8601DateFormatter — ISO 8601 formatında tarixlərlə işləmək üçün ixtisaslaşdırılmış formatlayıcıdır. Bu format REST API, JSON və məlumat mübadiləsi üçün de-fakto standartdır. ISO8601DateFormatter DateFormatter-dən xeyli sürətli işləyir, çünki lokaldan asılı deyil və sabit təhlil qrammatikasından istifadə edir.

Formatlayıcının əsas seçimləri — .withInternetDateTime (2026-07-21T14:30:00Z), .withFractionalSeconds (millisaniyələri əlavə edir), .withTimeZone (saat qurşağı yerdəyişməsini daxil edir). Seçimləri birləşdirərək istənilən ISO 8601 variantını əldə edə bilərsiniz: millisaniyələrlə, saat qurşağı ilə, vaxtsız tarixlə.

JSONEncoder.DateEncodingStrategy bütün Codable modelləri üçün tarixlərin kodlaşdırılmasını qlobal olaraq konfiqurasiya etməyə imkan verir. Variantlar — .iso8601 (ISO8601DateFormatter istifadə edir), .formatted(DateFormatter), .millisecondsSince1970, .secondsSince1970. Strategiya seçimi serializasiyanın bütün həyat dövrünə təsir edir və bütün API endpointləri üçün vahid olmalıdır.

// ISO8601DateFormatter
let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let isoString = isoFormatter.string(from: Date())
// "2026-07-21T14:30:00.000Z"

// JSONEncoder ISO8601 ilə
let encoder = JSONEncoder()
encoder.dateEncodingStrategy = .iso8601

// Alternativ: Xüsusi formatter ilə JSONEncoder
let customEncoder = JSONEncoder()
customEncoder.dateEncodingStrategy = .formatted(myFormatter)

DateFormatter vs ISO8601DateFormatter — API-də tarixlərin serializasiyası və təhlili üçün ISO8601DateFormatter seçin, çünki DateFormatter-dən 5-10 dəfə sürətli işləyir və lokalizasiya səhvlərinə məruz qalmır. DateFormatter-i istifadəçi interfeysi üçün saxlayın, burada ayların və həftə günlərinin adları ilə lokalizasiya olunmuş göstərim tələb olunur.

Tarix formatlaşdırma nümunələri

iOS tətbiqində DateFormatter-dən istifadənin real ssenarilərini nəzərdən keçirək: xəbər siyahısında göstərmə, doğum tarixi daxil etmə və müxtəlif saat qurşaqlarında tarixlərlə hesabat ixracı.

Siyahıda xəbər tarixinin göstərilməsi

RelativeDateFormatter xəbər lentləri üçün optimaldır. Təzə xəbərlər üçün “az əvvəl”, “5 dəqiqə əvvəl”, “dünən” göstərir və köhnə xəbərlər üçün tam tarixə keçir. Keçid həddi calendar vasitəsilə konfiqurasiya olunur: xəbərlər üçün 24 saat, messencerlər üçün bir həftə həddi istifadə edin.

func formatRelativeDate(_ date: Date) -> String {
    let relative = RelativeDateFormatter()
    relative.unitsStyle = .full

    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    formatter.timeStyle = .short

    let daysDiff = Calendar.current.dateComponents(
        [.day], from: date, to: Date()
    ).day ?? 0

    return daysDiff < 1
        ? relative.localizedString(for: date, relativeTo: Date())
        : formatter.string(from: date)
}

Doğum tarixinin daxil edilməsi — başqa bir tez-tez rast gəlinən ssenaridir. DateFormatter konkret dateFormat “dd.MM.yyyy” və lokal “az_AZ” ilə konfiqurasiya olunur. Daxil edilmiş sətri təhlil edərkən mümkün səhvləri idarə etmək vacibdir: formatlayıcı yanlış sətr üçün nil qaytarır. Uğurlu təhlildən sonra tarix icazə verilən diapazonda olduğu yoxlanılır — 1900-cü ildən tez deyil, bugünkü tarixdən gec deyil.

Hesabatın tarixlərlə ixracı istifadəçinin lokaldan asılı olmayan sabit format tələb edir. en_US_POSIX lokalı və UTC saat qurşağı ilə dateFormat “yyyy-MM-dd HH:mm:ss” istifadə edin. Bu yanaşma faylın sistemin regional parametrlərindən asılı olmayaraq istənilən ölkədə düzgün açılmasını təmin edir.