بسیاری از برنامهها باید مجموعههایی از موارد را نمایش دهند. این سند توضیح میدهد که چگونه میتوانید این کار را بهطور مؤثر در Jetpack Compose انجام دهید.
اگر میدانید که مورد استفاده شما به پیمایش نیاز ندارد، میتوانید از Column یا Row ساده (بسته به جهت) استفاده کنید و محتوای هر مورد را با تکرار روی فهرست به روش زیر منتشر کنید:
@Composable fun MessageList(messages: List<Message>) { Column { messages.forEach { message -> MessageRow(message) } } }
میتوانیم بااستفاده از اصلاحکننده verticalScroll()، Column را پیمایشپذیر کنیم.
فهرستهای تنبل
اگر لازم است تعداد زیادی از موارد (یا فهرستی با طول نامشخص) را نمایش دهید،
استفاده از چیدمانی مانند Column میتواند باعث مشکلات عملکردی شود، زیرا همه موارد، چه قابلمشاهده باشند و چه نباشند، ترکیب و چیده خواهند شد.
Compose مجموعهای از مؤلفهها را ارائه میدهد که فقط مواردی را که در نمای مؤلفه قابلمشاهده هستند، ترکیب و چیدمان میکنند. این مؤلفهها شامل
LazyColumn
و
LazyRow است.
همانطور که از نامشان پیداست، تفاوت بین
LazyColumn
و
LazyRow
در جهتگیریای است که موارد را میچینند و پیمایش میکنند. LazyColumn
فهرستی با پیمایش عمودی تولید میکند و LazyRow فهرستی با پیمایش افقی تولید میکند.
مؤلفههای Lazy با اکثر چیدمانها در Compose متفاوت هستند. بهجای
پذیرفتن پارامتر بلوک محتوای @Composable، که به برنامهها اجازه میدهد مستقیماً
ترکیبپذیرها را منتشر کنند، مؤلفههای Lazy یک بلوک LazyListScope.() ارائه میدهند. این
LazyListScope
بلوک DSL ارائه میدهد که به برنامهها اجازه میدهد محتوای مورد را توصیف کنند. سپس مؤلفه Lazy مسئول افزودن محتوای هر مورد است، همانطور که
توسط چیدمان و موقعیت پیمایش لازم است.
LazyListScope DSL
DSL مربوط به LazyListScope تعدادی تابع برای توصیف موارد
در چیدمان ارائه میدهد. در ابتداییترین حالت،
item()
یک مورد اضافه میکند، و
items(Int)
چند مورد اضافه میکند:
LazyColumn { // Add a single item item { Text(text = "First item") } // Add 5 items items(5) { index -> Text(text = "Item: $index") } // Add another single item item { Text(text = "Last item") } }
همچنین تعدادی تابع افزونه وجود دارد که به شما امکان میدهد مجموعهای از موارد را اضافه کنید، مانند List. این افزونهها به ما امکان میدهند بهراحتی
نمونه Column بالا را انتقال دهیم:
/** * import androidx.compose.foundation.lazy.items */ LazyColumn { items(messages) { message -> MessageRow(message) } }
همچنین نوعی از تابع افزونه
items()
بهنام
itemsIndexed()
وجود دارد که نمایه را ارائه میدهد. برای جزئیات بیشتر، لطفاً به مرجع
LazyListScope
مراجعه کنید.
شبکههای تنبل
ترکیبپذیرهای
LazyVerticalGrid
و
LazyHorizontalGrid
از نمایش موارد در جدول پشتیبانی میکنند. یک شبکه عمودی Lazy
موارد خود را در یک محفظه قابل پیمایش عمودی نمایش میدهد که در چندین ستون گسترده شده است، درحالیکه شبکههای افقی Lazy همان رفتار را در محور افقی خواهند داشت.
شبکهها همان قابلیتهای API قدرتمند فهرستها را دارند و همچنین از DSL بسیار مشابهی برای توصیف محتوا استفاده میکنند -
LazyGridScope.()
پارامتر columns در
LazyVerticalGrid
و پارامتر rows در
LazyHorizontalGrid
نحوه تشکیل ستونها یا ردیفها از سلولها را کنترل میکنند. مثال زیر
موارد را در جدولی نمایش میدهد و از
GridCells.Adaptive
استفاده میکند تا عرض هر ستون را حداقل 128.dp تنظیم کند:
LazyVerticalGrid( columns = GridCells.Adaptive(minSize = 128.dp) ) { items(photos) { photo -> PhotoItem(photo) } }
LazyVerticalGrid به شما امکان میدهد عرضی برای موارد مشخص کنید، و سپس جدول
تا جایی که ممکن است ستونها را در خود جای میدهد. هر عرض باقیماندهای بهطور مساوی بین ستونها توزیع میشود،
بعداز اینکه تعداد ستونها محاسبه شد.
این روش تطبیقی برای اندازهگذاری بهویژه برای نمایش مجموعههای موارد
در اندازههای مختلف صفحهنمایش مفید است.
اگر تعداد دقیق ستونهایی را که باید استفاده شود میدانید، میتوانید بهجای آن یک
نمونه از
GridCells.Fixed
حاوی تعداد ستونهای موردنیاز ارائه دهید.
اگر طراحی شما فقط برای موارد خاصی به ابعاد غیراستاندارد نیاز دارد،
میتوانید از پشتیبانی شبکه برای ارائه گسترههای ستون سفارشی برای موارد استفاده کنید.
با پارامتر span از روشهای
LazyGridScope DSL
item و items، گستره ستون را مشخص کنید.
maxLineSpan،
یکی از مقادیر دامنه گستردگی، بهویژه زمانی مفید است که از
اندازه تطبیقی استفاده میکنید، زیرا تعداد ستونها ثابت نیست.
این مثال نحوه ارائه گستره کامل ردیف را نشان میدهد:
LazyVerticalGrid( columns = GridCells.Adaptive(minSize = 30.dp) ) { item(span = { // LazyGridItemSpanScope: // maxLineSpan GridItemSpan(maxLineSpan) }) { CategoryCard("Fruits") } // ... }
شبکه پلکانی تنبل
LazyVerticalStaggeredGrid
و
LazyHorizontalStaggeredGrid
ساختنیهایی هستند که به شما امکان میدهند یک شبکه نامنظم از موارد با بارگیری کُند ایجاد کنید.
شبکه نامنظم عمودی تنبل موارد را در محفظه پیمایشی عمودی نمایش میدهد که در چندین ستون گسترده شده است و به موارد تکی اجازه میدهد ارتفاعهای متفاوتی داشته باشند. شبکههای افقی تنبل در محور افقی با مواردی با عرضهای مختلف رفتار یکسانی دارند.
تکهکد زیر نمونهای ساده از استفاده از LazyVerticalStaggeredGrid
با عرض 200.dp برای هر مورد است:
LazyVerticalStaggeredGrid( columns = StaggeredGridCells.Adaptive(200.dp), verticalItemSpacing = 4.dp, horizontalArrangement = Arrangement.spacedBy(4.dp), content = { items(randomSizedPhotos) { photo -> AsyncImage( model = photo, contentScale = ContentScale.Crop, contentDescription = null, modifier = Modifier .fillMaxWidth() .wrapContentHeight() ) } }, modifier = Modifier.fillMaxSize() )
برای تنظیم تعداد ثابتی از ستونها، میتوانید از
StaggeredGridCells.Fixed(columns) بهجای StaggeredGridCells.Adaptive استفاده کنید.
این کار عرض دردسترس را بر تعداد ستونها (یا ردیفها برای توری افقی) تقسیم میکند و هر مورد آن عرض (یا ارتفاع برای توری افقی) را اشغال میکند:
LazyVerticalStaggeredGrid( columns = StaggeredGridCells.Fixed(3), verticalItemSpacing = 4.dp, horizontalArrangement = Arrangement.spacedBy(4.dp), content = { items(randomSizedPhotos) { photo -> AsyncImage( model = photo, contentScale = ContentScale.Crop, contentDescription = null, modifier = Modifier .fillMaxWidth() .wrapContentHeight() ) } }, modifier = Modifier.fillMaxSize() )
بهبود عملکرد پیمایش با LazyLayoutCacheWindow
LazyLayoutCacheWindow یک API است که برای کمک به بهبود
عملکرد پیمایش در فهرستها، شبکهها، و شبکههای نامنظم طراحی شده است. در CacheWindow، میتوانید فضای مجازیای تعریف کنید که در آن موارد بتوانند درطول رویدادهای پیمایش پیشواکشی شوند (پنجره جلو) یا زنده نگه داشته شوند (پنجره پشت). این یعنی ترکیببندی و اندازهگیری مورد، حافظه نهان داخلی را آماده میکند — وقتی این موارد واقعاً موردنیاز باشند (وقتی نمایان میشوند)، نمایش آنها زمان بسیار کمتری نسبت به زمانی که از ابتدا ساخته میشوند میبرد.
همه مجموعههای تنبل از CacheWindow بهعنوان استراتژی پیشواکشی پیشفرض استفاده میکنند. پنجره پیشفرض، فاصله پیشواکشی جلوتر را بین ۱۰٪ و ۵۰٪ از نمای دید محدود میکند. این گزینه پنجره پشت را روی ۰ پیکسل تنظیم میکند و ذخیره موقت غیرپیمایشی را غیرفعال میکند.
پیکربندی پنجره
میتوانید پنجره حافظه پنهان را بااستفاده از کسر نمای هدف یا فاصلههای ثابت در
Dp پیکربندی کنید:
// Fraction-based cache window: prefetch 50% of viewport ahead, keep 20% behind LazyColumn( cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f) ) { items(itemsList) { item -> Text("Item $item") } } // Dp-based cache window: prefetch 150.dp ahead, keep 50.dp behind LazyVerticalGrid( columns = GridCells.Fixed(3), cacheWindow = LazyLayoutCacheWindow( ahead = 150.dp, behind = 50.dp, isNonScrollCachingEnabled = true ) ) { items(itemsList) { item -> Text("Item $item") } }
پنجره حافظه پنهان دو منطقه متمایز را نسبت به جهت پیمایش مدیریت میکند:
- پنجره پیشرو: چارچوب، موارد آینده را قبلاز ورود به نمای دیداری پیشساخت و پیشاندازهگیری میکند. این تنظیم بهطور پیشفرض روی
0dpیا0fاست. - پشت پنجره: چارچوب موارد اخیراً پیمایششده را بدون دور انداختن آنها حفظ میکند. وقتی کاربران جهت پیمایش را برعکس میکنند، موارد حفظشده
بلافاصله بدون ترکیب مجدد یا اندازهگیری مجدد نمایش داده میشوند. این
بهطور پیشفرض روی
0dpیا0fاست.
علاوهبراین، وقتی isNonScrollCachingEnabled = true (مقدار پیشفرض) را تنظیم میکنید، چیدمان در دورههای غیرفعال خارج از پیمایشهای کاربر فعال، پنجره پیشرو را پر میکند. این راهاندازها شامل گذر چیدمان اولیه، بهروزرسانیهای مجموعه داده، و تغییر ترتیب موارد است. وقتی روی false تنظیم شود، ذخیره در حافظه نهان فقط درطول
رویدادهای پیمایش رخ میدهد.
سفارشی CacheWindow
وقتی فاصلههای ثابت یا کسرهای نمای دید با الگوهای چیدمان شما مطابقت ندارند،
میتوانید میانای LazyLayoutCacheWindow را مستقیماً پیادهسازی کنید:
interface LazyLayoutCacheWindow { fun Density.calculateAheadWindow(viewport: Int): Int = 0 fun Density.calculateBehindWindow(viewport: Int): Int = 0 val isNonScrollCachingEnabled: Boolean get() = false }
روشهای محاسبه را برای برگرداندن اندازه پنجره ترجیحی برحسب پیکسل برای اندازه نمای هدف مشخص پیادهسازی کنید:
class ScaledCacheWindow( val someLayoutState: LayoutState ) : LazyLayoutCacheWindow { override fun Density.calculateAheadWindow(viewport: Int): Int { return someLayoutState.specialDynamicCalculation().coerceAtMost(viewport * 5) } override fun equals(other: Any?): Boolean { if (this === other) return true if (other !is ScaledCacheWindow) return false return someLayoutState == other.someLayoutState } override fun hashCode(): Int { return someLayoutState.hashCode() } } @Composable fun ScaledCacheWindowSample() { val state = rememberLazyListState() val newCacheWindow = remember { ScaledCacheWindow(state) } LazyColumn( state = state, cacheWindow = newCacheWindow, ) { items(100) { index -> Text( text = "Item #$index", modifier = Modifier .fillMaxWidth() .padding(16.dp), ) } } }
راهنمای انتقال
میاناهای برنامهسازی کاربردی پیکربندی پیشواکشی اولیه (PrefetchStrategy) و اولین
نسخه LazyLayoutCacheWindow اجازه میدادند پیکربندی در
وضعیتها انجام شود، اما این عملکرد اکنون منسوخ شده است. این بخش نحوه انتقال از میاناهای برنامهسازی کاربردی و پارامترهای منسوخ زیر را شرح میدهد:
- پارامترهای
cacheWindowحالتمحور درrememberLazyListStateوrememberLazyGridState. LazyListPrefetchStrategyوLazyGridPrefetchStrategyباLazyLayoutCacheWindow.
گزینه ۱: انتقال cacheWindow متغیر مستقل
برای انتقال به میاناهای برنامهسازی کاربردی توصیهشده، آرگومانهای cacheWindow را از
rememberLazyListState و rememberLazyGridState منتقل کنید تا از آرگومان cacheWindow
در LazyColumn، LazyRow، LazyVerticalGrid، و
LazyHorizontalGrid استفاده کنید. LazyVerticalStaggeredGrid و
LazyHorizontalStaggeredGrid ازقبل الگوی جدید را در ترکیبپذیر چیدمان
پیادهسازی کردهاند.
// Before (Experimental in Compose 1.9 to 1.12, now Deprecated) val state = rememberLazyListState( cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f) ) LazyColumn(state = state) { items(itemsList) { item -> Text("Item $item") } }
// Now in Compose 1.13 (Stable) val state = rememberLazyListState() LazyColumn( state = state, cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f) ) { items(itemsList) { item -> Text("Item $item") } }
گزینه ۲: جایگزین کردن LazyListPrefetchStrategy و LazyGridPrefetchStrategy
موارد استفاده از میاناهای برنامهسازی کاربردی منسوخشده LazyListPrefetchStrategy و
LazyGridPrefetchStrategy را با LazyLayoutCacheWindow جایگزین کنید. ازنظر داخلی، همه
رفتارهای پیشواکشی اکنون به cacheWindow متکی است. این تغییر رفتار واکشی پیشاپیش را در سناریوهای زیر تغییر میدهد:
- موارد کوچک: وقتی موارد کمتر از ۱۰٪ از نمای دید را اشغال میکنند، Compose چند مورد را ازقبل واکشی میکند. این کار باعث کاهش لرزش پیمایش درطول حرکتهای سریع میشود.
- موارد بزرگ: وقتی موارد تکی بیشاز ۵۰٪ از نمای دید را اشغال میکنند، پنجره محدودشده نمیتواند کل مورد بعدی را پوشش دهد. اگر موارد بلندی دارید، مانند فیدهای رسانه یا رشتههای پیامرسانی، ممکن است محرکهای پیشواکشی دیرهنگام را مشاهده کنید و باید پنجره پیشرو را تنظیم کنید.
- اگر استراتژی سفارشی شما به زمانبندی موردبهمورد متکی بود، منطق را به
LazyLayoutCacheWindow.calculateAheadWindowمنتقل کنید. برای تکرار رفتار پیشواکشی مشابهی از ترکیببندی و اندازهگیری یک مورد جلوتر در جهت پیمایش، یک پنجره سفارشی براساس سنجههای مورد قابلمشاهده پیادهسازی کنید. توجه داشته باشید که اگرچه این دقیقاً همان رفتار نیست، اما نزدیکترین رفتاری است که میتوانید هنگام استفاده از پیشواکشی مبتنی بر پنجره داشته باشید:
val state = rememberLazyListState() val legacyCacheWindow = remember(state) { object : LazyLayoutCacheWindow { override fun Density.calculateAheadWindow(viewport: Int): Int { val visibleItems = state.layoutInfo.visibleItemsInfo if (visibleItems.isEmpty()) return 0 val averageItemHeight = visibleItems.sumOf { it.size } / visibleItems.size return averageItemHeight } } } LazyColumn( state = state, cacheWindow = legacyCacheWindow ) { items(itemsList) { item -> Text("Item $item") } }
حاشیه داخلی محتوا
گاهی اوقات لازم است در اطراف لبههای محتوا لایه اضافه کنید. مؤلفههای تنبل به شما امکان میدهند تا برای پشتیبانی از این مورد، مقداری
PaddingValues
به پارامتر contentPadding ارسال کنید:
LazyColumn( contentPadding = PaddingValues(horizontal = 16.dp, vertical = 8.dp), ) { // ... }
در این مثال، 16.dp حاشیه داخلی به لبههای افقی (چپ و راست) و سپس 8.dp به بالا و پایین محتوا اضافه میکنیم.
لطفاً توجه داشته باشید که این لایه به محتوا اعمال میشود، نه به خود
LazyColumn. در مثال بالا، مورد اول 8.dp
حاشیه داخلی به بالای خود اضافه میکند، مورد آخر 8.dp به پایین خود اضافه میکند، و همه موارد
16.dp حاشیه داخلی در سمت چپ و راست خواهند داشت.
بهعنوان مثالی دیگر، میتوانید PaddingValues مربوط به Scaffold را به
contentPadding مربوط به LazyColumn منتقل کنید. راهنمای
لبهبهلبه را ببینید.
فاصلهگذاری محتوا
برای افزودن فاصله بین موارد، میتوانید از
Arrangement.spacedBy() استفاده کنید.
مثال زیر 4.dp فاصله بین هر مورد اضافه میکند:
LazyColumn( verticalArrangement = Arrangement.spacedBy(4.dp), ) { // ... }
بهطور مشابه برای LazyRow:
LazyRow( horizontalArrangement = Arrangement.spacedBy(4.dp), ) { // ... }
اما شبکهها هم آرایش عمودی و هم افقی را میپذیرند:
LazyVerticalGrid( columns = GridCells.Fixed(2), verticalArrangement = Arrangement.spacedBy(16.dp), horizontalArrangement = Arrangement.spacedBy(16.dp) ) { items(photos) { item -> PhotoItem(item) } }
کلیدهای مورد
بهطور پیشفرض، وضعیت هر مورد براساس موقعیت آن مورد در فهرست یا جدول کلیدگذاری میشود. اما اگر مجموعه داده تغییر کند، این کار میتواند مشکلاتی ایجاد کند، زیرا
مواردی که موقعیتشان تغییر میکند، هرگونه حالت بهخاطرسپردهشده را بهطور مؤثر ازدست میدهند. اگر
سناریوی LazyRow را در LazyColumn تصور کنید، اگر ردیف جایگاه مورد را تغییر دهد،
کاربر جایگاه پیمایش خود را در ردیف ازدست میدهد.
برای مقابله با این مشکل، میتوانید کلیدی پایدار و یکتا برای هر مورد ارائه دهید و
بلوکی برای پارامتر key فراهم کنید. ارائه کلید پایدار باعث میشود وضعیت مورد در سراسر تغییرات مجموعه داده سازگار باشد:
LazyColumn { items( items = messages, key = { message -> // Return a stable + unique key for the item message.id } ) { message -> MessageRow(message) } }
با ارائه کلیدها، به Compose کمک میکنید تا ترتیبهای مجدد را بهدرستی مدیریت کند. برای مثال، اگر مورد شما حاوی وضعیت بهخاطرسپردهشده باشد، تنظیم کلیدها به Compose اجازه میدهد این وضعیت را همراه با مورد، هنگام تغییر موقعیت آن، جابهجا کند.
LazyColumn { items(books, key = { it.id }) { val rememberedValue = remember { Random.nextInt() } } }
اما یک محدودیت درباره نوع کلیدهای موردی که میتوانید استفاده کنید وجود دارد.
نوع کلید باید توسط
Bundle، سازوکار Android برای حفظ
وضعیتها هنگام بازآفرینی «فعالیت»، پشتیبانی شود. Bundle از انواع دادهای مانند دادههای اولیه،
انواع شمارشی، یا Parcelable پشتیبانی میکند.
LazyColumn { items(books, key = { // primitives, enums, Parcelable, etc. }) { // ... } }
کلید باید توسط Bundle پشتیبانی شود تا rememberSaveable داخل
مورد قابلساخت بتواند هنگام بازسازی «فعالیت» یا حتی
وقتی از این مورد دور میشوید و دوباره به آن برمیگردید، بازیابی شود.
LazyColumn { items(books, key = { it.id }) { val rememberedValue = rememberSaveable { Random.nextInt() } } }
پویانماییهای مورد
اگر از ابزاره RecyclerView استفاده کرده باشید، میدانید که تغییرات مورد را بهطور خودکار پویانمایی میکند.
چیدمانهای تنبل عملکرد یکسانی برای مرتبسازی مجدد موارد ارائه میدهند.
این میانای برنامهسازی کاربردی ساده است - فقط باید اصلاحکننده
animateItem
را برای محتوای مورد تنظیم کنید:
LazyColumn { // It is important to provide a key to each item to ensure animateItem() works as expected. items(books, key = { it.id }) { Row(Modifier.animateItem()) { // ... } } }
حتی میتوانید درصورت نیاز، مشخصات پویانمایی سفارشی ارائه دهید:
LazyColumn { items(books, key = { it.id }) { Row( Modifier.animateItem( fadeInSpec = tween(durationMillis = 250), fadeOutSpec = tween(durationMillis = 100), placementSpec = spring(stiffness = Spring.StiffnessLow, dampingRatio = Spring.DampingRatioMediumBouncy) ) ) { // ... } } }
مطمئن شوید که کلیدهایی برای مواردتان ارائه میدهید تا امکان پیدا کردن موقعیت جدید برای عنصر منتقلشده وجود داشته باشد.
مثال: پویانمایی کردن موارد در فهرستهای تنبل
با Compose، میتوانید تغییرات موارد را در فهرستهای تنبل پویانمایی کنید. وقتی از قطعههای زیر باهم استفاده شود، پویانماییهایی را هنگام افزودن، برداشتن، و بازآرایی موارد فهرست تنبل پیادهسازی میکنند.
این قطعه کد فهرستی از رشتهها را با گذارهای پویانماییشده هنگام اضافه شدن، برداشته شدن، یا تغییر ترتیب موارد نمایش میدهد:
@Composable fun ListAnimatedItems( items: List<String>, modifier: Modifier = Modifier ) { LazyColumn(modifier) { // Use a unique key per item, so that animations work as expected. items(items, key = { it }) { ListItem( headlineContent = { Text(it) }, modifier = Modifier .animateItem( // Optionally add custom animation specs ) .fillParentMaxWidth() .padding(horizontal = 8.dp, vertical = 0.dp), ) } } }
نکات کلیدی درباره کد
ListAnimatedItemsفهرستی از رشتهها را درLazyColumnبا انتقالهای پویانماییشده هنگام اصلاح موارد نمایش میدهد.- تابع
itemsکلید یکتایی را به هر مورد در فهرست اختصاص میدهد. Compose از کلیدها برای ردیابی موارد و شناسایی تغییرات در موقعیت آنها استفاده میکند. ListItemطرحبندی هر مورد فهرست را تعریف میکند. پارامترheadlineContentرا میگیرد که محتوای اصلی مورد را تعریف میکند.- اصلاحکننده
animateItemپویانماییهای پیشفرض را برای افزودن، برداشتن، و جابهجا کردن موارد اعمال میکند.
قطعه کد زیر صفحهای را نشان میدهد که کنترلهایی برای افزودن و برداشتن موارد و همچنین مرتبسازی فهرست ازپیش تعریفشده را دربرمیگیرد:
@Composable private fun ListAnimatedItemsExample( data: List<String>, modifier: Modifier = Modifier, onAddItem: () -> Unit = {}, onRemoveItem: () -> Unit = {}, resetOrder: () -> Unit = {}, onSortAlphabetically: () -> Unit = {}, onSortByLength: () -> Unit = {}, ) { val canAddItem = data.size < 10 val canRemoveItem = data.isNotEmpty() Scaffold(modifier) { paddingValues -> Column( modifier = Modifier .padding(paddingValues) .fillMaxSize() ) { // Buttons that change the value of displayedItems. AddRemoveButtons(canAddItem, canRemoveItem, onAddItem, onRemoveItem) OrderButtons(resetOrder, onSortAlphabetically, onSortByLength) // List that displays the values of displayedItems. ListAnimatedItems(data) } } }
نکات کلیدی درباره کد
ListAnimatedItemsExampleصفحهای را ارائه میدهد که شامل کنترلهایی برای افزودن، برداشتن، و مرتبسازی موارد است.-
onAddItemوonRemoveItemعبارتهای لامبدا هستند که بهAddRemoveButtonsارسال میشوند تا موارد را به فهرست اضافه کنند یا از آن بردارند. -
resetOrder،onSortAlphabetically، وonSortByLengthعبارتهای لامبدا هستند که بهOrderButtonsارسال میشوند تا ترتیب موارد را در فهرست تغییر دهند.
-
AddRemoveButtonsدکمههای «افزودن» و «برداشتن» را نمایش میدهد. این دکمهها را فعال/غیرفعال میکند و کلیکهای دکمه را مدیریت میکند.OrderButtonsدکمههای تغییر ترتیب فهرست را نمایش میدهد. این تابع توابع لامبدا را برای بازنشانی ترتیب و مرتبسازی فهرست براساس طول یا حروف الفبا دریافت میکند.-
ListAnimatedItemsListAnimatedItemscomposable را فراخوانی میکند و فهرستdataرا برای نمایش فهرست پویانماییشده رشتهها ارسال میکند. dataدر جای دیگری تعریف شده است.
این قطعه کد یک واسط کاربر با دکمههای افزودن مورد و حذف مورد ایجاد میکند:
@Composable private fun AddRemoveButtons( canAddItem: Boolean, canRemoveItem: Boolean, onAddItem: () -> Unit, onRemoveItem: () -> Unit ) { Row( modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.Center ) { Button(enabled = canAddItem, onClick = onAddItem) { Text("Add Item") } Spacer(modifier = Modifier.padding(25.dp)) Button(enabled = canRemoveItem, onClick = onRemoveItem) { Text("Delete Item") } } }
نکات کلیدی درباره کد
AddRemoveButtonsردیفی از دکمهها را برای انجام عملیات افزودن و برداشتن در فهرست نمایش میدهد.- پارامترهای
canAddItemوcanRemoveItemوضعیت فعال بودن دکمهها را کنترل میکنند. اگرcanAddItemیاcanRemoveItemنادرست باشد، دکمه مربوطه غیرفعال میشود. - پارامترهای
onAddItemوonRemoveItemعبارتهای لامبدایی هستند که وقتی کاربر روی دکمه مربوطه کلیک میکند اجرا میشوند.
درنهایت، این قطعه کد سه دکمه برای مرتبسازی فهرست نمایش میدهد (بازنشانی، الفبایی، و طول):
@Composable private fun OrderButtons( resetOrder: () -> Unit, orderAlphabetically: () -> Unit, orderByLength: () -> Unit ) { Row( modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.Center ) { var selectedIndex by remember { mutableIntStateOf(0) } val options = listOf("Reset", "Alphabetical", "Length") SingleChoiceSegmentedButtonRow { options.forEachIndexed { index, label -> SegmentedButton( shape = SegmentedButtonDefaults.itemShape( index = index, count = options.size ), onClick = { Log.d("AnimatedOrderedList", "selectedIndex: $selectedIndex") selectedIndex = index when (options[selectedIndex]) { "Reset" -> resetOrder() "Alphabetical" -> orderAlphabetically() "Length" -> orderByLength() } }, selected = index == selectedIndex ) { Text(label) } } } } }
نکات کلیدی درباره کد
OrderButtonsSingleChoiceSegmentedButtonRowرا نمایش میدهد تا به کاربران اجازه دهد روش مرتبسازی را در فهرست انتخاب کنند یا ترتیب فهرست را بازنشانی کنند. مؤلفهSegmentedButtonبه شما امکان میدهد یک گزینه را از فهرست گزینهها انتخاب کنید.-
resetOrder،orderAlphabetically، وorderByLengthتوابع لامبدا هستند که وقتی دکمه مربوطه انتخاب میشود اجرا میشوند. - متغیر حالت
selectedIndexگزینه انتخابشده را ردیابی میکند.
نتیجه
این ویدیو نتیجه قطعههای قبلی را هنگام مرتبسازی مجدد موارد نشان میدهد:
سرصفحههای چسبان
الگوی «سرصفحه چسبان» هنگام نمایش فهرستهای دادههای گروهبندیشده مفید است. در زیر میتوانید نمونهای از «فهرست مخاطبین» را ببینید که براساس حرف اول نام هر مخاطب گروهبندی شده است:

برای دستیابی به سرایند چسبان با LazyColumn، میتوانید از
stickyHeader() استفاده کنید
تابع، ارائه محتوای سرصفحه:
@Composable fun ListWithHeader(items: List<Item>) { LazyColumn { stickyHeader { Header() } items(items) { item -> ItemRow(item) } } }
برای دستیابی به فهرستی با چند سرایند، مانند مثال «فهرست مخاطبین» در بالا، میتوانید این کار را انجام دهید:
// This ideally would be done in the ViewModel val grouped = contacts.groupBy { it.firstName[0] } @Composable fun ContactsList(grouped: Map<Char, List<Contact>>) { LazyColumn { grouped.forEach { (initial, contactsForInitial) -> stickyHeader { CharacterHeader(initial) } items(contactsForInitial) { contact -> ContactListItem(contact) } } } }
واکنش به موقعیت پیمایش
بسیاری از برنامهها باید به تغییرات موقعیت پیمایش و چیدمان موارد واکنش نشان دهند و آنها را رصد کنند.
مؤلفههای Lazy با بالا بردن
LazyListState از این مورد استفاده پشتیبانی میکنند:
@Composable fun MessageList(messages: List<Message>) { // Remember our own LazyListState val listState = rememberLazyListState() // Provide it to LazyColumn LazyColumn(state = listState) { // ... } }
برای موارد استفاده ساده، برنامهها معمولاً فقط باید اطلاعات مربوط به اولین مورد قابلمشاهده را بدانند. برای این
LazyListState
ویژگیهای
firstVisibleItemIndex
و
firstVisibleItemScrollOffset
را ارائه میدهد.
اگر از مثال نشان دادن و پنهان کردن دکمه براساس اینکه کاربر از اولین مورد رد شده است یا نه استفاده کنیم:
@Composable fun MessageList(messages: List<Message>) { Box { val listState = rememberLazyListState() LazyColumn(state = listState) { // ... } // Show the button if the first visible item is past // the first item. We use a remembered derived state to // minimize unnecessary compositions val showButton by remember { derivedStateOf { listState.firstVisibleItemIndex > 0 } } AnimatedVisibility(visible = showButton) { ScrollToTopButton() } } }
خواندن مستقیم وضعیت در ترکیببندی زمانی مفید است که لازم باشد سایر ترکیبشدنیهای میانای کاربر را بهروز کنید، اما سناریوهایی نیز وجود دارد که در آنها نیازی به مدیریت رویداد در همان ترکیببندی نیست. نمونه رایج این مورد ارسال رویداد تجزیهوتحلیل پساز پیمایش کاربر از نقطهای خاص است. برای مدیریت کارآمد این موضوع، میتوانیم از snapshotFlow() استفاده کنیم:
val listState = rememberLazyListState() LazyColumn(state = listState) { // ... } LaunchedEffect(listState) { snapshotFlow { listState.firstVisibleItemIndex } .map { index -> index > 0 } .distinctUntilChanged() .filter { it } .collect { MyAnalyticsService.sendScrolledPastFirstItemEvent() } }
LazyListState همچنین اطلاعاتی درباره همه مواردی که درحالحاضر نمایش داده میشوند و حدود آنها در صفحه، ازطریق ویژگی layoutInfo ارائه میدهد. برای اطلاعات بیشتر، کلاس
LazyListLayoutInfo
را ببینید.
کنترل کردن موقعیت پیمایش
علاوهبر واکنش به موقعیت پیمایش، برای برنامهها مفید است که بتوانند
موقعیت پیمایش را نیز کنترل کنند.
LazyListState
این را ازطریق تابع scrollToItem()
پشتیبانی میکند که موقعیت پیمایش را «فوراً» میرباید، و animateScrollToItem()
که بااستفاده از پویانمایی پیمایش میکند (بهعنوان پیمایش روان نیز شناخته میشود):
@Composable fun MessageList(messages: List<Message>) { val listState = rememberLazyListState() // Remember a CoroutineScope to be able to launch val coroutineScope = rememberCoroutineScope() LazyColumn(state = listState) { // ... } ScrollToTopButton( onClick = { coroutineScope.launch { // Animate scroll to the first item listState.animateScrollToItem(index = 0) } } ) }
مجموعههای بزرگ داده (صفحهبندی)
کتابخانه صفحهبندی به برنامهها امکان میدهد از فهرستهای بزرگ موارد پشتیبانی کنند و بخشهای کوچکی از فهرست را درصورت لزوم بار کنند و نمایش دهند. Paging 3.0 و نسخههای جدیدتر ازطریق کتابخانه androidx.paging:paging-compose از Compose پشتیبانی میکند.
برای نمایش فهرستی از محتوای صفحهبندیشده، میتوانیم از تابع افزونه
collectAsLazyPagingItems()
استفاده کنیم و سپس
LazyPagingItems
برگرداندهشده را به items() در LazyColumn خود ارسال کنیم. مشابه پشتیبانی از «صفحهبندی» در نماها، میتوانید
با بررسی اینکه آیا item برابر با null است یا نه، درحین بار شدن دادهها، جایبانها را نمایش دهید:
@Composable fun MessageList(pager: Pager<Int, Message>) { val lazyPagingItems = pager.flow.collectAsLazyPagingItems() LazyColumn { items( lazyPagingItems.itemCount, key = lazyPagingItems.itemKey { it.id } ) { index -> val message = lazyPagingItems[index] if (message != null) { MessageRow(message) } else { MessagePlaceholder() } } } }
نکاتی درباره استفاده از چیدمانهای Lazy
چند نکته وجود دارد که میتوانید برای اطمینان از اینکه چیدمانهای Lazy شما طبق انتظار کار میکنند، درنظر بگیرید.
از استفاده از موارد با اندازه ۰ پیکسل خودداری کنید
این اتفاق میتواند در سناریوهایی رخ دهد که، برای مثال، انتظار دارید بهصورت ناهمگام برخی دادهها مانند تصاویر را بازیابی کنید تا موارد فهرستتان را در مرحله بعدی پر کنید. این کار باعث میشود که چیدمان Lazy همه مواردش را در اولین اندازهگیری ترکیب کند، زیرا ارتفاع آنها ۰ پیکسل است و میتواند همه آنها را در نمای دید جا دهد. Once the items have loaded and their height expanded, Lazy layouts would then discard all of the other items that have unnecessarily been composed the first time around as they cannot in fact fit the viewport. برای جلوگیری از این مشکل، باید اندازه پیشفرض را برای موارد خود تنظیم کنید تا چیدمان Lazy بتواند محاسبه درستی از تعداد مواردی که واقعاً میتوانند در نمای دید قرار گیرند، انجام دهد:
@Composable fun Item(imageUrl: String) { AsyncImage( model = rememberAsyncImagePainter(model = imageUrl), modifier = Modifier.size(30.dp), contentDescription = null // ... ) }
وقتی اندازه تقریبی مواردتان را پساز بار شدن ناهمگام دادهها میدانید، روش خوب این است که مطمئن شوید اندازه مواردتان قبل و بعداز بار شدن یکسان باقی میماند، برای مثال، با افزودن چند جایبان. این کار به حفظ موقعیت پیمایش صحیح کمک میکند.
از تودرتو کردن مؤلفههای پیمایششدنی در یک جهت خودداری کنید
این فقط برای مواردی اعمال میشود که فرزندان پیمایشپذیر بدون اندازه ازپیش تعریفشده در داخل والد پیمایشپذیر دیگری با همان جهت تودرتو شده باشند. برای مثال، تلاش برای
قرار دادن LazyColumn فرزند بدون ارتفاع ثابت در داخل Column والد
با پیمایش عمودی:
// throws IllegalStateException Column( modifier = Modifier.verticalScroll(state) ) { LazyColumn { // ... } }
درعوض، میتوان با قرار دادن همه composable-ها در یک LazyColumn والد و استفاده از DSL آن برای ارسال انواع مختلف محتوا، به همان نتیجه رسید. این کار امکان انتشار موارد تکی و همچنین موارد فهرست چندگانه را
همه در یک مکان فراهم میکند:
LazyColumn { item { Header() } items(data) { item -> PhotoItem(item) } item { Footer() } }
بهیاد داشته باشید که مواردی که در آنها چیدمانهای جهتی مختلف را تودرتو میکنید،
برای مثال، Row والد پیمایشی و LazyColumn فرزند، مجاز هستند:
Row( modifier = Modifier.horizontalScroll(scrollState) ) { LazyColumn { // ... } }
و همچنین مواردی که هنوز از همان طرحبندیهای جهت استفاده میکنید، اما اندازه ثابتی را برای فرزندان تودرتو تنظیم میکنید:
Column( modifier = Modifier.verticalScroll(scrollState) ) { LazyColumn( modifier = Modifier.height(200.dp) ) { // ... } }
مراقب باشید چند عنصر را در یک مورد قرار ندهید
در این مثال، لامبدا مورد دوم ۲ مورد را در یک بلوک منتشر میکند:
LazyVerticalGrid( columns = GridCells.Adaptive(100.dp) ) { item { Item(0) } item { Item(1) Item(2) } item { Item(3) } // ... }
چیدمانهای تنبل این کار را طبق انتظار انجام میدهند - عناصر را یکی پساز دیگری بهگونهای میچینند که گویی موارد متفاوتی هستند. بااینحال، چند مشکل در انجام این کار وجود دارد.
وقتی چند عنصر بهعنوان بخشی از یک مورد منتشر میشوند، بهعنوان یک موجودیت مدیریت میشوند، یعنی دیگر نمیتوان آنها را بهصورت جداگانه ترکیب کرد. اگر یک عنصر در صفحه نمایان شود، همه عناصر مربوط به آن مورد باید ترکیببندی و اندازهگیری شوند. اگر بیشازحد استفاده شود، میتواند به عملکرد آسیب برساند. در حالت افراطی قرار دادن همه عناصر در یک مورد،
هدف استفاده از چیدمانهای Lazy را کاملاً ازبین میبرد. Apart from potential
performance issues, putting more elements in one item will also interfere
with scrollToItem() & animateScrollToItem().
بااینحال، موارد استفاده معتبری برای قرار دادن چندین عنصر در یک مورد وجود دارد، مانند داشتن تقسیمکنندهها در داخل یک فهرست. نمیخواهید جداکنندهها نمایههای پیمایش را تغییر دهند، زیرا نباید بهعنوان عناصر مستقل درنظر گرفته شوند. همچنین، عملکرد تحت تأثیر قرار نمیگیرد زیرا جداکنندهها کوچک هستند. جداکننده احتمالاً باید زمانیکه مورد قبلاز آن نمایان است، نمایان باشد، بنابراین میتواند بخشی از مورد قبلی باشد:
LazyVerticalGrid( columns = GridCells.Adaptive(100.dp) ) { item { Item(0) } item { Item(1) Divider() } item { Item(2) } // ... }
استفاده از تنظیمات سفارشی را درنظر بگیرید
معمولاً فهرستهای Lazy موارد زیادی دارند و فضایی بیشتر از اندازه محفظه پیمایش را اشغال میکنند. بااینحال، وقتی فهرست شما با چند مورد پر میشود، طراحی شما میتواند الزامات خاصتری برای نحوه قرارگیری این موارد در نمای دید داشته باشد.
برای دستیابی به این هدف، میتوانید از عمودی سفارشی
Arrangement
استفاده کنید و آن را به LazyColumn منتقل کنید. در مثال زیر، شیء TopWithFooter
فقط باید روش arrange را پیادهسازی کند. اولاً، موارد را یکی پساز دیگری قرار میدهد. دوم اینکه اگر کل ارتفاع استفادهشده کمتر از ارتفاع نمای هدف باشد، پاورقی را در پایین قرار میدهد:
object TopWithFooter : Arrangement.Vertical { override fun Density.arrange( totalSize: Int, sizes: IntArray, outPositions: IntArray ) { var y = 0 sizes.forEachIndexed { index, size -> outPositions[index] = y y += size } if (y < totalSize) { val lastIndex = outPositions.lastIndex outPositions[lastIndex] = totalSize - sizes.last() } } }
contentType اضافه کنید
از Compose 1.2 به بعد، برای بیشینه کردن عملکرد چیدمان Lazy،
contentType
را به فهرستها یا شبکههایتان اضافه کنید. این به شما امکان میدهد نوع محتوا را برای هر مورد از چیدمان مشخص کنید، در مواردی که درحال ترکیب کردن فهرست یا شبکهای متشکل از چندین نوع مختلف از موارد هستید:
LazyColumn { items(elements, contentType = { it.type }) { // ... } }
وقتی
contentType را ارائه میدهید،
Compose فقط میتواند ترکیببندیها را بین موارد
از همان نوع دوباره استفاده کند. ازآنجاییکه استفاده مجدد هنگام ترکیب کردن موارد با ساختار مشابه کارآمدتر است، ارائه انواع محتوا تضمین میکند که Compose سعی نمیکند موردی از نوع A را روی موردی کاملاً متفاوت از نوع B ترکیب کند. این کار به حداکثر رساندن مزایای استفاده مجدد از ترکیببندی و عملکرد چیدمان Lazy کمک میکند.
سنجش عملکرد
فقط زمانی میتوانید عملکرد چیدمان Lazy را بهطور قابلاطمینان اندازهگیری کنید که در حالت انتشار اجرا شود و بهینهسازی R8 فعال باشد. در ساختهای اشکالزدایی، پیمایش چیدمان Lazy ممکن است کندتر بهنظر برسد. برای اطلاعات بیشتر درباره این موضوع، عملکرد Compose را بخوانید.
منابع بیشتر
- ایجاد فهرست پیمایششدنی محدود
- ایجاد شبکه پیمایشی
- نمایش موارد پیمایش تودرتو در فهرست
- فیلتر کردن فهرست درحین تایپ کردن
- بار کردن کُند دادهها با فهرستها و صفحهبندی
- ساختن فهرست بااستفاده از چند نوع مورد
- ویدیو: فهرستها در Compose
توصیهشده برای شما
- توجه: وقتی جاوا اسکریپت خاموش باشد، نوشتار پیوند نمایش داده میشود
- انتقال
RecyclerViewبه Lazy list - ذخیره کردن وضعیت میانای کاربر در Compose
- Kotlin برای Jetpack Compose