نشانگرهای پیشرفت وضعیت عملیات را بهصورت دیداری نشان میدهند. آنها از حرکت استفاده میکنند تا توجه کاربر را به این جلب کنند که فرایند چقدر به تکمیل نزدیک است، مثلاً بار کردن یا پردازش دادهها. همچنین میتوانند نشان دهند که پردازش درحال انجام است، بدون اینکه اشارهای به میزان تکمیل آن داشته باشند.
این سه مورد استفاده را که ممکن است در آنها از نشانگر پیشرفت استفاده کنید درنظر بگیرید:
- درحال بار کردن محتوا: هنگام واکشی محتوا از شبکه، مثلاً بار کردن تصویر یا داده برای نمایه کاربر.
- بارگذاری فایل: به کاربر بازخورد دهید که بارگذاری ممکن است چقدر طول بکشد.
- پردازش طولانی: وقتی برنامهای درحال پردازش حجم زیادی از دادهها است، به کاربر اطلاع دهید چه مقدار از کل فرایند تکمیل شده است.
در «طراحی مواد»، دو نوع نشانگر پیشرفت وجود دارد:
- مشخص: دقیقاً نشان میدهد چقدر پیشرفت حاصل شده است.
- نامشخص: بهطور مداوم و بدون توجه به پیشرفت، پویانمایی میکند.
بههمین ترتیب، نشانگر پیشرفت میتواند یکی از دو شکل زیر را داشته باشد:
- خطی: نوار افقی که از چپ به راست پر میشود.
- دایرهای: دایرهای که طول خط آن افزایش مییابد تا کل محیط دایره را دربرگیرد.
سطح میانای برنامهسازی کاربردی
اگرچه چندین ترکیبپذیر وجود دارد که میتوانید برای ایجاد نشانگرهای پیشرفت سازگار با Material Design استفاده کنید، پارامترهای آنها تفاوت چندانی ندارند. ازجمله پارامترهای کلیدی که باید درنظر داشته باشید موارد زیر است:
-
progress: پیشرفت فعلی که نشانگر نمایش میدهد.Floatرا بین0.0و1.0رد کنید. -
color: رنگ نشانگر واقعی. یعنی بخشی از مؤلفه که پیشرفت را نشان میدهد و وقتی پیشرفت کامل میشود، مؤلفه را کاملاً دربرمیگیرد. trackColor: رنگ قطعهای که نشانگر روی آن کشیده شده است.
بهروزرسانی M3 Expressive
Material 3 Expressive LinearWavyProgressIndicator و
CircularWavyProgressIndicator را بهعنوان گزینههای اضافی درکنار
LinearProgressIndicator و CircularProgressIndicator استاندارد معرفی میکند. این نشانگرها
دارای سبک گرد و پیکربندیهایی برای ارتفاع قطعه و شکل موج هستند.
سبک دیداریای را انتخاب کنید که بیشترین تناسب را با محصولتان دارد.
برای اطلاعات بیشتر درباره بهروزرسانیهای M3 Expressive برای نشانگرهای پیشرفت، رهنمودهای نشانگر پیشرفت Material Design 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) } }
وقتی بار کردن تاحدی کامل شده باشد، نشانگر خطی در مثال قبلی بهصورت زیر نشان داده میشود:
بههمین ترتیب، نشانگر دایرهای بهصورت زیر نشان داده میشود:
نشانگرهای نامشخص
نشانگر نامعین نشان نمیدهد که عملیات چقدر به تکمیل نزدیک است. درعوض، از حرکت برای نشان دادن به کاربر استفاده میکند که پردازش درحال انجام است، اما هیچ درجهای از تکمیل را مشخص نمیکند.
برای ایجاد نشانگر پیشرفت نامعین، از ترکیبپذیر 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 آورده شده است: