LazyRow در Jetpack Compose — چیست، ویژگی‌ها و نحوه کار

LazyRow در Jetpack Compose چیست

LazyRow — یک تابع composable است که یک لیست افقی قابل پیمایش با بارگذاری تنبل عناصر را پیاده‌سازی می‌کند. برخلاف Row که همه عناصر فرزند را همزمان رندر می‌کند، LazyRow فقط عناصر قابل مشاهده در ناحیه نمایش را ایجاد می‌کند.

LazyRow مانند LazyColumn کار می‌کند، اما عناصر را به صورت افقی قرار می‌دهد. هنگام پیمایش به چپ یا راست، عناصری که از ناحیه دید خارج شده‌اند برای نمایش عناصر جدید مجدداً استفاده می‌شوند. این برای گالری‌هایی با تعداد زیادی تصویر یا لیست‌های طولانی دسته‌بندی بسیار مهم است.

به گفته Android Developers Blog, 2024، LazyRow از همان معماری LazyList مانند LazyColumn استفاده می‌کند، از جمله LazyListState، مکانیسم استفاده مجدد از طریق Pool و پشتیبانی از انواع مختلف عناصر. حداکثر کارایی با استفاده از ارتفاع ثابت عناصر به دست می‌آید.

امضای پایه LazyRow

LazyRow پارامترهای modifier، state، contentPadding، reverseLayout، horizontalArrangement و verticalAlignment را می‌پذیرد. محتوا از طریق توابع DSL items و item، مشابه LazyColumn تعریف می‌شود.

@Composable
fun SimpleLazyRow() {
    val items = (1..50).toList()
    LazyRow(
        modifier = Modifier.fillMaxWidth().height(100.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp),
        contentPadding = PaddingValues(start = 16.dp, end = 16.dp)
    ) {
        items(items) { item ->
            Box(
                modifier = Modifier.size(80.dp).background(Color.Gray)
            ) {
                Text(text = "$item", modifier = Modifier.align(Alignment.Center))
            }
        }
    }
}

ویژگی‌های LazyRow: horizontalArrangement و contentPadding

horizontalArrangement توزیع عناصر را در امتداد محور افقی در داخل LazyRow کنترل می‌کند. همان مقادیر Arrangement که در Row وجود دارد در دسترس است: Start، Center، End، SpaceBetween، SpaceEvenly، SpaceAround و spacedBy با فاصله سفارشی.

contentPadding به لبه‌های کانتینر LazyRow حاشیه اضافه می‌کند. برخلاف Modifier.padding، contentPadding هنگام پیمایش در نظر گرفته می‌شود: اولین عنصر از لبه چپ فاصله خواهد داشت و آخرین عنصر از لبه راست. به گفته Material Design Guidelines, 2025، contentPadding برای چرخ فلک‌ها و گالری‌ها الزامی است تا اولین و آخرین عنصر به لبه صفحه نچسبند.

verticalAlignment عناصر را به صورت عمودی در داخل LazyRow تراز می‌کند. به طور پیش‌فرض از Alignment.Top استفاده می‌شود. برای مرکز کردن عناصر با ارتفاع مختلف از Alignment.CenterVertically استفاده کنید که برای چرخ فلک‌هایی با تصاویر با نسبت‌های مختلف مفید است.

جدول پارامترهای LazyRow

کنترل پیمایش افقی با LazyListState

LazyListState برای LazyRow دقیقاً مانند LazyColumn کار می‌کند: اولین عنصر قابل مشاهده، افست و موقعیت کلی پیمایش را ردیابی می‌کند. حالت از طریق rememberLazyListState() ایجاد و در پارامتر state منتقل می‌شود.

کنترل برنامه‌ای پیمایش LazyRow با همان روش‌ها انجام می‌شود: animateScrollToItem برای انیمیشن روان و scrollToItem برای پیمایش فوری. هر دو در داخل یک کوروتین فراخوانی می‌شوند. این برای چرخ فلک‌هایی با دکمه‌های «چپ/راست» یا پیمایش خودکار مفید است.

