Pemburaman di Compose

Efek blur melembutkan detail visual, menciptakan depth of field fotografi, dan menarik fokus ke elemen UI latar depan. Di Jetpack Compose, gunakan Modifier.blur untuk memburamkan konten yang digambar di dalam composable, termasuk gambar, bentuk, teks, dan penampung tata letak. Menerapkan Modifier.blur akan merender composable ke dalam lapisan grafis terpisah.

Gambar 1. Kiri: gambar asli. Tengah: gambar dengan blur seragam yang diterapkan di seluruh permukaan. Kanan: gambar dengan blur progresif yang tajam di bagian atas dan meningkat ke arah bawah.

Bergantung pada sasaran desain, Anda dapat memvariasikan blur dengan dua cara:

• Blur seragam: Menerapkan radius blur yang konstan di seluruh composable, baik secara merata pada kedua sumbu maupun dengan radius horizontal dan vertikal independen (radiusX, radiusY).
• Blur progresif: Memvariasikan radius blur secara spasial di seluruh composable menggunakan gradien BlurRadiusSpec atau Shader kustom.

Catatan: Modifier.blur memburamkan konten yang digambar composable itu sendiri: gambar, teks, bentuk, dan composable turunannya. Hal ini terkadang disebut blur permukaan atau lapisan, berbeda dengan blur latar belakang, yang memburamkan apa pun yang digambar di belakang composable. Halaman ini membahas blur permukaan.

Menerapkan blur seragam

Catatan: Contoh di bagian ini juga meneruskan edgeTreatment yang memotong hasil buram ke sudut membulat. Untuk mengetahui informasi selengkapnya, lihat Mengontrol pemangkasan tepi dengan BlurredEdgeTreatment.

Untuk menerapkan blur konstan di seluruh composable, teruskan radius Dp ke Modifier.blur. Teruskan satu nilai radius untuk memburamkan konten secara merata di sepanjang sumbu horizontal (X) dan vertikal (Y):

@Composable
fun UniformBlurExample() {
    Image(
        painter = painterResource(id = R.drawable.dog),
        contentDescription = stringResource(id = R.string.dog_content_description),
        contentScale = ContentScale.Crop,
        modifier = Modifier
            .size(150.dp)
            .blur(
                radius = 8.dp,
                edgeTreatment = BlurredEdgeTreatment(RoundedCornerShape(8.dp)),
            ),
    )
}
BlurSnippets.kt

Gambar 2. Anjing yang diburamkan secara seragam pada sumbu horizontal dan vertikal.

Untuk membuat efek motion blur terarah, teruskan nilai radiusX dan radiusY terpisah ke Modifier.blur. radiusX dan radiusY harus lebih besar dari 0.dp agar efek blur diterapkan, seperti yang ditunjukkan dalam contoh berikut:

@Composable
fun DirectionalBlurExample() {
    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 = 2.dp,
                edgeTreatment = BlurredEdgeTreatment(RoundedCornerShape(8.dp)),
            ),
    )
}
BlurSnippets.kt

Gambar 3. Gambar persegi seekor anjing dengan efek blur gerakan horizontal yang kuat.

Menerapkan blur progresif

Catatan: API blur progresif (BlurRadiusSpec, BlurStop, dan blok konfigurasi Modifier.blur { }) tersedia di androidx.compose.ui:ui 1.13.0-beta01 dan yang lebih tinggi.

Blur progresif memvariasikan radius blur di seluruh composable, sehingga menciptakan transisi yang mulus antara area yang tajam dan buram.

Teruskan BlurRadiusSpec ke Modifier.blur. Misalnya, gunakan BlurRadiusSpec.verticalGradient dengan startRadius = 0.dp dan endRadius = 6.dp untuk menjaga bagian atas gambar tetap tajam sambil memburamkannya secara progresif ke arah bawah, seperti yang ditunjukkan dalam contoh berikut:

@Composable
fun ProgressiveBlurExample() {
    Image(
        painter = painterResource(id = R.drawable.dog),
        contentDescription = stringResource(id = R.string.dog_content_description),
        contentScale = ContentScale.Crop,
        modifier = Modifier
            .size(150.dp)
            .blur(
                // Sharp at the top (0.dp), progressively blurred toward the bottom (6.dp)
                blurRadiusSpec = BlurRadiusSpec.verticalGradient(
                    startRadius = 0.dp,
                    endRadius = 6.dp,
                ),
                edgeTreatment = BlurredEdgeTreatment(RoundedCornerShape(8.dp)),
            ),
    )
}
BlurSnippets.kt

Gambar 4. Gambar anjing yang tajam di bagian atas dan secara bertahap menjadi buram ke arah bawah.

Menentukan gradien blur dengan BlurRadiusSpec

Di BlurRadiusSpec, pengukuran ditetapkan dalam Dp dan otomatis disesuaikan dengan ukuran dan kepadatan tampilan lapisan saat digambar. Blur yang bervariasi secara spasial dibatasi hingga 150 piksel setelah dikonversi, sedangkan BlurRadiusSpec.uniform tidak memiliki batas.

Tabel berikut mencantumkan fungsi factory yang tersedia di BlurRadiusSpec:

BlurRadiusSpec factory	Deskripsi
BlurRadiusSpec.verticalGradient	Mengubah radius blur secara vertikal dengan mulus dari atas (0f) ke bawah (1f) di seluruh lapisan.
BlurRadiusSpec.horizontalGradient	Mengubah radius blur secara halus secara horizontal dari tepi kiri (0f) ke tepi kanan (1f).
BlurRadiusSpec.linearGradient	Menerapkan transisi blur terarah di sepanjang garis lurus yang menghubungkan koordinat DpOffset tertentu.
BlurRadiusSpec.radialGradient	Menyebarkan blur ke luar dari titik fokus ke batas fallOffRadius.
BlurRadiusSpec.uniform	Menerapkan radius blur yang merata di seluruh lapisan.
BlurRadiusSpec.shader	Menggunakan saluran alfa Shader kustom untuk mengontrol dan menskalakan maxRadius di setiap piksel.

Menyesuaikan distribusi blur dengan BlurStop

Blur gradien standar melakukan interpolasi secara linear antara 0f dan 1f. Untuk menyesuaikan distribusi blur di seluruh permukaan, seperti memburamkan beberapa tepi atau menjaga bagian tengah tetap tajam, teruskan List<BlurStop> yang berisi 2 hingga 16 entri BlurStop ke verticalGradient, horizontalGradient, linearGradient, atau radialGradient. Tentukan hal berikut untuk setiap entri BlurStop:

• fraction: Posisi relatif di sepanjang gradien dari 0.0f hingga 1.0f. Perhentian diurutkan secara otomatis berdasarkan pecahan.
• radius: Radius blur dalam Dp yang diterapkan pada posisi pecahan tersebut.

Misalnya, empat perhentian memburamkan tepi atas dan bawah gambar, sekaligus menjaga bagian tengah tetap tajam, seperti yang ditunjukkan dalam contoh berikut:

@Composable
fun MultiStopBlurExample() {
    Image(
        painter = painterResource(id = R.drawable.dog),
        contentDescription = stringResource(id = R.string.dog_content_description),
        contentScale = ContentScale.Crop,
        modifier = Modifier
            .size(150.dp)
            .blur(
                // Blurred at the top and bottom edges, sharp in the middle (0.3f..0.7f)
                blurRadiusSpec = BlurRadiusSpec.verticalGradient(
                    stops = listOf(
                        BlurStop(fraction = 0.0f, radius = 20.dp),
                        BlurStop(fraction = 0.3f, radius = 0.dp),
                        BlurStop(fraction = 0.7f, radius = 0.dp),
                        BlurStop(fraction = 1.0f, radius = 20.dp),
                    ),
                ),
                edgeTreatment = BlurredEdgeTreatment.Unbounded,
            ),
    )
}
BlurSnippets.kt

Gambar 5. Gambar anjing dengan tepi atas dan bawah yang diburamkan, sementara strip horizontal tengah tetap dalam fokus yang tajam.

Mengonfigurasi properti lapisan dengan BlurScope

Alih-alih meneruskan blurRadiusSpec secara langsung, Anda dapat meneruskan blok konfigurasi ke Modifier.blur { ... }. Blok ini berjalan di dalam BlurScope, yang memberi Anda akses langsung ke kepadatan tata letak dan properti berikut:

• size: DpSize: Lebar dan tinggi lapisan buram yang diukur dalam Dp, yang menentukan ruang koordinat untuk geometri gradien.
• blurRadiusSpec: BlurRadiusSpec: Konfigurasi radius blur di seluruh platform. Nilai defaultnya adalah BlurRadiusSpec.uniform(0.dp) (tanpa blur).
• edgeTreatment: BlurredEdgeTreatment: Strategi yang digunakan untuk mengambil sampel dan memangkas piksel di luar batas konten. Nilai defaultnya adalah BlurredEdgeTreatment.Rectangle.
• alpha: Float: Opasitas lapisan buram dalam rentang 0f..1f. Setelan defaultnya adalah 1f.

Karena blok BlurScope berjalan selama fase lapisan grafis, setelah pengukuran dan tata letak, Anda dapat menghitung geometri gradien dari size tanpa memicu rekomposisi.

Catatan: Blur seragam memerlukan Android 12 (level API 31) dan yang lebih tinggi, dan blur progresif memerlukan Android 13 (level API 33) dan yang lebih tinggi. Pada versi yang lebih rendah, Compose merender konten tanpa blur, meskipun setelan pemangkasan bentuk dan alfa BlurredEdgeTreatment masih berlaku.

Mengontrol pemangkasan tepi dengan BlurredEdgeTreatment

Karena pemburaman mengambil sampel piksel di sekitarnya dalam radius blur, output yang diburamkan akan melampaui batas konten asli sebesar radius blur. BlurredEdgeTreatment menentukan cara piksel di luar batas asli diambil sampelnya dan apakah hasilnya dipangkas menjadi bentuk.

BlurredEdgeTreatment berfungsi dengan blur seragam dan progresif:

BlurredEdgeTreatment	Perilaku	Output
BlurredEdgeTreatment.Rectangle (default)	Memotong hasil blur ke batas persegi panjang konten orisinal dan mengambil sampel piksel tepi terdekat (TileMode.Clamp).
BlurredEdgeTreatment(shape)	Memotong hasil blur ke Shape yang ditentukan (seperti RoundedCornerShape(8.dp)) dan mengambil sampel piksel tepi terdekat (TileMode.Clamp). Menjaga hasil blur tetap tajam di batas bentuk tanpa meluber ke luar batas aslinya.
BlurredEdgeTreatment.Unbounded	Tidak memotong hasil blur (TileMode.Decal). Piksel di luar batas konten mengambil sampel warna hitam transparan, sehingga tepi luar gambar tampak buram dan blur di luar batas aslinya.

Untuk melihat cara API ini digabungkan dalam pola UI lengkap, seperti memudarkan tepi konten scroll, menyoroti titik fokus, atau menyamarkan blur dengan shading kustom, lihat Kasus penggunaan blur umum.