時間挑選器

時間挑選器可讓使用者選取時間。您可以使用 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")
        }
    }
}

請注意這個程式碼片段中的下列事項：

  • 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")
        }
    }
}

這項導入作業的注意事項：

  • 結構基本上與錶盤時間挑選器相同，主要差異在於使用 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")
        }
    }
}

接著，您可以像這樣呼叫可組合項：

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.")
}

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

其他資源