شاخص های پیشرفت

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

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

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

در طراحی متریال، دو نوع شاخص پیشرفت وجود دارد:

• Determinate : دقیقاً میزان پیشرفت را نشان می دهد.
• نامشخص : به طور مداوم بدون توجه به پیشرفت متحرک می شود.

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

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

سطح API

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

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

تعیین شاخص ها

یک شاخص معین دقیقاً نشان می دهد که یک عمل چقدر کامل است. از ترکیب‌پذیرهای LinearProgressIndicator یا CircularProgressIndicator استفاده کنید و مقداری را برای پارامتر progress ارسال کنید.

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

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableStateOf(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)
    }
}
ProgressIndicator.kt

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

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

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

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

برای ایجاد یک نشانگر پیشرفت نامشخص، از 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,
    )
}
ProgressIndicator.kt

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

نمونه زیر نمونه ای از همین پیاده سازی است اما با LinearProgressIndicator به جای CircularProgressIndicator .

منابع اضافی

• اسناد رابط کاربری مواد