Utilizza caratteri scaricabili

Prova la modalità Scrivi

Jetpack Compose è il toolkit dell'interfaccia utente consigliato per Android. Scopri come utilizzare il testo in Compose.

Caratteri scaricabili →

Nota: questa pagina descrive come utilizzare i caratteri scaricabili con una UI basata su View. Se utilizzi Jetpack Compose, consulta la documentazione relativa ai caratteri scaricabili in Compose.

La funzionalità dei 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. La funzionalità Caratteri scaricabili è disponibile sui dispositivi con l'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 installazione dell'app riuscita.
• Migliora l'integrità complessiva del sistema, poiché più app possono condividere lo stesso carattere tramite un provider. In questo modo, gli utenti potranno risparmiare rete dati, memoria del telefono e spazio su disco. In questo modello, il carattere viene recuperato sulla rete quando necessario.

Per un'esperienza pratica con i caratteri scaricabili, guarda 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 localmente in modo che altre app possano richiedere e condividere i caratteri. La figura seguente illustra il processo.

Figura 1. Procedura relativa ai caratteri scaricabili.

Nozioni di base

Puoi utilizzare la funzionalità dei caratteri scaricabili nei seguenti modi, che tratteremo in dettaglio nelle sezioni successive:

• Utilizzare Android Studio e Google Play Services
• In modo programmatico
• Utilizzare la libreria AndroidX Core

Utilizzare i caratteri scaricabili con Android Studio e Google Play Services

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

Nota: per poter utilizzare il fornitore di Google Fonts, un dispositivo deve avere Google Play Services 11 o versioni successive.

1. Nell'Editor di layout, seleziona un TextView. Quindi, in Attributi, seleziona fontFamily > Altri caratteri.

   

   Figura 2. Utilizzando l'Editor di 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.

   

   Figura 3. Seleziona un carattere dalla finestra Risorse.

Android Studio genera automaticamente i file XML pertinenti necessari per visualizzare correttamente il carattere nella tua app.



Figura 4. Anteprima del file dei caratteri.

Utilizza caratteri scaricabili in modo programmatico

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

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

• android.graphics.fonts.FontRequest: questa classe consente di creare una richiesta di caratteri.
• FontsContractCompat: questa classe consente di creare un nuovo oggetto Typeface in base alla richiesta del carattere.

L'app recupera i caratteri dal fornitore utilizzando l'API FontsContract. Ogni provider ha il proprio insieme di limitazioni relative alle versioni di Android e al 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, procedi nel seguente modo:

1. Crea un'istanza della classe android.graphics.fonts.FontRequest per richiedere il carattere al provider. Per creare una richiesta, trasmetti i seguenti parametri:
   • L'autorità del fornitore di 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 insiemi di hash per i certificati per verificare l'identità del provider.
     Nota: non è necessario aggiungere un certificato se richiedi i caratteri a provider preinstallati. Tuttavia, fornisci sempre un certificato se richiedi caratteri tramite la libreria AndroidX Core.

   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);
   

   Nota: puoi ricevere i valori dei parametri dal tuo fornitore di caratteri. Android Studio compila automaticamente questi valori per i fornitori supportati nella sua UI.
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 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 elemento TextView.
4. Esegui l'override del metodo onTypefaceRequestFailed() per ricevere informazioni sugli errori nel processo di richiesta dei caratteri. Per saperne di più sui codici di errore, consulta le costanti dei codici di errore.
5. Richiama il metodo FontsContract.requestFont() per recuperare il carattere dal fornitore. Il metodo avvia un controllo per determinare se il carattere è presente nella cache. Se il carattere non è disponibile a livello locale, chiama il fornitore di caratteri, recupera il carattere in modo asincrono e passa il risultato al callback. Trasmetti i seguenti parametri:
   • Un'istanza di classe Context
   • Un'istanza di classe android.graphics.fonts.FontRequest
   • Un callback per ricevere i risultati della richiesta di carattere.
   • Un gestore per recuperare i caratteri in un thread
   Nota: assicurati che questo gestore non sia il gestore dei thread dell'interfaccia utente.

Il seguente codice di esempio illustra la procedura generale relativa ai 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.

Usare caratteri scaricabili con AndroidX Core

AndroidX Core fornisce supporto per la funzionalità dei caratteri scaricabili su dispositivi su cui è in esecuzione l'API Android 14 o versioni successive. Il pacchetto androidx.core.provider contiene le classi FontsContractCompat e FontRequest per implementare il supporto della funzionalità dei caratteri scaricabili compatibili con le versioni precedenti. Le classi AndroidX contengono metodi simili ai metodi framework e il processo per scaricare i caratteri è simile a quello descritto nella sezione di questa pagina sull'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é delle classi di framework FontsContract e android.graphics.fonts.FontRequest.

Nota: devi fornire un certificato quando richiedi caratteri tramite la libreria AndroidX Core. Ciò vale anche per i fornitori di caratteri preinstallati.

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:

trendy

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

Kotlin

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

Usa 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 in modo da velocizzare l'usabilità per più stili e ponderazioni, ad esempio grassetto, medio o chiaro, se fornito.

1. Crea un nuovo file XML nella cartella res/font.
2. Aggiungi un elemento principale <font-family> e imposta gli attributi relativi ai caratteri, come mostrato nel seguente file XML di esempio:

<?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 a questo file come @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-dichiara i caratteri nel file manifest

L'aumento del layout e il recupero delle risorse sono attività sincrone. Per impostazione predefinita, il primo tentativo di recuperare i caratteri attiva una richiesta al fornitore di caratteri e, di conseguenza, aumenta la durata del primo layout. Per evitare questo ritardo, puoi predichiarare i caratteri che devono essere recuperati nel file manifest. Una volta che il sistema recupera il font dal provider, diventa subito disponibile. Se il recupero dei caratteri richiede più tempo del previsto, il sistema interrompe la procedura di recupero e utilizza il carattere predefinito.

Per predichiarare i caratteri nel file manifest, procedi nel seguente modo:

1. Crea un array di risorse in res/values/arrays.xml e dichiara i caratteri che vuoi precaricare.

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.

<meta-data android:name="preloaded_fonts" android:resource="@array/preloaded_fonts" />

Aggiungi certificati

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

Nota: Android Studio può inserire automaticamente i valori per il fornitore di Google Play Services se utilizzi lo strumento di selezione dei caratteri in Android Studio. Per ulteriori informazioni sull'utilizzo di Android Studio per il download dei caratteri, consulta la sezione Utilizzare i caratteri scaricabili con Android Studio e Google Play Services in questa pagina.

Per aggiungere certificati, procedi nel seguente modo:

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.

<?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.

android:fontProviderCerts="@array/certs"

Nota: se il provider ha più di un set di certificati, puoi definire un array di array di stringhe.

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 Scrivi caratteri scaricabili.