Éléments graphiques dans Compose

De nombreuses applications doivent pouvoir contrôler avec précision ce qui apparaît à l'écran, que ce soit simplement pour aligner un cadre ou un cercle, ou pour minutieusement agencer toute une série d'éléments graphiques aux styles variés.

Dessin de base avec modificateurs et DrawScope

La méthode principale pour dessiner des éléments personnalisés dans Compose consiste à utiliser des modificateurs tels que Modifier.drawWithContent, Modifier.drawBehind et Modifier.drawWithCache.

Par exemple, pour dessiner un objet derrière un composable, vous pouvez utiliser le modificateur drawBehind pour commencer à exécuter des commandes de dessin :

Spacer(
    modifier = Modifier
        .fillMaxSize()
        .drawBehind {
            // this = DrawScope
        }
)
CanvasSnippets.kt

Si vous n'avez besoin que d'un composable qui dessine, vous pouvez utiliser Canvas. Le composable Canvas est un wrapper pratique pour Modifier.drawBehind. Vous positionnez le Canvas dans votre mise en page de la même manière que n'importe quel autre élément d'interface utilisateur avec Compose. Dans le Canvas, vous pouvez dessiner des éléments avec un contrôle précis sur leur style et leur emplacement.

Remarque : En coulisses, Compose s'appuie sur le canevas et les autres objets associés de l'interface utilisateur basée sur les vues. Cependant, Compose simplifie un grand nombre des aspects plus complexes de Canvas. Par exemple, la plupart des éléments graphiques basés sur des vues reposent sur un objet Helper Paint. Vous devez connaître les options de configuration que vous avez définies dans Paint et celles que vous avez définies dans l'appel de méthode. Vous devez également veiller à ce que vos objets Paint ne nuisent pas aux performances. Compose se charge de ces détails à votre place.

Tous les modificateurs de dessin exposent un DrawScope, un environnement de dessin cloisonné qui gère son propre état. Cela vous permet de définir les paramètres d'un groupe d'éléments graphiques. DrawScope fournit plusieurs champs utiles, tels que size, un objet Size spécifiant les dimensions actuelles de DrawScope.

Pour dessiner un objet, vous pouvez utiliser l'une des nombreuses fonctions de dessin sur DrawScope. Par exemple, le code suivant dessine un rectangle dans l'angle supérieur gauche de l'écran :

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasQuadrantSize = size / 2F
    drawRect(
        color = Color.Magenta,
        size = canvasQuadrantSize
    )
}
CanvasSnippets.kt

Figure 1 : Rectangle dessiné à l'aide d'un canevas dans Compose

Pour en savoir plus sur les différents modificateurs de dessin, consultez la documentation sur les modificateurs graphiques.

Système de coordonnées

Pour dessiner un élément à l'écran, vous devez connaître son décalage (x et y) et sa taille. Avec de nombreuses méthodes de dessin sur DrawScope, la position et la taille sont fournies par les valeurs de paramètres par défaut. Les paramètres par défaut placent généralement l'élément sur le point [0, 0] du canevas et indiquent une taille (size) par défaut qui remplit toute la zone de dessin, comme dans l'exemple ci-dessus. Le rectangle est positionné en haut à gauche. Pour ajuster la taille et la position de votre élément, vous devez comprendre le système de coordonnées de Compose.

L'origine du système de coordonnées ([0,0]) se trouve tout en haut à gauche de la zone de dessin. x augmente à mesure qu'il se déplace vers la droite, et y augmente à mesure qu'il descend.

Remarque : Toutes les opérations de dessin sont effectuées par dimensionnement des pixels. Pour vous assurer que la taille de vos éléments est cohérente entre les différentes densités d'appareil et tailles d'écran, veillez à effectuer une conversion à partir de dp à l'aide de .toPx() ou à utiliser des fractions de la taille.

Figure 2 : Système de coordonnées dessiné/ Grille de dessin

