Utilizza caratteri scaricabili

Prova il modo di comporre
Jetpack Compose è il toolkit per la UI consigliato per Android. Scopri come utilizzare il testo in Scrivi.
Caratteri scaricabili →

La funzionalità Caratteri scaricabili consente alle API di richiedere caratteri da un'applicazione del fornitore anziché raggruppare i file nell'app o consentire all'app di scaricare i caratteri. I caratteri scaricabili sono disponibili sui dispositivi con versioni dell'API Android 14 e successive tramite la libreria AndroidX Core.

I caratteri scaricabili offrono i seguenti vantaggi:

  • Riduce le dimensioni dell'app, aumentando così il tasso di successo dell'installazione.
  • Migliora lo stato generale del sistema, in quanto più app possono condividere lo stesso carattere tramite un provider. In questo modo, gli utenti risparmiano dati mobili, memoria dello smartphone e spazio su disco. In questo modello, il font viene recuperato dalla rete quando necessario.
Per un'esperienza pratica con i caratteri scaricabili, consulta l'app di esempio DownloadableFonts.

Come funziona Downloadable Fonts?

Un fornitore di caratteri è un'applicazione che recupera i caratteri e li memorizza nella cache localmente in modo che altre app possano richiederli e condividerli. La figura seguente illustra la procedura.

Un'immagine che mostra i componenti principali del processo di compatibilità delle emoji
Figura 1. Procedura per i caratteri scaricabili.

Nozioni di base

Puoi utilizzare la funzionalità Font scaricabili nei seguenti modi, descritti in dettaglio nelle sezioni successive:

Utilizzare i caratteri scaricabili con Android Studio e Google Play Services

Puoi impostare l'applicazione per scaricare i caratteri utilizzando Android Studio 3.0 o versioni successive. Per iniziare a utilizzare le funzionalità dei caratteri scaricabili, puoi utilizzare il provider di caratteri di Google Play Services.

  1. Nell'editor del layout, seleziona un TextView. Poi, in Attributi, seleziona fontFamily > Altri caratteri.
    Un'immagine che mostra l'editor layout di Android Studio
    Figura 2. Utilizzo dell'editor di layout.
    Viene visualizzata la finestra Risorse.
  2. Nel menu Origine, seleziona Google Fonts.
  3. Nella casella Caratteri, seleziona un carattere nell'area "Scaricabile".
  4. Seleziona Crea carattere scaricabile e fai clic su Ok.
    Un'immagine che mostra come selezionare i caratteri dalla finestra Risorse
    Figura 3. Selezionando un carattere dalla finestra Risorse.

    5. Android Studio genera automaticamente i file XML pertinenti necessari per eseguire il rendering del carattere correttamente nella tua app.

    Un'immagine che mostra come visualizzare l'anteprima dei caratteri
    Figura 4. Visualizzazione dell'anteprima del file del carattere.

Utilizzare i caratteri scaricabili in modo programmatico

A partire da Android 8.0 (livello API 26), AndroidX Core fornisce il supporto completo per i caratteri scaricabili. Per maggiori informazioni sull'utilizzo della libreria AndroidX Core, consulta la sezione Libreria AndroidX Core per i caratteri scaricabili in questa pagina.

Per utilizzare la funzionalità Caratteri scaricabili in modo programmatico, interagisci con due classi chiave:

La tua app recupera i caratteri dal fornitore di caratteri utilizzando l'API FontsContract. Ogni fornitore ha il proprio insieme di limitazioni relative alle versioni di Android e al linguaggio di query supportato. Per ulteriori informazioni sulle versioni di Android e sul formato delle query, consulta la documentazione del tuo provider.

Per scaricare un carattere:

  1. Crea un'istanza della classe android.graphics.fonts.FontRequest per richiedere il carattere al fornitore. Per creare una richiesta, trasmetti i seguenti parametri:
    • L'autorità del fornitore di caratteri.
    • Il pacchetto del fornitore di caratteri per verificare la sua identità.
    • La stringa di query del carattere. Per ulteriori informazioni sui formati delle query, consulta la documentazione del tuo fornitore di caratteri, ad esempio Google Fonts.
    • Un elenco di set di hash per i certificati per verificare l'identità del fornitore.

    Kotlin

    val request = FontRequest(
        "com.example.fontprovider.authority",
        "com.example.fontprovider",
        "my font",
        certs
)

    Java

    FontRequest request = new FontRequest("com.example.fontprovider",
                   "com.example.fontprovider", "my font", certs);
  2. Crea un'istanza della classe FontsContract.FontRequestCallback.
  3. Esegui l'override del metodo onTypefaceRetrieved() per indicare che la richiesta di carattere è stata completata. Fornisci il carattere recuperato come parametro. Puoi utilizzare questo metodo per impostare il carattere in base alle tue esigenze. Ad esempio, puoi impostare il carattere su un TextView.
  4. Esegui l'override del metodo onTypefaceRequestFailed() per ricevere informazioni sugli errori nella procedura di richiesta dei caratteri. Per saperne di più sui codici di errore, consulta le costanti dei codici di errore.
  5. Chiama il metodo FontsContract.requestFont() per recuperare il carattere dal fornitore di caratteri. Il metodo avvia un controllo per determinare se il carattere esiste nella cache. Se il carattere non è disponibile localmente, chiama il fornitore del carattere, lo recupera in modo asincrono e passa il risultato al callback. Trasmetti i seguenti parametri:
    • Un'istanza della classe Context
    • Un'istanza della classe android.graphics.fonts.FontRequest
    • Una richiamata per ricevere i risultati della richiesta di carattere
    • Un gestore per recuperare i caratteri in un thread

Il seguente codice di esempio illustra la procedura generale per i caratteri scaricabili:

Kotlin

val request = FontRequest(
        "com.example.fontprovider.authority",
        "com.example.fontprovider",
        "my font",
        certs
)
val callback = object : FontsContract.FontRequestCallback() {

    override fun onTypefaceRetrieved(typeface: Typeface) {
        // Your code to use the font goes here.
        ...
    }

    override fun onTypefaceRequestFailed(reason: Int) {
        // Your code to deal with the failure goes here.
        ...
    }
}
FontsContract.requestFonts(context, request, handler, null, callback)

Java

FontRequest request = new FontRequest("com.example.fontprovider.authority",
        "com.example.fontprovider", "my font", certs);
FontsContract.FontRequestCallback callback =
    new FontsContract.FontRequestCallback() {
        @Override
        public void onTypefaceRetrieved(Typeface typeface) {
            // Your code to use the font goes here.
            ...
        }

        @Override
        public void onTypefaceRequestFailed(int reason) {
            // Your code to deal with the failure goes here.
            ...
        }
};
FontsContract.requestFonts(context, request, handler, null, callback);

Per ulteriori informazioni su come scaricare un carattere da un fornitore, consulta l'app di esempio DownloadableFonts.

Utilizzare i caratteri scaricabili con AndroidX Core

AndroidX Core fornisce il supporto per la funzionalità Caratteri scaricabili sui dispositivi con versioni API Android 14 o successive. Il pacchetto androidx.core.provider contiene le classi FontsContractCompat e FontRequest per implementare il supporto della funzionalità Caratteri scaricabili compatibile con le versioni precedenti. Le classi AndroidX contengono metodi simili a quelli del framework e la procedura per scaricare i caratteri è simile a quella descritta nella sezione di questa pagina relativa all'utilizzo dei caratteri scaricabili a livello di programmazione.

Per scaricare i caratteri utilizzando AndroidX, importa le classi FontsContractCompat e FontRequest dal pacchetto androidx.core.provider. Crea istanze di queste classi anziché classi framework FontsContract e android.graphics.fonts.FontRequest.

Aggiungi la dipendenza AndroidX Core

Per utilizzare le classi FontsContractCompat e FontRequest, devi modificare le dipendenze del classpath del progetto dell'app all'interno dell'ambiente di sviluppo.

Per aggiungere AndroidX Core al progetto dell'applicazione, aggiungi la seguente dipendenza al file build.gradle dell'app:

Groovy

dependencies {
    ...
    implementation "androidx.core:core-ktx:1.16.0"
}

Kotlin

dependencies {
    ...
    implementation("androidx.core:core-ktx:1.16.0")
}

Utilizzare i caratteri scaricabili come risorse in XML

Android 8.0 (livello API 26) e AndroidX Core offrono un modo più rapido e pratico per dichiarare un carattere personalizzato come risorsa nel layout XML. Ciò significa che non è necessario raggruppare il carattere come asset. Puoi definire un carattere personalizzato per l'intero tema, il che accelera l'usabilità per più pesi e stili, ad esempio grassetto, medio o chiaro, se forniti.

  1. Crea un nuovo file XML nella cartella res/font.
  2. Aggiungi un elemento principale <font-family> e imposta gli attributi relativi al carattere, come mostrato nel seguente file XML di esempio:
    3. <?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android="http://schemas.android.com/apk/res/android"
        android:fontProviderAuthority="com.example.fontprovider.authority"
        android:fontProviderPackage="com.example.fontprovider"
        android:fontProviderQuery="example font"
        android:fontProviderCerts="@array/certs">
</font-family>
  3. Fai riferimento al file come @font/font_file_name nel file XML del layout. Puoi anche utilizzare il metodo getFont() per recuperare il file in modo programmatico, ad esempio getFont(R.font.font_file_name).

Dichiarare in anticipo i caratteri nel manifest

L'espansione del layout e il recupero delle risorse sono attività sincrone. Per impostazione predefinita, il primo tentativo di recupero dei caratteri attiva una richiesta al fornitore di caratteri e quindi aumenta il tempo del primo layout. Per evitare il ritardo, puoi pre-dichiarare nel manifest i caratteri che devono essere recuperati. Dopo che il sistema recupera il carattere dal fornitore, questo è disponibile immediatamente. Se il recupero del carattere richiede più tempo del previsto, il sistema interrompe il processo di recupero e utilizza il carattere predefinito.

Per pre-dichiarare i caratteri nel manifest, completa i seguenti passaggi:

  1. Crea un array di risorse in res/values/arrays.xml e dichiara i caratteri che vuoi precaricare.
    2. res/values/arrays.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="preloaded_fonts">
        <item>@font/font1</item>
        <item>@font/font2</item>
    </array>
</resources>
  2. Utilizza un tag meta-data per dichiarare l'array di risorse nel manifest.
    3. <meta-data android:name="preloaded_fonts" android:resource="@array/preloaded_fonts" />

Aggiungere certificati

Quando un fornitore di caratteri non è preinstallato o se utilizzi la libreria AndroidX Core, dichiara i certificati con cui è firmato il fornitore di caratteri. Il sistema utilizza i certificati per verificare l'identità del fornitore di caratteri.

Per aggiungere certificati, segui questi passaggi:

  1. Crea un array di stringhe con i dettagli del certificato. Per ulteriori informazioni sui dettagli del certificato, consulta la documentazione del fornitore del carattere.
    2. <?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="certs">
       <item>MIIEqDCCA5CgAwIBAgIJA071MA0GCSqGSIb3DQEBBAUAMIGUMQsww...</item>
    </string-array>
</resources>
  2. Imposta l'attributo fontProviderCerts sull'array.
    3. android:fontProviderCerts="@array/certs"

Caratteri scaricabili in Scrivi