Personalizzare un'immagine

Puoi personalizzare le immagini utilizzando le proprietà di un Image composable (contentScale, colorFilter). Puoi anche applicare i modificatori esistenti per applicare effetti diversi a Image. I modificatori possono essere utilizzati su qualsiasi composable, non solo sul composable Image, mentre contentScale e colorFilter sono parametri espliciti del composable Image.

Scala dei contenuti

Specifica un'opzione contentScale per ritagliare o modificare la scalabilità di un'immagine all'interno dei relativi limiti. Per impostazione predefinita, se non specifichi un'opzione contentScale, viene utilizzato ContentScale.Fit.

Nell'esempio seguente, il composable Image è limitato a una dimensione di 150 dp con un bordo e lo sfondo è impostato su giallo nel composable Image per mostrare le diverse opzioni ContentScale nella tabella seguente.

val imageModifier = Modifier
    .size(150.dp)
    .border(BorderStroke(1.dp, Color.Black))
    .background(Color.Yellow)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Fit,
    modifier = imageModifier
)
CustomizeImageSnippets.kt

L'impostazione di diverse opzioni ContentScale genera output diversi. La tabella seguente ti aiuta a scegliere la modalità ContentScale corretta:

Immagine di origine L'origine del ritratto, che mostra un cane. La fonte del paesaggio, che mostra un cane diverso.
ContentScale Risultato: immagine verticale Risultato: immagine orizzontale
ContentScale.Fit: scala l'immagine in modo uniforme, mantenendo le proporzioni (impostazione predefinita). Se i contenuti sono più piccoli della dimensione, l'immagine viene scalata per adattarsi ai limiti. Il ritratto di un cane scalato in modo uniforme. Un paesaggio con un cane scalato in modo uniforme.
ContentScale.Crop: ritaglia l'immagine al centro nello spazio disponibile. Un'immagine verticale ritagliata per riempire un fotogramma quadrato, che mostra solo la parte centrale dell'immagine. Un'immagine orizzontale ritagliata per riempire un fotogramma quadrato, che mostra solo la parte centrale dell'immagine.
ContentScale.FillHeight: scala l'origine mantenendo le proporzioni in modo che i limiti corrispondano all'altezza di destinazione. Un'immagine verticale ridimensionata per riempire l'altezza di un riquadro quadrato, che mostra l'immagine completa con lo sfondo giallo visibile a sinistra e a destra. Un'immagine orizzontale scalata per riempire l'altezza di un fotogramma quadrato, con i lati ritagliati.
ContentScale.FillWidth: scala l'origine mantenendo le proporzioni in modo che i limiti corrispondano alla larghezza di destinazione. Un'immagine verticale scalata per riempire la larghezza di un fotogramma quadrato, con la parte superiore e inferiore ritagliate. Un'immagine orizzontale ridimensionata per riempire la larghezza di un riquadro quadrato, che mostra l'immagine completa con lo sfondo giallo visibile nella parte superiore e inferiore.
ContentScale.FillBounds: scala i contenuti verticalmente e orizzontalmente in modo non uniforme per riempire i limiti di destinazione. (Nota: le immagini vengono distorte se le inserisci in container che non corrispondono alle proporzioni esatte dell'immagine). Un'immagine verticale distorta per riempire completamente un frame quadrato, allungando l'immagine. Un'immagine orizzontale distorta per riempire completamente un fotogramma quadrato, allungando l'immagine.
ContentScale.Inside: scala l'origine per mantenere le proporzioni all'interno dei limiti di destinazione. Se l'origine è più piccola o uguale alla destinazione in entrambe le dimensioni, si comporta in modo simile a None. I contenuti saranno sempre contenuti all'interno dei limiti. Se i contenuti sono più piccoli dei limiti, non verrà applicata alcuna scalabilità. Immagine di origine più grande dei limiti: Un'immagine verticale, originariamente più grande dei suoi limiti quadrati, ridimensionata per adattarsi mantenendo le proporzioni, che mostra uno sfondo giallo sui lati. Immagine di origine più piccola dei limiti: Un'immagine verticale, originariamente più piccola dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali all'interno del frame, che mostra uno sfondo giallo intorno. Immagine di origine più grande dei limiti: Un'immagine orizzontale, originariamente più grande dei suoi limiti quadrati, ridimensionata per adattarsi mantenendo le proporzioni, che mostra uno sfondo giallo nella parte superiore e inferiore. Immagine di origine più piccola dei limiti: Un'immagine orizzontale, originariamente più piccola dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali all'interno del frame, con uno sfondo giallo intorno.
ContentScale.None: non applica alcuna scalabilità all'origine. Se i contenuti sono più piccoli dei limiti di destinazione, non verranno scalati per adattarsi all'area. Immagine di origine più grande dei limiti: Un'immagine verticale, originariamente più grande dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali, con parti che si estendono oltre la parte superiore e inferiore del frame. Immagine di origine più piccola dei limiti: Un'immagine verticale, originariamente più piccola dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali all'interno del frame, che mostra uno sfondo giallo intorno. Immagine di origine più grande dei limiti: Un'immagine orizzontale, originariamente più grande dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali, con parti che si estendono oltre i lati sinistro e destro del frame. Immagine di origine più piccola dei limiti: Un'immagine orizzontale, originariamente più piccola dei suoi limiti quadrati, visualizzata nelle sue dimensioni originali all'interno del frame, con uno sfondo giallo intorno.

Ritagliare un composable Image in una forma

Per adattare un'immagine a una forma, utilizza il modificatore clip integrato. Per ritagliare un'immagine in una forma circolare, utilizza Modifier.clip(CircleShape):

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(CircleShape)
)
CustomizeImageSnippets.kt

