@ScaledMetric — wat is het, property wrapper SwiftUI en Dynamic Type

Wat is @ScaledMetric?

@ScaledMetric — property wrapper SwiftUI, toegevoegd in iOS 14, die automatisch een numerieke waarde (CGFloat, Int, Double) schaalt naar de huidige Dynamic Type-lettergrootte. In tegenstelling tot .font(.body) voor lettertypen, schaalt @ScaledMetric alle numerieke parameters: padding, spacing, cornerRadius, iconSize — alles wat proportioneel moet toenemen bij grote tekst.

De hoofdtaak van @ScaledMetric is het zorgen voor accessibility-schaling van niet-tekstuele interface-elementen. Wanneer de gebruiker het lettertype vergroot in de iOS-instellingen, moeten knoppen, pictogrammen en tussenruimten proportioneel toenemen om de interface in balans te houden. @ScaledMetric lost deze taak automatisch op, zonder handmatige berekening van multipliers.

Syntax van @ScaledMetric

Basis syntax @ScaledMetric gebruikt een standaardwaarde en een optionele parameter relativeTo. Als relativeTo is opgegeven, wordt de schaling gekoppeld aan een specifieke tekststijl (UIFontTextStyle). Zo niet — wordt de .body-schaal gebruikt.

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

padding wordt geschaald ten opzichte van .body (standaard), iconSize — ten opzichte van .title. Bij grote tekst zullen tussenruimten en pictogram proportioneel toenemen. Zonder @ScaledMetric zouden tussenruimten 12 pt blijven bij elke lettergrootte, wat zou leiden tot visuele disbalans.

Hoe werkt @ScaledMetric

Het mechanisme van @ScaledMetric is gebaseerd op UIFontMetrics uit UIKit. Wanneer SwiftUI een @ScaledMetric-instantie maakt, berekent het een multiplier op basis van de huidige preferred content size category (UIContentSizeCategory). De basiswaarde wordt vermenigvuldigd met scaledValue van UIFontMetrics voor de opgegeven tekststijl.

Wiskundig: ScaledMetricValue = baseValue × UIFontMetrics.scaledValue(for: relativeTo). Als relativeTo niet is opgegeven, wordt UIFontMetrics.default gebruikt, gekoppeld aan .body. Bij wijziging van Dynamic Type maakt SwiftUI de body van de View opnieuw aan, berekent @ScaledMetric de nieuwe scaledValue en wordt de UI automatisch bijgewerkt via het mechanisme van @State-achtige PropertyWrappers.

De schalingsschaal van Dynamic Type

De iOS-schaal omvat 11 groottes: van .extraSmall (5 pt) tot .accessibilityExtraExtraExtraLarge (77 pt voor .body). De schalingsfactor voor .body varieert van 0.85 (XS) tot 1.71 (XXXL) ten opzichte van de basiswaarde. @ScaledMetric gebruikt precies deze schaal, dus een waarde van 12 pt voor padding kan ~20 pt worden bij de maximale accessibility-grootte.

Keuze van relativeTo: gebruik .body voor waarden die verband houden met de hoofdtekst (padding, spacing in lijsten), .title voor grote elementen (iconSize, imageSize), .caption voor kleine elementen (badge-grootte). Dit garandeert dat elementen in de pas schalen met de omringende tekst.

@ScaledMetric en Dynamic Type

Dynamic Type — iOS-functie waarmee de gebruiker de systeemlettergrootte kan aanpassen in Settings → Display & Brightness → Text Size. De wijziging wordt wereldwijd toegepast op alle apps. @ScaledMetric reageert automatisch op deze wijziging: SwiftUI werkt alle @ScaledMetric-variabelen bij bij verandering van UIContentSizeCategory.

Belangrijk: @ScaledMetric schaalt alleen numerieke waarden, maar beheert niet direct lettertypen. Gebruik voor lettertypen .font() met een tekststijl (.body, .title, .headline) — SwiftUI schaalt het lettertype automatisch. @ScaledMetric vult de letterschaling aan voor padding, spacing en elementgroottes.

Toegankelijkheid controleren via Canvas

Canvas Preview ondersteunt Dynamic Type: in de Canvas-werkbalk is er een schuifregelaar Text Size (A–A) om de UI te controleren bij verschillende lettergroottes. Gebruik het met @ScaledMetric om er zeker van te zijn dat tussenruimten en groottes correct schalen.

