時間挑選器

時間挑選器可讓使用者選取時間。您可以使用 TimePicker 和 TimeInput 可組合項，在應用程式中實作時間挑選器。

類型

時間挑選器分為兩種：

  • 轉盤：使用者可在轉盤上移動手柄來設定時間。
  • 輸入：讓使用者使用鍵盤設定時間。

下圖左側為轉盤時間挑選工具，右側為輸入時間挑選工具：

錶面和輸入時間選擇器。
圖 1. 錶面和輸入時間挑選器。

API 介面

如要實作時間挑選器，請使用 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 脫糖功能，以便在所有 Android 版本上使用 java.time.LocalTime。
  • TimePicker 可組合項會顯示時間挑選器，並將 timePickerState 做為參數。
  • 實作內容包含兩個按鈕：一個用於確認所選項目，另一個則用於關閉選擇器。

此實作方式如下所示：

時鐘時間挑選器。使用者可以使用轉盤選取時間。
圖 2. 時鐘時間挑選器。

輸入時間挑選器

這個程式碼片段示範如何實作基本輸入樣式的時間挑選器。

@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

這項實作方式的重點如下：

  • 這個結構與撥號時間選擇器大致相同，主要差異在於使用 TimeInput 而非 TimePicker。
  • timePickerState 的 is24Hour 參數已明確設為 true。根據預設，這個值為 false。

此實作方式如下所示：

輸入時間選擇器。使用者可以使用文字欄位輸入時間。
圖 3. 輸入時間選擇器。

使用狀態

如要使用使用者在時間挑選器中選取的時間，請將適當的 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.")
}

詳情請參閱程式碼片段應用程式中的完整實作方式。

其他資源