L'immagine di un cane ritagliata in un cerchio perfetto.
Figura 1. Ritagliare un'immagine con CircleShape.

Per una forma con angoli arrotondati, utilizza Modifier.clip(RoundedCornerShape(16.dp)), con le dimensioni degli angoli da arrotondare:

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(RoundedCornerShape(16.dp))
)
CustomizeImageSnippets.kt

Un'immagine quadrata di un cane ritagliata con angoli arrotondati.
Figura 2. Ritagliare un'immagine con RoundedCornerShape.

Puoi anche creare la tua forma di ritaglio estendendo Shape e fornendo un Path per la forma da ritagliare:

class SquashedOval : Shape {
    override fun createOutline(
        size: Size,
        layoutDirection: LayoutDirection,
        density: Density
    ): Outline {
        val path = Path().apply {
            // We create an Oval that starts at ¼ of the width, and ends at ¾ of the width of the container.
            addOval(
                Rect(
                    left = size.width / 4f,
                    top = 0f,
                    right = size.width * 3 / 4f,
                    bottom = size.height
                )
            )
        }
        return Outline.Generic(path = path)
    }
}

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(SquashedOval())
)
CustomizeImageSnippets.kt

Un'immagine quadrata di un cane ritagliata in una forma ovale personalizzata.
Figura 3. Ritagliare un'immagine con una forma di percorso personalizzata.

Aggiungere un bordo a un composable Image

Un'operazione comune consiste nel combinare Modifier.border() con Modifier.clip() per creare un bordo attorno a un'immagine:

val borderWidth = 4.dp
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .border(
            BorderStroke(borderWidth, Color.Yellow),
            CircleShape
        )
        .padding(borderWidth)
        .clip(CircleShape)
)
CustomizeImageSnippets.kt

Un'immagine quadrata di un cane ritagliata in un cerchio, con un bordo giallo intorno alla forma circolare.
Figura 4. Un'immagine ritagliata con un bordo attorno.

Per creare un bordo sfumato, puoi utilizzare l'API Brush per disegnare un bordo sfumato arcobaleno attorno all'immagine:

val rainbowColorsBrush = remember {
    Brush.sweepGradient(
        listOf(
            Color(0xFF9575CD),
            Color(0xFFBA68C8),
            Color(0xFFE57373),
            Color(0xFFFFB74D),
            Color(0xFFFFF176),
            Color(0xFFAED581),
            Color(0xFF4DD0E1),
            Color(0xFF9575CD)
        )
    )
}
val borderWidth = 4.dp
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .border(
            BorderStroke(borderWidth, rainbowColorsBrush),
            CircleShape
        )
        .padding(borderWidth)
        .clip(CircleShape)
)
CustomizeImageSnippets.kt

Un'immagine circolare di un cane con un bordo sfumato arcobaleno intorno alla forma circolare.
Figura 5. Bordo circolare sfumato arcobaleno.

Impostare proporzioni personalizzate

Per trasformare un'immagine in proporzioni personalizzate, utilizza Modifier.aspectRatio(16f/9f) per fornire proporzioni personalizzate per un'immagine (o qualsiasi composable).

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    modifier = Modifier.aspectRatio(16f / 9f)
)
CustomizeImageSnippets.kt

Un'immagine quadrata di un cane, trasformata in proporzioni 16:9, che la rendono più larga e più corta.
Figura 6. Utilizzo di Modifier.aspectRatio(16f/9f) su un Image.

Filtro colore: trasformare i colori dei pixel dell'immagine

Il composable Image ha un parametro colorFilter che può modificare l'output dei singoli pixel dell'immagine.

Colorare le immagini

L'utilizzo di ColorFilter.tint(color, blendMode) applica una modalità di fusione con il colore specificato al composable Image. ColorFilter.tint(color, blendMode) utilizza BlendMode.SrcIn per colorare i contenuti, il che significa che il colore fornito viene visualizzato dove l'immagine viene visualizzata sullo schermo. Questa opzione è utile per le icone e i vettori che devono essere tematizzati in modo diverso.

