Utilizzare i caratteri

Questa pagina descrive come impostare i caratteri nella tua app Compose.

Impostare il carattere

Text ha un parametro fontFamily per consentire l'impostazione del carattere utilizzato nel composable. Per impostazione predefinita, le famiglie di caratteri serif, sans-serif, monospace e corsivo sono incluse:

@Composable
fun DifferentFonts() {
    Column {
        Text("Hello World", fontFamily = FontFamily.Serif)
        Text("Hello World", fontFamily = FontFamily.SansSerif)
    }
}
TextSnippets.kt

Le parole

Puoi utilizzare l'attributo fontFamily per lavorare con caratteri e tipi di carattere personalizzati definiti nella cartella res/font:

Rappresentazione grafica della cartella res > font nell'ambiente di sviluppo

Questo esempio mostra come definire un fontFamily in base a questi file di caratteri e utilizzando la funzione Font:

val firaSansFamily = FontFamily(
    Font(R.font.firasans_light, FontWeight.Light),
    Font(R.font.firasans_regular, FontWeight.Normal),
    Font(R.font.firasans_italic, FontWeight.Normal, FontStyle.Italic),
    Font(R.font.firasans_medium, FontWeight.Medium),
    Font(R.font.firasans_bold, FontWeight.Bold)
)
TextSnippets.kt

Puoi passare questo fontFamily al tuo composable Text. Poiché un fontFamily può includere pesi diversi, puoi impostare manualmente fontWeight per selezionare il peso corretto per il testo:

Column {
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Light)
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Normal)
    Text(
        text = "text",
        fontFamily = firaSansFamily,
        fontWeight = FontWeight.Normal,
        fontStyle = FontStyle.Italic
    )
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Medium)
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Bold)
}
TextSnippets.kt

Le parole

Per scoprire come impostare la tipografia nell'intera app, consulta Sistemi di progettazione personalizzati in Compose.

Caratteri scaricabili

A partire da Compose 1.2.0, puoi utilizzare l'API dei caratteri scaricabili nella tua app Compose per scaricare in modo asincrono i caratteri Google e utilizzarli nella tua app.

Al momento non è disponibile il supporto per i caratteri scaricabili forniti da provider personalizzati.

Utilizzare i caratteri scaricabili a livello di programmazione

Per scaricare un carattere a livello di programmazione dall'interno dell'app:

  1. Aggiungi la dipendenza:

    Alla moda

    dependencies {
    ...
    implementation "androidx.compose.ui:ui-text-google-fonts:1.10.5"
}

    Kotlin

    dependencies {
    ...
    implementation("androidx.compose.ui:ui-text-google-fonts:1.10.5")
}
  2. Inizializza GoogleFont.Provider con le credenziali per Google Fonts: 
    val provider = GoogleFont.Provider(
    providerAuthority = "com.google.android.gms.fonts",
    providerPackage = "com.google.android.gms",
    certificates = R.array.com_google_android_gms_fonts_certs
)
    TextDownloadableFontsSnippets.kt
     I parametri ricevuti dal provider sono:
    • L'autorità del provider di caratteri per Google Fonts.
    • Il pacchetto del provider di caratteri per verificare l'identità del provider.
    • Un elenco di set di hash per i certificati per verificare l'identità del provider. Puoi trovare gli hash richiesti per il provider di Google Fonts nel file font_certs.xml nell'app di esempio Jetchat.
  3. Definisci un FontFamily: 
    // ...
 import androidx.compose.ui.text.googlefonts.GoogleFont
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider)
)
    TextDownloadableFontsSnippets.kt
     Puoi eseguire query per altri parametri del carattere, come peso e stile, rispettivamente con FontWeight e FontStyle: 
    // ...
 import androidx.compose.ui.text.googlefonts.GoogleFont
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(
        googleFont = fontName,
        fontProvider = provider,
        weight = FontWeight.Bold,
        style = FontStyle.Italic
    )
)
    TextDownloadableFontsSnippets.kt
  4. Configura FontFamily da utilizzare nella funzione composable Text:

Text(
    fontFamily = fontFamily, text = "Hello World!"
)
TextDownloadableFontsSnippets.kt

Puoi anche definire la tipografia per utilizzare il tuo FontFamily:

val MyTypography = Typography(
    bodyMedium = TextStyle(
        fontFamily = fontFamily, fontWeight = FontWeight.Normal, fontSize = 12.sp/*...*/
    ),
    bodyLarge = TextStyle(
        fontFamily = fontFamily,
        fontWeight = FontWeight.Bold,
        letterSpacing = 2.sp,
        /*...*/
    ),
    headlineMedium = TextStyle(
        fontFamily = fontFamily, fontWeight = FontWeight.SemiBold/*...*/
    ),
    /*...*/
)
TextDownloadableFontsSnippets.kt

Dopodiché, imposta la tipografia sul tema della tua app:

MyAppTheme(
    typography = MyTypography
)/*...*/
TextDownloadableFontsSnippets.kt

Per un esempio di un'app che implementa i caratteri scaricabili in Compose insieme a Material3, consulta l'app di esempio Jetchat.

Aggiungere caratteri di riserva

Puoi determinare una catena di fallback per il carattere nel caso in cui il download non vada a buon fine. Ad esempio, se hai definito il carattere scaricabile in questo modo:

// ...
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider),
    Font(googleFont = fontName, fontProvider = provider, weight = FontWeight.Bold)
)
TextDownloadableFontsSnippets.kt

Puoi definire i valori predefiniti per il carattere per entrambi i pesi in questo modo:

// ...
 import androidx.compose.ui.text.font.Font
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider),
    Font(resId = R.font.my_font_regular),
    Font(googleFont = fontName, fontProvider = provider, weight = FontWeight.Bold),
    Font(resId = R.font.my_font_regular_bold, weight = FontWeight.Bold)
)
TextDownloadableFontsSnippets.kt

Assicurati di aggiungere le importazioni corrette.

La definizione di FontFamily in questo modo crea un FontFamily contenente due catene, una per peso. Il meccanismo di caricamento tenterà di risolvere prima il carattere online e poi il carattere che si trova nella cartella delle risorse R.font locale.

Eseguire il debug dell'implementazione

Per verificare se il download del carattere è corretto, puoi definire un gestore di coroutine di debug. Il gestore fornisce il comportamento da adottare nel caso in cui il caricamento asincrono del carattere non vada a buon fine.

Inizia creando un CoroutineExceptionHandler:

val handler = CoroutineExceptionHandler { _, throwable ->
    // process the Throwable
    Log.e(TAG, "There has been an issue: ", throwable)
}
TextDownloadableFontsSnippets.kt

Passalo al createFontFamilyResolver metodo per fare in modo che il resolver utilizzi il nuovo gestore:

CompositionLocalProvider(
    LocalFontFamilyResolver provides createFontFamilyResolver(LocalContext.current, handler)
) {
    Column {
        Text(
            text = "Hello World!", style = MaterialTheme.typography.bodyMedium
        )
    }
}
TextDownloadableFontsSnippets.kt

Puoi anche utilizzare l' isAvailableOnDevice API del provider per verificare se il provider è disponibile e se i certificati sono configurati correttamente. Per farlo, puoi chiamare il metodo isAvailableOnDevice che restituisce false se il provider non è configurato correttamente.

val context = LocalContext.current
LaunchedEffect(Unit) {
    if (provider.isAvailableOnDevice(context)) {
        Log.d(TAG, "Success!")
    }
}
TextDownloadableFontsSnippets.kt

Precisazioni

Google Fonts impiega diversi mesi per rendere disponibili i nuovi caratteri su Android. Esiste un intervallo di tempo tra il momento in cui un carattere viene aggiunto in fonts.google.com e il momento in cui è disponibile tramite l'API dei caratteri scaricabili (nel sistema View o in Compose). Il caricamento dei caratteri appena aggiunti potrebbe non riuscire nella tua app con un IllegalStateException. Per aiutare gli sviluppatori a identificare questo errore rispetto ad altri tipi di errori di caricamento dei caratteri, abbiamo aggiunto messaggi descrittivi per l'eccezione in Compose con le modifiche qui. Se riscontri problemi, segnalali utilizzando lo strumento di monitoraggio dei problemi.

Utilizzare i caratteri variabili

