Bild anpassen

Bilder können mithilfe von Attributen in einem Image-Komposit (contentScale, colorFilter) angepasst werden. Sie können auch die vorhandenen Modifiers-Effekte anwenden, um verschiedene Effekte auf Ihre Image anzuwenden. Modifikatoren können für alle Composables verwendet werden, nicht nur für das Image-Composable. contentScale und colorFilter sind dagegen explizite Parameter für das Image-Composable.

Inhaltsskala

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

Im folgenden Beispiel ist das Bild-Composeable auf eine Größe von 150 dp mit einem Rahmen beschränkt und der Hintergrund des Image-Composeables ist auf Gelb festgelegt, um die verschiedenen ContentScale-Optionen in der folgenden Tabelle zu veranschaulichen.

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

Wenn Sie unterschiedliche ContentScale-Optionen festlegen, erhalten Sie unterschiedliche Ergebnisse. Die folgende Tabelle hilft Ihnen bei der Auswahl des richtigen ContentScale-Modus:

Quellbild
ContentScale	Ergebnis – Bild im Hochformat:	Ergebnis – Bild im Querformat:
ContentScale.Fit: Bild gleichmäßig skalieren und das Seitenverhältnis beibehalten (Standard). Ist der Inhalt kleiner als die Größe, wird das Bild so skaliert, dass es in die Grenzen passt.
ContentScale.Crop: Mit dieser Option wird das Bild auf den verfügbaren Platz zugeschnitten.
ContentScale.FillHeight: Skalieren Sie die Quelle unter Beibehaltung des Seitenverhältnisses so, dass die Begrenzungen der Zielhöhe entsprechen.
ContentScale.FillWidth: Skaliert die Quelle unter Beibehaltung des Seitenverhältnisses, sodass die Grenzen der Zielbreite entsprechen.
ContentScale.FillBounds: Die Inhalte werden vertikal und horizontal nicht einheitlich skaliert, um die Zielgrenzen zu füllen. (Hinweis: Bilder werden verzerrt dargestellt, wenn sie in Containern platziert werden, die nicht genau mit dem Seitenverhältnis des Bildes übereinstimmen.)
ContentScale.Inside: Die Quelle wird so skaliert, dass das Seitenverhältnis innerhalb der Zielgrenzen beibehalten wird. Wenn die Quelle in beiden Dimensionen kleiner oder gleich dem Ziel ist, verhält sie sich ähnlich wie „None“. 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 größer als die Grenzen: Quellbild kleiner als die Grenzen:
ContentScale.None: Wenden Sie keine Skalierung auf die Quelle an. Wenn der Inhalt kleiner als die Zielgrenzen ist, wird er nicht auf die Größe des Bereichs skaliert.	Quellbild größer als die Grenzen: Quellbild kleiner als die Grenzen:	Quellbild größer als die Grenzen: Quellbild kleiner als die Grenzen:

Image-Komposition an eine Form anpinnen

Wenn Sie ein Bild in eine Form einpassen möchten, verwenden Sie die integrierte clip-Modifikation. Wenn Sie ein Bild zu einem Kreis zuschneiden möchten, verwenden Sie 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

Abbildung 1: Bild mit CircleShape zuschneiden

Form mit abgerundeten 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 zuschneiden

Einem Image-Element einen Rahmen hinzufügen

Häufig wird Modifier.border() mit Modifier.clip() kombiniert, 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 zuschneiden und einen Rahmen darum einfügen

Wenn du einen Farbverlaufsrand erstellen möchtest, kannst du mit der Brush API einen Regenbogen-Farbverlaufsrand 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 du ein Bild in ein benutzerdefiniertes Seitenverhältnis umwandeln möchtest, verwende Modifier.aspectRatio(16f/9f), um ein benutzerdefiniertes Seitenverhältnis für ein Bild (oder ein beliebiges bearbeitbares Element) anzugeben.

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) auf einem Bild verwenden

Farbfilter – Pixelfarben des Bilds transformieren

Das Bild-Composit hat einen colorFilter-Parameter, mit dem sich die Ausgabe einzelner Pixel des Bilds ändern lässt.

Bilder einfärben

Wenn Sie ColorFilter.tint(color, blendMode) verwenden, wird auf das Image-Composeable ein Mischmodus mit der angegebenen Farbe angewendet. ColorFilter.tint(color, blendMode) verwendet BlendMode.SrcIn, um Inhalte zu färben. Das bedeutet, dass die angegebene Farbe dort angezeigt wird, wo das Bild auf dem Bildschirm zu sehen ist. Das ist nützlich für Symbole und Vektoren, die unterschiedlich gestaltet werden 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 führen zu anderen Effekten. Wenn Sie beispielsweise BlendMode.Darken mit einem Color.Green auf einem Bild festlegen, erhalten Sie das folgende 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 verfügbaren Überblendungsmodi finden Sie in der Referenzdokumentation zu „BlendMode“.

Image-Filter mit Farbmatrix anwenden

Transformieren Sie das Bild mit der Option „Farbmatrix“ ColorFilter. Wenn Sie beispielsweise einen Schwarz-Weiß-Filter auf Ihre Bilder anwenden möchten, können Sie ColorMatrix verwenden und die Sättigung auf 0f setzen.

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 eines Image-Composeables anpassen

Mit der Taste ColorMatrix können Sie den Kontrast und die Helligkeit eines Bildes ä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: Mit ColorMatrix angepasste Bildhelligkeit und -kontrast

Farben eines Image-Kompositionselements 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: Inversion der Farben im Bild

Zusammensetzbare Funktion vom Typ „Image“ unkenntlich machen

Wenn Sie ein Bild unscharfstellen möchten, verwenden Sie Modifier.blur() und geben Sie radiusX und radiusY an, um den Unschärferadius in horizontaler und vertikaler Richtung anzugeben.

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 Bild angewendet

Wenn Sie Images unkenntlich machen möchten, empfehlen wir, BlurredEdgeTreatment(Shape) anstelle von BlurredEdgeTreatment.Unbounded zu verwenden. Letzteres wird zum Unkenntlichmachen beliebiger Renderings verwendet, die voraussichtlich außerhalb der Grenzen der ursprünglichen Inhalte gerendert werden. 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 für das Bild oben BlurredEdgeTreatment auf „Unbegrenzt“ festlegen, sind die Ränder des Bilds unscharf 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.