struct CardView: View {
    @ScaledMetric private var cornerRadius: CGFloat = 16
    @ScaledMetric private var spacing: CGFloat = 8
    
    var body: some View {
        VStack(spacing: spacing) {
            Text("Kaarttitel")
                .font(.headline)
            Text("Beschrijving met dynamic type-ondersteuning")
                .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 schaalt van 16 pt tot ~27 pt bij maximale accessibility-grootte. spacing — van 8 tot ~14 pt. Dit garandeert dat de kaart visueel in balans blijft bij elke lettergrootte.

Voorbeelden van @ScaledMetric

Voorbeeld: pictogram met Dynamic Type-ondersteuning. De grootte van Image(systemName:)-pictogrammen wordt standaard niet geschaald onder Dynamic Type. @ScaledMetric lost dit probleem op: door imageScale of framegrootte te wijzigen op basis van de huidige schalingsfactor.

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)
        }
    }
}

Voorbeeld: toegankelijke badge-component. Een badge met een getal moet proportioneel schalen met de tekst. @ScaledMetric voor de minimale badge-grootte garandeert dat de ronde badge zichtbaar blijft bij groot lettertype.

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 schaalt bovendien de inhoud van de Circle om aan te passen aan de vergrote badgeSize. Zonder fontScale zou de tekst in de badge mogelijk niet passen bij groot lettertype.

@ScaledMetric vs @State — verschillen

@ScaledMetric en @State — beide property wrappers die wijzigingen volgen, maar met verschillende updateronnen. @State werkt de waarde bij bij programmatische wijziging (via $stateBinding). @ScaledMetric werkt de waarde automatisch bij bij wijziging van systeem Dynamic Type, maar staat geen directe wijziging van de waarde uit code toe.

Het belangrijkste verschil: @ScaledMetric — read-only voor de ontwikkelaar en write-only voor het systeem. U kunt scaledValue niet wijzigen via een setter — het wordt berekend door SwiftUI op basis van de basiswaarde en de huidige Dynamic Type. @State daarentegen wordt volledig beheerd door de ontwikkelaar. Als u een waarde nodig hebt die zowel onder Dynamic Type schaalt als programmatisch wijzigbaar is — combineer dan @ScaledMetric met @State of gebruik een berekende eigenschap.

Gecombineerd patroon: als u padding programmatisch moet wijzigen (bijv. animatie bij indrukken) en tegelijkertijd moet schalen onder Dynamic Type, maak dan een @ScaledMetric voor de geschaalde basiswaarde en een @State voor de animatiemultiplier. De uiteindelijke waarde = scaledValue × animationMultiplier.

Veelvoorkomende fouten met @ScaledMetric

Fout 1: @ScaledMetric gebruiken voor lettertypen. @ScaledMetric schaalt getallen, geen lettertypen. Gebruik voor lettertypen .font(.body) — SwiftUI past automatisch Dynamic Type toe. Gebruik nooit @ScaledMetric met font(.system(size: scaledSize)) — dit verbreekt de systeem-accessibility.

Fout 2: ontbreken van relativeTo voor verschillende elementen. Als u padding (gekoppeld aan .body) en iconSize (gekoppeld aan .title) hebt, geef dan voor elk de juiste relativeTo op. Zonder relativeTo worden beide geschaald volgens .body, wat leidt tot een disproportionele toename van het pictogram ten opzichte van de tekstuele context.

Fout 3: @ScaledMetric in ViewModel/@ObservableObject. @ScaledMetric is een SwiftUI property wrapper die alleen binnen een View werkt. Het kan niet worden gebruikt in ViewModel of services. Voor schaling in ViewModel, geef de geschaalde waarde uit de View door als parameter of gebruik @Environment(\.sizeCategory) in de View.

Huidige sizeCategory ophalen in code

@Environment(\.sizeCategory) — alternatieve manier om de huidige Dynamic Type in een View te verkrijgen. Gebruik het wanneer u meer controle nodig hebt: een aangepaste multiplier berekenen, sizeCategory doorgeven aan ViewModel of combineren met @ScaledMetric voor flexibele schaling.

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("Aangepaste geschaalde inhoud")
            .font(.body)
            .padding(basePadding + extraPadding)
    }
}

Extra tussenruimte extraPadding wordt alleen toegevoegd bij accessibility-groottes, waardoor er meer ruimte komt voor grote tekst zonder de basis @ScaledMetric-logica te wijzigen.