第3章 Dynamic Colors 与支付品牌色冲突处理

3.1 冲突原理与类型

Material 3 的 Dynamic Colors（动态取色）通过 Monet 算法从用户壁纸中提取主色调，生成一套包含 Primary、Secondary、Tertiary 等角色的 ColorScheme。支付类应用通常拥有固定品牌色（如支付宝蓝 #1A6DFF、微信绿 #07C160、银联红 #E60012），当动态取色结果与品牌色在色相、饱和度或明度上偏差过大时，会破坏用户对品牌的识别，产生“换肤感”甚至信任风险。

3.2 动态取色算法解析

Monet 算法是 Dynamic Colors 的引擎，其输出决定了后续所有颜色角色。理解算法关键参数是制定保护策略的前提。

• 源颜色提取：从壁纸像素聚类出 4–6 个代表色，选择饱和度最高的作为 Seed Color。
• 色调板生成：以 Seed Color 的色相（Hue）为基准，按固定色相偏移生成 5 个主色调 primary、secondary、tertiary、neutral、neutralVariant。
• 关键参数：色相（H）、饱和度（S）、明度（L）三个维度各自独立计算，其中 Hue 是品牌色保护的核心监控对象。
• 输出接口：Android 通过 dynamicLightColorScheme(context) 返回 ColorScheme 对象，内部包含 52 个颜色槽。

// 获取动态 ColorScheme 的标准方式
val dynamicScheme = dynamicLightColorScheme(context)
val primaryHue = dynamicScheme.primary.hue       // 提取色相值 (0..360)
val primarySat = dynamicScheme.primary.saturation // 提取饱和度 (0..100)
val primaryLum = dynamicScheme.primary.lightness  // 提取明度 (0..100)

3.3 强制覆盖方案

当品牌识别要求统一时，可完全禁用动态取色对品牌色的影响。此方案适用于“品牌色必须精确等于规范值”的场景，如支付密码页、品牌权益页。

// 方式一：在应用主题中硬编码品牌色（res/values/themes.xml）
<style name="Theme.Pay" parent="Theme.Material3.DayNight.NoActionBar">
    <item name="colorPrimary">@color/brand_blue</item>
    <item name="colorOnPrimary">@android:color/white</item>
    <item name="colorPrimaryContainer">@color/brand_blue_container</item>
    <!-- 完全禁用动态取色 -->
    <item name="dynamicColorTheme">@null</item>
</style>

// 方式二：在 Compose 中强制覆盖
val colorScheme = dynamicLightColorScheme(context).copy(
    primary = Color(0xFF1A6DFF),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFD6E4FF)
)

3.4 品牌色保护策略

品牌色保护的核心思想是“锁定色相，释放饱和度与明度”，在保留壁纸个性的同时确保品牌识别。保护策略分为三个层级：

// L1 — 色相锁定实现（Kotlin）
fun protectBrandHue(dynamicColor: Color, brandHue: Float): Color {
    val hsl = FloatArray(3)
    Color.colorToHSL(dynamicColor.hashCode(), hsl)
    // 锁定色相为品牌色相，保留饱和度和明度
    hsl[0] = brandHue
    return Color.HSLToColor(hsl).let { Color(it) }
}

// L2 — 色相邻域保护
fun hueProtectedScheme(context: Context, brandHue: Float): ColorScheme {
    val original = dynamicLightColorScheme(context)
    val primaryHsl = FloatArray(3)
    Color.colorToHSL(original.primary.hashCode(), primaryHsl)
    return if (abs(primaryHsl[0] - brandHue) > 30f) {
        original.copy(primary = protectBrandHue(original.primary, brandHue))
    } else {
        original
    }
}

// L3 — 加权混合
fun blendWithBrand(dynamicColor: Color, brandColor: Color, ratio: Float = 0.7f): Color {
    val d = FloatArray(3); val b = FloatArray(3)
    Color.colorToHSL(dynamicColor.hashCode(), d)
    Color.colorToHSL(brandColor.hashCode(), b)
    // 色相取品牌，饱和度和明度按权重混合
    return Color.HSLToColor(floatArrayOf(
        b[0],
        d[1] * (1 - ratio) + b[1] * ratio,
        d[2] * (1 - ratio) + b[2] * ratio
    )).let { Color(it) }
}

3.5 实现流程

下图展示了从壁纸取色到品牌色保护输出的完整决策流程。关键分叉点在“冲突检测”节点，根据色相差值决定走强制覆盖、品牌色保护还是直接通过。

3.6 代码实现

以下代码演示了在 Compose 中集成品牌色保护策略的完整步骤，包含依赖配置、保护函数封装、以及主题注入。

// 1. build.gradle (app) 依赖
implementation("androidx.compose.material3:material3:1.2.0")
implementation("androidx.compose.ui:ui:1.5.0")
implementation("androidx.compose.material3:material3-dynamic:1.2.0")

// 2. 品牌色保护工具类 BrandProtection.kt
object BrandProtection {
    // 支付宝品牌蓝 色相 = 214°
    const val BRAND_HUE_ALIPAY = 214f
    // 微信品牌绿 色相 = 152°
    const val BRAND_HUE_WECHAT = 152f
    // 银联品牌红 色相 = 356°
    const val BRAND_HUE_UNIONPAY = 356f
    // 冲突阈值
    const val HUE_THRESHOLD = 30f

    fun protect(
        context: Context,
        brandHue: Float,
        level: ProtectionLevel = ProtectionLevel.L2
    ): ColorScheme {
        val original = dynamicLightColorScheme(context)
        val primaryHsl = FloatArray(3)
        Color.colorToHSL(original.primary.hashCode(), primaryHsl)
        val delta = abs(primaryHsl[0] - brandHue).let { if (it > 180) 360 - it else it }

        return when {
            delta <= HUE_THRESHOLD -> original  // 无需保护
            level == ProtectionLevel.L1 -> original.copy(
                primary = lockHue(original.primary, brandHue),
                primaryContainer = lockHue(original.primaryContainer, brandHue),
                onPrimary = Color.White
            )
            level == ProtectionLevel.L2 -> original.copy(
                primary = lockHue(original.primary, brandHue),
                primaryContainer = lockHue(original.primaryContainer, brandHue)
            )
            else -> blendWithBrand(original, brandColor(brandHue), ratio = 0.7f)
        }
    }

    private fun lockHue(color: Color, targetHue: Float): Color {
        val hsl = FloatArray(3)
        Color.colorToHSL(color.hashCode(), hsl)
        hsl[0] = targetHue
        return Color.HSLToColor(hsl).let { Color(it) }
    }

    private fun blendWithBrand(original: ColorScheme, brand: Color, ratio: Float): ColorScheme {
        val dHsl = FloatArray(3); val bHsl = FloatArray(3)
        Color.colorToHSL(original.primary.hashCode(), dHsl)
        Color.colorToHSL(brand.hashCode(), bHsl)
        val blended = Color.HSLToColor(floatArrayOf(
            bHsl[0],
            dHsl[1] * (1 - ratio) + bHsl[1] * ratio,
            dHsl[2] * (1 - ratio) + bHsl[2] * ratio
        )).let { Color(it) }
        return original.copy(primary = blended, onPrimary = Color.White)
    }

    private fun brandColor(hue: Float): Color {
        return Color.HSLToColor(floatArrayOf(hue, 0.85f, 0.50f)).let { Color(it) }
    }

    enum class ProtectionLevel { L1, L2, L3 }
}

// 3. 在 Activity 或 Composable 中注入
class PaymentActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val protectedScheme = BrandProtection.protect(
            context = this,
            brandHue = BrandProtection.BRAND_HUE_ALIPAY,
            level = BrandProtection.ProtectionLevel.L2
        )
        setContent {
            MaterialTheme(
                colorScheme = protectedScheme,
                content = { PayContent() }
            )
        }
    }
}

3.7 调试方法

调试品牌色冲突的核心是量化验证色相、饱和度、明度三个维度的实际输出值。推荐使用以下手段：

• ADB 日志输出：在保护函数中打印动态色相与品牌色相，观察触发保护的频率。
• 调色板预览：在开发者选项中切换不同壁纸，截图后使用取色工具读取 Primary 颜色值。
• 单元测试：构造极端壁纸 Seed Color，验证保护逻辑是否按预期触发。

// 调试日志输出示例
fun debugHueDelta(context: Context, brandHue: Float) {
    val scheme = dynamicLightColorScheme(context)
    val hsl = FloatArray(3)
    Color.colorToHSL(scheme.primary.hashCode(), hsl)
    val delta = abs(hsl[0] - brandHue).let { if (it > 180) 360 - it else it }
    Log.d("BrandProtection", "动态色相=${hsl[0]}, 品牌色相=$brandHue, 差值=$delta")
    if (delta > 30f) Log.w("BrandProtection", "⚠️ 触发色相保护")
}

// 单元测试 (JUnit)
@Test
fun testHueProtectionTriggered() {
    val extremeHue = 10f   // 与品牌蓝 214° 差 204° > 30°
    val protected = BrandProtection.protect(
        mockContext(),
        brandHue = 214f,
        level = BrandProtection.ProtectionLevel.L1
    )
    val protectedHsl = FloatArray(3)
    Color.colorToHSL(protected.primary.hashCode(), protectedHsl)
    assertThat(protectedHsl[0]).isEqualTo(214f)  // 色相被锁定
}

3.8 常见错误

3.9 性能优化

// 使用 remember 缓存 ColorScheme
@Composable
fun rememberProtectedScheme(
    context: Context = LocalContext.current,
    brandHue: Float = BrandProtection.BRAND_HUE_ALIPAY
): ColorScheme {
    return remember(brandHue) {
        BrandProtection.protect(context, brandHue, BrandProtection.ProtectionLevel.L2)
    }
}

// 应用层使用
@Composable
fun PayTheme(content: @Composable () -> Unit) {
    val scheme = rememberProtectedScheme()
    MaterialTheme(colorScheme = scheme) { content() }
}