Utilizza caratteri scaricabili

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

La funzionalità Caratteri scaricabili consente alle API di richiedere caratteri da un'applicazione provider 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ì la percentuale di successo dell'installazione dell'app.
  • 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 carattere viene recuperato dalla rete quando necessario.
Per un'esperienza pratica con i caratteri scaricabili, consulta l'app di esempio DownloadableFonts.

Come funzionano i caratteri scaricabili?

Un provider di caratteri è un'applicazione che recupera i caratteri e li memorizza nella cache in locale in modo che altre app possano richiedere e condividere i caratteri. 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, descritti in dettaglio nelle sezioni successive:

Utilizzare i caratteri scaricabili con Android Studio e Google Play Services

Puoi impostare l'applicazione in modo che scarichi 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 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 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. Selezione di un carattere dalla finestra Risorse.

    5. Android Studio genera automaticamente i file XML pertinenti necessari per eseguire il rendering corretto del carattere nell'app.

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

Utilizzare i caratteri scaricabili a livello di programmazione

A partire da Android 8.0 (livello API 26), AndroidX Core fornisce il supporto completo per i caratteri scaricabili. Per ulteriori 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 a livello di programmazione, interagisci con due classi chiave:

L'app recupera i caratteri dal provider di caratteri utilizzando l'API FontsContract. Ogni provider ha il proprio set di limitazioni sulle versioni di Android e sul linguaggio di query che supporta. 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 provider. Per creare una richiesta, passa i seguenti parametri:
    • L'autorità del provider di caratteri.
    • Il pacchetto del provider di caratteri per verificare l'identità del provider.
    • La stringa di query del carattere. Per ulteriori informazioni sui formati delle query, consulta la documentazione del provider di caratteri, ad esempio Google Fonts.
    • Un elenco di set di hash per i certificati per 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 FontsContract.FontRequestCallback classe.
  3. Esegui l'override del onTypefaceRetrieved() metodo per indicare che la richiesta di caratteri è stata completata. Fornisci il carattere recuperato come parametro. Puoi utilizzare questo metodo per impostare il carattere in base alle esigenze. Ad esempio, puoi impostare il carattere su un TextView.
  4. Esegui l'override del onTypefaceRequestFailed() metodo per ricevere informazioni sugli errori nella procedura di richiesta dei caratteri. Per ulteriori informazioni sui codici di errore, consulta le costanti dei codici di errore.
  5. Chiama il metodo FontsContract.requestFont() per recuperare il carattere dal provider di caratteri. Il metodo avvia un controllo per determinare se il carattere esiste nella cache. Se il carattere non è disponibile localmente, chiama il provider di caratteri, recupera il carattere in modo asincrono e passa il risultato al callback. Passa i seguenti parametri:
    • Un'istanza della Context classe
    • Un'istanza della classe android.graphics.fonts.FontRequest
    • Un callback per ricevere i risultati della richiesta di caratteri
    • Un gestore per recuperare i caratteri su 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 provider di caratteri, 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 dell'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 ai metodi del framework e la procedura per scaricare i caratteri è simile a quella descritta nella sezione di questa pagina su come utilizzare i 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é delle classi del framework FontsContract e android.graphics.fonts.FontRequest.

Aggiungere 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:

Alla moda

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

Kotlin

dependencies {
    ...
    implementation("androidx.core:core-ktx:1.19.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 leggero, se forniti.

  1. Crea un nuovo file XML nella cartella res/font.
  2. Aggiungi un elemento radice <font-family> e imposta gli attributi relativi ai caratteri, 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 getFont() metodo per recuperare il file a livello di programmazione, 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 recuperare i caratteri attiva una richiesta al provider di caratteri e, di conseguenza, aumenta il tempo del primo layout. Per evitare il ritardo, puoi dichiarare in anticipo i caratteri da recuperare nel manifest. Dopo che il sistema ha recuperato il carattere dal provider, è disponibile immediatamente. Se il recupero dei caratteri richiede più tempo del previsto, il sistema interrompe la procedura di recupero e utilizza il carattere predefinito.

Per dichiarare in anticipo i caratteri nel manifest:

  1. Crea un array di risorse in res/values/arrays.xml e dichiara i caratteri di cui vuoi eseguire il precaricamento.
    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" />

Aggiungi certificati

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

Per aggiungere i certificati:

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