apppublic/aidocs/set_fgcolor.md

Kivy 颜色对比度与前景色自动选择工具文档

# Kivy 前景色自适应选择函数技术文档

## 概述

该模块提供两个核心函数，用于在 Kivy 框架中根据背景颜色（`bgcolor`）智能选择合适的前景色（如文本颜色），以确保良好的可读性和视觉对比度。其原理基于人眼对不同颜色的感知灰度值，使用心理学标准公式计算灰度，并据此判断应使用深色或浅色前景。

## 编码说明

```python
# -*- coding=utf-8 -*-

源码采用 UTF-8 编码，支持中文注释和文档。

---

核心原理

灰度感知公式

人眼对不同颜色的敏感度不同，因此即使 RGB 值相同，感知亮度也不同。本模块使用标准灰度转换公式：

\text{灰度} = R \times 0.299 + G \times 0.587 + B \times 0.114

其中：

• $ R $：红色分量（0 ~ 1）
• $ G $：绿色分量（0 ~ 1）
• $ B $：蓝色分量（0 ~ 1）

✅ 说明：此权重来源于 ITU-R BT.601 标准，广泛应用于图像处理领域。

根据计算出的灰度值：

• 若灰度 > 0.5，表示背景较亮，应使用暗色前景；
• 若灰度 ≤ 0.5，表示背景较暗，应使用亮色前景。

---

函数接口

color_gray_rate(color)

计算给定颜色的感知灰度值。

参数

参数名	类型	描述
color	list[float]	颜色列表 [R, G, B, A] 或 [R, G, B]，各分量范围为 0~1

⚠️ 注意：Alpha 通道（透明度）不参与灰度计算。

返回值

• float：计算得到的灰度值（0 ~ 1 范围内）

示例

color_gray_rate([1.0, 0.0, 0.0])  # 红色 -> 返回约 0.299
color_gray_rate([0.0, 1.0, 0.0])  # 绿色 -> 返回约 0.587
color_gray_rate([0.0, 0.0, 1.0])  # 蓝色 -> 返回约 0.114

---

get_fgcolor_from_bgcolor(bgcolor, colors=None)

根据背景色自动选择最佳前景色。

参数

参数名	类型	默认值	描述
bgcolor	list[float]	——	背景颜色，格式为 [R, G, B, A]
colors	list[list[float]] 或 None	None	可选的两个前景候选颜色；若为 None，则使用内置默认颜色

内置默认颜色

• 深色前景：[0.11, 0.11, 0.11, 1]（接近黑色）
• 浅色前景：[0.89, 0.89, 0.89, 1]（接近白色）

返回值

• list[float]：推荐使用的前景颜色（四元组 [R, G, B, A]）

工作逻辑

1. 计算背景色的灰度值 graylevel
2. 如果未传入 colors：
   • 若 graylevel > 0.5，返回深色前景
   • 否则返回浅色前景
3. 如果传入了 colors = [color1, color2]：
   • 分别计算两个候选颜色的灰度值 r1, r2
   • 选择与背景灰度差异更大的那个颜色（即对比度更高）
   • 即：比较 |graylevel - r1| 与 |graylevel - r2|

✅ 优势：支持自定义配色方案，适用于品牌色、主题色等场景。

示例

# 使用默认颜色
get_fgcolor_from_bgcolor([1.0, 1.0, 1.0])     # 白色背景 → 返回 [0.11,0.11,0.11,1]
get_fgcolor_from_bgcolor([0.0, 0.0, 0.0])     # 黑色背景 → 返回 [0.89,0.89,0.89,1]

# 自定义前景颜色
custom_colors = [
    [0.2, 0.6, 0.8, 1],  # 蓝绿色
    [1.0, 0.9, 0.1, 1]   # 明黄色
]
get_fgcolor_from_bgcolor([0.1, 0.1, 0.6], custom_colors)

---

应用场景

• 动态 UI 主题系统（如深色/浅色模式自动切换文字颜色）
• 标签、按钮、卡片组件的文字颜色适配
• 数据可视化中动态调整标签颜色
• 提升无障碍访问性（Accessibility）

---

注意事项

1. 所有颜色值需归一化到 0~1 范围（Kivy 要求），不可使用 0~255 的整数。
2. 推荐前景色的 Alpha 通常设为 1（完全不透明）。
3. 在极端中间色调（灰度 ≈ 0.5）时建议人工微调或增加容差判断。

---

版权与许可

© 2025 开源工具函数
可用于 Kivy 项目中的颜色对比优化，欢迎自由使用与扩展。

> 💡 **提示**：可将此文档保存为 `README.md` 或集成至 Sphinx 文档系统中。