如何在Jetpack Compose中实现图片裁剪？为何未找到相关官方文档？

I get it, the official Jetpack Compose docs don’t have a dedicated guide for image cropping yet—super frustrating when you need this feature for your app. Let’s walk through two solid approaches to implement it, depending on whether you want a quick library-based solution or full control with a custom build.

Option 1: Use a Compose-First Third-Party Library #

The easiest way to add cropping is to leverage a library built specifically for Jetpack Compose. A reliable choice is compose-image-cropper, which handles gesture logic, UI overlays, and result handling out of the box.

Step 1: Add the Dependency #

Drop this into your app-level build.gradle.kts (or build.gradle):

dependencies {
    implementation("com.github.canopas:compose-image-cropper:1.5.0")
}

(Pro tip: Double-check for the latest version number before implementing—library versions get updated regularly!)

Step 2: Implement the Cropper #

Here’s a straightforward example to launch the cropper and handle the result:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.canopas.cropper.CropImage
import com.canopas.cropper.CropResult
import com.canopas.cropper.rememberCropState
import coil.compose.AsyncImage
import android.net.Uri

@Composable
fun ImageCropperDemo() {
    val cropState = rememberCropState()
    val croppedImageUri = remember { mutableStateOf<Uri?>(null) }

    Column {
        Button(onClick = {
            // Launch the crop flow—you can pass a pre-selected image Uri here (e.g., from gallery picker)
            cropState.launchCrop()
        }) {
            Text("Pick & Crop Image")
        }

        // Show the cropped image once available
        croppedImageUri.value?.let { uri ->
            AsyncImage(
                model = uri,
                contentDescription = "Cropped image",
                modifier = Modifier.size(200.dp).clickable { cropState.launchCrop() }
            )
        }

        // Handle crop results
        CropImage(
            cropState = cropState,
            onCropComplete = { result ->
                when (result) {
                    is CropResult.Success -> {
                        croppedImageUri.value = result.uri
                    }
                    is CropResult.Error -> {
                        // Handle errors (e.g., show a toast or error message)
                        println("Crop failed: ${result.exception.message}")
                    }
                    CropResult.Cancelled -> {
                        // User backed out of cropping—no action needed unless you want to log it
                    }
                }
            }
        )
    }
}

Don’t forget permissions: For Android 13+, you’ll need READ_MEDIA_IMAGES to access gallery photos. If you want to let users capture a photo directly from the cropper, add the CAMERA permission too.

Option 2: Build a Custom Cropper (For Full Control) #

If you prefer avoiding third-party dependencies, you can build a basic cropper yourself. Here’s a simplified version to get you started:

Step 1: Load Image & Track Crop Region #

First, load your image (using Coil in this example) and add gesture handlers to let users pan/zoom the image within a crop frame:

import androidx.compose.foundation.gestures.detectTransformGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.geometry.Rect
import androidx.compose.ui.geometry.Size
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.drawscope.Stroke
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
import coil.compose.AsyncImage
import android.net.Uri

@Composable
fun CustomImageCropper(imageUri: Uri) {
    val scale = remember { mutableStateOf(1f) }
    val offset = remember { mutableStateOf(Offset.Zero) }
    val cropSize = Size(300f, 300f) // Fixed square crop—adjust to your needs

    Box(modifier = Modifier.fillMaxSize()) {
        // Load and transform the image
        AsyncImage(
            model = imageUri,
            contentDescription = "Image to crop",
            contentScale = ContentScale.Fit,
            modifier = Modifier
                .fillMaxSize()
                .pointerInput(Unit) {
                    detectTransformGestures { _, pan, zoom, _ ->
                        scale.value = (scale.value * zoom).coerceIn(1f, 5f) // Limit zoom range
                        offset.value += pan
                    }
                }
                .graphicsLayer(
                    scaleX = scale.value,
                    scaleY = scale.value,
                    translationX = offset.value.x,
                    translationY = offset.value.y
                )
        )

        // Draw crop overlay and border
        androidx.compose.foundation.Canvas(modifier = Modifier.fillMaxSize()) {
            val center = Offset(size.width / 2, size.height / 2)
            val cropRect = Rect(
                center.x - cropSize.width / 2,
                center.y - cropSize.height / 2,
                center.x + cropSize.width / 2,
                center.y + cropSize.height / 2
            )

            // Dark overlay outside crop area
            drawRect(Color.Black.copy(alpha = 0.5f))
            // Transparent area for crop
            drawRect(Color.Transparent, topLeft = cropRect.topLeft, size = cropRect.size)
            // White crop border
            drawRect(
                color = Color.White,
                topLeft = cropRect.topLeft,
                size = cropRect.size,
                style = Stroke(2.dp.toPx())
            )
        }

        // Crop button
        Button(
            onClick = {
                // Call crop logic here (see Step 2)
                val croppedBitmap = cropImage(context, imageUri, cropRect, scale.value, offset.value)
                // Use the cropped bitmap (save to file, display, etc.)
            },
            modifier = Modifier.align(androidx.compose.ui.Alignment.BottomCenter).padding(16.dp)
        ) {
            Text("Crop Image")
        }
    }
}

Step 2: Implement Crop Logic #

Add this helper function to crop the bitmap based on the user’s selected region:

import android.content.Context
import android.graphics.Bitmap
import android.graphics.Canvas
import android.graphics.Matrix
import android.graphics.RectF
import android.net.Uri
import androidx.compose.ui.geometry.Rect
import coil.request.ImageRequest
import coil.size.Scale

fun cropImage(
    context: Context,
    imageUri: Uri,
    cropRect: Rect,
    scale: Float,
    offset: Offset
): Bitmap? {
    // Load original bitmap using Coil
    val request = ImageRequest.Builder(context)
        .data(imageUri)
        .scale(Scale.FILL)
        .allowHardware(false) // Required for bitmap manipulation
        .build()

    val originalBitmap = coil.imageLoader(context).execute(request).drawable?.bitmap ?: return null

    // Calculate crop region on original bitmap
    val matrix = Matrix().apply {
        postScale(1f / scale, 1f / scale)
        postTranslate(-offset.x, -offset.y)
    }

    val cropRectF = RectF(cropRect)
    matrix.mapRect(cropRectF)

    // Adjust for image vs layout size ratio
    val imageAspectRatio = originalBitmap.width.toFloat() / originalBitmap.height.toFloat()
    val layoutAspectRatio = cropRect.width / cropRect.height
    val scaleFactor = if (imageAspectRatio > layoutAspectRatio) {
        originalBitmap.width.toFloat() / cropRect.width
    } else {
        originalBitmap.height.toFloat() / cropRect.height
    }

    val finalCropRect = RectF(
        cropRectF.left * scaleFactor,
        cropRectF.top * scaleFactor,
        cropRectF.right * scaleFactor,
        cropRectF.bottom * scaleFactor
    )

    // Crop and return the bitmap
    return Bitmap.createBitmap(
        originalBitmap,
        finalCropRect.left.toInt(),
        finalCropRect.top.toInt(),
        finalCropRect.width().toInt(),
        finalCropRect.height().toInt()
    )
}

This custom approach lets you tweak every part of the UI and behavior, but you’ll need to handle edge cases like varying aspect ratios and gesture smoothing on your own.

内容的提问来源于stack exchange，提问作者Someone