Pengubah scroll
Pengubah verticalScroll
dan horizontalScroll
memberikan cara termudah untuk memungkinkan pengguna men-scroll elemen jika batas kontennya lebih besar dari batasan ukuran maksimumnya. Dengan pengubah verticalScroll
dan horizontalScroll
, Anda tidak perlu menerjemahkan atau melakukan offset pada konten tersebut.
@Composable private fun ScrollBoxes() { Column( modifier = Modifier .background(Color.LightGray) .size(100.dp) .verticalScroll(rememberScrollState()) ) { repeat(10) { Text("Item $it", modifier = Modifier.padding(2.dp)) } } }
ScrollState
memungkinkan Anda mengubah posisi scroll atau mendapatkan statusnya saat ini. Untuk membuatnya dengan parameter default, gunakan rememberScrollState()
.
@Composable private fun ScrollBoxesSmooth() { // Smoothly scroll 100px on first composition val state = rememberScrollState() LaunchedEffect(Unit) { state.animateScrollTo(100) } Column( modifier = Modifier .background(Color.LightGray) .size(100.dp) .padding(horizontal = 8.dp) .verticalScroll(state) ) { repeat(10) { Text("Item $it", modifier = Modifier.padding(2.dp)) } } }
Pengubah yang dapat di-scroll
Pengubah
scrollable
berbeda dengan pengubah scroll karena scrollable
mendeteksi
gestur scroll dan menangkap delta, tetapi tidak mengimbangi kontennya
secara otomatis. Sebaliknya, ini didelegasikan kepada pengguna melalui
ScrollableState
, yang diperlukan agar pengubah ini berfungsi dengan benar.
Saat membuat ScrollableState
, Anda harus menyediakan fungsi consumeScrollDelta
yang akan dipanggil pada setiap langkah scroll (dengan input gestur, scroll
halus, atau ayunkan jari) dengan delta dalam piksel. Fungsi ini harus menampilkan
jumlah jarak scroll yang digunakan untuk memastikan peristiwa disebarkan
dengan benar jika ada elemen bertingkat yang memiliki pengubah
scrollable
.
Cuplikan berikut mendeteksi gestur dan menampilkan nilai numerik untuk offset, tetapi tidak melakukan offset pada elemen apa pun:
@Composable private fun ScrollableSample() { // actual composable state var offset by remember { mutableStateOf(0f) } Box( Modifier .size(150.dp) .scrollable( orientation = Orientation.Vertical, // Scrollable state: describes how to consume // scrolling delta and update offset state = rememberScrollableState { delta -> offset += delta delta } ) .background(Color.LightGray), contentAlignment = Alignment.Center ) { Text(offset.toString()) } }
Scrolling bertingkat
Scrolling bertingkat adalah sistem tempat beberapa komponen scroll yang terdapat di dalam satu sama lain bekerja sama dengan bereaksi terhadap satu gestur scroll dan mengomunikasikan delta scroll (perubahannya).
Sistem scroll bertingkat memungkinkan koordinasi antar-komponen yang dapat di-scroll dan ditautkan secara hierarkis (paling sering dengan berbagi induk yang sama). Sistem ini menautkan penampung scroll dan memungkinkan interaksi dengan delta scroll yang sedang disebarkan dan digunakan bersama.
Compose menyediakan beberapa cara untuk menangani scroll bertingkat di antara composable. Contoh umum scroll bertingkat adalah daftar di dalam daftar lain, dan kasus yang lebih kompleks adalah toolbar yang dapat diciutkan.
Scrolling bertingkat otomatis
Scroll bertingkat sederhana tidak memerlukan tindakan dari Anda. Gestur yang memulai tindakan scroll diterapkan dari turunan ke induk secara otomatis, sehingga saat turunan tidak dapat men-scroll lagi, gestur tersebut akan ditangani oleh elemen induknya.
Scroll bertingkat otomatis didukung dan disediakan siap pakai oleh beberapa
komponen dan pengubah Compose:
verticalScroll
,
horizontalScroll
,
scrollable
,
Lazy
API, dan TextField
. Ini berarti bahwa saat pengguna men-scroll turunan
dalam dari komponen bertingkat, pengubah sebelumnya akan menyebarkan delta
scroll ke induk yang memiliki dukungan scroll bertingkat.
Contoh berikut menunjukkan elemen dengan pengubah
verticalScroll
yang diterapkan di dalam penampung yang juga memiliki pengubah verticalScroll
yang diterapkan pada elemen tersebut.
@Composable private fun AutomaticNestedScroll() { val gradient = Brush.verticalGradient(0f to Color.Gray, 1000f to Color.White) Box( modifier = Modifier .background(Color.LightGray) .verticalScroll(rememberScrollState()) .padding(32.dp) ) { Column { repeat(6) { Box( modifier = Modifier .height(128.dp) .verticalScroll(rememberScrollState()) ) { Text( "Scroll here", modifier = Modifier .border(12.dp, Color.DarkGray) .background(brush = gradient) .padding(24.dp) .height(150.dp) ) } } } } }
Menggunakan pengubah nestedScroll
Jika Anda perlu membuat scroll terkoordinasi lanjutan di antara beberapa elemen, pengubah nestedScroll
memberi Anda lebih banyak fleksibilitas dengan menentukan hierarki scroll bertingkat. Seperti
yang disebutkan di bagian sebelumnya, beberapa komponen memiliki dukungan scroll bertingkat
bawaan. Namun, untuk composable yang tidak dapat di-scroll secara otomatis, seperti
Box
atau Column
, delta scroll pada komponen tersebut tidak akan diterapkan dalam
sistem scroll bertingkat dan delta tidak akan menjangkau NestedScrollConnection
atau
komponen induk. Untuk mengatasi hal ini, Anda dapat menggunakan nestedScroll
untuk memberikan
dukungan tersebut kepada komponen lain, termasuk komponen kustom.
Siklus scroll bertingkat
Siklus scroll bertingkat adalah alur delta scroll yang dikirim ke atas dan ke bawah
dalam hierarki melalui semua komponen (atau node) yang merupakan bagian dari sistem
scroll bertingkat, misalnya dengan menggunakan komponen dan pengubah yang dapat di-scroll, atau
nestedScroll
.
Fase siklus scroll bertingkat
Saat peristiwa pemicu (misalnya, gestur) terdeteksi oleh komponen yang dapat di-scroll, bahkan sebelum tindakan scroll yang sebenarnya dipicu, delta yang dihasilkan akan dikirim ke sistem scroll bertingkat dan melalui tiga fase: pra-scroll, pemakaian node, dan pasca-scroll.
Pada fase pra-scroll pertama, komponen yang menerima delta peristiwa pemicu akan mengirimkan peristiwa tersebut ke atas, melalui hierarki hierarki, ke induk paling atas. Peristiwa delta kemudian akan menjadi balon ke bawah, yang berarti bahwa delta akan disebarkan dari induk root ke bawah ke turunan yang memulai siklus scroll bertingkat.
Hal ini memberi induk scroll bertingkat (composable menggunakan nestedScroll
atau
pengubah yang dapat di-scroll) peluang untuk melakukan sesuatu dengan delta sebelum
node itu sendiri dapat menggunakannya.
Pada fase pemakaian node, node itu sendiri akan menggunakan delta apa pun yang tidak digunakan oleh induknya. Inilah saat gerakan scroll benar-benar selesai dan terlihat.
Selama fase ini, turunan dapat memilih untuk menggunakan semua atau sebagian dari scroll yang tersisa. Semua yang tersisa akan dikirim kembali untuk melewati fase pasca-scroll.
Terakhir, pada fase pasca-scroll, apa pun yang tidak dikonsumsi oleh node akan dikirim lagi ke ancestor-nya untuk digunakan.
Fase pasca-scroll berfungsi dengan cara yang mirip dengan fase pra-scroll, saat mana pun induk dapat memilih untuk memakai atau tidak.
Demikian pula untuk men-scroll, saat gestur tarik selesai, intent pengguna dapat diterjemahkan menjadi kecepatan yang digunakan untuk mengayunkan (scroll menggunakan animasi) container yang dapat di-scroll. fling juga merupakan bagian dari siklus scroll bertingkat, dan kecepatan yang dihasilkan oleh peristiwa tarik melewati fase yang serupa: pre-fling, konsumsi node, dan post-fling. Perhatikan bahwa animasi mengayunkan jari hanya dikaitkan dengan gestur sentuh dan tidak akan dipicu oleh peristiwa lain, seperti a11y atau scroll hardware.
Berpartisipasi dalam siklus scroll bertingkat
Partisipasi dalam siklus berarti mencegat, memakai, dan melaporkan konsumsi delta di sepanjang hierarki. Compose menyediakan sekumpulan alat untuk memengaruhi cara kerja sistem scroll bertingkat dan cara berinteraksi langsung dengannya, misalnya saat Anda perlu melakukan sesuatu dengan delta scroll sebelum komponen yang dapat di-scroll bahkan mulai men-scroll.
Jika siklus scroll bertingkat adalah sistem yang bertindak pada rantai node, pengubah
nestedScroll
adalah cara untuk menangkap dan menyisipkan ke dalam perubahan ini, serta
memengaruhi data (delta scroll) yang disebarluaskan dalam rantai. Pengubah
ini dapat ditempatkan di mana saja dalam hierarki, dan berkomunikasi dengan
instance pengubah scroll bertingkat ke atas hierarki sehingga dapat berbagi informasi melalui
saluran ini. Elemen penyusun pengubah ini adalah NestedScrollConnection
dan NestedScrollDispatcher
.
NestedScrollConnection
menyediakan cara untuk merespons fase siklus scroll bertingkat dan memengaruhi
sistem scroll bertingkat. Kode ini terdiri dari empat metode callback, masing-masing
mewakili salah satu fase pemakaian: pre/post-scroll dan pre/post-fling:
val nestedScrollConnection = object : NestedScrollConnection { override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset { println("Received onPreScroll callback.") return Offset.Zero } override fun onPostScroll( consumed: Offset, available: Offset, source: NestedScrollSource ): Offset { println("Received onPostScroll callback.") return Offset.Zero } }
Setiap callback juga memberikan informasi tentang delta yang disebarluaskan: delta available
untuk fase tertentu, dan delta consumed
yang digunakan dalam fase sebelumnya. Jika suatu saat Anda ingin berhenti menyebarkan delta ke atas
hierarki, Anda dapat menggunakan koneksi scroll bertingkat untuk melakukannya:
val disabledNestedScrollConnection = remember { object : NestedScrollConnection { override fun onPostScroll( consumed: Offset, available: Offset, source: NestedScrollSource ): Offset { return if (source == NestedScrollSource.SideEffect) { available } else { Offset.Zero } } } }
Semua callback memberikan informasi tentang
jenis
NestedScrollSource
.
NestedScrollDispatcher
melakukan inisialisasi siklus scroll bertingkat. Menggunakan dispatcher dan memanggil metodenya akan memicu siklus. Penampung yang dapat di-scroll memiliki dispatcher bawaan yang mengirim
delta yang diambil selama gestur ke sistem. Karena alasan ini, sebagian besar kasus penggunaan
penyesuaian scroll bertingkat melibatkan penggunaan NestedScrollConnection
, bukan
dispatcher, untuk bereaksi terhadap delta yang sudah ada, bukan mengirim yang baru.
Lihat
NestedScrollDispatcherSample
untuk penggunaan lainnya.
Interop scroll bertingkat
Saat mencoba menyusun bertingkat elemen View
yang dapat di-scroll dalam composable yang dapat di-scroll, atau
sebaliknya, Anda mungkin mengalami masalah. Yang paling terlihat akan
terjadi saat Anda men-scroll turunan dan mencapai batas awal atau akhirnya, serta mengharapkan
induk untuk mengambil alih scroll. Namun, perilaku yang diharapkan ini
mungkin tidak terjadi atau tidak berfungsi seperti yang diharapkan.
Masalah ini adalah hasil dari ekspektasi yang dibuat di composable yang dapat di-scroll.
Composable yang dapat di-scroll memiliki aturan "nested-scroll-by-default", yang berarti
setiap penampung yang dapat di-scroll harus berpartisipasi dalam rantai scroll bertingkat, baik sebagai
induk melalui
NestedScrollConnection
maupun sebagai turunan melalui
NestedScrollDispatcher
.
Turunan kemudian akan mendorong scroll bertingkat untuk induk saat turunan berada di
batas. Sebagai contoh, aturan ini memungkinkan Compose Pager
dan Compose LazyRow
untuk bekerja sama dengan baik. Namun, jika scroll interoperabilitas dilakukan
dengan ViewPager2
atau RecyclerView
, karena scroll ini tidak mengimplementasikan
NestedScrollingParent3
,
scrolling berkelanjutan dari turunan ke induk tidak dapat dilakukan.
Untuk mengaktifkan API interop scroll bertingkat antara elemen View
yang dapat di-scroll dan
composable yang dapat di-scroll, yang ditumpuk di kedua arah, Anda dapat menggunakan API interop
scroll bertingkat untuk mengurangi masalah ini, dalam skenario berikut.
Induk View
yang bekerja sama berisi turunan ComposeView
View
induk yang bekerja sama adalah salah satu yang sudah mengimplementasikan
NestedScrollingParent3
sehingga dapat menerima delta scroll dari composable turunan bertingkat
yang bekerja sama. Dalam hal ini, ComposeView
akan bertindak sebagai turunan dan
perlu (secara tidak langsung) mengimplementasikan
NestedScrollingChild3
.
Salah satu contoh induk yang bekerja sama adalah
androidx.coordinatorlayout.widget.CoordinatorLayout
.
Jika memerlukan interoperabilitas scroll bertingkat antara penampung induk View
yang
dapat di-scroll dan composable turunan yang dapat di-scroll, Anda dapat menggunakan
rememberNestedScrollInteropConnection()
.
rememberNestedScrollInteropConnection()
mengizinkan dan mengingat
NestedScrollConnection
yang memungkinkan interoperabilitas scroll bertingkat antara induk View
yang
mengimplementasikan
NestedScrollingParent3
dan turunan Compose. Ini harus digunakan bersama pengubah
nestedScroll
. Karena scroll bertingkat diaktifkan secara default di sisi Compose, Anda
dapat menggunakan koneksi ini untuk mengaktifkan scroll bertingkat di sisi View
dan menambahkan
logika glue yang diperlukan antara Views
dan composable.
Kasus penggunaan yang sering digunakan adalah menggunakan CoordinatorLayout
, CollapsingToolbarLayout
, dan
composable turunan, yang ditunjukkan dalam contoh ini:
<androidx.coordinatorlayout.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" android:layout_width="match_parent" android:layout_height="match_parent"> <com.google.android.material.appbar.AppBarLayout android:id="@+id/app_bar" android:layout_width="match_parent" android:layout_height="100dp" android:fitsSystemWindows="true"> <com.google.android.material.appbar.CollapsingToolbarLayout android:id="@+id/collapsing_toolbar_layout" android:layout_width="match_parent" android:layout_height="match_parent" android:fitsSystemWindows="true" app:layout_scrollFlags="scroll|exitUntilCollapsed"> <!--...--> </com.google.android.material.appbar.CollapsingToolbarLayout> </com.google.android.material.appbar.AppBarLayout> <androidx.compose.ui.platform.ComposeView android:id="@+id/compose_view" app:layout_behavior="@string/appbar_scrolling_view_behavior" android:layout_width="match_parent" android:layout_height="match_parent"/> </androidx.coordinatorlayout.widget.CoordinatorLayout>
Dalam Aktivitas atau Fragmen, Anda harus menyiapkan composable turunan dan
NestedScrollConnection
yang diperlukan:
open class MainActivity : ComponentActivity() { @OptIn(ExperimentalComposeUiApi::class) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) findViewById<ComposeView>(R.id.compose_view).apply { setContent { val nestedScrollInterop = rememberNestedScrollInteropConnection() // Add the nested scroll connection to your top level @Composable element // using the nestedScroll modifier. LazyColumn(modifier = Modifier.nestedScroll(nestedScrollInterop)) { items(20) { item -> Box( modifier = Modifier .padding(16.dp) .height(56.dp) .fillMaxWidth() .background(Color.Gray), contentAlignment = Alignment.Center ) { Text(item.toString()) } } } } } } }
Composable induk yang berisi AndroidView
turunan
Skenario ini mencakup implementasi API interop scroll bertingkat di
sisi Compose - jika Anda memiliki composable induk yang berisi AndroidView
turunan. AndroidView
akan mengimplementasikan
NestedScrollDispatcher
,
karena berfungsi sebagai turunan dari induk scroll Compose, serta
NestedScrollingParent3
, karena berfungsi sebagai induk untuk turunan scrolling View
. Induk Compose
akan dapat menerima delta scroll bertingkat dari View
turunan bertingkat
yang dapat di-scroll.
Contoh berikut menunjukkan cara mencapai interop scroll bertingkat dalam skenario ini, beserta toolbar Compose yang diciutkan:
@Composable
private fun NestedScrollInteropComposeParentWithAndroidChildExample() {
val toolbarHeightPx = with(LocalDensity.current) { ToolbarHeight.roundToPx().toFloat() }
val toolbarOffsetHeightPx = remember { mutableStateOf(0f) }
// Sets up the nested scroll connection between the Box composable parent
// and the child AndroidView containing the RecyclerView
val nestedScrollConnection = remember {
object : NestedScrollConnection {
override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
// Updates the toolbar offset based on the scroll to enable
// collapsible behaviour
val delta = available.y
val newOffset = toolbarOffsetHeightPx.value + delta
toolbarOffsetHeightPx.value = newOffset.coerceIn(-toolbarHeightPx, 0f)
return Offset.Zero
}
}
}
Box(
Modifier
.fillMaxSize()
.nestedScroll(nestedScrollConnection)
) {
TopAppBar(
modifier = Modifier
.height(ToolbarHeight)
.offset { IntOffset(x = 0, y = toolbarOffsetHeightPx.value.roundToInt()) }
)
AndroidView(
{ context ->
LayoutInflater.from(context)
.inflate(R.layout.view_in_compose_nested_scroll_interop, null).apply {
with(findViewById<RecyclerView>(R.id.main_list)) {
layoutManager = LinearLayoutManager(context, VERTICAL, false)
adapter = NestedScrollInteropAdapter()
}
}.also {
// Nested scrolling interop is enabled when
// nested scroll is enabled for the root View
ViewCompat.setNestedScrollingEnabled(it, true)
}
},
// ...
)
}
}
private class NestedScrollInteropAdapter :
Adapter<NestedScrollInteropAdapter.NestedScrollInteropViewHolder>() {
val items = (1..10).map { it.toString() }
override fun onCreateViewHolder(
parent: ViewGroup,
viewType: Int
): NestedScrollInteropViewHolder {
return NestedScrollInteropViewHolder(
LayoutInflater.from(parent.context)
.inflate(R.layout.list_item, parent, false)
)
}
override fun onBindViewHolder(holder: NestedScrollInteropViewHolder, position: Int) {
// ...
}
class NestedScrollInteropViewHolder(view: View) : ViewHolder(view) {
fun bind(item: String) {
// ...
}
}
// ...
}
Contoh ini menunjukkan cara menggunakan API dengan pengubah scrollable
:
@Composable
fun ViewInComposeNestedScrollInteropExample() {
Box(
Modifier
.fillMaxSize()
.scrollable(rememberScrollableState {
// View component deltas should be reflected in Compose
// components that participate in nested scrolling
it
}, Orientation.Vertical)
) {
AndroidView(
{ context ->
LayoutInflater.from(context)
.inflate(android.R.layout.list_item, null)
.apply {
// Nested scrolling interop is enabled when
// nested scroll is enabled for the root View
ViewCompat.setNestedScrollingEnabled(this, true)
}
}
)
}
}
Terakhir, contoh ini menunjukkan cara API interop scroll bertingkat digunakan dengan
BottomSheetDialogFragment
untuk mencapai perilaku tarik lalu tutup yang sukses:
class BottomSheetFragment : BottomSheetDialogFragment() {
override fun onCreateView(
inflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?
): View {
val rootView: View = inflater.inflate(R.layout.fragment_bottom_sheet, container, false)
rootView.findViewById<ComposeView>(R.id.compose_view).apply {
setContent {
val nestedScrollInterop = rememberNestedScrollInteropConnection()
LazyColumn(
Modifier
.nestedScroll(nestedScrollInterop)
.fillMaxSize()
) {
item {
Text(text = "Bottom sheet title")
}
items(10) {
Text(
text = "List item number $it",
modifier = Modifier.fillMaxWidth()
)
}
}
}
return rootView
}
}
}
Perhatikan bahwa
rememberNestedScrollInteropConnection()
akan menginstal
NestedScrollConnection
di elemen tempat Anda menambahkannya. NestedScrollConnection
bertanggung jawab untuk
mengirim delta dari level Compose ke level View
. Hal ini memungkinkan
elemen berpartisipasi dalam scroll bertingkat, tetapi tidak mengaktifkan
scroll elemen secara otomatis. Untuk composable yang tidak dapat di-scroll
secara otomatis, seperti Box
atau Column
, delta scroll pada komponen tersebut tidak akan
disebarkan dalam sistem scroll bertingkat dan delta tidak akan menjangkau
NestedScrollConnection
yang disediakan oleh rememberNestedScrollInteropConnection()
,
sehingga delta tersebut tidak akan menjangkau komponen View
induk. Untuk mengatasi hal ini,
pastikan Anda juga menetapkan pengubah yang dapat di-scroll ke jenis composable
bertingkat ini. Anda dapat melihat bagian sebelumnya tentang Scrolling bertingkat untuk informasi lebih mendetail.
View
induk yang tidak bekerja sama berisi turunan ComposeView
View yang tidak bekerja sama adalah View yang tidak mengimplementasikan antarmuka
NestedScrolling
yang diperlukan di sisi View
. Perlu diperhatikan bahwa ini berarti
interoperabilitas scroll bertingkat dengan Views
ini tidak langsung berfungsi
dari awal. Views
yang tidak bekerja sama adalah RecyclerView
dan ViewPager2
.
Direkomendasikan untuk Anda
- Catatan: teks link ditampilkan saat JavaScript nonaktif
- Memahami gestur
- Memigrasikan
CoordinatorLayout
ke Compose - Menggunakan View di Compose