Switch

Switch 元件可讓使用者在兩種狀態 (勾選和未勾選) 之間切換。在應用程式中，您可以使用切換按鈕讓使用者執行下列任一操作：

  • 開啟或關閉設定。
  • 啟用或停用功能。
  • 選取所需選項。

元件包含兩個部分：滑桿和滑桿軌道。拇指是切換按鈕的可拖曳部分，而軌道則是背景。使用者可以將指標拖曳至左側或右側，以變更切換鈕的狀態。使用者也可以輕觸切換鈕來檢查及清除。

淺色和深色模式中的 Switch 元件範例。
圖 1. 切換元件。

基本導入

如需完整的 API 定義，請參閱 Switch 參考資料。以下是您可能需要使用的部分重要參數：

  • checked：切換按鈕的初始狀態。
  • onCheckedChange：當切換器狀態變更時，系統會呼叫的回呼。
  • enabled：切換鈕是否已啟用或停用。
  • colors：切換鈕使用的顏色。

以下範例是 Switch 可組合函式的最小實作項目。

@Composable
fun SwitchMinimalExample() {
    var checked by remember { mutableStateOf(true) }

    Switch(
        checked = checked,
        onCheckedChange = {
            checked = it
        }
    )
}
Switch.kt

取消勾選後，這個實作方式會顯示如下：

未勾選的基本切換鈕。
圖 2. 未勾選的切換鈕。

勾選後的顯示效果如下：

已勾選的基本切換鈕。
圖 3. 已勾選的切換鈕。

進階導入

實作較進階的切換時，您可能會想使用的主要參數如下：

  • thumbContent：用於自訂勾選時的拇指圖示外觀。
  • colors：用於自訂音軌和滑桿的顏色。

自訂縮圖

您可以為 thumbContent 參數傳遞任何可組合項，以建立自訂縮圖。以下是使用自訂圖示做為滑鈕按鈕的範例：

@Composable
fun SwitchWithIconExample() {
    var checked by remember { mutableStateOf(true) }

    Switch(
        checked = checked,
        onCheckedChange = {
            checked = it
        },
        thumbContent = if (checked) {
            {
                Icon(
                    imageVector = Icons.Filled.Check,
                    contentDescription = null,
                    modifier = Modifier.size(SwitchDefaults.IconSize),
                )
            }
        } else {
            null
        }
    )
}
Switch.kt

在這個實作中，未勾選的顯示方式與上一節的範例相同。不過，勾選後，這項實作會顯示如下：

使用 thumbContent 參數的切換鈕，在勾選時顯示自訂圖示。
圖 4. 開關，內含自訂勾選圖示。

自訂顏色

以下範例說明如何使用 colors 參數，根據開關是否已勾選來變更開關的拇指和軌跡顏色。

@Composable
fun SwitchWithCustomColors() {
    var checked by remember { mutableStateOf(true) }

    Switch(
        checked = checked,
        onCheckedChange = {
            checked = it
        },
        colors = SwitchDefaults.colors(
            checkedThumbColor = MaterialTheme.colorScheme.primary,
            checkedTrackColor = MaterialTheme.colorScheme.primaryContainer,
            uncheckedThumbColor = MaterialTheme.colorScheme.secondary,
            uncheckedTrackColor = MaterialTheme.colorScheme.secondaryContainer,
        )
    )
}
Switch.kt

此實作方式如下所示：

使用 colors 參數的切換鈕，可顯示手動選擇器和標記皆使用自訂顏色的切換鈕。
圖 5. 使用自訂顏色的切換鈕。

其他資源