القوائم

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

تظهر قائمة منسدلة تتضمّن خيارَين. يشير رمز النقاط الثلاث العمودية إلى أنّ النقر عليه يفتح القائمة.
الشكل 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(painter = rememberVectorPainter(AppIcons.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 إلى توسيع القائمة وتصغيرها.

النتيجة

قائمة منسدلة يتم تشغيلها بواسطة رمز بثلاث نقاط عمودية. تعرض القائمة خيارَين يمكن تحديدهما، هما الخيار 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(painter = rememberVectorPainter(AppIcons.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 أو تصغيره.
  • تتيح لك دالة lambda onClick ضمن كل DropdownMenuItem تحديد الإجراء الذي يتم تنفيذه عندما يختار المستخدم عنصر قائمة.

النتيجة

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

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

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

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

@Composable
fun DropdownMenuWithDetails() {
    var expanded by remember { mutableStateOf(false) }

    Box(
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp)
    ) {
        IconButton(onClick = { expanded = !expanded }) {
            Icon(painter = rememberVectorPainter(AppIcons.MoreVert), contentDescription = "More options")
        }
        DropdownMenu(
            expanded = expanded,
            onDismissRequest = { expanded = false }
        ) {
            // First section
            DropdownMenuItem(
                text = { Text("Profile") },
                leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Person), contentDescription = null) },
                onClick = { /* Do something... */ }
            )
            DropdownMenuItem(
                text = { Text("Settings") },
                leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Settings), contentDescription = null) },
                onClick = { /* Do something... */ }
            )

            HorizontalDivider()

            // Second section
            DropdownMenuItem(
                text = { Text("Send Feedback") },
                leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Feedback), contentDescription = null) },
                trailingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Send), contentDescription = null) },
                onClick = { /* Do something... */ }
            )

            HorizontalDivider()

            // Third section
            DropdownMenuItem(
                text = { Text("About") },
                leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Info), contentDescription = null) },
                onClick = { /* Do something... */ }
            )
            DropdownMenuItem(
                text = { Text("Help") },
                leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Help), contentDescription = null) },
                trailingIcon = { Icon(painter = rememberVectorPainter(AppIcons.OpenInNew), contentDescription = null) },
                onClick = { /* Do something... */ }
            )
        }
    }
}

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

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

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

النتيجة

ينتج عن المقتطف السابق قائمة منسدلة تحتوي على رموز وفواصل:

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

مراجع إضافية