Bild anpassen

Sie können Bilder mithilfe von Properties in einer Image komponierbaren Funktion (contentScale, colorFilter) anpassen. Sie können auch vorhandene Modifikatoren anwenden, um verschiedene Effekte auf Ihre Image anzuwenden. Modifikatoren können für jede zusammensetzbare Funktion verwendet werden, nicht nur für die zusammensetzbare Funktion Image. contentScale und colorFilter sind dagegen explizite Parameter für die zusammensetzbare Funktion Image.

Inhaltsskalierung

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

Im folgenden Beispiel ist das Compose-Element Image auf eine Größe von 150 dp mit einem Rahmen beschränkt. Der Hintergrund des Compose-Elements Image 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
)

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

Quellbild Die Porträtquelle, die einen Hund zeigt. Die Quelle im Querformat, die einen anderen Hund zeigt.
ContentScale Ergebnis – Bild im Hochformat: Ergebnis – Bild im Querformat:
ContentScale.Fit: Das Bild wird gleichmäßig 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. Ein Hundebild, das einheitlich skaliert wurde. Ein Hund im Querformat, gleichmäßig skaliert.
ContentScale.Crop: Das Bild wird mittig auf den verfügbaren Platz zugeschnitten. Ein Bild im Hochformat, das so zugeschnitten ist, dass es einen quadratischen Rahmen ausfüllt. Es ist nur der mittlere Teil des Bildes zu sehen. Ein Bild im Querformat, das auf einen quadratischen Rahmen zugeschnitten ist und nur den mittleren Teil des Bildes zeigt.
ContentScale.FillHeight: Die Quelle wird unter Beibehaltung des Seitenverhältnisses so skaliert, dass die Grenzen der Zielhöhe entsprechen. Ein Bild im Hochformat, das so skaliert ist, dass es die Höhe eines quadratischen Rahmens ausfüllt. Das vollständige Bild ist zu sehen, links und rechts ist ein gelber Hintergrund sichtbar. Ein Bild im Querformat, das so skaliert ist, dass es die Höhe eines quadratischen Rahmens ausfüllt, wobei die Seiten abgeschnitten sind.
ContentScale.FillWidth: Die Quelle wird unter Beibehaltung des Seitenverhältnisses so skaliert, dass die Grenzen mit der Zielbreite übereinstimmen. Ein Bild im Hochformat, das so skaliert ist, dass es die Breite eines quadratischen Rahmens ausfüllt, wobei der obere und untere Teil abgeschnitten sind. Ein Bild im Querformat, das so skaliert ist, dass es die Breite eines quadratischen Rahmens ausfüllt. Das vollständige Bild ist zu sehen, wobei oben und unten ein gelber Hintergrund sichtbar ist.
ContentScale.FillBounds: Der Inhalt wird vertikal und horizontal nicht einheitlich skaliert, um die Zielgrenzen auszufüllen. Hinweis: Dadurch werden Bilder verzerrt, wenn Sie sie in Container einfügen, die nicht genau dem Seitenverhältnis des Bildes entsprechen. Ein Bild im Hochformat, das so verzerrt ist, dass es einen quadratischen Rahmen vollständig ausfüllt. Das Bild wird dabei gestreckt. Ein Bild im Querformat, das verzerrt wurde, um einen quadratischen Rahmen vollständig auszufüllen. Das Bild wird dabei gestreckt.
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. Inhalte werden immer innerhalb der Grenzen angezeigt. Wenn der Inhalt kleiner als die Grenzen ist, wird keine Skalierung angewendet. Quellbild größer als die Grenzen: Ein Bild im Hochformat, das ursprünglich größer als die quadratischen Grenzen war, wurde unter Beibehaltung des Seitenverhältnisses verkleinert, sodass an den Seiten ein gelber Hintergrund zu sehen ist. Quellbild kleiner als die Grenzen: Ein Bild im Hochformat, das ursprünglich kleiner als der quadratische Rahmen war, wird in seiner Originalgröße im Rahmen angezeigt. Der Hintergrund ist gelb. Quellbild größer als die Grenzen: Ein Bild im Querformat, das ursprünglich größer als die quadratischen Grenzen war, wurde unter Beibehaltung des Seitenverhältnisses herunterskaliert. Oben und unten ist ein gelber Hintergrund zu sehen. Quellbild kleiner als die Grenzen: Ein Bild im Querformat, das ursprünglich kleiner als der quadratische Rahmen war, wird in seiner Originalgröße im Rahmen angezeigt, wobei ein gelber Hintergrund um das Bild herum zu sehen ist.
ContentScale.None: Es wird keine Skalierung auf die Quelle angewendet. Wenn der Inhalt kleiner als die Zielgrenzen ist, wird er nicht auf die Größe des Bereichs skaliert. Quellbild größer als die Grenzen: Ein Bild im Hochformat, das ursprünglich größer als die quadratischen Begrenzungen war, wird in seiner Originalgröße angezeigt, wobei Teile über den oberen und unteren Rand des Rahmens hinausragen. Quellbild kleiner als die Grenzen: Ein Bild im Hochformat, das ursprünglich kleiner als der quadratische Rahmen war, wird in seiner Originalgröße im Rahmen angezeigt. Der Hintergrund ist gelb. Quellbild größer als Begrenzung: Ein Bild im Querformat, das ursprünglich größer als der quadratische Rahmen war, wird in seiner Originalgröße angezeigt, wobei Teile über den linken und rechten Rand des Rahmens hinausragen. Quellbild kleiner als Begrenzung: Ein Bild im Querformat, das ursprünglich kleiner als der quadratische Rahmen war, wird in seiner Originalgröße im Rahmen angezeigt, wobei ein gelber Hintergrund um das Bild herum zu sehen ist.

