القوائم

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

قائمة منسدلة تتضمّن خيارَين تشير الأيقونة التي تتضمّن ثلاث نقاط عمودية إلى أنّ النقر عليها يفتح القائمة.
الشكل 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... */ }
            )
        }
    }
}

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

  • يحدّد 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... */ }
                )
            }
        }
    }
}

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

  • يمكن الانتقال عموديًا في 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(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 تُدرِج الدوال القابلة للإنشاء خطًا أفقيًا لفصل مجموعات عناصر القائمة.

النتيجة

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

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

مراجع إضافية