نشانگرهای پیشرفت

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

این سه مورد استفاده را که ممکن است در آن‌ها از نشانگر پیشرفت استفاده کنید درنظر بگیرید:

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

در «طراحی مواد»، دو نوع نشانگر پیشرفت وجود دارد:

  • مشخص: دقیقاً نشان می‌دهد چقدر پیشرفت حاصل شده است.
  • نامشخص: به‌طور مداوم و بدون توجه به پیشرفت، پویانمایی می‌کند.

به‌همین ترتیب، نشانگر پیشرفت می‌تواند یکی از دو شکل زیر را داشته باشد:

  • خطی: نوار افقی که از چپ به راست پر می‌شود.
  • دایره‌ای: دایره‌ای که طول خط آن افزایش می‌یابد تا کل محیط دایره را دربرگیرد.
نشانگر پیشرفت خطی در کنار نشانگر پیشرفت دایره‌ای.
شکل ۱. دو نوع نشانگر پیشرفت.

سطح میانای برنامه‌سازی کاربردی

اگرچه چندین ترکیب‌پذیر وجود دارد که می‌توانید برای ایجاد نشانگرهای پیشرفت سازگار با Material Design استفاده کنید، پارامترهای آن‌ها تفاوت چندانی ندارند. ازجمله پارامترهای کلیدی که باید درنظر داشته باشید موارد زیر است:

  • ‫progress: پیشرفت فعلی که نشانگر نمایش می‌دهد. Float را بین 0.0 و 1.0 رد کنید.
  • ‫color: رنگ نشانگر واقعی. یعنی بخشی از مؤلفه که پیشرفت را نشان می‌دهد و وقتی پیشرفت کامل می‌شود، مؤلفه را کاملاً دربرمی‌گیرد.
  • trackColor: رنگ قطعه‌ای که نشانگر روی آن کشیده شده است.

به‌روزرسانی M3 Expressive

‫Material 3 Expressive‏ LinearWavyProgressIndicator و CircularWavyProgressIndicator را به‌عنوان گزینه‌های اضافی درکنار LinearProgressIndicator و CircularProgressIndicator استاندارد معرفی می‌کند. این نشانگرها دارای سبک گرد و پیکربندی‌هایی برای ارتفاع قطعه و شکل موج هستند. سبک دیداری‌ای را انتخاب کنید که بیشترین تناسب را با محصولتان دارد.

برای اطلاعات بیشتر درباره به‌روزرسانی‌های M3 Expressive برای نشانگرهای پیشرفت، رهنمودهای نشانگر پیشرفت Material Design 3 را ببینید.

شکل ۲. اشکال موج‌دار نشانگر پیشرفت Material 3 Expressive و ارتفاع‌های متغیر قطعه.

نشانگرهای پیشرفت دارای سبک گرد و رنگارنگ و پیکربندی‌های اضافی برای انتخاب هستند، ازجمله شکل موج‌دار و ارتفاع متغیر شیار. نشانگر فعال دو گزینه شکل دارد: موج‌دار و تخت.

موج‌دار

نشانگرهای پیشرفت موج‌دار هم انواع مشخص و هم نامشخص را ارائه می‌دهند و به شما امکان می‌دهند ظاهر آن‌ها را با پارامترهای موج سفارشی‌سازی کنید تا جلوه‌های بصری گویاتری داشته باشید.

شکل ۳. نشانگرهای پیشرفت موج‌دار با پارامترهای موج گویا.

نشانگرهای خطی موج‌دار ارتفاع کل محفظه را افزایش می‌دهند.

دو نوع نشانگر پیشرفت موج‌دار وجود دارد: خطی و دایره‌ای.

نشانگر پیشرفت موج‌دار خطی معین

به‌طور پیش‌فرض، هنگام استفاده از نشانگر پیشرفت موجی، سرعت موجی اعمال می‌شود تا حرکت موجی ثابتی ایجاد شود، حتی در حالت معین. می‌توانید این حرکت موجی را با ارسال 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)
    }
}

وقتی بار کردن تاحدی کامل شده باشد، نشانگر خطی در مثال قبلی به‌صورت زیر نشان داده می‌شود:

شکل ۴. نشانگر پیشرفت خطی معین.

به‌همین ترتیب، نشانگر دایره‌ای به‌صورت زیر نشان داده می‌شود:

شکل ۵. نشانگر پیشرفت دایره‌ای معین.

نشانگرهای نامشخص

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

برای ایجاد نشانگر پیشرفت نامعین، از ترکیب‌پذیر 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")
        }
    }
}

در زیر نمونه‌ای از این پیاده‌سازی در زمانی که نشانگر فعال است آورده شده است:

شکل ۶. نشانگر پیشرفت نامشخص دایره‌ای.

در زیر نمونه‌ای از همان پیاده‌سازی، اما با LinearProgressIndicator به‌جای CircularProgressIndicator آورده شده است:

شکل ۷. نشانگر پیشرفت نامشخص خطی.

منابع بیشتر