دکمه‌های نماد

دکمه‌های نمادین کنش‌هایی را که کاربران می‌توانند انجام دهند نمایش می‌دهند. دکمه‌های نماد باید از نمادی با معنی واضح استفاده کنند و معمولاً کنش‌های رایج یا پرکاربرد را نشان می‌دهند.

دو نوع دکمه نماد وجود دارد:

• پیش‌فرض: این دکمه‌ها می‌توانند عناصر دیگری مانند منو یا جستجو را باز کنند.
• دکمه مبدل: این دکمه‌ها می‌توانند کنش‌های دودویی را نشان دهند که می‌توان آن‌ها را روشن یا خاموش کرد، مانند «مورد علاقه» یا «نشانک».

سطح میانای برنامه‌سازی کاربردی

از ترکیب‌پذیر IconButton برای پیاده‌سازی دکمه‌های نماد استاندارد استفاده کنید. برای ایجاد سبک‌های دیداری مختلف مثل پرشده، پرشده با رنگ، یا با خطوط پیرامونی، به‌ترتیب از FilledIconButton، FilledTonalIconButton، و OutlinedIconButton استفاده کنید.

پارامترهای کلیدی برای IconButton شامل موارد زیر است:

• onClick: تابع لامبدا که وقتی کاربر روی دکمه نماد تک‌ضرب می‌زند اجرا می‌شود.
• enabled: مقدار بولی که وضعیت فعال بودن دکمه را کنترل می‌کند. وقتی false، دکمه به ورودی کاربر پاسخ نمی‌دهد.
• content: محتوای قابل‌ترکیب داخل دکمه، معمولاً یک Icon.

مثال ساده: دکمه نماد مبدل

این مثال نحوه پیاده‌سازی دکمه نماد ضامن را نشان می‌دهد. دکمه نماد مبدل ظاهرش را براساس اینکه انتخاب شده یا نشده است تغییر می‌دهد.

@Preview
@Composable
fun ToggleIconButtonExample() {
    // isToggled initial value should be read from a view model or persistent storage.
    var isToggled by rememberSaveable { mutableStateOf(false) }

    IconButton(
        onClick = { isToggled = !isToggled }
    ) {
        Icon(
            painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite),
            contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button."
        )
    }
}
IconButton.kt

نکات کلیدی درباره کد

• ToggleIconButtonExample composable یک IconButton قابل‌تغییر را تعریف می‌کند.
  • mutableStateOf(false) یک شیء MutableState ایجاد می‌کند که حاوی یک مقدار بولی است، در ابتدا false. این کار isToggled را به نگه‌دارنده حالت تبدیل می‌کند، یعنی هرگاه مقدار آن تغییر کند، Compose میانای کاربر را بازترکیب می‌کند.
  • rememberSaveable تضمین می‌کند که وضعیت isToggled درطول تغییرات پیکربندی، مانند چرخش صفحه‌نمایش، حفظ شود.
• ‫onClick lambda از IconButton رفتار دکمه را هنگام کلیک کردن تعریف می‌کند و وضعیت را بین true و false تغییر می‌دهد.
• پارامتر painter از ترکیب‌پذیر Icon به‌طور مشروط یک painterResource متفاوت را براساس وضعیت isToggled بار می‌کند. این کار ظاهر دیداری نماد را تغییر می‌دهد.
  • اگر isToggled برابر با true باشد، قلب توپر قابل‌رسم را بار می‌کند.
  • اگر isToggled برابر با false باشد، قلب خطی قابل‌رسم را بار می‌کند.
• ‫contentDescription مربوط به Icon نیز براساس وضعیت isToggled به‌روز می‌شود تا اطلاعات دسترس‌پذیری مناسب را ارائه دهد.

نتیجه

تصویر زیر دکمه نماد مبدل را از قطعه کد قبلی در حالت لغو انتخاب‌شده نشان می‌دهد:

مثال پیشرفته: کنش‌های تکراری هنگام فشار دادن

این بخش نشان می‌دهد که چگونه دکمه‌های نمادی ایجاد کنید که به‌طور مداوم کنشی را راه‌اندازی می‌کنند وقتی کاربر آن‌ها را فشار می‌دهد و نگه می‌دارد، به‌جای اینکه فقط یک‌بار با هر کلیک راه‌اندازی شوند.

@Composable
fun MomentaryIconButton(
    unselectedImage: Int,
    selectedImage: Int,
    contentDescription: String,
    modifier: Modifier = Modifier,
    stepDelay: Long = 100L, // Minimum value is 1L milliseconds.
    onClick: () -> Unit
) {
    val interactionSource = remember { MutableInteractionSource() }
    val isPressed by interactionSource.collectIsPressedAsState()
    val pressedListener by rememberUpdatedState(onClick)

    LaunchedEffect(isPressed) {
        while (isPressed) {
            delay(stepDelay.coerceIn(1L, Long.MAX_VALUE))
            pressedListener()
        }
    }

    IconButton(
        modifier = modifier,
        onClick = onClick,
        interactionSource = interactionSource
    ) {
        Icon(
            painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage),
            contentDescription = contentDescription,
        )
    }
}
IconButton.kt

نکات کلیدی درباره کد

• ‫MomentaryIconButton یک unselectedImage: Int می‌گیرد، شناسه منبع ترسیم‌شدنی برای نماد وقتی دکمه فشار داده نشده است، و selectedImage: Int، شناسه منبع ترسیم‌شدنی برای نماد وقتی دکمه فشار داده شده است.
• این برنامه از interactionSource برای ردیابی دقیق تعاملات «فشار دادن» ازسوی کاربر استفاده می‌کند.
• isPressed وقتی دکمه به‌طور فعال فشار داده می‌شود درست است و درغیراین‌صورت نادرست است. وقتی isPressed true است، LaunchedEffect وارد حلقه می‌شود.
  • درون این حلقه، از delay (با stepDelay) برای ایجاد مکث بین کنش‌های راه‌انداز استفاده می‌کند. coerceIn اطمینان می‌دهد که تأخیر حداقل ۱ میلی‌ثانیه است تا از حلقه‌های بی‌نهایت جلوگیری شود.
  • pressedListener پس‌از هر تأخیر در حلقه فراخوانی می‌شود. این باعث تکرار کنش می‌شود.
• pressedListener از rememberUpdatedState استفاده می‌کند تا مطمئن شود که onClick lambda (کنش قابل‌اجرا) همیشه به‌روزترین نسخه از آخرین ترکیب‌بندی است.
• Icon تصویر نمایش‌داده‌شده خود را براساس اینکه دکمه درحال‌حاضر فشار داده شده است یا نه تغییر می‌دهد.
  • اگر isPressed درست باشد، selectedImage نشان داده می‌شود.
  • درغیراین‌صورت، unselectedImage نشان داده می‌شود.

سپس، از این MomentaryIconButton در یک مثال استفاده کنید. قطعه کد زیر دو دکمه نماد را نشان می‌دهد که شمارنده‌ای را کنترل می‌کنند:

@Preview()
@Composable
fun MomentaryIconButtonExample() {
    var pressedCount by remember { mutableIntStateOf(0) }

    Row(
        modifier = Modifier.fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_rewind,
            selectedImage = R.drawable.fast_rewind_filled,
            stepDelay = 100L,
            onClick = { pressedCount -= 1 },
            contentDescription = "Decrease count button"
        )
        Spacer(modifier = Modifier)
        Text("advanced by $pressedCount frames")
        Spacer(modifier = Modifier)
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_forward,
            selectedImage = R.drawable.fast_forward_filled,
            contentDescription = "Increase count button",
            stepDelay = 100L,
            onClick = { pressedCount += 1 }
        )
    }
}
IconButton.kt

نکات کلیدی درباره کد

• MomentaryIconButtonExample composable displays a Row containing two MomentaryIconButton instances and a Text composable to build a UI for incrementing and decrementing a counter.
• این تابع یک متغیر حالت تغییرپذیر pressedCount را بااستفاده از remember و mutableIntStateOf حفظ می‌کند که مقدار اولیه آن ۰ است. When pressedCount changes, any composables observing it (like the Text composable) recompose to reflect the new value.
• MomentaryIconButton اول با کلیک کردن یا نگه داشتن pressedCount کاهش می‌یابد.
• MomentaryIconButton دوم با کلیک کردن یا نگه داشتن، pressedCount را افزایش می‌دهد.
• هر دو دکمه از stepDelay ۱۰۰ میلی‌ثانیه‌ای استفاده می‌کنند، یعنی کنش onClick هر ۱۰۰ میلی‌ثانیه یک‌بار تکرار می‌شود تا زمانی که دکمه نگه داشته شود.

نتیجه

ویدیو زیر میانای کاربری را با دکمه‌های نماد و شمارنده نشان می‌دهد:

منابع بیشتر

• Material 3 - دکمه‌های نماد