TimeZone — ano ito, klase ng Foundation at mga time zone

Ano ang TimeZone sa Foundation?

TimeZone — ay isang value type sa Swift na nagbibigay ng impormasyon tungkol sa isang heyograpikong time zone: offset na may kaugnayan sa UTC, pangalan, pagdadaglat, at mga panuntunan sa paglipat ng daylight saving time. Sa Objective-C, ang klase ay tinatawag na NSTimeZone. Ang parehong klase ay batay sa IANA Time Zone Database (kilala rin bilang Olson database), na naglalaman ng kasaysayan ng mga pagbabago sa time zone mula noong 1970.

Ang bawat instance ng TimeZone ay nag-iimbak ng identifier ng time zone (hal. Europe/Moscow), kasalukuyang offset sa mga segundo mula sa UTC, flag na isDaylightSavingTime, at petsa ng susunod na paglipat. Ang identifier ay ang pangunahing susi: sa pagsisimula ng TimeZone(identifier:), ini-load ng system ang kaukulang tala mula sa database ng time zone ng device.

Ayon sa datos ng IANA (2024), ang database ay naglalaman ng higit sa 600 natatanging identifier ng time zone. Ang Apple ay nagsasama ng bahagi ng database na ito sa bawat bersyon ng iOS at macOS, na ginagarantiyahan ang pagkakapareho ng mga kalkulasyon sa lahat ng device nang walang pangangailangan para sa mga kahilingan sa network.

Paano gumagana ang TimeZone sa iOS at macOS?

Arkitektura ng TimeZone sa Foundation ay binuo sa isang dalawang antas na sistema: identifier ng time zone (isang pangalan na nababasa ng tao) at ang numerikong representasyon nito (offset mula sa UTC). Awtomatikong pinipili ng system ang kasalukuyang time zone mula sa mga setting ng device, ngunit maaaring i-override ito ng developer para sa mga tiyak na operasyon ng pagfo-format.

Ang TimeZone ay malapit na nauugnay sa Calendar at DateFormatter. Kapag nagfo-format ng isang petsa, ginagamit ng DateFormatter ang property na timeZone ng isang instance ng TimeZone upang i-convert ang absolute moment ng oras (Date) sa tekstuwal na representasyon sa tamang time zone. Kung hindi nakatakda ang timeZone, ginagamit ang default na system time zone — TimeZone.current.

Mga uri ng instance ng TimeZone

Mahalagang nuance: Ang TimeZone(identifier:) ay nagbabalik ng nil para sa mga hindi kilalang identifier. Ito ay isang karaniwang sanhi ng pag-crash ng app — nakakalimutan ng mga developer na pangasiwaan ang opsyonal na halaga, na nagpapasa ng maling identifier mula sa input ng user. Para sa mga identifier ng IANA, mahalaga ang pagiging malaki/maliit ng titik: Europe/Moscow — tama, europe/moscow — nil.

Mga format ng identifier ng time zone

IANA Time Zone Database ay gumagamit ng format na “Rehiyon/Lungsod” (Continent/City), kung saan ang rehiyon ay isa sa mga kontinente (Africa, America, Asia, Atlantic, Australia, Europe, Indian, Pacific) o karagatan, at ang lungsod ay ang pinakamalaking pamayanan sa zone ng time zone. Tinitiyak ng format na ito ang pagiging natatangi at pagiging nababasa ng identifier.

Bukod sa pangunahing format, sinusuportahan ng TimeZone ang tatlong karagdagang paraan ng pagkilala: mga pagdadaglat (MSK, EST, PST), tatlong-titik na code ng time zone (GMT, UTC), at numerikong offset (+0300, -0500). Gayunpaman, ang mga pagdadaglat ay malabo: ang EST ay maaaring mangahulugan ng Eastern Standard Time (GMT-5) o Eastern Summer Time (GMT+10) sa Australia. Inirerekomenda ng Apple ang eksklusibong paggamit ng mga identifier ng IANA.

import Foundation

// Kunin ang lahat ng kilalang identifier ng time zone
let allIdentifiers: [String] = TimeZone.knownTimeZoneIdentifiers
print("Kabuuang mga time zone: \(allIdentifiers.count)")

// Salain ayon sa rehiyon
let europeZones = allIdentifiers.filter { $0.hasPrefix("Europe/") }
print("Mga time zone sa Europa: \(europeZones)")

// Mga pagdadaglat (hindi inirerekomenda para sa produksyon)
if let moscowTimeZone = TimeZone(abbreviation: "MSK") {
    print("MSK segundo mula sa GMT: \(moscowTimeZone.secondsFromGMT())")
}