Un carattere variabile è un formato di carattere che consente a un file di carattere di contenere stili diversi. Con i caratteri variabili, puoi modificare gli assi (o i parametri) per generare lo stile che preferisci. Questi assi possono essere standard, come peso, larghezza, inclinazione e corsivo, o personalizzati, che variano a seconda dei caratteri variabili.

Cinque configurazioni dello stesso carattere variabile con valori degli assi diversi.
Figura 1. Testo che utilizza lo stesso carattere variabile personalizzato con valori di assi diversi.

L'utilizzo di caratteri variabili anziché di file di caratteri normali consente di avere un solo file di caratteri anziché più file.

Per ulteriori informazioni sui caratteri variabili, consulta la sezione Google Fonts Conoscenze, l'intero catalogo dei caratteri variabili disponibili e una tabella degli assi supportati per ogni carattere.

Questo documento mostra come implementare un carattere variabile nella tua app Compose.

Caricare un carattere variabile

  1. Scarica il carattere variabile che vuoi utilizzare (ad esempio Roboto Flex) e inseriscilo nella cartella app/res/font della tua app. Assicurati che il file .ttf che aggiungi sia la versione del carattere variabile e che il nome del file del carattere sia tutto in minuscolo e non contenga caratteri speciali.

  2. Per caricare un carattere variabile, definisci un FontFamily utilizzando il carattere inserito nella directory res/font/:

    // In Typography.kt
@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily =
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(950),
                FontVariation.width(30f),
                FontVariation.slant(-6f),
            )
        )
    )
    VariableFontsSnippets.kt

    L'API FontVariation consente di configurare gli assi dei caratteri standard, come peso, larghezza e inclinazione. Questi sono assi standard disponibili con qualsiasi carattere variabile. Puoi creare configurazioni diverse del carattere in base a dove verrà utilizzato.

  3. I caratteri variabili sono disponibili solo per le versioni di Android O e successive, quindi aggiungi una protezione e configura un fallback appropriato:

    // In Typography.kt
val default = FontFamily(
    /*
    * This can be any font that makes sense
    */
    Font(
        R.font.robotoflex_static_regular
    )
)
@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(950),
                FontVariation.width(30f),
                FontVariation.slant(-6f),
            )
        )
    )
} else {
    default
}
    VariableFontsSnippets.kt

  4. Estrai le impostazioni in un insieme di costanti per un riutilizzo più semplice e sostituisci le impostazioni dei caratteri con queste costanti:

    // VariableFontDimension.kt
object DisplayLargeVFConfig {
    const val WEIGHT = 950
    const val WIDTH = 30f
    const val SLANT = -6f
    const val ASCENDER_HEIGHT = 800f
    const val COUNTER_WIDTH = 500
}

@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(DisplayLargeVFConfig.WEIGHT),
                FontVariation.width(DisplayLargeVFConfig.WIDTH),
                FontVariation.slant(DisplayLargeVFConfig.SLANT),
            )
        )
    )
} else {
    default
}
    VariableFontsSnippets.kt

  5. Configura la tipografia Material Design 3 typography per utilizzare il FontFamily:

    // Type.kt
val Typography = Typography(
    displayLarge = TextStyle(
        fontFamily = displayLargeFontFamily,
        fontSize = 50.sp,
        lineHeight = 64.sp,
        letterSpacing = 0.sp,
        /***/
    )
)
    VariableFontsSnippets.kt

    Questo esempio utilizza displayLarge la tipografia Material 3, che ha impostazioni dei caratteri predefinite e utilizzi consigliati diversi. Ad esempio, devi utilizzare displayLarge per il testo breve e critico, poiché è il testo più grande sullo schermo.

    Con Material 3, puoi modificare i valori predefiniti di TextStyle e fontFamily per personalizzare la tipografia. Nello snippet sopra, configuri le istanze di TextStyle per personalizzare le impostazioni dei caratteri per ogni famiglia di caratteri.

  6. Ora che hai definito la tipografia, passala a MaterialTheme M3:

    MaterialTheme(
    colorScheme = MaterialTheme.colorScheme,
    typography = Typography,
    content = content
)
    VariableFontsSnippets.kt

  7. Infine, utilizza un composable Text e specifica lo stile in uno degli stili di tipografia definiti, MaterialTheme.typography.displayLarge:

    @Composable
@Preview
fun CardDetails() {
    MyCustomTheme {
        Card(
            shape = RoundedCornerShape(8.dp),
            elevation = CardDefaults.cardElevation(defaultElevation = 4.dp),
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp)
        ) {
            Column(
                modifier = Modifier.padding(16.dp)
            ) {
                Text(
                    text = "Compose",
                    style = MaterialTheme.typography.displayLarge,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 1
                )
                Text(
                    text = "Beautiful UIs on Android",
                    style = MaterialTheme.typography.headlineMedium,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 2
                )
                Text(
                    text = "Jetpack Compose is Android’s recommended modern toolkit for building native UI. It simplifies and accelerates UI development on Android. Quickly bring your app to life with less code, powerful tools, and intuitive Kotlin APIs.",
                    style = MaterialTheme.typography.bodyLarge,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 3
                )
            }
        }
    }
}
    VariableFontsSnippets.kt

    Ogni composable Text viene configurato tramite lo stile del tema Material e contiene una configurazione di caratteri variabili diversa. Puoi utilizzare MaterialTheme.typography per recuperare la tipografia fornita al composable M3 MaterialTheme.

Tre testi diversi, tutti con configurazioni di caratteri differenti.
Figura 2. Carattere variabile applicato in tre configurazioni diverse.

Utilizzare gli assi personalizzati

I caratteri possono avere anche assi personalizzati. Questi sono definiti all'interno del file del carattere stesso. Ad esempio, il carattere Roboto Flex ha l'asse dell'altezza dell'ascendente ("YTAS"), che regola l'altezza degli ascendenti minuscoli, mentre la larghezza del contatore ("XTRA") regola la larghezza di ogni lettera.

Puoi modificare il valore di questi assi con le impostazioni FontVariation.

Per ulteriori informazioni sugli assi personalizzati che puoi configurare per un carattere, consulta la tabella degli assi supportati per ogni carattere.

  1. Per utilizzare gli assi personalizzati, definisci le funzioni per gli assi personalizzati ascenderHeight e counterWidth:

    fun ascenderHeight(ascenderHeight: Float): FontVariation.Setting {
    require(ascenderHeight in 649f..854f) { "'Ascender Height' must be in 649f..854f" }
    return FontVariation.Setting("YTAS", ascenderHeight)
}

fun counterWidth(counterWidth: Int): FontVariation.Setting {
    require(counterWidth in 323..603) { "'Counter width' must be in 323..603" }
    return FontVariation.Setting("XTRA", counterWidth.toFloat())
}
    VariableFontsSnippets.kt

    Queste funzioni eseguono le seguenti operazioni:

    • Definiscono le protezioni per i valori che possono accettare. Come puoi vedere nel catalogo dei caratteri variabili, ascenderHeight (YTAS) ha un valore minimo di 649f e un valore massimo di 854f.
    • Restituiscono l'impostazione del carattere, in modo che la configurazione sia pronta per essere aggiunta al carattere. Nel metodo FontVariation.Setting(), il nome dell'asse (YTAS, XTRA) è hardcoded e accetta il valore come parametro.

  2. Utilizzando gli assi con la configurazione dei caratteri, passa parametri aggiuntivi a ogni Font caricato:

    @OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(DisplayLargeVFConfig.WEIGHT),
                FontVariation.width(DisplayLargeVFConfig.WIDTH),
                FontVariation.slant(DisplayLargeVFConfig.SLANT),
                ascenderHeight(DisplayLargeVFConfig.ASCENDER_HEIGHT),
                counterWidth(DisplayLargeVFConfig.COUNTER_WIDTH)
            )
        )
    )
} else {
    default
}
    VariableFontsSnippets.kt

    Tieni presente che l'altezza degli ascendenti minuscoli è aumentata e l'altro testo è più ampio:

Tre testi diversi che mostrano configurazioni diverse per i caratteri variabili, con assi personalizzati impostati: alcuni hanno ascendenti minuscoli più alti e sono più larghi di prima.
Figura 3. Testo che mostra gli assi personalizzati impostati sui caratteri variabili.

Risorse aggiuntive

Per ulteriori informazioni, consulta il seguente post del blog sui caratteri variabili: