القوائم

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

قائمة منسدلة تتضمّن خيارَين تشير الأيقونة التي تتضمّن ثلاث نقاط عمودية إلى أنّ النقر عليها يفتح القائمة.
الشكل 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 قابلة للإنشاء. لا يتم إنشاء العناصر بشكل مؤجّل، ما يعني أنّه يتم إنشاء جميع العناصر المئة في القائمة المنسدلة وتكون متوفّرة في التركيبة.
  • يؤدي الرمز 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. قائمة منسدلة مقسّمة إلى أقسام مع أيقونات في المقدّمة والمؤخّرة

مراجع إضافية