القوائم

تتيح القوائم المنسدلة للمستخدمين النقر على رمز أو حقل نصي أو مكوّن آخر، ثم تحديد خيار من قائمة الخيارات على سطح مؤقت. يوضِّح هذا الدليل كيفية إنشاء قوائم أساسية وقوائم أكثر تعقيدًا باستخدام الفواصل والرموز.

قائمة منسدلة تعرض خيارَين يشير الرمز الذي يتضمّن ثلاث نقاط رأسية إلى أنّ النقر عليه يفتح القائمة.
الشكل 1. قائمة منسدلة أساسية تتضمّن عنصرَين

واجهة برمجة التطبيقات

استخدِم المكوّنات 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... */ }
            )
        }
    }
}
Menus.kt

النقاط الرئيسية حول الرمز

  • لتحديد DropdownMenu أساسي يحتوي على عنصرَي قائمة.
  • تتحكّم المَعلمة expanded في مستوى رؤية القائمة على أنّها مُوسّعة أو مُدمجة.
  • تحدِّد المَعلمة onDismissRequest دالة ردّ اتصال يتم تنفيذها عندما يغلق المستخدم القائمة.
  • يمثّل العنصر القابل للتجميع DropdownMenuItem العناصر القابلة للاختيار في القائمة المنسدلة.
  • يؤدي النقر على IconButton إلى توسيع القائمة وتصغيرها.

النتيجة

قائمة منسدلة يتم تفعيلها من خلال رمز يضم ثلاث نقاط رأسية تعرض القائمة خيارَين قابلَين للاختيار، وهما الخيار 1 والخيار 2.
الشكل 2. قائمة منسدلة بسيطة تتضمّن خيارَين فقط

إنشاء قائمة منسدلة أطول

يمكن التمرير في 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... */ }
                )
            }
        }
    }
}
Menus.kt

النقاط الرئيسية حول الرمز

  • يمكن تمرير DropdownMenu عندما يتجاوز إجمالي ارتفاع محتواه المساحة المتوفّرة. تُنشئ هذه التعليمة البرمجية DropdownMenu قابلاً للتنقّل يعرض 100 عنصر نائب.
  • تُنشئ حلقة forEach DropdownMenuItem عنصرًا قابلاً للتجميع ديناميكيًا. لا يتم إنشاء العناصر بشكلٍ كسول، ما يعني أنّه يتم إنشاء كل العناصر المنسدلة الـ 100 وتوفّرها في التركيب.
  • يؤدي النقر على IconButton إلى توسيع DropdownMenu وتصغيرها.
  • تتيح لك دالة onClick lambda ضمن كل DropdownMenuItem تحديد الإجراء الذي يتم تنفيذه عندما يختار المستخدم عنصر قائمة.

النتيجة

ينتج مقتطف الرمز البرمجي السابق القائمة القابلة للتنقّل التالية:

قائمة منسدلة تحتوي على العديد من الخيارات، وتتطلّب الانتقال للأعلى أو للأسفل لعرض كل العناصر
الشكل 3. قائمة منسدلة طويلة يمكن التمرير فيها

إنشاء قائمة منسدلة أطول باستخدام فواصل

يعرض المقتطف التالي عملية تنفيذ أكثر تقدمًا لقائمة منسدلة. في هذا المقتطف، تتم إضافة الرموز البادئة واللاحقة إلى عناصر القائمة، وتعمل المقسمات على فصل مجموعات عناصر القائمة.

@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... */ }
            )
        }
    }
}
Menus.kt

يحدِّد هذا الرمز DropdownMenu ضمن Box.

النقاط الرئيسية حول الرمز

  • تُضيف المَعلمتَان leadingIcon وtrailingIcon رموزًا إلى بدايةDropdownMenuItem و نهايته.
  • يؤدي الرمز IconButton إلى توسيع القائمة.
  • يحتوي DropdownMenu على عدّة عناصر DropdownMenuItem قابلة للتجميع، يمثّل كلّ منها إجراءً قابلاً للاختيار.
  • تُدرِج العناصر القابلة للتجميع HorizontalDivider خطًا أفقيًا لفصل مجموعات عناصر القائمة.

النتيجة

يعرض المقتطف السابق قائمة منسدلة تتضمّن رموزًا ومقسمات:

قائمة منسدلة تتضمّن أقسامًا للملف الشخصي والإعدادات وإرسال الملاحظات والقسم "لمحة"
الشكل 4. قائمة منسدلة مقسمة إلى أقسام تتضمّن رموزًا في البداية والنهاية

مصادر إضافية