به گفته Android Developers, 2024، LazyRow همچنین از SnapFlingBehavior پشتیبانی می‌کند — رفتاری که در هنگام پیمایش سریع به جای توقف بین عناصر، روی نزدیک‌ترین عنصر متوقف می‌شود. این یک اثر «چسبیدن» به عنصر ایجاد می‌کند که برای چرخ فلک‌ها و گالری‌ها آشناست.

@Composable
fun CarouselWithSnap() {
    val listState = rememberLazyListState()
    val scope = rememberCoroutineScope()
    val items = listOf("A", "B", "C", "D", "E")

    Column {
        LazyRow(
            state = listState,
            flingBehavior = SnapFlingBehavior(listState),
            horizontalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            items(items) { item ->
                Card(modifier = Modifier.width(150.dp)) {
                    Text(text = item, modifier = Modifier.padding(16.dp))
                }
            }
        }

        Row(modifier = Modifier.fillMaxWidth()) {
            Button(onClick = {
                scope.launch {
                    listState.animateScrollToItem(0)
                }
            }) { Text("برای شروع") }
        }
    }
}

نمونه‌های استفاده از LazyRow در رابط‌ها

اولین نمونه — LazyRow برای گالری تصاویر با پیش‌نمایش. هر عنصر یک Box با تصویر و عنوان است. LazyRow ده‌ها و صدها تصویر را به طور مؤثر مدیریت می‌کند و فقط تصاویر قابل مشاهده را بارگذاری می‌کند.

@Composable
fun ImageGallery(images: List<String>) {
    LazyRow(
        contentPadding = PaddingValues(start = 16.dp, end = 16.dp),
        horizontalArrangement = Arrangement.spacedBy(12.dp)
    ) {
        items(images, key = { it }) { url ->
            AsyncImage(
                model = url,
                contentDescription = "Image",
                modifier = Modifier.size(120.dp)
            )
        }
    }
}

دومین نمونه — LazyRow برای لیست دسته‌بندی‌ها با آیکون‌ها. دسته‌بندی‌ها به صورت چیپ نمایش داده می‌شوند و کاربر می‌تواند آنها را به صورت افقی پیمایش کند. LazyRow با spacedBy و contentPadding فاصله بین دسته‌بندی‌ها و لبه‌ها را ایجاد می‌کند.

@Composable
fun CategoryChips(categories: List<String>) {
    LazyRow(
        contentPadding = PaddingValues(horizontal = 16.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        items(categories, key = { it }) { category ->
            AssistChip(
                onClick = {},
                label = { Text(category) }
            )
        }
    }
}

LazyRow در مقابل Row: چه زمانی کدام را انتخاب کنیم

انتخاب بین LazyRow و Row به تعداد عناصر بستگی دارد. Row برای 5–10 عنصر که همیشه روی صفحه قابل مشاهده هستند مناسب است. LazyRow زمانی ضروری است که عناصر زیاد هستند یا تعداد آنها پویا است.

Row همه عناصر را یکباره رندر می‌کند که با تعداد زیاد عناصر منجر به تأخیر می‌شود. LazyRow فقط عناصر قابل مشاهده را رندر می‌کند و آن را برای لیست‌های پیمایشی ترجیح‌پذیر می‌کند. به گفته Android Developers Blog, 2024، آستانه گذار حدود 10 عنصر است: اگر عناصر بیشتری دارید، از LazyRow استفاده کنید.

LazyRow همچنین از انیمیشن‌ها، SnapFlingBehavior و گروه‌بندی از طریق جداکننده‌ها پشتیبانی می‌کند که آن را برای رابط‌های پیچیده انعطاف‌پذیرتر می‌کند. Row ساده‌تر است و به LazyListState نیاز ندارد، اما برای لیست‌های طولانی بهینه نشده است.

• Row — برای 5–10 عنصر استاتیک بدون پیمایش
• LazyRow — برای 10+ عنصر با پیمایش افقی
• LazyRow — برای چرخ فلک‌ها، گالری‌ها، لیست‌های پویا