Image-Composable auf eine Form zuschneiden

Wenn Sie ein Bild in eine Form einpassen möchten, verwenden Sie den integrierten clip-Modifikator. So schneiden Sie ein Bild kreisförmig zu: 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)
)

Ein Bild eines Hundes, das in einen perfekten Kreis zugeschnitten ist.
Abbildung 1: Bild mit CircleShape ausschneiden.

Verwenden Sie für eine abgerundete Form 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))
)

Ein quadratisches Bild eines Hundes mit abgerundeten Ecken.
Abbildung 2: Bild mit RoundedCornerShape ausschneiden.

Sie können auch eine eigene Clipping-Form erstellen, indem Sie Shape erweitern und einen Path für die Form angeben, um die herum geclippt 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())
)

Ein quadratisches Bild eines Hundes, das in eine benutzerdefinierte, ovale Form zugeschnitten wurde.
Abbildung 3: Bild mit einer benutzerdefinierten Pfadform ausschneiden

Einem Image-Composable einen Rahmen hinzufügen

Ein gängiger Vorgang ist die Kombination von Modifier.border() mit Modifier.clip(), 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)
)

Ein quadratisches Bild eines Hundes, das zu einem Kreis zugeschnitten ist, mit einem gelben Rand um die Kreisform.
Abbildung 4: Ein zugeschnittenes Bild mit einem Rahmen.

Wenn Sie einen Farbverlaufsrahmen erstellen möchten, können Sie mit der Brush API einen Regenbogen-Farbverlaufsrahmen 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)
)

Ein kreisförmiges Bild eines Hundes mit einem regenbogenfarbenen Rand um die Kreisform.
Abbildung 5: Regenbogenfarbverlauf-Kreisrahmen.

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 Verhältnis für ein Bild (oder ein beliebiges Kompositionselement) anzugeben.

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

Ein quadratisches Bild eines Hundes, das in ein Seitenverhältnis von 16:9 umgewandelt wurde, wodurch es breiter und kürzer wird.
Abbildung 6: Modifier.aspectRatio(16f/9f) auf einem Image verwenden.

Farbfilter: Pixelfarben des Bildes transformieren

Das Compose-Element Image hat einen colorFilter-Parameter, mit dem die Ausgabe einzelner Pixel des Bildes geändert werden kann.

Bilder tönen

Wenn du ColorFilter.tint(color, blendMode) verwendest, wird ein Mischmodus mit der angegebenen Farbe auf dein Image-Composable 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. 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)
)

Bild eines Busses mit einem gelben Farbton.
Abbildung 7. ColorFilter.tint mit BlendMode.SrcIn angewendet.

Andere BlendModes führen zu anderen Effekten. Wenn Sie beispielsweise BlendMode.Darken mit einem Color.Green für ein Image festlegen, 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)
)

Ein Hund mit einem grünen Farbton, der mit BlendMode.Darken angewendet wurde, was zu dunkleren Grüntönen führt.
Abbildung 8. Color.Green tint mit BlendMode.Darken.

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

Image-Filter mit Farbmatrix anwenden

Transformieren Sie Ihr Bild mit der Farbmatrixoption 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 festlegen.

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

Ein Hund mit einem Schwarz-Weiß-Filter, der die gesamte Farbsättigung entfernt.
Abbildung 9. Farbmatrix mit Sättigung 0 (Schwarz-Weiß-Bild).

Kontrast oder Helligkeit einer Image-Komposition 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))
)

Ein Hund mit erhöhter Helligkeit und erhöhtem Kontrast, wodurch er lebendiger wirkt.
Abbildung 10. Helligkeit und Kontrast des Bildes wurden mit ColorMatrix angepasst.

Farben eines Image-Kompositums umkehren

Wenn Sie die Farben eines Bildes invertieren möchten, legen Sie ColorMatrix fest, um die Farben zu invertieren:

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))
)

Ein Hund mit Farbumkehr, der wie ein Negativ aussieht.
Abbildung 11: Umgekehrte Farben auf dem Bild.

Image-Composable weichzeichnen

Wenn Sie ein Bild weichzeichnen möchten, verwenden Sie Modifier.blur() und geben Sie radiusX und radiusY an, um den Weichzeichnungsradius in horizontaler bzw. vertikaler Richtung festzulegen.

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))
        )
)

Ein Hund mit einem starken Unschärfeeffekt, der ihn undeutlich und unscharf erscheinen lässt.
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 voraussichtlich außerhalb der Grenzen des Originalinhalts gerendert werden. Bilder werden wahrscheinlich nicht außerhalb der Grenzen des Inhalts gerendert, während beim Weichzeichnen eines abgerundeten Rechtecks diese Unterscheidung erforderlich sein kann.

Wenn wir beispielsweise BlurredEdgeTreatment im vorherigen Bild auf Unbounded setzen, werden die Kanten des Bildes unscharf statt 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))
)

Ein unscharfes Bild eines Hundes, bei dem die Unschärfe über die ursprünglichen Bildgrenzen hinausgeht, sodass die Ränder verschwommen sind.
Abbildung 13. BlurEdgeTreatment.Unbounded.
Zurück
Materialsymbole
Weiter
Maler und Lackierer