@ScaledMetric — mi ez, property wrapper SwiftUI és Dynamic Type

Mi az @ScaledMetric?

@ScaledMetric — iOS 14-ben hozzáadott SwiftUI property wrapper, amely automatikusan skálázza a numerikus értéket (CGFloat, Int, Double) az aktuális Dynamic Type betűméretre. Ellentétben a .font(.body) betűtípusokhoz való használatával, az @ScaledMetric bármilyen numerikus paramétert skáláz: padding, spacing, cornerRadius, iconSize — mindent, aminek arányosan kell nőnie nagy szövegnél.

Az @ScaledMetric fő feladata a nem szöveges felületelemek akadálymentesítési skálázásának biztosítása. Amikor a felhasználó megnöveli a betűméretet az iOS beállításaiban, a gomboknak, ikonoknak és távolságoknak arányosan kell nőniük, hogy a felület egyensúlyban maradjon. Az @ScaledMetric automatikusan oldja meg ezt a feladatot, a szorzók kézi kiszámítása nélkül.

Az @ScaledMetric szintaxisa

Alap szintaxis Az @ScaledMetric alapértelmezett értéket és opcionális relativeTo paramétert használ. Ha a relativeTo meg van adva, a skálázás egy adott szövegstílushoz (UIFontTextStyle) van kötve. Ha nincs — a .body skála használatos.

struct AccessibleButton: View {
    @ScaledMetric private var padding: CGFloat = 12
    @ScaledMetric(relativeTo: .title) private var iconSize: CGFloat = 24
    
    var body: some View {
        Label("Küldés", systemImage: "checkmark.circle.fill")
            .font(.body)
            .padding(padding)
            .imageScale(.init(rawValue: iconSize / 24) ?? .medium)
    }
}

padding a .body-hoz (alapértelmezett), iconSize a .title-hez képest skálázódik. Nagy szövegnél a távolságok és az ikon arányosan nőnek. @ScaledMetric nélkül a távolságok 12 pt maradnának bármilyen betűméretnél, ami vizuális egyensúlyhiányhoz vezetne.

Hogyan működik az @ScaledMetric

Az @ScaledMetric mechanizmusa a UIKit-ből származó UIFontMetrics-en alapul. Amikor a SwiftUI létrehoz egy @ScaledMetric példányt, kiszámít egy szorzót az aktuális preferred content size category (UIContentSizeCategory) alapján. Az alapérték megszorzásra kerül a UIFontMetrics scaledValue-jával a megadott szövegstílushoz.

Matematikailag: ScaledMetricValue = baseValue × UIFontMetrics.scaledValue(for: relativeTo). Ha a relativeTo nincs megadva, a .body-hoz kötött UIFontMetrics.default használatos. Dynamic Type változásakor a SwiftUI újra létrehozza a View törzsét, az @ScaledMetric kiszámítja az új scaledValue-ot, és a UI automatikusan frissül a @State-szerű PropertyWrappers mechanizmusán keresztül.

A Dynamic Type skálázási skálája

Az iOS skála 11 méretet tartalmaz: .extraSmall (5 pt) és .accessibilityExtraExtraExtraLarge (77 pt .body esetén) között. A .body skálázási együtthatója 0.85 (XS) és 1.71 (XXXL) között változik az alapértékhez képest. Az @ScaledMetric pontosan ezt a skálát használja, így a 12 pt padding érték ~20 pt lehet a maximális akadálymentesítési méretnél.

relativeTo kiválasztása: használja a .body-t a fő szöveghez kapcsolódó értékekhez (padding, spacing listákban), .title-t nagy elemekhez (iconSize, imageSize), .caption-t kis elemekhez (badge méret). Ez biztosítja, hogy az elemek a környező szöveggel összhangban skálázódjanak.

@ScaledMetric és Dynamic Type

Dynamic Type — iOS funkció, amely lehetővé teszi a felhasználónak a rendszer betűméretének beállítását a Settings → Display & Brightness → Text Size menüpontban. A változás globálisan érvényesül az összes alkalmazásra. Az @ScaledMetric automatikusan reagál erre a változásra: a SwiftUI frissíti az összes @ScaledMetric változót a UIContentSizeCategory változásakor.

Fontos: Az @ScaledMetric csak numerikus értékeket skáláz, de nem kezeli közvetlenül a betűtípusokat. Betűtípusokhoz használja a .font()-ot szövegstílussal (.body, .title, .headline) — a SwiftUI automatikusan skálázza a betűtípust. Az @ScaledMetric kiegészíti a betűtípus skálázást padding, spacing és elem méretek esetében.

Akadálymentesítés ellenőrzése a Canvas segítségével

Canvas Preview támogatja a Dynamic Type-ot: a Canvas eszköztárán van egy Text Size (A–A) csúszka a UI ellenőrzéséhez különböző betűméreteknél. Használja az @ScaledMetric-kel, hogy megbizonyosodjon a távolságok és méretek helyes skálázódásáról.

struct CardView: View {
    @ScaledMetric private var cornerRadius: CGFloat = 16
    @ScaledMetric private var spacing: CGFloat = 8
    
    var body: some View {
        VStack(spacing: spacing) {
            Text("Kártya címe")
                .font(.headline)
            Text("Leírás dynamic type támogatással")
                .font(.body)
        }
        .padding(spacing * 2)
        .background(.regularMaterial)
        .cornerRadius(cornerRadius)
    }
}

struct CardView_Previews: PreviewProvider {
    static var previews: some View {
        CardView()
            .dynamicTypeSize(.large)
            .previewDisplayName("Large")
        CardView()
            .dynamicTypeSize(.accessibility5)
            .previewDisplayName("Accessibility 5")
    }
}