Par exemple, si vous souhaitez dessiner une ligne diagonale entre l'angle supérieur droit de la zone de canevas et l'angle inférieur gauche, vous pouvez utiliser la fonction DrawScope.drawLine() et spécifier un décalage de début et de fin avec les positions x et y correspondantes :

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasWidth = size.width
    val canvasHeight = size.height
    drawLine(
        start = Offset(x = canvasWidth, y = 0f),
        end = Offset(x = 0f, y = canvasHeight),
        color = Color.Blue
    )
}
CanvasSnippets.kt

Transformations de base

DrawScope propose des transformations pour modifier la façon dont les commandes de dessin sont exécutées, ou à quel emplacement.

Remarque : Ces transformations ne s'appliquent qu'à la phase de dessin du cycle de vie du composable. Toute modification de la taille ou de la position ne modifie pas la taille ni la position de la mise en page. Les éléments peuvent se superposer aux autres éléments s'ils sont déplacés en dehors de la taille et de la position de leur mise en page.

Mise à l'échelle

Utilisez DrawScope.scale() pour augmenter d'un facteur la taille de vos opérations de dessin. Les opérations telles que scale() s'appliquent à toutes les opérations de dessin dans le lambda correspondant. Par exemple, le code suivant multiplie scaleX par 10 et scaleY par 15 :

Canvas(modifier = Modifier.fillMaxSize()) {
    scale(scaleX = 10f, scaleY = 15f) {
        drawCircle(Color.Blue, radius = 20.dp.toPx())
    }
}
CanvasSnippets.kt

Figure 3 : Application d'une opération de mise à l'échelle à un cercle sur un canevas

Translation

Utilisez DrawScope.translate() pour déplacer vos opérations de dessin vers le haut, le bas, la gauche ou la droite. Par exemple, le code suivant déplace le dessin de 100 pixels vers la droite et de 300 pixels vers le haut :

Canvas(modifier = Modifier.fillMaxSize()) {
    translate(left = 100f, top = -300f) {
        drawCircle(Color.Blue, radius = 200.dp.toPx())
    }
}
CanvasSnippets.kt

Figure 4 : Application d'une opération de translation à un cercle dans le canevas

Rotation

Utilisez DrawScope.rotate() pour faire pivoter vos opérations de dessin autour d'un point pivot. Par exemple, le code suivant fait pivoter un rectangle à 45 degrés :

Canvas(modifier = Modifier.fillMaxSize()) {
    rotate(degrees = 45F) {
        drawRect(
            color = Color.Gray,
            topLeft = Offset(x = size.width / 3F, y = size.height / 3F),
            size = size / 3F
        )
    }
}
CanvasSnippets.kt

Figure 5 : L'opération rotate() nous permet d'appliquer une rotation à l'environnement d'affichage actuel, ce qui fait pivoter le rectangle de 45 degrés

Encart

Utilisez DrawScope.inset() pour ajuster les paramètres par défaut du DrawScope actuel afin de modifier les limites de tracé et de translater les éléments graphiques en conséquence :

Canvas(modifier = Modifier.fillMaxSize()) {
    val canvasQuadrantSize = size / 2F
    inset(horizontal = 50f, vertical = 30f) {
        drawRect(color = Color.Green, size = canvasQuadrantSize)
    }
}
CanvasSnippets.kt

Ce code ajoute une marge intérieure aux commandes de dessin :

Figure 6 : Appliquer un encart aux commandes de dessin

Plusieurs transformations

Pour appliquer plusieurs transformations à vos dessins, utilisez la fonction DrawScope.withTransform(), qui crée et applique une seule transformation combinant toutes les modifications souhaitées. Il est plus efficace d'utiliser withTransform() que de passer des appels imbriqués pour des transformations individuelles, car toutes les transformations sont effectuées ensemble en une seule opération, ce qui évite à Compose de devoir calculer et enregistrer chaque étape imbriquée.

Par exemple, le code suivant applique une translation et une rotation au rectangle :

