HyperUI

外观

HyperColorPicker ​

  • 分类：容器组件
  • 包名：hyper_ui
  • 状态模型：受控组件；selectedId 由调用方持有
  • 源码：library/src/main/java/hyper_ui/components/panel/HyperColorPicker.kt
  • Preview 注册：preview/src/commonMain/kotlin/hyper_ui/docs/data/ContainerComponentDemos.kt
  • Preview 交互：preview/src/commonMain/kotlin/hyper_ui/docs/ui/ContainerComponentShowcases.kt

公开 API ​

kotlin
@Composable
fun HyperColorPicker(
    options: List<HyperColorOption> = HyperColorPickerDefaults.presetOptions,
    selectedId: String,
    onSelected: (HyperColorOption) -> Unit,
    modifier: Modifier = Modifier,
    colorSize: Dp = HyperColorPickerDefaults.colorSize,
    horizontalSpacing: Dp = HyperColorPickerDefaults.horizontalSpacing,
    verticalSpacing: Dp = HyperColorPickerDefaults.verticalSpacing,
    labelTopSpacing: Dp = HyperColorPickerDefaults.labelTopSpacing
)

关键公开类型 ​

kotlin
data class HyperColorOption(
    val id: String,
    val label: String,
    val color: Color
)

object HyperColorPickerDefaults {
    val colorSize = 36.dp
    val horizontalSpacing = 10.dp
    val verticalSpacing = 14.dp
    val labelTopSpacing = 5.dp
    val presetOptions: List<HyperColorOption>
}

presetOptions 在源码中初始化为下表的 32 项。

id标签颜色
classic_red经典红rgba(231, 76, 60, 1f)
brick_red砖红rgba(184, 92, 56, 1f)
peach_orange蜜橘rgba(255, 140, 105, 1f)
vibrant_orange活力橙rgba(255, 103, 0, 1f)
sunny_yellow暖阳黄rgba(255, 159, 67, 1f)
amber_yellow琥珀黄rgba(255, 183, 0, 1f)
golden金盏rgba(255, 195, 0, 1f)
lemon_green柠檬绿rgba(164, 209, 82, 1f)
bud_green嫩芽绿rgba(123, 200, 108, 1f)
emerald翡翠绿rgba(46, 204, 113, 1f)
forest_green森林绿rgba(39, 174, 96, 1f)
mint_green薄荷绿rgba(26, 188, 156, 1f)
pine_green青松绿rgba(0, 200, 150, 1f)
lake_blue湖蓝rgba(72, 201, 176, 1f)
sky_blue天蓝rgba(93, 173, 226, 1f)
ocean_blue海蓝rgba(64, 120, 255, 1f)
sapphire宝石蓝rgba(41, 128, 185, 1f)
navy_blue藏蓝rgba(30, 55, 153, 1f)
indigo靛青rgba(56, 103, 214, 1f)
purple_blue紫蓝rgba(108, 92, 231, 1f)
violet紫罗兰rgba(156, 89, 209, 1f)
lavender薰衣草rgba(162, 155, 254, 1f)
sunset_orange日暮橙rgba(235, 109, 52, 1f)
deep_sea深海蓝rgba(15, 118, 178, 1f)
moss_green苔藓绿rgba(122, 168, 82, 1f)
wine_red酒红rgba(192, 57, 43, 1f)
warm_brown暖棕rgba(211, 84, 0, 1f)
olive_green橄榄绿rgba(106, 176, 76, 1f)
cyan_blue青蓝rgba(34, 166, 179, 1f)
hibiscus木槿紫rgba(179, 51, 113, 1f)
warm_gray暖灰rgba(149, 165, 166, 1f)
graphite石墨黑rgba(45, 52, 54, 1f)

参数 ​

参数类型必填默认值状态归属 / 作用
optionsList<HyperColorOption>否HyperColorPickerDefaults.presetOptions调用方可替换的颜色选项列表。
selectedIdString是无调用方持有的当前选项 ID。
onSelected(HyperColorOption) -> Unit是无点击后回传完整选项；调用方应更新 selectedId。
modifierModifier否Modifier调整颜色板外层布局。
colorSizeDp否HyperColorPickerDefaults.colorSize（36.dp）单个颜色圆的尺寸。
horizontalSpacingDp否HyperColorPickerDefaults.horizontalSpacing（10.dp）选项的水平间距。
verticalSpacingDp否HyperColorPickerDefaults.verticalSpacing（14.dp）选项的垂直间距。
labelTopSpacingDp否HyperColorPickerDefaults.labelTopSpacing（5.dp）颜色圆与标签之间的间距。

状态归属 ​

  • 组件不会在内部更新选中项。
  • 调用方持有 selectedId，并在 onSelected 中读取 option.id 后写回。
  • 将所选颜色应用到主题、保存到设置或同步到业务层均由调用方负责。

最小用法 ​

kotlin
var selectedId by remember { mutableStateOf("ocean_blue") }

HyperColorPicker(
    selectedId = selectedId,
    onSelected = { option -> selectedId = option.id }
)

自定义选项：

kotlin
val colors = listOf(
    HyperColorOption("brand", "品牌色", rgba(64, 120, 255, 1f)),
    HyperColorOption("success", "成功色", rgba(52, 199, 89, 1f))
)

HyperColorPicker(
    options = colors,
    selectedId = selectedId,
    onSelected = { selectedId = it.id }
)

约束与行为 ​

  • 组件使用 FlowRow 响应式换行，并在水平方向居中排列。
  • 选中判断只比较 option.id == selectedId；自定义选项的 ID 应稳定且唯一。
  • selectedId 不在 options 中时不会有任何选项呈现选中态。
  • 组件没有 enabled 参数；如需业务禁用策略，由调用方决定是否接受 onSelected 的结果。
  • onSelected 返回完整 HyperColorOption，不要把它当作只返回 ID 或 Color。
  • 项目颜色规范禁止十六进制硬编码；自定义选项使用项目允许的 RGBA 写法。

常见误用 ​

kotlin
// 错误：回调参数不是 String。
HyperColorPicker(
    selectedId = selectedId,
    onSelected = { id -> selectedId = id }
)

正确回调参数是 HyperColorOption，应使用 option.id、option.label 或 option.color。

相关 API ​

  • HyperColorOption
  • HyperColorPickerDefaults
  • HyperThemeConfig

交互预览 ​

HyperColorPicker 交互预览 在新窗口打开