فهرست‌های تنبل و جدول‌های تنبل

بسیاری از برنامه‌ها باید مجموعه‌هایی از موارد را نمایش دهند. این سند توضیح می‌دهد که چگونه می‌توانید این کار را به‌طور مؤثر در 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()
)
جدول نامنظم کُند از تصاویر در Compose
شکل ۲. مثالی از شبکه عمودی متناوب با ستون‌های ثابت

بهبود عملکرد پیمایش با 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 دکمه‌های تغییر ترتیب فهرست را نمایش می‌دهد. این تابع توابع لامبدا را برای بازنشانی ترتیب و مرتب‌سازی فهرست براساس طول یا حروف الفبا دریافت می‌کند.
  • ‫ListAnimatedItems ListAnimatedItems composable را فراخوانی می‌کند و فهرست 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)
                }
            }
        }
    }
}

نکات کلیدی درباره کد

  • OrderButtons SingleChoiceSegmentedButtonRow را نمایش می‌دهد تا به کاربران اجازه دهد روش مرتب‌سازی را در فهرست انتخاب کنند یا ترتیب فهرست را بازنشانی کنند. مؤلفه 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 را بخوانید.

منابع بیشتر