انتخاب‌گرهای زمان

انتخابگرهای زمان روشی برای انتخاب زمان توسط کاربران ارائه می‌دهند. می‌توانید از عناصر ترکیبی TimePicker و TimeInput برای پیاده‌سازی انتخابگر زمان در برنامه‌تان استفاده کنید.

انواع

دو نوع انتخابگر زمان وجود دارد:

• گردونه: به کاربران امکان می‌دهد با حرکت دادن دسته‌ای در اطراف گردونه، زمان را تنظیم کنند.
• ورودی: به کاربران امکان می‌دهد بااستفاده از صفحه‌کلیدشان زمان تنظیم کنند.

تصویر زیر نمونه‌ای از انتخابگر زمان چرخشی در سمت راست و انتخابگر زمان ورودی در سمت چپ ارائه می‌دهد:

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

برای پیاده‌سازی انتخابگر زمان، از TimePicker یا TimeInput ترکیبی استفاده کنید:

• TimePicker: انتخابگر زمان شماره‌گیری را پیاده‌سازی می‌کند.
• TimeInput: انتخابگر زمان ورودی را پیاده‌سازی می‌کند.

ایالت

برای هر دو TimePicker و TimeInput، باید TimePickerState را نیز بگذرانید. این به شما امکان می‌دهد زمان انتخابی پیش‌فرضی را که در انتخاب‌گر نشان داده می‌شود تنظیم کنید. همچنین زمانی را که کاربر بااستفاده از انتخاب‌گر انتخاب کرده است ضبط می‌کند.

کادر گفتگو

انتخاب‌گرهای زمان در کادرهای گفتگو نشان داده می‌شوند. نمونه‌های این راهنما از چارگوش‌های گفتگو استفاده نمی‌کنند. برای نمونه‌هایی که از کادرهای گفتگو استفاده می‌کنند، راهنمای کادرهای گفتگو برای انتخابگرهای زمان را ببینید.

انتخاب‌گر زمان شماره‌گیری

این تکه‌کد نحوه پیاده‌سازی انتخابگر زمان چرخشی پایه را نشان می‌دهد.

@Composable
fun DialExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

موارد زیر را در این تکه‌کد درنظر بگیرید:

• ‫Calendar.getInstance() TimePickerState را با زمان فعلی مقداردهی اولیه می‌کند.
  • این مثال از java.util.Calendar استفاده می‌کند. Java 8+ API desugaring را در پروژه‌تان فعال کنید تا بتوانید به‌جای آن از java.time.LocalTime در همه نسخه‌های Android استفاده کنید.
• ترکیب‌پذیر TimePicker انتخاب‌گر زمان را نمایش می‌دهد و timePickerState را به‌عنوان پارامتر می‌گیرد.
• پیاده‌سازی شامل دو دکمه است: یکی برای تأیید انتخاب و دیگری برای بستن انتخاب‌گر.

این پیاده‌سازی به‌صورت زیر نشان داده می‌شود:

انتخاب‌گر زمان ورودی

این گزیده نشان می‌دهد که چگونه یک گزینش‌گر زمان با سبک ورودی پایه را پیاده‌سازی کنید.

@Composable
fun InputExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimeInput(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

نکات کلیدی که باید در این پیاده‌سازی درنظر داشته باشید:

• این ساختار اساساً همان انتخابگر زمان شماره‌گیری است، با این تفاوت اصلی که به‌جای TimePicker از TimeInput استفاده می‌شود.
• پارامتر is24Hour برای timePickerState به‌طور صریح روی true تنظیم شده است. به‌طور پیش‌فرض، این مقدار false است.

این پیاده‌سازی به‌صورت زیر نشان داده می‌شود:

استفاده از وضعیت

برای استفاده از زمانی که کاربر در انتخابگر زمان انتخاب کرده است، TimePickerState مناسب را به تابع onConfirm خود ارسال کنید. سپس عنصر ترکیبی ولی می‌تواند ازطریق TimePickerState.hour و TimePickerState.minute به زمان انتخاب‌شده دسترسی پیدا کند.

تکه‌کد زیر نحوه انجام این کار را نشان می‌دهد:

@Composable
fun DialUseStateExample(
    onConfirm: (TimePickerState) -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = { onConfirm(timePickerState) }) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

سپس می‌توانید این عنصر ترکیبی را به این صورت فراخوانی کنید:

var selectedTime: TimePickerState? by remember { mutableStateOf(null) }

// ...

DialUseStateExample(
    onDismiss = {
        showDialExample = false
    },
    onConfirm = {
            time ->
        selectedTime = time
        showDialExample = false
    },
)

// ...

if (selectedTime != null) {
    val cal = Calendar.getInstance()
    cal.set(Calendar.HOUR_OF_DAY, selectedTime!!.hour)
    cal.set(Calendar.MINUTE, selectedTime!!.minute)
    cal.isLenient = false
    Text("Selected time = ${formatter.format(cal.time)}")
} else {
    Text("No time selected.")
}

برای جزئیات بیشتر، پیاده‌سازی کامل در برنامه گزیده‌ها را ببینید.

منابع بیشتر

• TimePicker
• طراحی مادی - انتخابگرهای زمان