مؤشرات التقدم

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

ضع في اعتبارك حالات الاستخدام الثلاث هذه حيث يمكنك استخدام مؤشر التقدم:

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

في التصميم المتعدد الأبعاد، هناك نوعان من مؤشرات مستوى التقدّم:

  • محدّد: يعرض مقدار التقدّم الذي تم إحرازه بالضبط.
  • غير محدّد: يتم عرض الصور المتحركة باستمرار بدون مراعاة مستوى التقدّم.

وبالمثل، يمكن أن يتخذ مؤشر التقدم أحد الشكلين التاليين:

  • خطّي: شريط أفقي يمتلئ من اليسار إلى اليمين.
  • دائري: دائرة يزداد طول خطها حتى يشمل محيط الدائرة بالكامل.
مؤشر تقدّم خطي بجانب مؤشر تقدّم دائري
الشكل 1. نوعا مؤشرات مستوى التقدّم

مساحة عرض واجهة برمجة التطبيقات

على الرغم من توفّر العديد من الدوال المركّبة التي يمكنك استخدامها لإنشاء مؤشرات تقدّم متوافقة مع "التصميم المتعدد الأبعاد"، فإنّ مَعلماتها لا تختلف كثيرًا. من بين المعلمات الرئيسية التي يجب أن تضعها في اعتبارك ما يلي:

  • ‫progress: مستوى التقدّم الحالي الذي يعرضه المؤشر يجب إدخال قيمة Float بين 0.0 و1.0.
  • ‫color: لون المؤشر الفعلي أي الجزء من المكوّن الذي يعكس مستوى التقدّم ويشمل المكوّن بالكامل عند اكتمال مستوى التقدّم.
  • trackColor: لون المسار الذي يظهر عليه المؤشر.

مؤشرات محدّدة

يعكس المؤشر المحدّد مدى اكتمال الإجراء بدقة. يمكنك استخدام الدالة المركّبة LinearProgressIndicator أو CircularProgressIndicator وتمرير قيمة للمَعلمة progress.

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

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableFloatStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope

    Column(
        verticalArrangement = Arrangement.spacedBy(12.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.fillMaxWidth()
    ) {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }, enabled = !loading) {
            Text("Start loading")
        }

        if (loading) {
            LinearProgressIndicator(
                progress = { currentProgress },
                modifier = Modifier.fillMaxWidth(),
            )
        }
    }
}

/** Iterate the progress value */
suspend fun loadProgress(updateProgress: (Float) -> Unit) {
    for (i in 1..100) {
        updateProgress(i.toFloat() / 100)
        delay(100)
    }
}

عند اكتمال التحميل جزئيًا، يظهر المؤشر الخطي في المثال السابق على النحو التالي:

وبالمثل، يظهر المؤشر الدائري على النحو التالي:

المؤشرات غير المحدّدة

لا يعكس المؤشر غير المحدّد مدى اقتراب العملية من الاكتمال، بل يستخدم الحركة للإشارة إلى المستخدم بأنّ المعالجة جارية، ولكن بدون تحديد أي درجة من الاكتمال.

لإنشاء مؤشر تقدّم غير محدّد، استخدِم الدالة المركّبة LinearProgressIndicator أو CircularProgressIndicator، ولكن لا تُدخِل قيمة لـ progress. يوضّح المثال التالي كيفية تبديل مؤشر غير محدّد من خلال الضغط على زر.

@Composable
fun IndeterminateCircularIndicator() {
    var loading by remember { mutableStateOf(false) }

    Button(onClick = { loading = true }, enabled = !loading) {
        Text("Start loading")
    }

    if (!loading) return

    CircularProgressIndicator(
        modifier = Modifier.width(64.dp),
        color = MaterialTheme.colorScheme.secondary,
        trackColor = MaterialTheme.colorScheme.surfaceVariant,
    )
}

في ما يلي مثال على هذا التنفيذ عندما يكون المؤشر نشطًا:

في ما يلي مثال على عملية التنفيذ نفسها ولكن باستخدام LinearProgressIndicator بدلاً من CircularProgressIndicator.

مراجع إضافية