Risorse in Compose

Jetpack Compose può accedere alle risorse definite nel tuo progetto Android. Questo documento spiega alcune delle API offerte da Compose per farlo.

Le risorse sono i file aggiuntivi e i contenuti statici utilizzati dal codice, come bitmap, definizioni di layout, stringhe dell'interfaccia utente, istruzioni di animazione e altro ancora. Se non hai dimestichezza con le risorse in Android, consulta la guida di panoramica delle risorse per le app.

Stringhe

Il tipo di risorsa più comune sono le stringhe. Utilizza l'API stringResource per recuperare una stringa definita in modo statico nelle risorse XML.

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

stringResource funziona anche con la formattazione posizionale.

// In the res/values/strings.xml file
// <string name="congratulate">Happy %1$s %2$d</string>

// In your Compose code
Text(
    text = stringResource(R.string.congratulate, "New Year", 2021)
)
ResourcesSnippets.kt

Stringhe plurali (sperimentale)

Utilizza l'API pluralStringResource per caricare una forma plurale con una determinata quantità.

// In the res/strings.xml file
// <plurals name="runtime_format">
//    <item quantity="one">%1$d minute</item>
//    <item quantity="other">%1$d minutes</item>
// </plurals>

// In your Compose code
Text(
    text = pluralStringResource(
        R.plurals.runtime_format,
        quantity,
        quantity
    )
)
ResourcesSnippets.kt

Quando utilizzi il metodo pluralStringResource, devi superare il conteggio due volte se la stringa include la formattazione della stringa con un numero. Ad esempio, per stringa %1$d minutes, il primo parametro di conteggio seleziona il plurale appropriato e il secondo parametro di conteggio viene inserito nel segnaposto %1$d. Se le stringhe plurali non includono la formattazione delle stringhe, non è necessario passare il terzo parametro a pluralStringResource.

Per saperne di più sui plurali, consulta la documentazione delle stringhe di quantità.

Dimensioni

Analogamente, utilizza l'API dimensionResource per ottenere dimensioni da una risorsa XML .

// In the res/values/dimens.xml file
// <dimen name="padding_small">8dp</dimen>

// In your Compose code
val smallPadding = dimensionResource(R.dimen.padding_small)
Text(
    text = "...",
    modifier = Modifier.padding(smallPadding)
)
ResourcesSnippets.kt

Colori

Se adotti Compose in modo incrementale nella tua app, utilizza colorResource per ottenere i colori da un file XML delle risorse.

// In the res/colors.xml file
// <color name="purple_200">#FFBB86FC</color>

// In your Compose code
Divider(color = colorResource(R.color.purple_200))
ResourcesSnippets.kt

colorResource funziona come previsto con colori statici, ma appiattisce il colore dell'elenco di stati delle risorse.

Attenzione: preferisci i colori del tema anziché quelli hardcoded. Anche se è possibile accedere ai colori utilizzando la funzione colorResource, è consigliabile che i colori dell'app siano definiti in un MaterialTheme, ai componenti componibili, ad esempio MaterialTheme.colors.primary. Impara Scopri di più al riguardo nella pagina Progettare sistemi in Compose documentazione.

Asset vettoriali e risorse immagine

Utilizza l'API painterResource per caricare drawable vettoriali o rasterizzati come i PNG. Non occorre conoscere il tipo di drawable, usa painterResource in Image componibili o paint modificatori.

// Files in res/drawable folders. For example:
// - res/drawable-nodpi/ic_logo.xml
// - res/drawable-xxhdpi/ic_logo.png

