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

Scaffold در Jetpack Compose چیست

Scaffold — یک تابع composable است که چارچوب صفحه را بر اساس مشخصات Material Design پیاده می‌کند. Scaffold یک کانتینر به معنای معمولی نیست — این یک مدیر چیدمان است که قرارگیری چند جزء ماننده استاندارد Material را در صفحه هماهنگ می‌کند.

Scaffold فاصله‌ها را برای TopAppBar، BottomBar و FloatingActionButton و نیز عناصر سیستم — نوار وضعیت و پانل ناوبری را مدیریت می‌کند. این تضمین می‌کند که محتوا روی عناصر سیستم قرار نگیرد و با دستورالعملهای Material Design مطابقت داشته باشد.

به گزارش Material Design Guidelines, 2025، Scaffold باید عنصر ریشه هر صفحه برنامه باشد. آن CoordinatorLayout منسوخ را از سیستم View جایگزین می‌کند و API ساده‌تر و اعلانی برای ساخت چیدمان صفحه تامین می‌کند.

امضای پایه Scaffold

Scaffold پارامترهای modifier، scaffoldState، topBar، bottomBar، floatingActionButton، drawerContent، snackbarHost و content را می‌پذیرد. پارامتر content PaddingValues — فاصله‌هایی را که محتوای اصلی باید در نظر بگیرد دریافت می‌کند.

@Composable
fun BasicScaffold() {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("خانه") }
            )
        },
        floatingActionButton = {
            FloatingActionButton(onClick = {}) {
                Icon(Icons.Default.Add, contentDescription = "Add")
            }
        }
    ) { innerPadding ->
        Column(
            modifier = Modifier.padding(innerPadding)
        ) {
            Text("محتوای اصلی")
        }
    }
}

سلاتهای Scaffold: topBar، bottomBar و floatingActionButton

topBar — سلاتی برای قراردادن پانل بالای برنامه، معمولاً TopAppBar یا LargeTopAppBar. Scaffold به طور خودکار یک فاصله در innerPadding برای محتوا اضافه می‌کند تا روی topBar قرار نگیرد. TopAppBar می‌تواند شامل عنوان، آیکون ناوبری و اقدامات باشد.

bottomBar — سلاتی برای پانل ناوبری پایین. از BottomNavigation، BottomAppBar یا NavigationBar پشتیبانی می‌کند. Scaffold ارتفاع bottomBar را در محاسبه innerPadding برای محتوا در نظر می‌گیرد. به گزارش Material Design Guidelines, 2025، bottomBar باید در صفحاتی با 3–5 نقطه ناوبری استفاده شود.

floatingActionButton — سلاتی برای دکمه شناور عمل. Scaffold FAB را بر اساس مشخصات Material Design به صورت خودکار موقعیت‌یابی می‌کند — در گوشه پایین راست با فاصله درست. floatingActionButtonPosition به شما اجازه می‌دهد FAB را به مرکز لبه پایین اکران منتقل کنید.

مثال با همه سلاتها

در این مثال، Scaffold از همه سلاتهای اصلی استفاده می‌کند: TopAppBar با عنوان، BottomBar با سه عنصر ناوبری و FloatingActionButton برای عمل اصلی.

@Composable
fun FullScaffold() {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("برنامه") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.Menu, "Menu")
                    }
                }
            )
        },
        bottomBar = {
            NavigationBar {
                NavigationBarItem(
                    icon = { Icon(Icons.Default.Home, "خانه") },
                    label = { Text("Home") },
                    selected = true,
                    onClick = {}
                )
                NavigationBarItem(
                    icon = { Icon(Icons.Default.Search, "جستجو") },
                    label = { Text("Search") },
                    selected = false,
                    onClick = {}
                )
            }
        },
        floatingActionButton = {
            FloatingActionButton(onClick = {}) {
                Icon(Icons.Default.Add, "Add")
            }
        }
    ) { innerPadding ->
        Box(modifier = Modifier.padding(innerPadding)) {
            Text("محتوای صفحه")
        }
    }
}

ScaffoldState: مدیریت Drawer و Snackbar

ScaffoldState — شیء وضعیت Scaffold است که DrawerState و SnackbarHostState را ترکیب می‌کند. DrawerState باز و بسته شدن منوی کناری را و SnackbarHostState نمایش و مخفی شدن Snackbar را مدیریت می‌کند. وضعیت از طریق rememberScaffoldState() ایجاد و به پارامتر scaffoldState ارسال می‌شود.

DrawerState روش‌های open و close را برای مدیریت برنامه‌ای Drawer تامین می‌کند. وضعیت Drawer می‌تواند باز، بسته یا قسمتاً باز باشد. drawerGesturesEnabled امکان غیرفعال سازی جست باز شدن Drawer با کشیدن را فراهم می‌کند و تنها باز کردن برنامه‌ای از طریق دکمه را نگه می‌داشته است.

SnackbarHostState Snackbar را مدیریت می‌کند — اطلاعیه‌های موقت در بخش پایین صفحه. روش showSnackbar Snackbar را با پیام و عمل اختیاری نمایش می‌دهد. به گزارش Material Design Guidelines, 2025، Snackbar برای پیام‌های کوتاه بدون اطلاعات حیاتی مهم استفاده شود.

@Composable
fun ScaffoldWithDrawer() {
    val scaffoldState = rememberScaffoldState()
    val scope = rememberCoroutineScope()

    Scaffold(
        scaffoldState = scaffoldState,
        topBar = {
            TopAppBar(
                title = { Text("منو") },
                navigationIcon = {
                    IconButton(onClick = {
                        scope.launch {
                            scaffoldState.drawerState.open()
                        }
                    }) {
                        Icon(Icons.Default.Menu, "Menu")
                    }
                }
            )
        },
        drawerContent = {
            Column(modifier = Modifier.padding(16.dp)) {
                Text("آیتم ۱")
                Text("آیتم ۲")
            }
        }
    ) { innerPadding ->
        Box(modifier = Modifier.padding(innerPadding)) {
            Text("محتوا")
        }
    }
}

مثال ساخت صفحه با Scaffold

یک مثال کامل از صفحه با Scaffold شامل TopAppBar، BottomNavigation، FloatingActionButton و Snackbar برای نمایش اطلاعیه پس از فشاردن FAB است. ScaffoldState برای هماهنگی وضعیت به همه کامپوننت‌ها ارسال می‌شود.

@Composable
fun MainScreen() {
    val state = rememberScaffoldState()
    val scope = rememberCoroutineScope()

    Scaffold(
        scaffoldState = state,
        topBar = {
            TopAppBar(
                title = { Text("IT Sectr") },
                actions = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.Notifications, "Notifications")
                    }
                }
            )
        },
        bottomBar = {
            NavigationBar {
                NavigationBarItem(icon = { Icon(Icons.Default.Home, "خانه") },
                    label = { Text("Home") }, selected = true, onClick = {})
                NavigationBarItem(icon = { Icon(Icons.Default.Settings, "تنظیمات") },
                    label = { Text("Settings") }, selected = false, onClick = {})
            }
        },
        floatingActionButton = {
            FloatingActionButton(onClick = {
                scope.launch {
                    state.snackbarHostState.showSnackbar("انجام شد")
                }
            }) {
                Icon(Icons.Default.Add, "Add")
            }
        }
    ) { padding ->
        Box(
            modifier = Modifier.padding(padding).fillMaxSize(),
            contentAlignment = Alignment.Center
        ) {
            Text("خوش آمدید")
        }
    }
}

InnerPadding و چیدمان سازگار با Scaffold

innerPadding — PaddingValuesی است که Scaffold به بلوک content ارسال می‌کند. آنها شامل فاصله‌هایی هستند که برای جلوگیری از قرار گرفتن محتوا روی statusBar، navigationBar، topBar و bottomBar لازم هستند. استفاده از innerPadding برای نمایش درست در دستگاه‌های مختلف اجباری است.

Scaffold innerPadding را بر اساس فاصله‌های سیستم و ارتفاع سلاتهای نصب شده به صورت خودکار محاسبه می‌کند. در دستگاه‌های با جزیره دوربین یا بریدگی صفحه، Scaffold فاصله‌ها را برای نوار وضعیت تصحیح می‌کند. در دستگاه‌های قدیمی با دکمه‌های فیزیکی، فاصله پایین ممکن است صفر باشد.

به گزارش Android Developers, 2024، innerPadding باید از طریق Modifier.padding(innerPadding) به کانتینر ریشه محتوا اعمال شود. اگر محتوا از کانتینر قابل پیمایش استفاده می‌کند، innerPadding از طریق Modifier.consumeWindowInsets برای کار درست صفحه کلید و جست‌های سیستم اعمال می‌شود.

• innerPadding را از طریق Modifier.padding(innerPadding) به کانتینر ریشه محتوا اعمال کنید
• برای کانتینرهای قابل پیمایش از Modifier.consumeWindowInsets(innerPadding) استفاده کنید
• فاصله‌های اضافی برای نوار وضعیت اضافه نکنید — Scaffold این کار را به صورت خودکار انجام می‌دهد
• در صورت عدم وجود topBar یا bottomBar، فاصله‌های مربوطه در innerPadding صفر خواهند بود