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
CoordinatorLayoutke Compose - Menggunakan View di Compose