Image(
    painter = painterResource(id = R.drawable.baseline_directions_bus_24),
    contentDescription = stringResource(id = R.string.bus_content_description),
    colorFilter = ColorFilter.tint(Color.Yellow)
)
CustomizeImageSnippets.kt

Un'immagine di un autobus con una tonalità gialla applicata.
Figura 7. ColorFilter.tint applicato con BlendMode.SrcIn.

Altri BlendMode generano effetti diversi. Ad esempio, l'impostazione di BlendMode.Darken con un Color.Green su un'immagine produce il seguente risultato:

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.tint(Color.Green, blendMode = BlendMode.Darken)
)
CustomizeImageSnippets.kt

Un cane con una tonalità verde applicata utilizzando BlendMode.Darken, che produce tonalità di verde più scure.
Figura 8. Color.Green tint con BlendMode.Darken.

Per ulteriori informazioni sulle diverse modalità di fusione disponibili, consulta la documentazione di riferimento BlendMode.

Applicare un filtro Image con la matrice colore

Trasforma l'immagine utilizzando l'opzione della matrice colore ColorFilter. Ad esempio, per applicare un filtro in bianco e nero alle immagini, puoi utilizzare ColorMatrix e impostare la saturazione su 0f.

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix().apply { setToSaturation(0f) })
)
CustomizeImageSnippets.kt

Un cane con un filtro in bianco e nero applicato, che rimuove tutta la saturazione del colore.
Figura 9. Matrice colore con saturazione 0 (immagine in bianco e nero).

Regolare il contrasto o la luminosità di un composable Image

Per modificare il contrasto e la luminosità di un'immagine, puoi utilizzare ColorMatrix per modificare i valori:

val contrast = 2f // 0f..10f (1 should be default)
val brightness = -180f // -255f..255f (0 should be default)
val colorMatrix = floatArrayOf(
    contrast, 0f, 0f, 0f, brightness,
    0f, contrast, 0f, 0f, brightness,
    0f, 0f, contrast, 0f, brightness,
    0f, 0f, 0f, 1f, 0f
)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix(colorMatrix))
)
CustomizeImageSnippets.kt

Un cane con luminosità e contrasto aumentati, che lo rendono più vivido.
Figura 10. Luminosità e contrasto dell'immagine regolati utilizzando ColorMatrix.

Invertire i colori di un composable Image

Per invertire i colori di un'immagine, imposta ColorMatrix in modo da invertire i colori:

val colorMatrix = floatArrayOf(
    -1f, 0f, 0f, 0f, 255f,
    0f, -1f, 0f, 0f, 255f,
    0f, 0f, -1f, 0f, 255f,
    0f, 0f, 0f, 1f, 0f
)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix(colorMatrix))
)
CustomizeImageSnippets.kt

Un cane con i colori invertiti, che mostra un effetto simile a un negativo.
Figura 11. Colori invertiti sull'immagine.

Sfocare un composable Image

Per sfocare un'immagine, utilizza Modifier.blur(), fornendo radiusX e radiusY, che specificano il raggio di sfocatura rispettivamente in direzione orizzontale e verticale.

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .blur(
            radiusX = 10.dp,
            radiusY = 10.dp,
            edgeTreatment = BlurredEdgeTreatment(RoundedCornerShape(8.dp))
        )
)
CustomizeImageSnippets.kt

Un cane a cui è stato applicato un forte effetto sfocatura, che lo rende indistinto e fuori fuoco.
Figura 12. BlurEffect applicato a un'immagine.

Quando sfocare le Images, è consigliabile utilizzare BlurredEdgeTreatment(Shape), anziché BlurredEdgeTreatment.Unbounded, poiché quest'ultima viene utilizzata per la sfocatura di rendering arbitrari che dovrebbero essere eseguiti al di fuori dei limiti dei contenuti originali. Per le immagini, è probabile che non vengano eseguite al di fuori dei limiti dei contenuti, mentre la sfocatura di un rettangolo arrotondato potrebbe richiedere questa distinzione.

Ad esempio, se impostiamo BlurredEdgeTreatment su Unbounded nell'immagine precedente, i bordi dell'immagine appaiono sfocati anziché nitidi:

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .blur(
            radiusX = 10.dp,
            radiusY = 10.dp,
            edgeTreatment = BlurredEdgeTreatment.Unbounded
        )
        .clip(RoundedCornerShape(8.dp))
)
CustomizeImageSnippets.kt

Un'immagine sfocata di un cane, in cui la sfocatura si estende oltre i confini dell'immagine originale, rendendo i bordi sfocati.
Figura 13. BlurEdgeTreatment.Unbounded.
Indietro
Icone dei materiali
Avanti
Pittura personalizzata