Canvas(modifier = Modifier.fillMaxSize()) {
    withTransform({
        translate(left = size.width / 5F)
        rotate(degrees = 45F)
    }) {
        drawRect(
            color = Color.Gray,
            topLeft = Offset(x = size.width / 3F, y = size.height / 3F),
            size = size / 3F
        )
    }
}
CanvasSnippets.kt

Figure 7 : Utilisation de withTransform pour appliquer à la fois une rotation et une translation, pour faire pivoter le rectangle et le décaler vers la gauche

Opérations de dessin courantes

Dessiner du texte

Pour dessiner du texte dans Compose, vous pouvez généralement utiliser le composable Text. Toutefois, si vous êtes dans un DrawScope ou si vous souhaitez dessiner le texte manuellement avec la personnalisation, vous pouvez opter pour la méthode DrawScope.drawText().

Pour dessiner du texte, créez un TextMeasurer à l'aide de rememberTextMeasurer et appelez drawText avec l'outil de mesure :

val textMeasurer = rememberTextMeasurer()

Canvas(modifier = Modifier.fillMaxSize()) {
    drawText(textMeasurer, "Hello")
}
CanvasSnippets.kt

Figure 8 : Dessiner du texte sur un canevas

Mesurer le texte

Le dessin de texte fonctionne légèrement différemment des autres commandes de dessin. Normalement, vous devez indiquer à la commande de dessin la taille (largeur et hauteur) requise pour dessiner la forme ou l'image. Avec le texte, plusieurs paramètres contrôlent la taille du texte affiché, tels que la taille de la police, la police elle-même, les ligatures et l'espacement entre les lettres.

Avec Compose, vous pouvez utiliser un TextMeasurer pour accéder à la taille de texte mesurée, en fonction des facteurs ci-dessus. Si vous souhaitez dessiner un arrière-plan derrière le texte, vous pouvez utiliser les informations mesurées pour obtenir la taille de la zone occupée par le texte :

val textMeasurer = rememberTextMeasurer()

