時間挑選器

「時間挑選器」可讓使用者選取時間。您可以使用 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. 輸入時間選擇器。

使用狀態

如要使用使用者在時間挑選器中選取的時間，請傳遞 適用於 onConfirm 函式的 TimePickerState。這樣一來，父項可組合項就能透過 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.")
}

詳情請參閱程式碼片段中的完整導入說明 app。

其他資源