البيانات ذات النطاق المحلي باستخدام MembershipLocal

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 الذي يتيح لك إنشاء عناصر مُسمّاة على مستوى الشجرة يمكن استخدامها كطريقة ضمنية لتوجيه تدفق data من خلال شجرة واجهة المستخدم.

يتم عادةً تزويد عناصر CompositionLocal بقيمة في عقدة معيّنة من شجرة واجهة المستخدم. ويمكن استخدام هذه القيمة من قِبل العناصر الفرعية القابلة للتجميع بدون تحديد CompositionLocal كمَعلمة في الدالة القابلة للتجميع.

CompositionLocal هو ما يستخدمه مظهر Material في الخلفية. 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. ستحصل دالة lambda content في CompositionLocalProvider على القيمة المقدَّمة عند الوصول إلى سمة current في CompositionLocal. عند تقديم قيمة جديدة، يعيد تطبيق "الإنشاء" تركيب أجزاء من التركيب التي تقرأ 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

الشكل 1: معاينة العنصر القابل للتجميع CompositionLocalExample

في المثال الأخير، تم استخدام نُسخ 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 في الخلفية. يمكن أن تضيف أداة اختيار الوسائط القابلة للتركيب وظائف جديدة للوصول إلى المحتوى المحمي بموجب إذن على الجهاز بدون تغيير واجهة برمجة التطبيقات الخاصة بها ومطالبة مُرسِلي طلبات أداة اختيار الوسائط بالانتباه إلى هذا السياق المُضاف المستخدَم من البيئة.

ومع ذلك، لا يكون CompositionLocal هو الحل الأفضل في كل الحالات. ننصح بعدم إساءة استخدام CompositionLocal لأنّ ذلك قد يؤدي إلى بعض النتائج السلبية:

CompositionLocal يجعل من الصعب تفسير سلوك العنصر القابل للتجميع. وبما أنّها تُنشئ تبعيات ضمنية، على مُستدعي العناصر القابلة للتجميع التي تستخدمها التأكّد من توفّر قيمة لكل CompositionLocal.

بالإضافة إلى ذلك، قد لا يتوفّر مصدر واضح لهذه التبعية لأنّه يمكن أن تتغيّر في أي جزء من التركيب. وبالتالي، قد يكون تصحيح أخطاء التطبيق عند حدوث مشكلة أكثر صعوبة لأنّك تحتاج إلى الانتقال إلى أعلى التركيبة لمعرفة مكان تقديم قيمة current. توفّر أدوات مثل العثور على موارد الاستعمال في IDE أو أداة فحص تنسيق الإنشاء معلومات كافية للتخفيف من هذه المشكلة.

تحديد ما إذا كنت تريد استخدام CompositionLocal

هناك شروط معيّنة يمكن أن تجعل CompositionLocal حلًا جيدًا لحالة الاستخدام:

يجب أن تحتوي سمة CompositionLocal على قيمة تلقائية جيدة. إذا لم تكن هناك قيمة CompositionLocalتلقائية، يجب التأكّد من أنّه من الصعب جدًا على المطوّر أن يقع في موقف لا يتم فيه تقديم قيمة لسمة CompositionLocal. يمكن أن يؤدي عدم تقديم قيمة تلقائية إلى حدوث مشاكل وإزعاج عند إنشاء اختبارات أو معاينة عنصر قابل للتجميع يستخدم CompositionLocal، لأنّه سيتطلب دائمًا تقديمها صراحةً.

تجنَّب استخدام CompositionLocal للعناصر التي لا تُعتبر على مستوى الشجرة أو على مستوى التسلسل الهرمي الفرعي. يكون استخدام CompositionLocal منطقيًا عندما يمكن استخدامه من قِبل أي نسل، وليس من قِبل بضعة سلالات.

إذا لم تستوفِ حالة الاستخدام هذه المتطلبات، اطّلِع على القسم البدائل التي يجب أخذها في الاعتبار قبل إنشاء CompositionLocal.

من الأمثلة على الممارسات غير الصحيحة إنشاء CompositionLocal يحتوي على ViewModel شاشة معيّنة لكي تتمكّن جميع العناصر القابلة للتجميع في تلك الشاشة من الحصول على مرجع إلى ViewModel لتنفيذ بعض المنطق. هذه ممارسة سيئة لأنّ بعض العناصر القابلة للتجميع ضمن شجرة واجهة مستخدِم معيّنة لا تحتاج إلى معرفة ViewModel. من أفضل الممارسات عدم تمرير سوى المعلومات التي تحتاجها العناصر القابلة للتجميع، وذلك باتّباع النمط الذي تتدفق فيه الحالة للأسفل وتتدفق الأحداث للأعلى. سيؤدي هذا النهج إلى جعل العناصر القابلة للتجميع أكثر قابلية لإعادة الاستخدام وأسهل في الاختبار.

إنشاء CompositionLocal

تتوفّر واجهتَا برمجة تطبيقات لإنشاء CompositionLocal:

  • compositionLocalOf: يؤدي تغيير القيمة المقدَّمة أثناء إعادة التركيب إلى إلغاء صلاحية المحتوى الذي يقرأ قيمة current فقط.

  • ‫staticCompositionLocalOf: على عكس compositionLocalOf، لا يتم تتبُّع عمليات قراءة staticCompositionLocalOf من خلال Compose. يؤدي تغيير القيمة إلى إعادة تركيب content لامدا بالكامل حيث يتم تقديم CompositionLocal، بدلاً من الأماكن التي تتم فيها قراءة قيمة current في التركيب فقط.

إذا كان من غير المرجّح أن تتغيّر القيمة المقدَّمة لسمة CompositionLocal أو لن تتغيّر أبدًا، استخدِم staticCompositionLocalOf للاستفادة من مزايا الأداء.

على سبيل المثال، قد يعتمد نظام تصميم التطبيق على آراء معيّنة في طريقة تمييز العناصر القابلة للتجميع باستخدام ظل لعنصر واجهة المستخدم. وبما أنّه يجب نشر الارتفاعات المختلفة للتطبيق في جميع أنحاء شجرة واجهة المستخدم، نستخدم CompositionLocal. بما أنّ قيمة CompositionLocal يتم الحصول عليها بشكل مشروط استنادًا إلى مظهر النظام، نستخدم واجهة برمجة التطبيقات compositionLocalOf:

// 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

تقديم قيم لسمة CompositionLocal

تربط السلسلة القابلة للتجميع CompositionLocalProvider القيم بمثيلات CompositionLocal للهرم المقترَح. لتقديم قيمة جديدة لسمة CompositionLocal، استخدِم دالة البادئة provides التي تربط مفتاح CompositionLocal بسمة value على النحو التالي:

// 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

استخدام CompositionLocal

تعرِض دالة CompositionLocal.current القيمة المقدَّمة من أقرب CompositionLocalProvider يقدّم قيمة لهذا CompositionLocal:

@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

بدائل يجب أخذها في الاعتبار

قد يكون CompositionLocal حلًا مفرطًا لبعض حالات الاستخدام. إذا كانت حالة الاستخدام لا تستوفي المعايير المحدّدة في قسم تحديد ما إذا كان سيتم استخدام CompositionLocal، من المحتمل أن يكون هناك حلّ آخر مناسب بشكل أفضل لحالة الاستخدام.

ضبط مَعلمات صريحة

من الجيد أن تكون واضحًا بشأن التبعيات المكوّنة. ننصحك بمنح العناصر القابلة للتجميع فقط ما تحتاجه. لتعزيز عملية فصل العناصر وإعادة استخدامها، يجب أن يحتوي كل عنصر قابل للتركيب على أقل قدر ممكن من المعلومات.

@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

استنادًا إلى الحالة، قد يكون لدى "MyDescendant" الكثير من المسؤوليات. بالإضافة إلى ذلك، يؤدي إرسال MyViewModel كمتطلّب إلى جعل MyDescendant أقل قابلية لإعادة الاستخدام لأنّه أصبحا مرتبطَين الآن. فكِّر في البديل الذي لا ينقل الاعتماد إلى العنصر اللاحق ويستخدم مبادئ عكس التحكّم التي تجعل العنصر السابق مسؤولاً عن تنفيذ المنطق:

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

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

يمكن أن يكون هذا النهج مناسبًا بشكلٍ أفضل لبعض حالات الاستخدام، لأنّه يفصل بين العنصر الفرعي وعناصره الأصلية المباشرة. تميل العناصر المكوّنة الرئيسية إلى أن تصبح أكثر تعقيدًا من أجل الحصول على عناصر مكوّنة أكثر مرونة من المستوى الأدنى.

وبالمثل، يمكن استخدام @Composable لامدا للمحتوى بالطريقة نفسها للحصول على الفوائد نفسها:

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

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