// Hanapin ang identifier ayon sa offset
let utcPlus3 = TimeZone(secondsFromGMT: 10800)
print("Identifier: \(utcPlus3.identifier)")

Mga pagdadaglat sa TimeZone.abbreviationDictionary ay naglalaman ng mga pagdadaglat para sa lahat ng kilalang time zone, ngunit hindi ginagarantiyahan ng diksyunaryong ito ang pagiging natatangi: ang key na PST ay maaaring tumugma sa America/Los_Angeles o sa Pacific/Pago_Pago. Sa production code, palaging gumamit ng mga identifier ng IANA.

Paglipat sa daylight saving time at TimeZone

TimeZone ay awtomatikong isinasaalang-alang ang paglipat sa daylight saving time at winter time (DST — Daylight Saving Time) para sa lahat ng rehiyon kung saan ito isinasagawa. Ginagamit ng system ang makasaysayang datos mula sa IANA Time Zone Database, na nagsasama ng eksaktong petsa ng paglipat para sa bawat time zone. Ang property na isDaylightSavingTime ay nagbabalik ng true kung ang time zone ay kasalukuyang nasa daylight saving time.

Ang pamamaraang nextDaylightSavingTimeTransition ay nagbibigay-daan sa iyo na malaman ang petsa ng susunod na paglipat, na kapaki-pakinabang para sa pagpaplano ng mga kaganapan sa hinaharap. Ang functionality na ito ay lalong mahalaga para sa mga rehiyon na may madalas na pagbabago sa mga panuntunan ng DST, tulad ng Brazil o Morocco — hanggang 2024, ang Brazil ay taunang nagbabago ng mga petsa ng paglipat, at ang manu-manong pagkalkula ay humantong sa mga error sa mga application.

Ayon sa datos ng Apple WWDC 2023, ang library ng ICU (International Components for Unicode), na nasa ilalim ng Foundation, ay nag-a-update ng data ng DST sa bawat pag-update ng iOS. Ang mga application ay hindi dapat mag-cache ng data ng daylight saving time nang higit sa isang araw pagkatapos ng pag-update ng system — ang IANA database ay maaaring magbago kahit na walang pag-update ng bersyon ng OS sa pamamagitan ng mga pagsasaayos ng time zone.

import Foundation

// Suriin ang DST para sa Europe/Moscow
let moscow = TimeZone(identifier: "Europe/Moscow")!
let now = Date()
let isMoscowDST = moscow.isDaylightSavingTime(for: now)
print("Ang Moscow ay kasalukuyang nasa DST: \(isMoscowDST)")

// Kunin ang susunod na petsa ng transition ng DST
if let nextTransition = moscow.nextDaylightSavingTimeTransition(
    after: now
) {
    let dstOffset = moscow.daylightSavingTimeOffset(
        for: nextTransition
    )
    print("Susunod na transition: \(nextTransition), offset ng DST: \(dstOffset)s")
}

// Ligtas na conversion na may kamalayan sa DST
let newYork = TimeZone(identifier: "America/New_York")!
let offsetNY = newYork.secondsFromGMT(for: now)
print("Kasalukuyang offset ng NY: \(offsetNY / 3600)h")

Kritikal na nuance: Ang secondsFromGMT(for:) ay isinasaalang-alang ang DST para sa tinukoy na petsa, habang ang secondsFromGMT() ay para lamang sa kasalukuyang oras. Kapag nagfo-format ng mga makasaysayang petsa, palaging gamitin ang bersyon na may parameter na Date: secondsFromGMT(for: someHistoricalDate). Ang pagkakaiba ay maaaring umabot ng 1–2 oras, na kritikal para sa mga log o makasaysayang datos.

TimeZone sa Swift: mga halimbawa ng code

Pagfo-format ng petsa na may tiyak na time zone — ang pinakakaraniwang gawain sa pagtatrabaho sa TimeZone. Ginagamit ng DateFormatter ang property na timeZone upang i-convert ang Date sa teksto. Kung hindi tahasang nakatakda ang timeZone, ginagamit ng pormatter ang TimeZone.current — ang time zone na nakatakda sa device ng user, na maaaring humantong sa hindi inaasahang resulta para sa data ng server.

import Foundation

// I-format ang petsa sa tiyak na time zone
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"

let tokyo = TimeZone(identifier: "Asia/Tokyo")!
formatter.timeZone = tokyo
let tokyoTime = formatter.string(from: Date())
print("Oras sa Tokyo: \(tokyoTime)")

// Mga available na identifier para sa pagpili ng user
let displayNames: [(String, String)] = TimeZone.knownTimeZoneIdentifiers
    .prefix(20)
    .map { ($0, TimeZone(identifier: $0)!.localizedName(
        for: .generic, locale: .current
    )) }

// Ikumpara ang dalawang time zone
let london = TimeZone(identifier: "Europe/London")!
let difference = tokyo.secondsFromGMT(for: Date())
    - london.secondsFromGMT(for: Date())
print("Pagkakaiba ng Tokyo-London: \(difference / 3600)h")

// Gumawa gamit ang diksyunaryo ng pagdadaglat
let knownAbbrevs = TimeZone.abbreviationDictionary
for (abbr, ident) in knownAbbrevs.sorted(by: { $0.key < $1.key }).prefix(5) {
    print("\(abbr) -> \(ident)")
}

Naka-localize na pangalan ng time zone sa pamamagitan ng localizedName(for:locale:) ay nagbabalik ng pangalan na nababasa ng tao sa tinukoy na wika. Halimbawa, para sa Europe/Moscow na may Russian locale, ang pamamaraan ay magbabalik ng “Moscow”, at sa English locale — “Moscow Time”. Mga available na estilo: .standard (standard na pangalan), .daylightSaving (daylight saving time) at .shortGeneric (maikli).

import Foundation

let paris = TimeZone(identifier: "Europe/Paris")!
let nameRU = paris.localizedName(
    for: .standard,
    locale: Locale(identifier: "ru_RU")
)
print("Pangalan sa Russian: \(nameRU)")

// Suriin kung ang rehiyon ay nasa parehong araw
let isSameDay = Calendar.current.isDate(
    Date(),
    equalTo: Date(),
    toGranularity: .day
)
print("Parehong araw sa iba’t ibang time zone: \(isSameDay)")

Serialization ng identifier ng time zone — pinakamahusay na kasanayan para sa pag-iimbak ng TimeZone sa mga database o UserDefaults. I-save ang identifier (isang string ng uri Europe/Moscow), hindi ang offset sa mga segundo o pagdadaglat. Maaaring magbago ang offset sa pagbabago ng DST, at ang pagdadaglat ay malabo. Pagbawi: TimeZone(identifier: savedString).

Mga karaniwang pagkakamali sa pagtatrabaho sa TimeZone

Paggamit ng nakapirming offset sa halip na identifier ng time zone — ang pinakakaraniwang pagkakamali. Ang TimeZone(secondsFromGMT: 10800) ay hindi isinasaalang-alang ang DST, kaya para sa Europe/Moscow sa tag-araw, ang konstruksiyon na ito ay nagbibigay ng maling offset ng 1 oras. Palaging gamitin ang IANA identifier para sa mga rehiyon na may daylight saving time.

Nakalimutang paghawak ng nil sa pagsisimula ng TimeZone(identifier:) — ang pangalawang pinakakaraniwang pagkakamali. Kung ang user ay nagpasok ng identifier na may error (hal. “moscow” sa halip na “Europe/Moscow”), ang constructor ay nagbabalik ng nil. Kung walang paghawak ng opsyonal na halaga, ang app ay mag-crash na may runtime error. Gumamit ng guard let o TimeZone(identifier:) na may kilalang fallback.

Pagbalewala sa DST kapag nagtatrabaho sa mga petsa sa hinaharap. Ang TimeZone.secondsFromGMT(for:) — ang tanging tamang paraan upang makuha ang offset para sa isang tiyak na petsa. Ang paggamit ng secondsFromGMT() nang walang parameter para sa mga makasaysayang o hinaharap na petsa ay nagbibigay ng offset para sa kasalukuyang sandali, na maaaring hindi tumugma sa aktwal na offset sa petsang iyon, lalo na para sa mga rehiyon na may pag-aalis o pagpapatupad ng DST.

Ayon sa datos ng Stack Overflow (2024), humigit-kumulang 15% ng mga tanong tungkol sa DateFormatter ay may kaugnayan sa maling setting ng timeZone. Karaniwang senaryo: ang server ay nagpapadala ng petsa sa UTC, bino-format ito ng developer nang hindi itinatakda ang timeZone ng pormatter, at ang petsa ay ipinapakita sa time zone ng device, na nagdudulot ng kalituhan sa mga user mula sa iba’t ibang rehiyon. Panuntunan: palaging tahasang itakda ang timeZone ng pormatter para sa data ng server.