تتيح القوائم المنسدلة للمستخدمين النقر على رمز أو حقل نص أو مكوّن آخر، ثم تحديد خيار من قائمة الخيارات على سطح مؤقت. يوضِّح هذا الدليل كيفية إنشاء قوائم أساسية وقوائم أكثر تعقيدًا باستخدام الفواصل والرموز.
واجهة برمجة التطبيقات
استخدِم المكوّنات DropdownMenu
وDropdownMenuItem
وIconButton
لتطبيق قائمة منسدلة مخصّصة. يتم استخدام المكوّنين DropdownMenu
و
DropdownMenuItem
لعرض عناصر القائمة، في حين أنّ
IconButton
هو العامل المشغِّل لعرض القائمة المنسدلة أو إخفائها.
تشمل المَعلمات الرئيسية لمكوّن DropdownMenu
ما يلي:
expanded
: يشير إلى ما إذا كانت القائمة مرئية.onDismissRequest
: يُستخدَم هذا الإجراء للتعامل مع إغلاق القائمة.-
content
: محتوى القائمة القابل للتجميع، والذي يحتوي عادةً علىDropdownMenuItem
عناصر قابلة للتجميع.
تشمل المَعلمات الرئيسية لـ DropdownMenuItem
ما يلي:
-
text
: لتحديد المحتوى المعروض في عنصر القائمة -
onClick
: دالة ردّ اتصال لمعالجة التفاعل مع العنصر في القائمة
إنشاء قائمة منسدلة أساسية
يوضّح المقتطف التالي الحد الأدنى لتنفيذ DropdownMenu
:
@Composable fun MinimalDropdownMenu() { var expanded by remember { mutableStateOf(false) } Box( modifier = Modifier .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(Icons.Default.MoreVert, contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { DropdownMenuItem( text = { Text("Option 1") }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Option 2") }, onClick = { /* Do something... */ } ) } } }
النقاط الرئيسية حول الرمز
- يحدِّد
DropdownMenu
أساسيًا يحتوي على عنصرَي قائمة. - تتحكّم المَعلمة
expanded
في مستوى رؤية القائمة على أنّها مُوسّعة أو مُدمجة. - تحدِّد المَعلمة
onDismissRequest
دالة ردّ اتصال يتم تنفيذها عندما يغلق المستخدم القائمة. - يمثّل العنصر القابل للإنشاء
DropdownMenuItem
العناصر القابلة للاختيار في القائمة المنسدلة. - يؤدي النقر على
IconButton
إلى توسيع القائمة وتصغيرها.
النتيجة
إنشاء قائمة منسدلة أطول
يمكن التمرير في DropdownMenu
تلقائيًا إذا تعذّر عرض كل عناصر القائمة
في آنٍ واحد. ينشئ المقتطف التالي قائمة منسدلة
أطول يمكن التمرير فيها:
@Composable fun LongBasicDropdownMenu() { var expanded by remember { mutableStateOf(false) } // Placeholder list of 100 strings for demonstration val menuItemData = List(100) { "Option ${it + 1}" } Box( modifier = Modifier .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(Icons.Default.MoreVert, contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { menuItemData.forEach { option -> DropdownMenuItem( text = { Text(option) }, onClick = { /* Do something... */ } ) } } } }
النقاط الرئيسية حول الرمز
- يمكن تمرير
DropdownMenu
عندما يتجاوز إجمالي ارتفاع محتواه المساحة المتوفّرة. تُنشئ هذه التعليمة البرمجيةDropdownMenu
قابلة للتنقّل تعرِض 100 عنصر نائب. - تُنشئ حلقة
forEach
DropdownMenuItem
عنصرًا قابلاً للتجميع ديناميكيًا. لا يتم إنشاء العناصر بشكلٍ كسول، ما يعني أنّه يتم إنشاء كل العناصر الـ 100 في القائمة المنسدلة وتصبح متوفّرة في التركيب. - يؤدي النقر على
IconButton
إلى توسيعDropdownMenu
وتصغيرها. - تتيح لك دالة
onClick
lambda ضمن كلDropdownMenuItem
تحديد الإجراء الذي يتم تنفيذه عندما يختار المستخدم عنصر قائمة.
النتيجة
ينتج مقتطف الرمز البرمجي السابق القائمة القابلة للتنقّل التالية:
إنشاء قائمة منسدلة أطول باستخدام فواصل
يعرض المقتطف التالي عملية تنفيذ أكثر تقدمًا لقائمة منسدلة. في هذا المقتطف، تتم إضافة الرموز البادئة واللاحقة إلى عناصر القائمة، وتعمل المقسمات على فصل مجموعات عناصر القائمة.
@Composable fun DropdownMenuWithDetails() { var expanded by remember { mutableStateOf(false) } Box( modifier = Modifier .fillMaxWidth() .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(Icons.Default.MoreVert, contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { // First section DropdownMenuItem( text = { Text("Profile") }, leadingIcon = { Icon(Icons.Outlined.Person, contentDescription = null) }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Settings") }, leadingIcon = { Icon(Icons.Outlined.Settings, contentDescription = null) }, onClick = { /* Do something... */ } ) HorizontalDivider() // Second section DropdownMenuItem( text = { Text("Send Feedback") }, leadingIcon = { Icon(Icons.Outlined.Feedback, contentDescription = null) }, trailingIcon = { Icon(Icons.AutoMirrored.Outlined.Send, contentDescription = null) }, onClick = { /* Do something... */ } ) HorizontalDivider() // Third section DropdownMenuItem( text = { Text("About") }, leadingIcon = { Icon(Icons.Outlined.Info, contentDescription = null) }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Help") }, leadingIcon = { Icon(Icons.AutoMirrored.Outlined.Help, contentDescription = null) }, trailingIcon = { Icon(Icons.AutoMirrored.Outlined.OpenInNew, contentDescription = null) }, onClick = { /* Do something... */ } ) } } }
يحدِّد هذا الرمز DropdownMenu
ضمن Box
.
النقاط الرئيسية حول الرمز
- تُضيف المَعلمتَان
leadingIcon
وtrailingIcon
رموزًا إلى بدايةDropdownMenuItem
و نهايته. - يؤدي الرمز
IconButton
إلى توسيع القائمة. - يحتوي
DropdownMenu
على عدة عناصرDropdownMenuItem
قابلة للتجميع، يمثّل كلّ منها إجراءً قابلاً للاختيار. - تُدرِج العناصر القابلة للتجميع
HorizontalDivider
خطًا أفقيًا لفصل مجموعات عناصر القائمة.
النتيجة
يعرض المقتطف السابق قائمة منسدلة تتضمّن رموزًا ومقسمات:
مصادر إضافية
- لغة تصميم Material: القوائم