إضافة مفتاح تبديل يمكن للمستخدمين تفعيله أو إيقافه
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يتيح المكوّن Switch للمستخدمين التبديل بين حالتَين: وضع العلامة
ووضع عدم وضع العلامة. استخدِم مفتاح تبديل للسماح للمستخدم بتنفيذ أحد الإجراءَين التاليَين:
فعِّل إعدادًا أو أوقِفه.
تفعيل ميزة أو إيقافها
حدِّد خيارًا.
يتكوّن المكوّن من جزأين: المقطع الصوتي والملصق. الإبهام هو الجزء قابل للجرّ
من المفتاح، والمسار هو الخلفية. يمكن للمستخدم سحب الإبهام
إلى اليسار أو اليمين لتغيير حالة المفتاح. ويمكنهم أيضًا النقر على
المفتاح للتأكّد من تفعيله أو إيقافه.
توافق الإصدار
يتطلّب هذا التنفيذ ضبط الحد الأدنى من إصدار حزمة SDK لمشروعك على المستوى 21 من واجهة برمجة التطبيقات أو
إصدار أحدث.
التبعيات
تنفيذ عملية تبديل
في ما يلي مثال على تنفيذ بسيط للعنصر القابل للتجميع Switch:
النتائج
الشكل 1. مفتاح تبديل لم يتم وضع علامة في المربّع بجانبهالشكل 2. مفتاح تحكّم تم وضع علامة عليه
إنشاء صورة مصغّرة مخصّصة
يمكنك تمرير أي عنصر قابل للتجميع للمَعلمة thumbContent لإنشاء Thumbnail مخصّص. في ما يلي مثال على مفتاح تبديل يستخدم رمزًا مخصّصًا ل
إصبع الإبهام:
النتائج
يشبه مظهر المربّع بدون علامة المثال الوارد في
القسم السابق. ومع ذلك، عند وضع علامة في المربّع بجانب هذا الخيار، يظهر التنفيذ على النحو التالي:
الشكل 3. مفتاح تبديل به رمز مخصّص تم وضع علامة عليه
استخدام ألوان مخصّصة
استخدِم المَعلمة colors لتغيير لون مؤشر التبديل ومسار التبديل، مع مراعاة ما إذا كان التبديل مفعّلاً.
النتائج
الشكل 4. مفتاح تبديل بألوان مخصّصة
النقاط الرئيسية
المَعلمات الأساسية:
checked: الحالة الأولية للتبديل
onCheckedChange: دالة استدعاء يتمّ تنفيذها عند تغيُّر حالة
المفتاح.
enabled: ما إذا كان مفتاح التبديل مفعَّلاً أم غير مفعَّل
colors: الألوان المستخدَمة في مفتاح التبديل
المَعلمات المتقدّمة
thumbContent: استخدِم هذا الخيار لتخصيص مظهر الإبهام عند
وضع علامة عليه.
colors: استخدِم هذا الخيار لتخصيص لون المقطع الصوتي والصورة المصغّرة.
المجموعات التي تتضمّن هذا الدليل
هذا الدليل هو جزء من مجموعات الأدلة السريعة المنظَّمة التي تتناول
أهداف تطوير Android الأوسع نطاقًا:
عرض المكونات التفاعلية
تعرَّف على كيفية استخدام الدوال القابلة للتجميع لإنشاء مكونات جميلة لواجهة المستخدم بسهولة استنادًا إلى نظام التصميم المتعدّد الأبعاد.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-05-08 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-05-08 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Add a switch that users can toggle\n\n\u003cbr /\u003e\n\nThe [`Switch`](/reference/kotlin/androidx/compose/material3/package-summary#Switch(kotlin.Boolean,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Boolean,androidx.compose.material3.SwitchColors,androidx.compose.foundation.interaction.MutableInteractionSource)) component lets users toggle between two states: checked\nand unchecked. Use a switch to let the user to do one of the\nfollowing:\n\n- Toggle a setting on or off.\n- Enable or disable a feature.\n- Select an option.\n\nThe component has two parts: the thumb and the track. The thumb is the draggable\npart of the switch, and the track is the background. The user can drag the thumb\nto the left or right to change the state of the switch. They can also tap the\nswitch to check and clear it.\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\nImplement a switch\n------------------\n\nThe following example is a minimal implementation of the `Switch` composable:\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun SwitchMinimalExample() {\n var checked by remember { mutableStateOf(true) }\n\n Switch(\n checked = checked,\n onCheckedChange = {\n checked = it\n }\n )\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Switch.kt#L65-L75\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\n**Figure 1.** An unchecked switch. **Figure 2.** A checked switch.\n\nCreate a custom thumb\n---------------------\n\nYou can pass any composable for the `thumbContent` parameter to create a custom\nthumb. The following is an example of a switch that uses a custom icon for its\nthumb:\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun SwitchWithIconExample() {\n var checked by remember { mutableStateOf(true) }\n\n Switch(\n checked = checked,\n onCheckedChange = {\n checked = it\n },\n thumbContent = if (checked) {\n {\n Icon(\n imageVector = Icons.Filled.Check,\n contentDescription = null,\n modifier = Modifier.size(SwitchDefaults.IconSize),\n )\n }\n } else {\n null\n }\n )\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Switch.kt#L80-L101\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\nThe unchecked appearance is the same as the example in\nthe preceding section. However, when checked, this implementation appears as\nfollows:\n**Figure 3.** A switch with a custom checked icon.\n\nUse custom colors\n-----------------\n\nUse the `colors` parameter to\nchange the color of a switch's thumb and track, taking into account whether the\nswitch is checked.\n\n\u003cbr /\u003e\n\n```kotlin\n@Composable\nfun SwitchWithCustomColors() {\n var checked by remember { mutableStateOf(true) }\n\n Switch(\n checked = checked,\n onCheckedChange = {\n checked = it\n },\n colors = SwitchDefaults.colors(\n checkedThumbColor = MaterialTheme.colorScheme.primary,\n checkedTrackColor = MaterialTheme.colorScheme.primaryContainer,\n uncheckedThumbColor = MaterialTheme.colorScheme.secondary,\n uncheckedTrackColor = MaterialTheme.colorScheme.secondaryContainer,\n )\n )\n}\n \n https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Switch.kt#L129-L145\n \n```\n\n\u003cbr /\u003e\n\n### Results\n\n**Figure 4.** A switch with custom colors.\n\nKey points\n----------\n\n- Basic parameters:\n\n - **`checked`**: The initial state of the switch.\n - **`onCheckedChange`**: A callback that is called when the state of the switch changes.\n - **`enabled`**: Whether the switch is enabled or disabled.\n - **`colors`**: The colors used for the switch.\n- Advanced parameters\n\n - **`thumbContent`**: Use this to customize the appearance of the thumb when it is checked.\n - **`colors`**: Use this to customize the color of the track and thumb.\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\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)"]]
