Utilizzare i caratteri

In questa pagina viene descritto come impostare i caratteri nell'app Compose.

Imposta carattere

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

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

Le parole

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

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

Questo esempio mostra come definire un fontFamily basato su 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)
)

Puoi passare questo fontFamily al tuo composable Text. Poiché una fontFamily può includere spessori diversi, puoi impostare manualmente fontWeight per selezionare lo spessore giusto 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)
}

Le parole

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

Font scaricabili

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

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

Utilizza i caratteri scaricabili in modo programmatico

Per scaricare un carattere in modo programmatico dall'interno della tua app, segui questi passaggi:

  1. Aggiungi la dipendenza:

    Alla moda

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

    Kotlin

    dependencies {
    ...
    implementation("androidx.compose.ui:ui-text-google-fonts:1.12.1")
}
  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
)
     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 insiemi di hash per i certificati per verificare l'identità del provider. Puoi trovare gli hash richiesti per il provider 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)
)
     Puoi eseguire query per altri parametri del carattere, come spessore 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
    )
)
  4. Configura FontFamily da utilizzare nella funzione componibile Text:

Text(
    fontFamily = fontFamily, text = "Hello World!"
)

Puoi inoltre 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/*...*/
    ),
    /*...*/
)

Poi, imposta la tipografia sul tema della tua app:

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

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

Aggiungi caratteri di riserva

Puoi determinare una catena di fallback per il tuo carattere nel caso in cui il download non venga eseguito correttamente. Ad esempio, se hai definito il tuo 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)
)

Puoi definire i valori predefiniti per il carattere per entrambi gli spessori 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)
)

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 proverà prima a risolvere il carattere online, poi quello che si trova nella cartella delle risorse R.font locale.

Esegui il debug dell'implementazione

Per aiutarti a verificare se il carattere viene scaricato correttamente, puoi definire un gestore di coroutine di debug. Il tuo handle 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)
}

Passalo al metodo createFontFamilyResolver 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
        )
    }
}

Puoi anche utilizzare l'API isAvailableOnDevice 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!")
    }
}

Precisazioni

Google Fonts impiega diversi mesi per rendere disponibili i nuovi caratteri su Android. C'è un intervallo di tempo tra l'aggiunta di un carattere in fonts.google.com e la sua disponibilità tramite l'API dei caratteri scaricabili (nel sistema di visualizzazione o in Compose). I caratteri appena aggiunti potrebbero non essere caricati nell'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 Issue Tracker.

Utilizza i caratteri variabili

Un carattere variabile è un formato di carattere che consente a un file di caratteri 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 spessore, larghezza, inclinazione e corsivo, o personalizzati, che variano a seconda dei caratteri variabili.

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

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

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

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

Carica un carattere variabile

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

  2. Per caricare un font variabile, definisci un FontFamily utilizzando il font 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),
            )
        )
    )

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

  3. I caratteri variabili sono disponibili solo per Android O e versioni successive, quindi aggiungi un controllo e configura un carattere di riserva 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
}

  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
}

  5. Configura la tipografia di Material Design 3 in modo che utilizzi FontFamily:

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

    Questo esempio utilizza la tipografia Material 3 di displayLarge, che ha impostazioni dei caratteri predefinite e utilizzi consigliati diversi. Ad esempio, dovresti utilizzare displayLarge per testi brevi e importanti, in quanto è il testo più grande sullo schermo.

    Con Material 3, puoi modificare i valori predefiniti di TextStyle e fontFamily per personalizzare la tipografia. Nello snippet riportato 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 M3 MaterialTheme:

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

  7. Infine, utilizza un componibile 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
                )
            }
        }
    }
}

    Ogni componibile Text è configurato tramite lo stile dei temi di Material e contiene una configurazione di font variabile diversa. Puoi utilizzare MaterialTheme.typography per recuperare la tipografia fornita al componibile MaterialTheme M3.

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

Utilizza assi personalizzati

I caratteri possono anche avere 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 saperne di più 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())
}

    Queste funzioni prevedono quanto segue:

    • Definisci i guardrail 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.
    • Restituisci 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) è impostato come 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
}

    Nota che l'altezza delle lettere minuscole con ascendenti è ora aumentata e l'altro testo è più largo:

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 saperne di più, consulta il seguente post del blog sui caratteri variabili: