تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تعرِض مؤشرات التقدّم حالة العملية بشكل مرئي. وتستخدم هذه التطبيقات الصور المتحركة
للفت انتباه المستخدم إلى مدى قرب اكتمال العملية، مثل
تحميل البيانات أو معالجتها. ويمكن أن تشير أيضًا إلى أنّه تتم معالجة الطلب، بدون الإشارة إلى مدى قرب اكتماله.
فكِّر في حالات الاستخدام الثلاث التالية التي قد تستخدم فيها مؤشر التقدّم:
تحميل المحتوى: أثناء جلب المحتوى من شبكة، مثل تحميل
صورة أو بيانات لملف شخصي لأحد المستخدمين
تحميل الملف: يمكنك تقديم ملاحظات للمستخدم حول الوقت الذي قد يستغرقه التحميل.
المعالجة الطويلة: أثناء معالجة التطبيق لكمية كبيرة من البيانات،
أعرِف المستخدم بمدى اكتمال العملية.
في التصميم المتعدّد الأبعاد، هناك نوعان من مؤشرات التقدم:
تحديد: تعرِض هذه الحالة مقدار التقدّم الذي تمّ تحقيقه بدقة.
غير محدّد: يتم تشغيل الصور المتحركة باستمرار بغض النظر عن مستوى التقدّم.
وبالمثل، يمكن أن يتّخذ مؤشر التقدّم أحد الشكلَين التاليَين:
خطي: شريط أفقي يملأ من اليسار إلى اليمين
دائري: دائرة يزداد طولها حتى تشمل
محيط الدائرة بالكامل.
توافق الإصدار
يتطلّب هذا التنفيذ ضبط الحد الأدنى من إصدار حزمة SDK لمشروعك على المستوى 21 من واجهة برمجة التطبيقات أو
إصدار أحدث.
يوفّر المقتطف التالي مثالاً مفصّلاً نسبيًا. عندما يضغط المستخدم
على الزر، يعرض التطبيق مؤشر التقدّم ويشغّل دالّة برمجية
متعدّدة المهام تزيد قيمة progress تدريجيًا. يؤدي ذلك إلى تكرار
مؤشر التقدّم صعودًا بدوره.
النتائج
عند اكتمال التحميل جزئيًا، يظهر المؤشر الخطي في المثال السابق
على النحو التالي:
وبالمثل، يظهر المؤشر الدائري على النحو التالي:
إنشاء مؤشرات غير محدّدة
لا يشير المؤشر غير المحدّد إلى مدى قرب اكتمال العملية، ولكنه يستخدم الحركة للإشارة إلى المستخدم بأنّ المعالجة جارية،
ولكن بدون تحديد أي درجة من الاكتمال.
لإنشاء مؤشر تقدم غير محدّد، استخدِم العنصر القابل للتجميع LinearProgressIndicator
أو CircularProgressIndicator، ولكن لا تُدخل قيمة لprogress. يوضّح المثال التالي كيفية تبديل أحد مؤشرات
القيمة غير المحدّدة من خلال الضغط على زر.
النتائج
في ما يلي مثال على هذا التنفيذ عندما يكون المؤشر نشطًا:
في ما يلي مثال على عملية التنفيذ نفسها ولكن باستخدام
LinearProgressIndicator بدلاً من CircularProgressIndicator.
النقاط الرئيسية
على الرغم من توفّر العديد من العناصر القابلة للتجميع التي يمكنك استخدامها لإنشاء مؤشرات مستوى التقدّم
المتوافقة مع لغة تصميم Material Design، لا تختلف مَعلماتها كثيرًا.
في ما يلي المَعلمات الرئيسية التي يجب أخذها في الاعتبار:
progress: مستوى التقدّم الحالي الذي يعرضه المؤشر مرِّر Float
بين 0.0 و1.0.
color: لون المؤشر، أي الجزء من العنصر الذي يعكس مستوى التقدّم والذي يشمل العنصر بالكامل عند اكتمال مستوى التقدّم
trackColor: لون المسار الذي يتم رسم المؤشر عليه
المجموعات التي تتضمّن هذا الدليل
هذا الدليل هو جزء من مجموعات الأدلة السريعة المنظَّمة التي تتناول
أهداف تطوير Android الأوسع نطاقًا:
عرض المكونات التفاعلية
تعرَّف على كيفية استخدام الدوال القابلة للتجميع لإنشاء مكونات جميلة لواجهة المستخدم بسهولة استنادًا إلى نظام التصميم المتعدّد الأبعاد.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Create a progress indicator\n\n\u003cbr /\u003e\n\nProgress indicators visually surface the status of an operation. They use motion\nto bring to the user's attention how near completion the process is, such as\nloading or processing data. They can also signify that processing is taking\nplace, without reference to how close to completion it might be.\n\nConsider these three use cases where you might use a progress indicator:\n\n- **Loading content**: While fetching content from a network, such as loading an image or data for a user profile.\n- **File upload**: Give the user feedback on how long the upload might take.\n- **Long processing**: While an app is processing a large amount of data, convey to the user how much of the total is complete.\n\nIn Material Design, there are two types of progress indicator:\n\n- [Determinate](#determinate): Displays exactly how much progress has been made.\n- [Indeterminate](#indeterminate): Animates continually without regard to progress.\n\nLikewise, a progress indicator can take one of the two following forms:\n\n- **Linear**: A horizontal bar that fills from left to right.\n- **Circular**: A circle whose stroke grows in length until it encompasses the full circumference of the circle.\n\nVersion compatibility\n---------------------\n\nThis implementation requires that your project minSDK be set to API level 21 or\nhigher.\n\n### Dependencies\n\n### Kotlin\n\n\u003cbr /\u003e\n\n```kotlin\n implementation(platform(\"androidx.compose:compose-bom:2025.08.00\"))\n \n```\n\n\u003cbr /\u003e\n\n### Groovy\n\n\u003cbr /\u003e\n\n```groovy\n implementation platform('androidx.compose:compose-bom:2025.08.00')\n \n```\n\n\u003cbr /\u003e\n\nCreate determinate indicators\n-----------------------------\n\nA determinate indicator reflects exactly how complete an action is. Use either\nthe [`LinearProgressIndicator`](/reference/kotlin/androidx/compose/material3/package-summary#LinearProgressIndicator(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.StrokeCap,androidx.compose.ui.unit.Dp)) or [`CircularProgressIndicator`](/reference/kotlin/androidx/compose/material3/package-summary#CircularProgressIndicator(androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.StrokeCap,androidx.compose.ui.unit.Dp))\ncomposables and pass a value for the `progress` parameter.\n\nThe following snippet provides a relatively detailed example. When the user\npresses the button, the app both displays the progress indicator, and launches a\ncoroutine that gradually increases the value of `progress`. This causes the\nprogress indicator to iterate up in turn.\n| **Note:** The following example uses a coroutine to do the work of iterating the `progress` value because it would otherwise block the UI thread.\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun LinearDeterminateIndicator() {\n var currentProgress by remember { mutableStateOf(0f) }\n var loading by remember { mutableStateOf(false) }\n val scope = rememberCoroutineScope() // Create a coroutine scope\n\n Column(\n verticalArrangement = Arrangement.spacedBy(12.dp),\n horizontalAlignment = Alignment.CenterHorizontally,\n modifier = Modifier.fillMaxWidth()\n ) {\n Button(onClick = {\n loading = true\n scope.launch {\n loadProgress { progress -\u003e\n currentProgress = progress\n }\n loading = false // Reset loading when the coroutine finishes\n }\n }, enabled = !loading) {\n Text(\"Start loading\")\n }\n\n if (loading) {\n LinearProgressIndicator(\n progress = { currentProgress },\n modifier = Modifier.fillMaxWidth(),\n )\n }\n }\n}\n\n/** Iterate the progress value */\nsuspend fun loadProgress(updateProgress: (Float) -\u003e Unit) {\n for (i in 1..100) {\n updateProgress(i.toFloat() / 100)\n delay(100)\n }\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/ProgressIndicator.kt#L66-L104\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\nWhen loading is partially complete, the linear indicator in the preceding\nexample appears as follows:\n\nLikewise, the circular indicator appears as follows:\n\nCreate indeterminate indicators\n-------------------------------\n\nAn indeterminate indicator does not reflect how close to completion an operation\nis. Rather, it uses motion to indicate to the user that processing is ongoing,\nthough without specifying any degree of completion.\n\nTo create an indeterminate progress indicator, use the `LinearProgressIndicator`\nor `CircularProgressIndicator` composable, but don't pass in a value for\n`progress`. The following example demonstrates how you can toggle an\nindeterminate indicator with a button press.\n| **Note:** This example also demonstrates how you can pass values for the `color` and `trackColor` parameters to customize the appearance of the indicator.\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun IndeterminateCircularIndicator() {\n var loading by remember { mutableStateOf(false) }\n\n Button(onClick = { loading = true }, enabled = !loading) {\n Text(\"Start loading\")\n }\n\n if (!loading) return\n\n CircularProgressIndicator(\n modifier = Modifier.width(64.dp),\n color = MaterialTheme.colorScheme.secondary,\n trackColor = MaterialTheme.colorScheme.surfaceVariant,\n )\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/ProgressIndicator.kt#L160-L175\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\nThe following is an example of this implementation when the indicator is active:\n\nThe following is an example of the same implementation but with\n`LinearProgressIndicator` instead of `CircularProgressIndicator`.\n\nKey points\n----------\n\nAlthough there are several composables you can use to create progress indicators\nconsistent with Material Design, their parameters don't differ greatly.\nAmong the key parameters you should keep in mind are the following:\n\n- `progress`: The current progress that the indicator displays. Pass a `Float` between `0.0` and `1.0`.\n- `color`: The color of the indicator, that is, the part of the component that reflects progress and which fully encompasses the component when progress is complete.\n- `trackColor`: The color of the track over which the indicator is drawn.\n\n| **Note:** The APIs for `LinearProgressIndicator` and `CircularProgressIndicator` are essentially the same and the way you use either one is identical.\n\nCollections that contain this guide\n-----------------------------------\n\nThis guide is part of these curated Quick Guide collections that cover\nbroader Android development goals: \n\n### Display interactive components\n\nLearn how composable functions can enable you to easily create beautiful UI components based on the Material Design design system. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-interactive-components) \n\n### Display a list or grid\n\nLists and grids allow your app to display collections in a visually pleasing form that's easy for users to consume. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-a-list-or-grid) \n\nHave questions or feedback\n--------------------------\n\nGo to our frequently asked questions page and learn about quick guides or reach out and let us know your thoughts. \n[Go to FAQ](/quick-guides/faq) [Leave feedback](https://issuetracker.google.com/issues/new?component=1573691&template=1993320)"]]
