مجموعات الأزرار

مجموعات الأزرار هي أزرار منظَّمة تتم إضافة تفاعلات بينها من خلال تطبيق تغييرات منسَّقة على الشكل والحركة والعرض على الأزرار وأزرار الرموز. هناك نوعان من مجموعات الأزرار:

  1. مجموعة الأزرار العادية: تضيف تفاعلاً بين الأزرار المتجاورة بحيث تستجيب لبعضها البعض عند الضغط عليها.
  2. مجموعة الأزرار المتصلة: تجمّع أزرار الإيقاف/التفعيل للسماح للمستخدمين بتحديد الخيارات أو تبديل طرق العرض أو ترتيب العناصر على الصفحة.
مجموعات الأزرار العادية على اليمين ومجموعات الأزرار المتصلة على اليسار.
الشكل 1. مجموعات الأزرار العادية (1، على اليمين) ومجموعات الأزرار المتصلة (2، على اليسار).

استخدام مجموعات الأزرار

  • يتم تطبيق تحويل الشكل عند الضغط على الأزرار أو اختيارها.
  • تحلّ مجموعات الأزرار المتصلة محلّ الأزرار المقسّمة.
  • تعمل مع جميع أحجام الأزرار: صغير جدًا (XS)، وصغير (S)، ومتوسط (M)، وكبير (L)، وكبير جدًا (XL).
  • يتيح هذا المكوّن أنماط الاختيار الفردي والاختيار المتعدّد والاختيار المطلوب.
مجموعات أزرار تحتوي على أزرار بأشكال وأحجام مختلفة
الشكل 2. مجموعات أزرار تحتوي على أزرار بأشكال وأحجام مختلفة

مجموعة الأزرار العادية

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

يوضّح المقتطف التالي كيفية تنفيذ مجموعة أزرار عادية مع مؤشر قائمة الكاملة:

@Composable
fun ButtonGroupSample() {
    val numButtons = 10
    ButtonGroup(
        overflowIndicator = { menuState ->
            ButtonGroupDefaults.OverflowIndicator(menuState = menuState)
        }
    ) {
        for (i in 0 until numButtons) {
            clickableItem(onClick = {}, label = "$i")
        }
    }
}

مجموعة الأزرار المتصلة

استخدِم مجموعات الأزرار المتصلة لأنماط الاختيار الفردي أو الاختيار المتعدد التي تم إنشاؤها باستخدام الدوال المركّبة ToggleButton والأشكال المتصلة ButtonGroupDefaults.

سلوك مجموعة الأزرار المرتبطة
الشكل 3. سلوك مجموعة الأزرار المتصلة المتجاوبة

تحديد مفرد

استخدِم مجموعة أزرار متصلة ذات اختيار واحد عندما يختار المستخدم خيارًا واحدًا من مجموعة حصرية متبادلة. ينفّذ المقتطف التالي مجموعة أزرار متصلة تتيح اختيارًا واحدًا باستخدام ToggleButton وRole.RadioButton:

@Composable
fun SingleSelectConnectedButtonGroupSample() {
    val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home")
    val unCheckedIcons =
        listOf(
            AppIcons.Work,
            AppIcons.Restaurant,
            AppIcons.Coffee,
            AppIcons.Search,
            AppIcons.Home,
        )
    val checkedIcons =
        listOf(
            AppIcons.WorkFilled,
            AppIcons.Restaurant,
            AppIcons.CoffeeFilled,
            AppIcons.Search,
            AppIcons.HomeFilled,
        )
    var selectedIndex by remember { mutableIntStateOf(0) }

    FlexBox(
        modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(),
        config = {
            direction(FlexDirection.Row)
            wrap(FlexWrap.Wrap)
            columnGap(ButtonGroupDefaults.ConnectedSpaceBetween)
            rowGap(2.dp)
        },
    ) {
        options.forEachIndexed { index, label ->
            ToggleButton(
                checked = selectedIndex == index,
                onCheckedChange = { selectedIndex = index },
                shapes =
                    when (index) {
                        0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                        options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes()
                        else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                    },
                modifier = Modifier.semantics { role = Role.RadioButton },
            ) {
                Icon(
                    painter =
                        rememberVectorPainter(
                            if (selectedIndex == index) checkedIcons[index] else unCheckedIcons[index]
                        ),
                    contentDescription = null,
                )
                Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                Text(label)
            }
        }
    }
}

تحديد متعدد

استخدِم مجموعة أزرار متصلة متعددة الاختيارات عندما يتمكّن المستخدم من تفعيل أو إيقاف خيار واحد أو أكثر بشكل مستقل. ينفّذ المقتطف التالي مجموعة أزرار متصلة متعددة الاختيارات باستخدام ToggleButton وmutableStateListOf:

@Composable
fun MultiSelectConnectedButtonGroupSample() {
    val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home")
    val unCheckedIcons =
        listOf(
            AppIcons.Work,
            AppIcons.Restaurant,
            AppIcons.Coffee,
            AppIcons.Search,
            AppIcons.Home,
        )
    val checkedIcons =
        listOf(
            AppIcons.WorkFilled,
            AppIcons.Restaurant,
            AppIcons.CoffeeFilled,
            AppIcons.Search,
            AppIcons.HomeFilled,
        )
    val checked = remember { mutableStateListOf(false, false, false, false, false) }

    FlexBox(
        modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(),
        config = {
            direction(FlexDirection.Row)
            wrap(FlexWrap.Wrap)
            columnGap(ButtonGroupDefaults.ConnectedSpaceBetween)
            rowGap(2.dp)
        },
    ) {
        options.forEachIndexed { index, label ->
            ToggleButton(
                checked = checked[index],
                onCheckedChange = { checked[index] = it },
                shapes =
                    when (index) {
                        0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                        options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes()
                        else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                    },
            ) {
                Icon(
                    painter =
                        rememberVectorPainter(
                            if (checked[index]) checkedIcons[index] else unCheckedIcons[index]
                        ),
                    contentDescription = null,
                )
                Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                Text(label)
            }
        }
    }
}