القوائم

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

الشكل 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 إلى توسيع القائمة وتصغيرها.

النتيجة

الشكل 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. قائمة منسدلة مقسمة إلى أقسام تتضمّن رموزًا في البداية والنهاية

مصادر إضافية

• لغة تصميم Material: القوائم