Bild anpassen

Bilder können mithilfe der Eigenschaften einer zusammensetzbaren Image (contentScale, colorFilter) angepasst werden. Sie können auch das vorhandene Modifiers anwenden, um verschiedene Effekte auf Image anzuwenden. Modifikatoren können für alle zusammensetzbaren Funktionen verwendet werden, nicht nur für die zusammensetzbare Image-Funktion. contentScale und colorFilter hingegen sind explizite Parameter der zusammensetzbaren Funktion Image.

Inhaltsumfang

Geben Sie eine contentScale-Option an, um ein Bild innerhalb seiner Begrenzungen zuzuschneiden oder zu ändern. Wenn Sie keine contentScale-Option angeben, wird standardmäßig ContentScale.Fit verwendet.

Im folgenden Beispiel ist die zusammensetzbare Funktion „Bild“ auf eine Größe von 150 dp mit Rahmen beschränkt und der Hintergrund ist in der zusammensetzbaren Funktion Image auf Gelb eingestellt, um die verschiedenen ContentScale-Optionen in der folgenden Tabelle zu zeigen.

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

Das Festlegen unterschiedlicher ContentScale-Optionen führt zu unterschiedlichen Ausgaben. Die folgende Tabelle hilft Ihnen bei der Auswahl des richtigen ContentScale-Modus:

Quell-Image
ContentScale	Ergebnis – Bild im Hochformat:	Ergebnis – Bild im Querformat:
ContentScale.Fit: Skaliert das Bild gleichmäßig unter Beibehaltung des Seitenverhältnisses (Standardeinstellung). Wenn der Inhalt kleiner als die Größe ist, wird das Bild so vergrößert, dass es in die Begrenzungen passt.
ContentScale.Crop: Mit dieser Option wird das Bild auf den verfügbaren Platz zugeschnitten.
ContentScale.FillHeight: Skaliert die Quelle unter Beibehaltung des Seitenverhältnisses, sodass die Grenzen der Zielhöhe entsprechen.
ContentScale.FillWidth: Skaliert die Quelle unter Beibehaltung des Seitenverhältnisses, sodass die Grenzen der Zielbreite entsprechen.
ContentScale.FillBounds: Der Inhalt wird ungleichmäßig vertikal und horizontal skaliert, um die Zielgrenzen auszufüllen. (Hinweis: Bilder werden verzerrt dargestellt, wenn sie in Containern platziert werden, die nicht genau mit dem Seitenverhältnis des Bildes übereinstimmen.)
ContentScale.Inside: Skaliert die Quelle, damit das Seitenverhältnis innerhalb der Zielgrenzen erhalten bleibt. Wenn die Quelle in beiden Dimensionen kleiner oder gleich dem Ziel ist, verhält sie sich ähnlich wie „Keine“. Der Inhalt bleibt immer innerhalb der Grenzen. Wenn der Inhalt die Grenzen überschreitet, wird keine Skalierung angewendet.	Quellbild ist größer als die Grenzen: Quellbild ist kleiner als die Grenzen:	Quellbild ist größer als die Grenzen: Quellbild ist kleiner als die Grenzen:
ContentScale.None: Es wird keine Skalierung auf die Quelle angewendet. Wenn der Inhalt kleiner als die Zielgrenzen ist, wird er nicht vertikal skaliert.	Quellbild ist größer als die Grenzen: Quellbild ist kleiner als die Grenzen:	Quellbild ist größer als die Grenzen: Quellbild ist kleiner als die Grenzen:

Zusammensetzbare Funktion Image an eine Form fixieren

Wenn Sie ein Bild an eine bestimmte Form anpassen möchten, verwenden Sie den integrierten clip-Modifikator. Verwenden Sie Modifier.clip(CircleShape), um ein Bild auf einen Kreis zuzuschneiden:

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

Abbildung 1: Bild mit CircleShape ausschneiden

Abgerundete Ecken – verwenden Sie Modifier.clip(RoundedCornerShape(16.dp)) mit der Größe der Ecken, die abgerundet werden sollen:

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

Abbildung 2: Bild mit RoundedCornerShape beschneiden

Sie können auch eine eigene Beschneidungsform erstellen, indem Sie Shape erweitern und ein Path angeben, um die Form zu verkleinern:

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

Abbildung 3: Bild mit benutzerdefinierter Pfadform beschneiden

Rahmen für zusammensetzbare Image-Elemente hinzufügen

Eine gängige Operation besteht darin, Modifier.border() mit Modifier.clip() zu kombinieren, um einen Rahmen um ein Bild zu erstellen:

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

Abbildung 4: Bild mit einem Rahmen versehen

Wenn Sie einen Farbverlaufsrahmen erstellen möchten, können Sie mit der Brush API einen Regenbogen-Farbverlauf-Rahmen um das Bild zeichnen:

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

Abbildung 5: Kreisränder mit Farbverlauf in Regenbogen

Benutzerdefiniertes Seitenverhältnis festlegen

Wenn Sie ein Bild in ein benutzerdefiniertes Seitenverhältnis umwandeln möchten, verwenden Sie Modifier.aspectRatio(16f/9f), um ein benutzerdefiniertes Seitenverhältnis für ein Bild (oder eine beliebige zusammensetzbare Funktion) bereitzustellen.

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

Abbildung 6: Modifier.aspectRatio(16f/9f) für Bild verwenden

Farbfilter: Bildfarben in Pixel umwandeln

Die zusammensetzbare Funktion „Bild“ hat einen colorFilter-Parameter, mit dem sich die Ausgabe einzelner Pixel Ihres Bildes ändern kann.

Bilder färben

Mit ColorFilter.tint(color, blendMode) wird ein Mischmodus mit der angegebenen Farbe auf die zusammensetzbare Funktion Image angewendet. ColorFilter.tint(color, blendMode) verwendet BlendMode.SrcIn zur Färbung von Inhalten. Das bedeutet, dass die angegebene Farbe dort angezeigt wird, wo das Bild auf dem Bildschirm zu sehen ist. Dies ist nützlich für Symbole und Vektoren, die ein anderes Thema haben müssen.

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

Abbildung 7: "ColorFilter.tint" mit "BlendMode.SrcIn" angewendet

Andere BlendMode haben andere Auswirkungen. Wenn Sie beispielsweise BlendMode.Darken mit einer Color.Green für ein Bild festlegen, führt dies zu folgendem Ergebnis:

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

Abbildung 8: Farbe.Grüne Färbung mit BlendMode.Darken

Weitere Informationen zu den verschiedenen Mischmodi finden Sie in der Referenzdokumentation zum Mischmodus.

Image-Filter mit Farbmatrix anwenden

Wandeln Sie Ihr Bild mit der Farbmatrix ColorFilter-Option um. Wenn Sie beispielsweise einen Schwarz-Weiß-Filter auf Ihre Bilder anwenden möchten, können Sie mit ColorMatrix die Sättigung auf 0f festlegen.

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

Abbildung 9: Farbmatrix mit Sättigung 0 (Schwarz-Weiß-Bild)

Kontrast oder Helligkeit einer mit Image zusammensetzbaren Funktion anpassen

Wenn Sie den Kontrast und die Helligkeit eines Bildes ändern möchten, können Sie die Werte mit ColorMatrix ändern:

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

Abbildung 10: Bildhelligkeit und Kontrast mit ColorMatrix angepasst

Farben einer zusammensetzbaren Funktion Image umkehren

Wenn Sie die Farben eines Bildes umkehren möchten, legen Sie mit ColorMatrix fest, dass die Farben umgekehrt werden:

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

Abbildung 11: Umgekehrte Farben des Bilds

Zusammensetzbare Funktion vom Typ „Image“ unkenntlich machen

Zum Unkenntlichmachen eines Bildes kannst du Modifier.blur() verwenden und die radiusX und radiusY angeben, die den Weichzeichner-Radius in horizontaler bzw. vertikaler Richtung angibt.

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

Abbildung 12: BlurEffect auf das Bild angewendet

Beim Unkenntlichmachen von Images wird empfohlen, BlurredEdgeTreatment(Shape) anstelle von BlurredEdgeTreatment.Unbounded zu verwenden, da letztere für die Unkenntlichmachung beliebiger Renderings verwendet wird, die außerhalb der Grenzen des Originalinhalts gerendert werden sollen. Bei Bildern ist es wahrscheinlich, dass sie außerhalb der Grenzen des Inhalts nicht gerendert werden. Das Weichzeichnen eines abgerundeten Rechtecks hingegen erfordert möglicherweise eine solche Unterscheidung.

Wenn wir beispielsweise BlurredEdgeTreatment im Bild oben auf „Unbegrenzt“ setzen, erscheinen die Bildränder verschwommen statt scharf:

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

Abbildung 13: BlurEdgeTreatment.Unbounded

Hinweis: Der Weichzeichner-Effekt wird erst ab Android 12 unterstützt. Versuche, diesen Modifikator unter älteren Android-Versionen zu verwenden, werden ignoriert.