@ScaledMetric — cos’è, property wrapper SwiftUI e Dynamic Type

Cos’è @ScaledMetric?

@ScaledMetric è un property wrapper SwiftUI, aggiunto in iOS 14, che ridimensiona automaticamente un valore numerico (CGFloat, Int, Double) in base alla dimensione del carattere Dynamic Type corrente. A differenza di .font(.body) per i font, @ScaledMetric ridimensiona qualsiasi parametro numerico: padding, spacing, cornerRadius, iconSize — tutto ciò che deve aumentare proporzionalmente con testo più grande.

Lo scopo principale di @ScaledMetric è fornire un ridimensionamento di accessibilità per gli elementi dell’interfaccia non testuali. Quando l’utente aumenta la dimensione del carattere nelle impostazioni iOS, pulsanti, icone e spaziature devono ridimensionarsi proporzionalmente per mantenere l’interfaccia equilibrata. @ScaledMetric gestisce tutto ciò automaticamente, senza calcolo manuale dei moltiplicatori.

Sintassi di @ScaledMetric

Sintassi di base di @ScaledMetric utilizza un valore predefinito e un parametro opzionale relativeTo. Se viene specificato relativeTo, il ridimensionamento è legato a uno specifico stile di testo (UIFontTextStyle). In caso contrario, viene utilizzata la scala .body.

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

padding verrà ridimensionato rispetto a .body (predefinito), iconSize rispetto a .title. Con testo più grande, le spaziature e le icone aumenteranno proporzionalmente. Senza @ScaledMetric, il padding rimarrebbe a 12 pt indipendentemente dalla dimensione del carattere, causando squilibrio visivo.

Come funziona @ScaledMetric

Il meccanismo @ScaledMetric è basato su UIFontMetrics di UIKit. Quando SwiftUI crea un’istanza di @ScaledMetric, calcola un moltiplicatore basato sulla categoria di dimensione del contenuto preferita corrente (UIContentSizeCategory). Il valore base viene moltiplicato per scaledValue di UIFontMetrics per lo stile di testo specificato.

Matematicamente: ScaledMetricValue = baseValue × UIFontMetrics.scaledValue(for: relativeTo). Se relativeTo non è specificato, viene utilizzato UIFontMetrics.default, legato a .body. Quando Dynamic Type cambia, SwiftUI ricrea il corpo della View, @ScaledMetric calcola un nuovo scaledValue e l’interfaccia viene aggiornata automaticamente attraverso il meccanismo dei PropertyWrappers simile a @State.

Scala di ridimensionamento Dynamic Type

La scala iOS include 11 dimensioni: da .extraSmall (5 pt) a .accessibilityExtraExtraExtraLarge (77 pt per .body). Il fattore di ridimensionamento per .body varia da 0.85 (XS) a 1.71 (XXXL) rispetto al valore base. @ScaledMetric utilizza esattamente questa scala, quindi un valore di padding di 12 pt può diventare ~20 pt alla dimensione di accessibilità massima.

Scegliere relativeTo: utilizzare .body per i valori relativi al testo del corpo (padding, spacing negli elenchi), .title per elementi grandi (iconSize, imageSize), .caption per elementi piccoli (dimensione badge). Ciò garantisce che gli elementi si ridimensionino in sincronia con il testo circostante.

@ScaledMetric e Dynamic Type

Dynamic Type è una funzionalità iOS che consente agli utenti di regolare la dimensione del carattere di sistema in Impostazioni → Schermo e luminosità → Dimensione testo. La modifica si applica globalmente a tutte le app. @ScaledMetric reagisce a questa modifica automaticamente: SwiftUI aggiorna tutte le variabili @ScaledMetric quando UIContentSizeCategory cambia.

Importante: @ScaledMetric ridimensiona solo valori numerici, non gestisce direttamente i font. Per i font, utilizzare .font() con uno stile di testo (.body, .title, .headline) — SwiftUI ridimensiona automaticamente il font. @ScaledMetric completa il ridimensionamento dei font per padding, spacing e dimensioni degli elementi.

Test di accessibilità tramite Canvas

Canvas Preview supporta Dynamic Type: la barra degli strumenti di Canvas ha un cursore della dimensione del testo (A–A) per testare l’interfaccia a diverse dimensioni del carattere. Usalo con @ScaledMetric per verificare che spaziature e dimensioni si ridimensionino correttamente.

