Ressources disponibles dans Compose

Jetpack Compose peut accéder aux ressources définies dans votre projet Android. Cet article présente certaines des API disponibles dans Compose pour ce faire.

Les ressources sont les fichiers supplémentaires et le contenu statique utilisés par votre code, tels que les bitmaps, les définitions de mise en page, les chaînes d'interface utilisateur, les instructions d'animation, etc. Si vous ne connaissez pas encore les ressources d'Android, consultez le guide de présentation des ressources d'application.

Chaînes

Les chaînes sont le type de ressource le plus courant. Utilisez l'API stringResource pour récupérer une chaîne définie de manière statique dans vos ressources 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 fonctionne également avec la mise en forme positionnelle.

// 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

Pluriel de chaînes (expérimental)

Utilisez l'API pluralStringResource pour charger un pluriel et une quantité donnée.

// 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

Lorsque vous utilisez la méthode pluralStringResource, vous devez transmettre le nombre deux fois si votre chaîne inclut une mise en forme avec un nombre. Par exemple, pour la chaîne %1$d minutes, le premier paramètre sélectionne la chaîne de pluriel appropriée, et le second paramètre est inséré dans l'espace réservé %1$d. Si vos chaînes de pluriel n'incluent pas de mise en forme de chaîne, vous n'avez pas besoin de transmettre le troisième paramètre à pluralStringResource.

Pour en savoir plus sur les pluriels, consultez la documentation sur les chaînes de quantité.

Dimensions

De même, vous pouvez utiliser l'API dimensionResource pour obtenir les dimensions d'un fichier XML de ressources.

// 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

Coloris

Si vous adoptez Compose de manière incrémentielle dans votre application, utilisez l'API colorResource pour obtenir les couleurs d'un fichier XML de ressources.

// 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 fonctionne comme prévu avec les couleurs statiques, mais aplatit les ressources de la liste d'états des couleurs.

Avertissement : Préférez les couleurs du thème plutôt que les couleurs codées en dur. Bien qu'il soit possible d'accéder aux couleurs à l'aide de la fonction colorResource, il est recommandé de définir les couleurs de votre application dans un MaterialTheme accessible à partir de vos composables, comme MaterialTheme.colors.primary Pour en savoir plus, consultez la documentation sur la conception de systèmes dans Compose.

Ressources vectorielles et d'images

Utilisez l'API painterResource pour charger des drawables vectoriels ou des formats d'éléments rastérisés tels que des fichiers PNG. Vous n'avez pas besoin de connaître le type du drawable, il vous suffit d'utiliser painterResource dans les composables Image ou les modificateurs paint.

// 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 décode et analyse le contenu de la ressource sur le thread principal.

Remarque : Contrairement à Context.getDrawable, painterResource charge uniquement les types Drawable des plates-formes BitmapDrawable et VectorDrawable.

Drawables vectoriels animés

Utilisez l'API AnimatedImageVector.animatedVectorResource pour charger un fichier XML de drawable vectoriel animé. La méthode renvoie une instance AnimatedImageVector. Pour afficher l'image animée, utilisez la méthode rememberAnimatedVectorPainter afin de créer un Painter utilisable dans les composables Image et Icon. Le paramètre booléen atEnd de la méthode rememberAnimatedVectorPainter indique si l'image doit être dessinée à la fin de toutes les animations. Si elle est utilisée avec un état modifiable, toute modification apportée à cette valeur déclenche l'animation correspondante.

// 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

Icônes

Jetpack Compose est fourni avec l'objet Icons, qui est le point d'entrée pour utiliser les icônes Material dans Compose. Il existe cinq thèmes d'icône : Plein, Contours, Arrondi, Bicolore et Net. Chaque thème contient les mêmes icônes, mais avec un style visuel propre. Il est généralement conseillé de choisir un thème pour l'ensemble de votre application pour plus de cohérence.

Pour dessiner une icône, vous pouvez utiliser le composable Icon, qui applique une teinte et fournit une taille de mise en page correspondant à l'icône.

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

Certaines des icônes les plus couramment utilisées sont disponibles dans le cadre de la dépendance androidx.compose.material. Pour utiliser l'une des autres icônes Material, ajoutez la dépendance material-icons-extended au fichier build.gradle.

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

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

Remarque :Les icônes ont les mêmes noms définis par Material, mais le nom snake_case a été converti au format PascalCase. Par exemple, add_alarm devient AddAlarm. Les icônes qui commencent par un chiffre, comme 360, sont précédées du préfixe _, devenu _360.

Avertissement: material-icons-extended est une bibliothèque volumineuse qui peut affecter la taille de votre APK. Pour cette raison, envisagez d'utiliser R8/ProGuard dans les versions de production pour supprimer les ressources qui ne sont pas utilisées. De plus, en raison de la taille importante de l'outil, le délai de compilation de votre projet et de chargement des aperçus d'Android Studio peut augmenter pendant le développement. material-icons-extended vous permet d'accélérer les itérations grâce à un accès rapide aux dernières versions de toutes les icônes. Vous pouvez également utiliser cette bibliothèque pour copier le code source de l'icône afin d'obtenir une copie fixe dans votre application, ou importer les icônes à l'aide de la fonctionnalité Importer un élément vectoriel d'Android Studio.

Polices

Pour utiliser des polices dans Compose, téléchargez et regroupez les fichiers de polices directement dans vos APK en les plaçant dans le dossier res/font.

Chargez chaque police à l'aide de l'API Font et créez une instance FontFamily que vous pourrez utiliser dans des instances TextStyle pour créer votre propre Typography. Voici le code extrait de l'exemple Compose Crane et de son fichier 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

Pour utiliser des polices téléchargeables dans Compose, consultez la page Polices téléchargeables.

Pour en savoir plus sur la typographie, consultez la documentation sur la personnalisation des thèmes dans Compose.