cornerRadius 16 pt-ról ~27 pt-ra skálázódik maximális akadálymentesítési méretnél. spacing — 8-ról ~14 pt-ra. Ez biztosítja, hogy a kártya vizuálisan egyensúlyban maradjon bármilyen betűméretnél.

@ScaledMetric példák

Példa: ikon Dynamic Type támogatással. Az Image(systemName:) ikonok mérete alapértelmezés szerint nem skálázódik Dynamic Type alatt. Az @ScaledMetric megoldja ezt a problémát: az imageScale vagy a frame méret módosításával az aktuális skálázási tényező alapján.

struct IconLabel: View {
    let title: String
    let icon: String
    
    @ScaledMetric private var iconDimension: CGFloat = 28
    @ScaledMetric(relativeTo: .body) private var spacing: CGFloat = 6
    
    var body: some View {
        HStack(spacing: spacing) {
            Image(systemName: icon)
                .resizable()
                .frame(width: iconDimension, height: iconDimension)
            Text(title)
                .font(.body)
        }
    }
}

Példa: akadálymentes badge-komponens. A számmal ellátott badge-nek arányosan kell skálázódnia a szöveggel. Az @ScaledMetric a badge minimális méretéhez biztosítja, hogy a kerek badge látható maradjon nagy betűméretnél.

struct BadgeView: View {
    let count: Int
    
    @ScaledMetric(relativeTo: .caption) private var badgeSize: CGFloat = 20
    @ScaledMetric(relativeTo: .caption) private var fontScale: CGFloat = 1
    
    var body: some View {
        ZStack {
            Circle()
                .fill(.red)
                .frame(width: badgeSize, height: badgeSize)
            
            Text("\(count)")
                .font(.caption)
                .foregroundColor(.white)
                .scaleEffect(fontScale)
        }
        .fixedSize()
    }
}

fontScale emellett skálázza a Circle tartalmát a megnövelt badgeSize-hoz igazodva. fontScale nélkül a badge-en belüli szöveg nem férne el nagy betűméretnél.

@ScaledMetric vs @State — eltérések

@ScaledMetric és @State — mindkettő property wrapper, amelyek változásokat követnek, de eltérő frissítési forrásokkal. A @State programozott változásnál frissíti az értéket ($stateBinding-en keresztül). Az @ScaledMetric automatikusan frissíti az értéket a rendszer Dynamic Type változásakor, de nem engedi az érték közvetlen módosítását kódból.

A kulcsfontosságú különbség: @ScaledMetric — read-only a fejlesztő számára és write-only a rendszer számára. Nem módosíthatja a scaledValue-t setteren keresztül — a SwiftUI számítja ki az alapérték és az aktuális Dynamic Type alapján. A @State ezzel szemben teljesen a fejlesztő által kezelt. Ha olyan értékre van szüksége, amely egyszerre skálázódik Dynamic Type alatt és programozottan is változtatható — kombinálja az @ScaledMetric-et a @State-tel, vagy használjon számított tulajdonságot.

Kombinált minta: ha programozottan kell módosítania a padding-et (pl. kattintás animáció) és egyidejűleg skáláznia Dynamic Type alatt, hozzon létre egy @ScaledMetric-et az alap skálázott értékhez és egy @State-t az animációs szorzóhoz. A végső érték = scaledValue × animationMultiplier.

Gyakori hibák az @ScaledMetric-kel

Hiba 1: @ScaledMetric használata betűtípusokhoz. Az @ScaledMetric számokat skáláz, nem betűtípusokat. Betűtípusokhoz használja a .font(.body)-t — a SwiftUI automatikusan alkalmazza a Dynamic Type-ot. Soha ne használja az @ScaledMetric-et font(.system(size: scaledSize))-val — ez tönkreteszi a rendszer akadálymentesítését.

Hiba 2: relativeTo hiánya heterogén elemeknél. Ha padding (.body-hoz kapcsolódó) és iconSize (.title-hez kapcsolódó) is van, adja meg a helyes relativeTo-t mindegyikhez. relativeTo nélkül mindkettő .body szerint skálázódik, ami az ikon aránytalan növekedéséhez vezet a szöveges kontextusához képest.

Hiba 3: @ScaledMetric ViewModel/@ObservableObject osztályban. Az @ScaledMetric egy SwiftUI property wrapper, amely csak View-n belül működik. Nem használható ViewModel-ben vagy szolgáltatásokban. A ViewModel-ben történő skálázáshoz adja át a skálázott értéket a View-ból paraméterként, vagy használja az @Environment(\.sizeCategory)-t a View-ban.

Aktuális sizeCategory lekérése kódból

@Environment(\.sizeCategory) — alternatív módszer az aktuális Dynamic Type lekérésére a View-ban. Használja, amikor több vezérlésre van szüksége: egyéni szorzó kiszámítása, sizeCategory átadása ViewModel-nek vagy kombinálás @ScaledMetric-kel a rugalmas skálázáshoz.

struct CustomScaledView: View {
    @Environment(\.sizeCategory) private var sizeCategory
    @ScaledMetric private var basePadding: CGFloat = 12
    
    private var extraPadding: CGFloat {
        if sizeCategory >= .accessibilityLarge {
            return basePadding * 0.5
        }
        return 0
    }
    
    var body: some View {
        Text("Egyéni skálázott tartalom")
            .font(.body)
            .padding(basePadding + extraPadding)
    }
}

Extra távolság Az extraPadding csak akadálymentesítési méreteknél adódik hozzá, több helyet biztosítva a nagy szöveg számára az alap @ScaledMetric logika megváltoztatása nélkül.