Bild anpassen

Sie können Bilder mit Eigenschaften in einer zusammensetzbaren Image-Funktion anpassen (contentScale, colorFilter). Sie können auch vorhandene Modifikatoren anwenden, um verschiedene Effekte auf Ihr Image anzuwenden. Modifikatoren können für jede zusammensetzbare Funktion verwendet werden, nicht nur für die zusammensetzbare Funktion Image. contentScale und colorFilter sind explizite Parameter für die zusammensetzbare Funktion Image.

Inhaltsskala

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

Im folgenden Beispiel ist die zusammensetzbare Funktion Image auf eine Größe von 150 dp mit einem Rahmen beschränkt. Der Hintergrund ist in der zusammensetzbaren Funktion Image gelb festgelegt, um die verschiedenen ContentScale-Optionen in der Tabelle unten 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 verschiedene ContentScale-Optionen festlegen, erhalten Sie unterschiedliche Ausgaben. Die folgende Tabelle hilft Ihnen bei der Auswahl des richtigen ContentScale-Modus:

Quellbild
ContentScale	Ergebnis – Bild im Hochformat:	Ergebnis – Bild im Querformat:
ContentScale.Fit: Das Bild wird einheitlich skaliert, wobei das Seitenverhältnis beibehalten wird (Standard). Wenn der Inhalt kleiner als die Größe ist, wird das Bild so skaliert, dass es in die Grenzen passt.
ContentScale.Crop: Das Bild wird mittig in den verfügbaren Bereich zugeschnitten.
ContentScale.FillHeight: Die Quelle wird unter Beibehaltung des Seitenverhältnisses so skaliert, dass die Grenzen der Zielhöhe entsprechen.
ContentScale.FillWidth: Die Quelle wird unter Beibehaltung des Seitenverhältnisses so skaliert, dass die Grenzen der Zielbreite entsprechen.
ContentScale.FillBounds: Der Inhalt wird vertikal und horizontal nicht einheitlich skaliert, um die Zielgrenzen zu füllen. Hinweis: Dadurch werden Bilder verzerrt, wenn Sie sie in Containern platzieren, die nicht dem genauen Verhältnis des Bildes entsprechen.
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 befindet sich immer innerhalb der Grenzen. Wenn der Inhalt kleiner als die Grenzen ist, wird keine Skalierung angewendet.	Quellbild größer als Grenzen: Quellbild kleiner als Grenzen:	Quellbild größer als Grenzen: Quellbild kleiner als Grenzen:
ContentScale.None: Auf die Quelle wird keine Skalierung angewendet. Wenn der Inhalt kleiner als die Zielgrenzen ist, wird er nicht so skaliert, dass er in den Bereich passt.	Quellbild größer als Grenzen: Quellbild kleiner als Grenzen:	Quellbild größer als Grenzen: Quellbild kleiner als Grenzen:

Zusammensetzbare Funktion Image auf eine Form zuschneiden

Verwenden Sie den integrierten Modifikator clip, um ein Bild an eine Form anzupassen. Verwenden Sie Modifier.clip(CircleShape), um ein Bild in eine Kreisform 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 zuschneiden.

Verwenden Sie für eine Form mit abgerundeten Ecken Modifier.clip(RoundedCornerShape(16.dp)), wobei Sie die Größe der Ecken angeben, 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 zuschneiden.

Sie können auch eine eigene Zuschneideform erstellen, indem Sie Shape erweitern und einen Path für die Form angeben, um die zugeschnitten werden soll:

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 einer benutzerdefinierten Pfadform zuschneiden.

Einer zusammensetzbaren Funktion Image 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. Ein zugeschnittenes Bild mit einem Rahmen.

Wenn Sie einen Farbverlaufsrahmen erstellen möchten, können Sie mit der Brush-API einen Regenbogenfarbverlaufsrahmen 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. Kreisrahmen mit Regenbogenfarbverlauf.

Benutzerdefiniertes Seitenverhältnis festlegen

Verwenden Sie Modifier.aspectRatio(16f/9f), um ein Bild in ein benutzerdefiniertes Seitenverhältnis umzuwandeln. Damit können Sie ein benutzerdefiniertes Verhältnis für ein Bild (oder eine beliebige zusammensetzbare Funktion) angeben.

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 ein Image verwenden.

Farbfilter: Pixelfarben des Bildes transformieren

Die zusammensetzbare Funktion Image hat einen colorFilter-Parameter, mit dem die Ausgabe einzelner Pixel Ihres Bildes geändert werden kann.

Bilder einfä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, um Inhalte einzufärben. 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 anders 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 BlendModes führen zu anderen Effekten. Wenn Sie beispielsweise BlendMode.Darken mit Color.Green auf ein Bild anwenden, erhalten Sie folgendes 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. Color.Green tint mit BlendMode.Darken.

Weitere Informationen zu den verschiedenen verfügbaren Mischmodi finden Sie in der BlendModeReferenzdokumentation.

Image-Filter mit Farbmatrix anwenden

Transformieren Sie Ihr Bild mit der ColorFilter-Option für die Farbmatrix. Wenn Sie beispielsweise einen Schwarz-Weiß-Filter auf Ihre Bilder anwenden möchten, können Sie die ColorMatrix verwenden und 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 zusammensetzbaren Funktion Image anpassen

Wenn Sie den Kontrast und die Helligkeit eines Bildes ändern möchten, können Sie die 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. Helligkeit und Kontrast des Bildes mit ColorMatrix angepasst.

Farben einer zusammensetzbaren Funktion Image umkehren

Wenn Sie die Farben eines Bildes umkehren möchten, legen Sie die ColorMatrix so 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. Farben im Bild umgekehrt.

Zusammensetzbare Funktion Image weichzeichnen

Verwenden Sie Modifier.blur(), um ein Bild weichzuzeichnen. Geben Sie dazu radiusX und radiusY an, die den Radius der Weichzeichnung in horizontaler bzw. vertikaler Richtung angeben.

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

Beim Weichzeichnen von Images wird empfohlen, BlurredEdgeTreatment(Shape) anstelle von BlurredEdgeTreatment.Unbounded zu verwenden, da Letzteres für das Weichzeichnen beliebiger Renderings verwendet wird, die außerhalb der Grenzen des ursprünglichen Inhalts gerendert werden sollen. Bei Bildern ist es wahrscheinlich, dass sie nicht außerhalb der Grenzen des Inhalts gerendert werden. Beim Weichzeichnen eines abgerundeten Rechtecks ist diese Unterscheidung jedoch möglicherweise erforderlich.

Wenn wir beispielsweise BlurredEdgeTreatment für das vorherige Bild auf Unbounded festlegen, werden die Ränder des Bildes weichgezeichnet anstatt scharf dargestellt:

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 Weichzeichnungseffekt wird nur unter Android 12 und höher unterstützt. Versuche, diesen Modifikator in älteren Android-Versionen zu verwenden, werden ignoriert.