struct CardView: View {
    @ScaledMetric private var cornerRadius: CGFloat = 16
    @ScaledMetric private var spacing: CGFloat = 8
    
    var body: some View {
        VStack(spacing: spacing) {
            Text("Card Title")
                .font(.headline)
            Text("Description with dynamic type support")
                .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 si ridimensiona da 16 pt a ~27 pt alla massima dimensione di accessibilità. spacing — da 8 a ~14 pt. Ciò garantisce che la carta rimanga visivamente equilibrata a qualsiasi dimensione del carattere.

Esempi di @ScaledMetric

Esempio: icona con supporto Dynamic Type. Le dimensioni delle icone Image(systemName:) non vengono ridimensionate per Dynamic Type per impostazione predefinita. @ScaledMetric risolve questo problema modificando imageScale o la dimensione del frame in base al fattore di scala corrente.

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

Esempio: componente badge accessibile. Un badge numerato deve ridimensionarsi proporzionalmente al testo. @ScaledMetric per la dimensione minima del badge garantisce che il badge circolare rimanga visibile con testo grande.

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 ridimensiona ulteriormente il contenuto del Circle per corrispondere a badgeSize ingrandito. Senza fontScale, il testo all’interno del badge potrebbe non entrare con testo grande.

@ScaledMetric vs @State — differenze

@ScaledMetric e @State sono entrambi property wrapper che tracciano i cambiamenti, ma con diverse fonti di aggiornamento. @State aggiorna il valore al cambiamento programmatico (tramite $stateBinding). @ScaledMetric aggiorna il valore automaticamente quando il Dynamic Type di sistema cambia, ma non consente di modificare il valore direttamente dal codice.

Differenza chiave: @ScaledMetric è di sola lettura per lo sviluppatore e di sola scrittura per il sistema. Non è possibile modificare scaledValue tramite un setter — viene calcolato da SwiftUI in base al valore base e al Dynamic Type corrente. @State, d’altra parte, è completamente controllato dallo sviluppatore. Se hai bisogno di un valore che sia ridimensionato per Dynamic Type e cambi anche programmaticamente — combina @ScaledMetric con @State o utilizza una proprietà calcolata.

Pattern combinato: se devi modificare il padding programmaticamente (ad esempio, animazione di tocco) mentre lo ridimensioni per Dynamic Type, crea un @ScaledMetric per il valore ridimensionato base e un @State per il moltiplicatore di animazione. Valore finale = scaledValue × animationMultiplier.

Errori comuni con @ScaledMetric

Errore 1: Usare @ScaledMetric per i font. @ScaledMetric ridimensiona numeri, non font. Per i font, utilizzare .font(.body) — SwiftUI applica Dynamic Type automaticamente. Non usare mai @ScaledMetric con font(.system(size: scaledSize)) — rompe l’accessibilità del sistema.

Errore 2: Mancanza di relativeTo per elementi eterogenei. Se hai padding (legato a .body) e iconSize (legato a .title), specifica il relativeTo corretto per ciascuno. Senza relativeTo, entrambi si ridimensioneranno secondo .body, dando un ridimensionamento sproporzionato dell’icona rispetto al suo contesto testuale.

Errore 3: @ScaledMetric in ViewModel/@ObservableObject. @ScaledMetric è un property wrapper SwiftUI che funziona solo all’interno di una View. Non può essere utilizzato in ViewModel o servizi. Per il ridimensionamento in ViewModel, passa il valore ridimensionato dalla View come parametro o utilizza @Environment(\.sizeCategory) nella View.

Ottenere la categoria di dimensione corrente nel codice

@Environment(\.sizeCategory) è un modo alternativo per ottenere il Dynamic Type corrente in una View. Usalo quando hai bisogno di più controllo: calcolare un moltiplicatore personalizzato, passare sizeCategory a un ViewModel o combinarlo con @ScaledMetric per un ridimensionamento flessibile.

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("Custom scaled content")
            .font(.body)
            .padding(basePadding + extraPadding)
    }
}

Padding extra extraPadding viene aggiunto solo alle dimensioni di accessibilità, dando più spazio per il testo grande senza modificare la logica di base di @ScaledMetric.