Spacer(
    modifier = Modifier
        .drawWithCache {
            val measuredText =
                textMeasurer.measure(
                    AnnotatedString(longTextSample),
                    constraints = Constraints.fixedWidth((size.width * 2f / 3f).toInt()),
                    style = TextStyle(fontSize = 18.sp)
                )

            onDrawBehind {
                drawRect(pinkColor, size = measuredText.size.toSize())
                drawText(measuredText)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

Remarque : L'exemple ci-dessus utilise Modifier.drawWithCache, car le dessin de texte est une opération coûteuse. L'utilisation de drawWithCache permet de mettre en cache les objets créés jusqu'à ce que la taille de la zone de dessin change. Pour en savoir plus, reportez-vous à la documentation sur Modifier.drawWithCache.

Cet extrait de code crée un arrière-plan rose pour le texte :

Figure 9 : Texte multiligne occupant 2⁄3 de la surface totale, avec un rectangle en arrière-plan

Si vous ajustez les contraintes, la taille de la police ou toute autre propriété qui affecte la taille mesurée, une nouvelle taille est signalée. Vous pouvez définir une taille fixe pour width et height. Le texte suit alors le TextOverflow spécifié. Par exemple, le code suivant affiche le texte dans un tiers de la hauteur et dans un tiers de la largeur de la zone du composable, et définit TextOverflow sur TextOverflow.Ellipsis :

val textMeasurer = rememberTextMeasurer()

Spacer(
    modifier = Modifier
        .drawWithCache {
            val measuredText =
                textMeasurer.measure(
                    AnnotatedString(longTextSample),
                    constraints = Constraints.fixed(
                        width = (size.width / 3f).toInt(),
                        height = (size.height / 3f).toInt()
                    ),
                    overflow = TextOverflow.Ellipsis,
                    style = TextStyle(fontSize = 18.sp)
                )

            onDrawBehind {
                drawRect(pinkColor, size = measuredText.size.toSize())
                drawText(measuredText)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

Le texte est maintenant dessiné dans les limites spécifiées, avec des points de suspension à la fin :

Figure 10 : TextOverflow.Ellipsis avec des contraintes fixes sur la mesure du texte

Remarque : Pour en savoir plus sur le texte, consultez la documentation sur le texte.

Dessiner une image

Pour dessiner un ImageBitmap avec DrawScope, chargez l'image à l'aide d'ImageBitmap.imageResource(), puis appelez drawImage :

val dogImage = ImageBitmap.imageResource(id = R.drawable.dog)

Canvas(modifier = Modifier.fillMaxSize(), onDraw = {
    drawImage(dogImage)
})
CanvasSnippets.kt

Figure 11 : Dessin d'un ImageBitmap sur un canevas

Remarque : Consultez la documentation sur la personnalisation des images pour en savoir plus sur l'application de filtres à vos images.

Dessiner des formes de base

De nombreuses fonctions permettent de dessiner des formes sur DrawScope. Pour dessiner une forme, utilisez l'une des fonctions de dessin prédéfinies, telles que drawCircle :

val purpleColor = Color(0xFFBA68C8)
Canvas(
    modifier = Modifier
        .fillMaxSize()
        .padding(16.dp),
    onDraw = {
        drawCircle(purpleColor)
    }
)
CanvasSnippets.kt

API	Sortie
drawCircle()
drawRect()
drawRoundedRect()
drawLine()
drawOval()
drawArc()
drawPoints()

Dessiner un tracé

Un tracé est une série d'instructions mathématiques qui permettent de générer un dessin une fois qu'elles sont exécutées. DrawScope peut dessiner un tracé à l'aide de la méthode DrawScope.drawPath().

Imaginons que vous souhaitiez dessiner un triangle. Vous pouvez générer un tracé avec des fonctions telles que lineTo() et moveTo() en utilisant la taille de la zone de dessin. Appelez ensuite drawPath() avec ce tracé nouvellement créé pour obtenir un triangle.

Spacer(
    modifier = Modifier
        .drawWithCache {
            val path = Path()
            path.moveTo(0f, 0f)
            path.lineTo(size.width / 2f, size.height / 2f)
            path.lineTo(size.width, 0f)
            path.close()
            onDrawBehind {
                drawPath(path, Color.Magenta, style = Stroke(width = 10f))
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

Figure 12 : Créer et dessiner un Path dans Compose

Accéder à l'objet Canvas

Avec DrawScope, vous n'avez pas d'accès direct à un objet Canvas. Vous pouvez utiliser DrawScope.drawIntoCanvas() pour accéder à l'objet Canvas lui-même au niveau duquel vous pouvez appeler des fonctions.

Par exemple, si vous disposez d'un Drawable personnalisé que vous souhaitez dessiner sur le canevas, vous pouvez accéder au canevas et appeler Drawable#draw(), en transmettant l'objet Canvas :

val drawable = ShapeDrawable(OvalShape())
Spacer(
    modifier = Modifier
        .drawWithContent {
            drawIntoCanvas { canvas ->
                drawable.setBounds(0, 0, size.width.toInt(), size.height.toInt())
                drawable.draw(canvas.nativeCanvas)
            }
        }
        .fillMaxSize()
)
CanvasSnippets.kt

Figure 13 : Accès au canevas pour dessiner un élément Drawable

En savoir plus

Pour en savoir plus sur le dessin dans Compose, consultez les ressources suivantes :

• Modificateurs graphiques : découvrez les différents types de modificateurs de dessin.
• Pinceau : découvrez comment personnaliser les couleurs de votre contenu.
• Graphiques et mises en page personnalisés dans Compose : Sommet des développeurs Android 2022 : découvrez comment créer une interface utilisateur personnalisée dans Compose avec des mises en page et des graphiques.
• Exemple JetLagged : exemple de composition qui montre comment dessiner un graphique personnalisé.