داده های محلی با CompositionLocal

@Composable
fun FruitText(fruitSize: Int) {
    // resources را از مقدار فعلی LocalContext دریافت می‌کند
    val resources = LocalContext.current.resources
    val fruitText = remember(resources, fruitSize) {
        resources.getQuantityString(R.plurals.fruit_title, fruitSize)
    }
    Text(text = fruitText)
}

نکته:
objectها یا constantهای مربوط به CompositionLocal معمولاً با پیشوند Local نام‌گذاری می‌شوند تا با auto-complete در IDE راحت‌تر پیدا شوند.

ساخت CompositionLocal مخصوص خودتان

CompositionLocal ابزاری برای ارسال ضمنی داده به سمت پایین در Composition است.

نشانه مهم دیگر برای استفاده از CompositionLocal زمانی است که پارامتر، cross-cutting باشد و لایه‌های میانی پیاده‌سازی نباید از وجود آن آگاه باشند؛ چون آگاه کردن آن لایه‌های میانی می‌تواند کاربردپذیری Composable را محدود کند.

برای مثال، درخواست permissionهای اندروید در پشت صحنه با یک CompositionLocal فراهم می‌شود. یک Composable مربوط به media picker می‌تواند قابلیت جدیدی برای دسترسی به محتوای محافظت‌شده با permission روی دستگاه اضافه کند، بدون اینکه API آن تغییر کند و بدون اینکه callerهای media picker مجبور باشند از این context اضافه‌شده در محیط آگاه شوند.

با این حال، CompositionLocal همیشه بهترین راه‌حل نیست. استفاده بیش از حد از CompositionLocal توصیه نمی‌شود، چون چند نقطه ضعف دارد:

CompositionLocal باعث می‌شود فهمیدن رفتار یک Composable سخت‌تر شود. چون وابستگی‌های ضمنی ایجاد می‌کند، callerهای Composableهایی که از آن استفاده می‌کنند باید مطمئن شوند برای هر CompositionLocal مقدار مناسبی فراهم شده است.

علاوه بر این، ممکن است منبع حقیقت واضحی برای این وابستگی وجود نداشته باشد، چون می‌تواند در هر بخشی از Composition تغییر کند. بنابراین debug کردن اپلیکیشن هنگام بروز مشکل می‌تواند چالش‌برانگیزتر باشد؛ چون باید در Composition به سمت بالا حرکت کنید تا ببینید مقدار فعلی یا current کجا ارائه شده است.

ابزارهایی مانند Find usages در IDE یا Compose layout inspector اطلاعات کافی برای کاهش این مشکل فراهم می‌کنند.

نکته:
CompositionLocal برای معماری‌های پایه‌ای خوب عمل می‌کند و Jetpack Compose به‌طور گسترده از آن استفاده می‌کند.

تصمیم‌گیری درباره استفاده از CompositionLocal

شرایطی وجود دارد که می‌تواند CompositionLocal را به راه‌حل خوبی برای مورد استفاده شما تبدیل کند:

یک CompositionLocal باید مقدار پیش‌فرض خوبی داشته باشد. اگر مقدار پیش‌فرض وجود ندارد، باید تضمین کنید که برای توسعه‌دهنده بسیار سخت باشد در موقعیتی قرار بگیرد که مقداری برای آن CompositionLocal ارائه نشده باشد. فراهم نکردن مقدار پیش‌فرض می‌تواند هنگام ساخت testها یا preview کردن Composableای که از آن CompositionLocal استفاده می‌کند مشکل و ناراحتی ایجاد کند، چون همیشه باید به‌صورت صریح مقدار ارائه شود.

برای conceptهایی که tree-scoped یا sub-hierarchy scoped در نظر گرفته نمی‌شوند، از CompositionLocal استفاده نکنید. یک CompositionLocal زمانی منطقی است که بتواند به‌صورت بالقوه توسط هر descendant استفاده شود، نه فقط توسط چند مورد محدود.

اگر مورد استفاده شما این نیازها را برآورده نمی‌کند، قبل از ساخت یک CompositionLocal، بخش راه‌حل‌های جایگزین را بررسی کنید.

یک مثال از روش بد این است که یک CompositionLocal بسازید که ViewModel یک صفحه خاص را نگه دارد تا همه Composableهای آن صفحه بتوانند reference مربوط به ViewModel را دریافت کرده و بعضی منطق‌ها را اجرا کنند. این روش بد است، چون همه Composableهای زیر یک درخت UI خاص لازم نیست درباره ViewModel بدانند.

روش درست این است که فقط اطلاعاتی را به Composableها پاس دهید که واقعاً به آن نیاز دارند، بر اساس الگویی که در آن State به پایین جریان پیدا می‌کند و Eventها به بالا می‌روند. این رویکرد باعث می‌شود Composableهای شما قابل استفاده مجددتر و تست‌پذیرتر شوند.

ساخت یک CompositionLocal

دو API برای ساخت CompositionLocal وجود دارد:

• compositionLocalOf: تغییر مقداری که هنگام Recomposition ارائه شده، فقط محتوایی را invalid می‌کند که مقدار current آن را می‌خواند.
• staticCompositionLocalOf: برخلاف compositionLocalOf، خواندن مقدارهای staticCompositionLocalOf توسط Compose دنبال نمی‌شود. تغییر مقدار باعث می‌شود کل lambda مربوط به content که CompositionLocal در آن ارائه شده Recomposition شود، نه فقط جاهایی که مقدار current در Composition خوانده شده است.

اگر مقداری که به CompositionLocal ارائه می‌شود به احتمال زیاد تغییر نمی‌کند یا هرگز تغییر نخواهد کرد، از staticCompositionLocalOf استفاده کنید تا از مزایای performance بهره ببرید.

برای مثال، design system یک اپلیکیشن ممکن است دیدگاه مشخصی درباره نحوه elevation دادن به Composableها با استفاده از shadow برای componentهای UI داشته باشد. چون elevationهای مختلف اپلیکیشن باید در سراسر درخت UI منتشر شوند، از یک CompositionLocal استفاده می‌کنیم. از آنجا که مقدار CompositionLocal به‌صورت شرطی بر اساس theme سیستم به دست می‌آید، از API به نام compositionLocalOf استفاده می‌کنیم:

// فایل LocalElevations.kt

data class Elevations(val card: Dp = 0.dp, val default: Dp = 0.dp)

// یک object عمومی CompositionLocal با مقدار پیش‌فرض تعریف می‌کند
// این instance می‌تواند توسط همه Composableهای اپلیکیشن استفاده شود
val LocalElevations = compositionLocalOf { Elevations() }

// فایل MyActivity.kt

class MyActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            // محاسبه elevationها بر اساس theme سیستم
            val elevations = if (isSystemInDarkTheme()) {
                Elevations(card = 1.dp, default = 1.dp)
            } else {
                Elevations(card = 0.dp, default = 0.dp)
            }

            // اتصال elevation به‌عنوان مقدار LocalElevations
            CompositionLocalProvider(LocalElevations provides elevations) {
                // ... محتوا اینجا قرار می‌گیرد ...
                // این بخش از Composition هنگام دسترسی به LocalElevations.current
                // instance مربوط به elevations را می‌بیند
            }
        }
    }
}

@Composable
fun SomeComposable() {
    // دسترسی به متغیر عمومی LocalElevations برای گرفتن
    // Elevations فعلی در این بخش از Composition
    MyCard(elevation = LocalElevations.current.card) {
        // محتوا
    }
}

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    MyDescendant(myViewModel.data)
}

// کل object را پاس ندهید! فقط چیزی را پاس دهید که descendant نیاز دارد.
// همچنین ViewModel را به‌عنوان یک وابستگی ضمنی با CompositionLocal پاس ندهید.
@Composable
fun MyDescendant(myViewModel: MyViewModel) { /* ... */ }

// فقط چیزی را پاس دهید که descendant لازم دارد
@Composable
fun MyDescendant(data: DataToDisplay) {
    // نمایش داده
}

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    MyDescendant(myViewModel)
}

@Composable
fun MyDescendant(myViewModel: MyViewModel) {
    Button(onClick = { myViewModel.loadData() }) {
        Text("Load data")
    }
}

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    ReusableLoadDataButton(
        onLoadClick = {
            myViewModel.loadData()
        }
    )
}

@Composable
fun ReusableLoadDataButton(onLoadClick: () -> Unit) {
    Button(onClick = onLoadClick) {
        Text("Load data")
    }
}

@Composable
fun MyComposable(myViewModel: MyViewModel = viewModel()) {
    // ...
    ReusablePartOfTheScreen(
        content = {
            Button(
                onClick = {
                    myViewModel.loadData()
                }
            ) {
                Text("Confirm")
            }
        }
    )
}

@Composable
fun ReusablePartOfTheScreen(content: @Composable () -> Unit) {
    Column {
        // ...
        content()
    }
}