// In your Compose code
Icon(
    painter = painterResource(id = R.drawable.ic_logo),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

painterResource decodifica e analizza i contenuti della risorsa nel thread principale.

Nota: a differenza di Context.getDrawable, painterResource può caricare solo tipi di piattaforme BitmapDrawable e VectorDrawable.

Drawable vettoriali animati

Usa l'API AnimatedImageVector.animatedVectorResource per caricare un'animazione XML Vector drawable. Il metodo restituisce un'istanza AnimatedImageVector. Nella per visualizzare l'immagine animata, utilizza rememberAnimatedVectorPainter per creare un Painter che possa essere utilizzato nei componibili Image e Icon. Il parametro booleano atEnd del metodo rememberAnimatedVectorPainter indica se l'immagine deve essere disegnata alla fine di tutte le animazioni. Se utilizzato con uno stato modificabile, le modifiche a questo valore attivano la corrispondenza l'animazione.

// Files in res/drawable folders. For example:
// - res/drawable/ic_hourglass_animated.xml

// In your Compose code
val image =
    AnimatedImageVector.animatedVectorResource(R.drawable.ic_hourglass_animated)
val atEnd by remember { mutableStateOf(false) }
Icon(
    painter = rememberAnimatedVectorPainter(image, atEnd),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

Icone

Jetpack Compose è dotato dell'oggetto Icons, che è il punto di contatto per l'utilizzo di Material Icons in Compose. Esistono cinque temi di icone distinti: Riempimento, Contorno, Ronde, Due tonalità e Nitide. Ogni tema contiene le stesse icone, ma con uno stile visivo distinto. In genere, per garantire la coerenza, è consigliabile scegliere un tema e utilizzarlo nell'intera applicazione.

Per disegnare un'icona, puoi utilizzare il composable Icon che applica la tinta e fornisce le dimensioni del layout corrispondenti all'icona.

Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
ResourcesSnippets.kt

Alcune delle icone di uso comune sono disponibili in Dipendenza androidx.compose.material. Per utilizzare una delle altre icone Material, aggiungi la dipendenza material-icons-extended al file build.gradle.

dependencies {
  def composeBom = platform('androidx.compose:compose-bom:2025.02.00')
  implementation composeBom

  implementation 'androidx.compose.material:material-icons-extended'
}

Nota: le icone mantengono gli stessi nomi definiti da Material, ma con il nome in snake_case convertito in PascalCase. Ad esempio, add_alarm diventa AddAlarm. Le icone che iniziano con un numero, ad esempio 360, hanno il prefisso _, diventando _360.

Avviso: material-icons-extended è una libreria di grandi dimensioni e può influire sulle dimensioni dell'APK. Per questo motivo, ti consigliamo di utilizzare R8/Proguard nelle build di produzione per rimuovere le risorse non utilizzate. Inoltre, a causa delle grandi dimensioni, il tempo di compilazione del progetto e il tempo di caricamento delle anteprime di Android Studio potrebbero aumentare durante lo sviluppo. D'altra parte, material-icons-extended ti consente di eseguire più rapidamente l'iterazione tramite l'accesso rapido alle versioni più recenti di tutte le icone. Puoi anche utilizzare questa libreria per copiare il codice sorgente dell'icona in modo da avere una copia fissa nell'app oppure, in alternativa, importare le icone utilizzando la funzionalità Importa asset vettoriale di Android Studio.

Caratteri

Per utilizzare i caratteri in Scrivi, scarica e raggruppa i file dei caratteri direttamente negli APK inserendoli nella cartella res/font.

Carica ogni carattere utilizzando API Font e crea un'istanza FontFamily con che puoi utilizzare TextStyle istanze in crea il tuo Typography. La che segue è il codice preso Gru scrivi un campione e i suoi Typography.kt: .

// Define and load the fonts of the app
private val light = Font(R.font.raleway_light, FontWeight.W300)
private val regular = Font(R.font.raleway_regular, FontWeight.W400)
private val medium = Font(R.font.raleway_medium, FontWeight.W500)
private val semibold = Font(R.font.raleway_semibold, FontWeight.W600)

// Create a font family to use in TextStyles
private val craneFontFamily = FontFamily(light, regular, medium, semibold)

// Use the font family to define a custom typography
val craneTypography = Typography(
    titleLarge = TextStyle(
        fontFamily = craneFontFamily
    ) /* ... */
)

// Pass the typography to a MaterialTheme that will create a theme using
// that typography in the part of the UI hierarchy where this theme is used
@Composable
fun CraneTheme(content: @Composable () -> Unit) {
    MaterialTheme(typography = craneTypography) {
        content()
    }
}
ResourcesSnippets.kt

Per l'utilizzo dei caratteri scaricabili in Compose, consulta le Pagina Caratteri scaricabili.

Scopri di più sulla tipografia nella documentazione relativa ai temi in Compose.