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

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

مقدمه‌ای بر CompositionLocal

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

@Composable
fun MyApp() {
    // Theme information tends to be defined near the root of the application
    val colors = colors()
}

// Some composable deep in the hierarchy
@Composable
fun SomeTextLabel(labelText: String) {
    Text(
        text = labelText,
        color = colors.onPrimary // ← need to access colors here
    )
}
CompositionLocalSnippets.kt

برای پشتیبانی از عدم نیاز به انتقال رنگ‌ها به‌عنوان وابستگی پارامتر صریح به اکثر عناصر ترکیب‌پذیر، ‫Compose CompositionLocal را ارائه می‌دهد که به شما امکان می‌دهد اشیاء نام‌گذاری‌شده با محدوده درختی ایجاد کنید که می‌توانند به‌عنوان روشی ضمنی برای جریان داده‌ها در درخت واسط کاربر استفاده شوند.

CompositionLocal عنصر معمولاً با مقداری در گره خاصی از درخت واسط کاربر ارائه می‌شود. فرزندان ترکیب‌پذیر آن می‌توانند بدون تعریف CompositionLocal به‌عنوان پارامتر در تابع ترکیب‌پذیر از این مقدار استفاده کنند.

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

• ترکیب سابقه نمودار تماس توابع ترکیبی است.
• درخت واسط کاربر یا سلسله مراتب واسط کاربر درخت LayoutNode ساخته‌شده، به‌روزرسانی‌شده، و نگهداری‌شده توسط فرایند ترکیب است.

CompositionLocal چیزی است که زمینه «ماتریال» در پشت صحنه از آن استفاده می‌کند. MaterialTheme شیئی است که سه نمونه CompositionLocal را ارائه می‌دهد: colorScheme، typography، و shapes، که به شما امکان می‌دهد آن‌ها را بعداً در هر بخش فرزند «قطعه» بازیابی کنید. به‌طور دقیق، این‌ها LocalColorScheme، LocalShapes، و LocalTypography دارایی‌هایی هستند که می‌توانید ازطریق MaterialTheme colorScheme، shapes، و typography مشخصه‌ها به آن‌ها دسترسی داشته باشید.

@Composable
fun MyApp() {
    // Provides a Theme whose values are propagated down its `content`
    MaterialTheme {
        // New values for colorScheme, typography, and shapes are available
        // in MaterialTheme's content lambda.

        // ... content here ...
    }
}

// Some composable deep in the hierarchy of MaterialTheme
@Composable
fun SomeTextLabel(labelText: String) {
    Text(
        text = labelText,
        // `primary` is obtained from MaterialTheme's
        // LocalColors CompositionLocal
        color = MaterialTheme.colorScheme.primary
    )
}
CompositionLocalSnippets.kt

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

برای ارائه مقدار جدید به CompositionLocal، از CompositionLocalProvider و تابع میانوند provides که کلید CompositionLocal را به value مرتبط می‌کند استفاده کنید. وقتی به دارایی current در CompositionLocal دسترسی پیدا می‌کنید، لامبدای content در CompositionLocalProvider مقدار ارائه‌شده را دریافت خواهد کرد. وقتی مقدار جدیدی ارائه می‌شود، Compose بخش‌هایی از «ترکیب» را که CompositionLocal را می‌خوانند دوباره ترکیب می‌کند.

به‌عنوان نمونه‌ای از این، LocalContentColor CompositionLocal حاوی رنگ محتوای ترجیحی است که برای نوشتار و نمادنگاری استفاده می‌شود تا اطمینان حاصل شود که با رنگ پس‌زمینه فعلی کنتراست دارد. در مثال زیر، از CompositionLocalProvider برای ارائه مقادیر مختلف برای بخش‌های مختلف «قطعه موسیقی» استفاده شده است.

@Composable
fun CompositionLocalExample() {
    MaterialTheme {
        // Surface provides contentColorFor(MaterialTheme.colorScheme.surface) by default
        // This is to automatically make text and other content contrast to the background
        // correctly.
        Surface {
            Column {
                Text("Uses Surface's provided content color")
                CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.primary) {
                    Text("Primary color provided by LocalContentColor")
                    Text("This Text also uses primary as textColor")
                    CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.error) {
                        DescendantExample()
                    }
                }
            }
        }
    }
}

@Composable
fun DescendantExample() {
    // CompositionLocalProviders also work across composable functions
    Text("This Text uses the error color now")
}
CompositionLocalSnippets.kt

در مثال آخر، CompositionLocal نمونه به‌صورت داخلی توسط عناصر ترکیبی Material استفاده شده است. برای دسترسی به مقدار فعلی CompositionLocal، از دارایی current آن استفاده کنید. در مثال زیر، مقدار Context فعلی LocalContext CompositionLocal که معمولاً در برنامه‌های Android استفاده می‌شود برای قالب‌بندی نوشتار استفاده می‌شود:

@Composable
fun FruitText(fruitSize: Int) {
    // Get `resources` from the current value of LocalContext
    val resources = LocalContext.current.resources
    val fruitText = remember(resources, fruitSize) {
        resources.getQuantityString(R.plurals.fruit_title, fruitSize)
    }
    Text(text = fruitText)
}
CompositionLocalSnippets.kt

‫CompositionLocal خودتان را بسازید

‫CompositionLocal ابزاری برای انتقال داده‌ها به‌صورت ضمنی ازطریق «ترکیب» است.

علامت کلیدی دیگر برای استفاده از CompositionLocal زمانی است که پارامتر لایه میانی و متقاطع پیاده‌سازی نباید از وجود آن آگاه باشد، زیرا آگاه کردن آن لایه‌های میانی کاربرد ترکیب‌شدنی را محدود می‌کند. برای مثال، پُرسمان برای اجازه‌های Android توسط CompositionLocal در پشت صحنه انجام می‌شود. ترکیب‌شدنی انتخابگر رسانه می‌تواند بدون تغییر دادن API آن و بدون نیاز به اینکه تماس‌گیرندگان انتخابگر رسانه از این بافت اضافه که از محیط استفاده می‌شود مطلع باشند، عملکرد جدیدی برای دسترسی به محتوای محافظت‌شده با اجازه در دستگاه اضافه کند.

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

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

علاوه‌براین، ممکن است منبع حقیقت واضحی برای این وابستگی وجود نداشته باشد زیرا می‌تواند در هر بخشی از «ترکیب» تغییر کند. بنابراین، عیب‌یابی برنامه هنگام بروز مشکل می‌تواند چالش‌برانگیزتر باشد زیرا باید در «ترکیب» پیمایش کنید تا ببینید مقدار current در کجا ارائه شده است. ابزارهایی مثل یافتن کاربردها در IDE یا بازرس چیدمان «ترکیب» اطلاعات کافی برای کاهش این مشکل ارائه می‌دهند.

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

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

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

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

// LocalElevations.kt file

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

// Define a CompositionLocal global object with a default
// This instance can be accessed by all composables in the app
val LocalElevations = compositionLocalOf { Elevations() }
CompositionLocalSnippets.kt

// MyActivity.kt file

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

        setContent {
            // Calculate elevations based on the system theme
            val elevations = if (isSystemInDarkTheme()) {
                Elevations(card = 1.dp, default = 1.dp)
            } else {
                Elevations(card = 0.dp, default = 0.dp)
            }

            // Bind elevation as the value for LocalElevations
            CompositionLocalProvider(LocalElevations provides elevations) {
                // ... Content goes here ...
                // This part of Composition will see the `elevations` instance
                // when accessing LocalElevations.current
            }
        }
    }
}
CompositionLocalSnippets.kt

@Composable
fun SomeComposable() {
    // Access the globally defined LocalElevations variable to get the
    // current Elevations in this part of the Composition
    MyCard(elevation = LocalElevations.current.card) {
        // Content
    }
}
CompositionLocalSnippets.kt

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

// Don't pass the whole object! Just what the descendant needs.
// Also, don't  pass the ViewModel as an implicit dependency using
// a CompositionLocal.
@Composable
fun MyDescendant(myViewModel: MyViewModel) { /* ... */ }

// Pass only what the descendant needs
@Composable
fun MyDescendant(data: DataToDisplay) {
    // Display data
}
CompositionLocalSnippets.kt

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

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

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

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

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

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