Utilizza caratteri scaricabili

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

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

I caratteri scaricabili offrono i seguenti vantaggi:

  • Riduce le dimensioni dell'app, aumentando di conseguenza la percentuale di successo dell'installazione dell'app.
  • Migliora l'integrità complessiva del sistema, poiché più app possono condividere lo stesso carattere tramite un provider. In questo modo si risparmiano dati cellulare, memoria e spazio su disco dell'utente. In questo modello, il carattere viene recuperato sulla rete quando necessario.
Per fare un'esperienza pratica con i caratteri scaricabili, vedi l'app di esempio DownloadableFonts.

Come funzionano i caratteri scaricabili?

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à Caratteri scaricabili nei seguenti modi, che verranno descritti dettagliatamente nelle sezioni successive:

Utilizzare i caratteri scaricabili con Android Studio e Google Play Services

Puoi impostare l'applicazione in modo che scarichi i caratteri con Android Studio 3.0 o versioni successive. Per iniziare a utilizzare le funzionalità Caratteri scaricabili, puoi utilizzare il fornitore di caratteri di Google Play Services.

  1. Nell'Editor layout, seleziona un TextView. Quindi, in Attributi, seleziona Famiglia di caratteri > Altri caratteri.
    Un'immagine che mostra l'Editor layout di Android Studio
    Figura 2. Utilizzando l'Editor layout.
    Viene visualizzata la finestra Risorse.
  2. Nel menu Origine, seleziona Google Fonts.
  3. Nella casella Caratteri, seleziona un carattere nell'area "Scaricabili".
  4. Seleziona Crea carattere scaricabile e fai clic su OK.
    Un'immagine che mostra come selezionare i caratteri dalla finestra Risorse
    Figura 3. Seleziona un carattere dalla finestra Risorse.

    5. Android Studio genera automaticamente i file XML pertinenti necessari per visualizzare correttamente il carattere nell'app.

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

Utilizza i caratteri scaricabili in modo programmatico

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

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

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

Per scaricare un carattere, procedi nel seguente modo:

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

    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 del carattere è stata completata. Fornisci come parametro il carattere recuperato. Puoi utilizzare questo metodo per impostare il carattere in base alle tue esigenze. Ad esempio, puoi impostare il carattere su TextView.
  4. Sostituisci il 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. Il metodo avvia un controllo per determinare se il carattere esiste nella cache. Se il carattere non è disponibile localmente, viene chiamato il fornitore del carattere, recupera il carattere 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
    • Un callback per ricevere i risultati della richiesta di carattere
    • Un gestore per il recupero dei 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 di caratteri, vedi l'app di esempio DownloadableFonts.

Utilizzare i caratteri scaricabili con AndroidX Core

AndroidX Core fornisce supporto per la funzionalità Caratteri scaricabili sui dispositivi con API Android 14 o versioni 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 ai metodi del framework e la procedura per scaricare i caratteri è simile a quella descritta nella sezione di questa pagina relativa all'utilizzo programmatico dei caratteri scaricabili.

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

Aggiungi dipendenza AndroidX Core

Per utilizzare le classi FontsContractCompat e FontRequest, devi modificare le dipendenze 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:

Alla moda

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

Kotlin

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

Utilizza 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 al fine di velocizzare l'usabilità per più spessori e stili, ad esempio grassetto, medio o chiaro, se disponibili.

  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 @font/font_file_name nel file XML di layout. Puoi anche utilizzare il metodo getFont() per recuperare il file in modo programmatico, ad esempio getFont(R.font.font_file_name).

Pre-dichiarare i caratteri nel manifest

L'aumento artificiale 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 di conseguenza aumenta il tempo di utilizzo del primo layout. Per evitare questo ritardo, puoi predichiarare i caratteri che devono essere recuperati nel file manifest. Una volta che il sistema ha recuperato il carattere dal provider, questo è immediatamente disponibile. Se il recupero del carattere richiede più tempo del previsto, il sistema interrompe la procedura 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 file manifest.
    3. <meta-data android:name="preloaded_fonts" android:resource="@array/preloaded_fonts" />

Aggiungi certificati

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

Per aggiungere certificati, segui questi passaggi:

  1. Crea un array di stringhe con i dettagli del certificato. Per ulteriori informazioni sui dettagli dei certificati, consulta la documentazione del fornitore di caratteri.
    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 Compose

A partire da Compose 1.2-alpha07 puoi utilizzare l'API Downloadable Fonts nell'app Compose per scaricare Google Fonts in modo asincrono e utilizzarli nella tua app. Per ulteriori informazioni, consulta la documentazione Compose Downloadable Fonts.