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

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

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

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

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

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

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

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

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

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

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

تحديث M3 Expressive

يقدّم Material 3 Expressive LinearWavyProgressIndicator وCircularWavyProgressIndicator كخيارات إضافية إلى جانب LinearProgressIndicator وCircularProgressIndicator المسطّحَين العاديَين. تتميّز هذه المؤشرات بنمط دائري وإعدادات لارتفاع المسار وشكل الموجة. اختَر النمط المرئي الأنسب لمنتجك.

لمزيد من المعلومات حول تعديلات M3 Expressive لمؤشرات مستوى التقدّم، يُرجى الاطّلاع على إرشادات مؤشر مستوى التقدّم في التصميم المتعدد الأبعاد 3.

الشكل 2. أشكال متموّجة لمؤشر التقدّم في Material 3 Expressive وارتفاعات متغيّرة للمسار

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

عالم مموَّج

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

الشكل 3. مؤشرات تقدّم متموّجة مع مَعلمات موجية معبّرة

تزيد المؤشرات الخطية المتموجة من ارتفاع الحاوية الإجمالية.

هناك نوعان من مؤشرات التقدّم المتموّجة: الخطية والدائرية.

مؤشر تقدّم خطي مموّج محدّد

بشكل تلقائي، عند استخدام مؤشر تقدّم متموّج، يتم تطبيق سرعة موجة لإنشاء حركة موجية ثابتة، حتى في الوضع المحدّد. يمكنك إيقاف حركة الموجة هذه من خلال تمرير 0.dp إلى waveSpeed.

يوضّح المقتطف التالي كيفية تنفيذ مكوّن LinearWavyProgressIndicator محدّد يتحكّم فيه مكوّن Slider:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

مؤشر تقدّم خطي مموّج غير محدّد

استخدم المؤشرات غير المحددة لإظهار أن عملية ما تحدث عندما يكون وقت الانتظار غير معروف. يوضّح المقتطف التالي كيفية تنفيذ LinearWavyProgressIndicator غير محدّد:

@Composable
fun IndeterminateLinearWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() }
}

مؤشر تقدّم دائري مموّج محدّد

يمكن أن يجعل الشكل المتموّج العمليات الطويلة تبدو أقل ثباتًا، ومن الأفضل استخدامه عندما يكون الأسلوب الأكثر تعبيرًا مناسبًا. يوضّح المقتطف التالي كيفية تنفيذ CircularWavyProgressIndicator محدّد يتم التحكّم فيه من خلال Slider:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

مؤشر تقدّم دائري مموج غير محدّد

يجب أن تكون مؤشرات التقدم الدائرية في منتصف الحاوية أو الصفحة التي يتم تحميلها مباشرةً، مثل زر أو بطاقة. يوضّح المقتطف التالي كيفية تنفيذ CircularWavyProgressIndicator غير محدّد:

@Composable
fun IndeterminateCircularWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator() }
}

ثابتة

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

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

يوضّح المقتطف التالي كيفية تنفيذ مكوّن LinearProgressIndicator محدّد يتحكّم فيه مكوّن Slider:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

يوضّح المقتطف التالي كيفية تنفيذ مكوّن CircularProgressIndicator محدّد يتحكّم فيه مكوّن Slider:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

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

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableFloatStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope
    // Animate between progress updates so the indicator fills smoothly.
    val animatedProgress by animateFloatAsState(
        targetValue = currentProgress,
        animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
    )

    if (loading) {
        LinearProgressIndicator(
            progress = { animatedProgress },
            modifier = Modifier.fillMaxWidth(),
        )
    } else {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }) {
            Text("Start loading")
        }
    }
}

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

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

الشكل 4. مؤشر تقدّم خطي محدّد

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

الشكل 5. مؤشر تقدّم دائري محدّد

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

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

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

@Composable
fun IndeterminateLinearProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator() }
}

يوضّح المقتطف التالي كيفية تنفيذ CircularProgressIndicator غير محدّد:

@Composable
fun IndeterminateCircularProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator() }
}

يوضّح المثال التالي كيفية تبديل مؤشر غير محدّد من خلال الضغط على زر. يوضّح هذا المثال أيضًا كيفية تمرير قيم للمَعلمتَين color وtrackColor لتخصيص مظهر المؤشر:

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

    if (loading) {
        CircularProgressIndicator(
            modifier = Modifier.size(64.dp),
            color = MaterialTheme.colorScheme.secondary,
            trackColor = MaterialTheme.colorScheme.surfaceVariant,
        )
    } else {
        Button(onClick = { loading = true }) {
            Text("Start loading")
        }
    }
}

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

الشكل 6: مؤشر تقدّم دائري غير محدّد

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

الشكل 7. مؤشر تقدّم خطي غير محدّد

مراجع إضافية