SOUI 颜色系统指南¶

颜色是用户界面设计中最基础也是最重要的视觉元素之一。SOUI 框架提供了强大而灵活的颜色管理系统，支持多种颜色定义方式。

颜色定义格式¶

SOUI 支持以下五种颜色定义格式，每种格式都有其特定的使用场景：

格式类型	语法结构	示例	透明度范围	适用场景
十六进制	`#RRGGBBAA` 或 `#RRGGBB`	`#FF0000FF`	00-FF (十六进制)	Web 标准格式，最常用
RGB	`rgb(R,G,B)`	`rgb(255,0,0)`	固定 255 (不透明)	简单纯色定义
RGBA	`rgba(R,G,B,A)`	`rgba(255,0,0,128)`	0-255 (十进制)	需要精确透明度控制
RGBA2	`rgba2(R,G,B,%)`	`rgba2(255,0,0,50%)`	0-100% (百分比)	直观透明度设置
RGBA3	`rgba3(R,G,B,0.x)`	`rgba3(255,0,0,0.5)`	0.0-1.0 (小数)	编程友好格式

格式详解¶

十六进制格式：遵循 Web 标准，#FF0000 表示红色，#FF0000FF 末尾的 FF 表示完全不透明
RGB/RGBA 格式：使用十进制数值，范围 0-255，符合设计师习惯
RGBA⅔ 格式：提供百分比和小数形式的透明度，便于程序化生成

具名颜色定义¶

创建颜色资源文件¶

在项目的 values 目录下创建颜色定义文件（推荐命名为 colors.xml）：

<?xml version="1.0" encoding="utf-8"?>
<color>
    <!-- 主题色定义 -->
    <primary value="#1976D2"/>
    <primary_dark value="#1565C0"/>
    <primary_light value="#BBDEFB"/>

    <!-- 强调色定义 -->
    <accent value="#FF4081"/>
    <accent_dark value="#F50057"/>

    <!-- 中性色定义 -->
    <text_primary value="#212121"/>
    <text_secondary value="#757575"/>
    <divider value="#BDBDBD"/>

    <!-- 状态色定义 -->
    <success value="#4CAF50"/>
    <warning value="#FF9800"/>
    <error value="#F44336"/>

    <!-- 透明色示例 -->
    <overlay value="rgba(0,0,0,128)"/>
    <highlight value="rgba2(255,193,7,20%)"/>
</color>

注册颜色资源¶

在资源索引文件注册（uires.idx）：

<values>
    <!-- 其他资源引用 -->
    <file name="colors" path="values\colors.xml"/>
</values>

在界面定义文件引用（init.xml）：

<UIDEF>
    <color src="values:colors"/>
    <!-- 其他配置 -->
</UIDEF>

💡 提示：如果是通过 SOUI 项目向导创建的项目，上述配置通常已自动完成。默认颜色资源文件为 values\colors.xml。

颜色使用方式¶

在布局文件中使用¶

通过 @color/颜色名称 语法引用定义的具名颜色：

<!-- 文本颜色 -->
<text name="title" text="欢迎使用 SOUI" colorText="@color/text_primary" />

<!-- 背景颜色 -->
<window name="container" colorBkgnd="@color/primary_light" />

<!-- 边框颜色 -->
<edit name="input" colorBorder="@color/divider" />

<!-- 状态颜色 -->
<button name="confirm" colorText="@color/primary" colorTextHover="@color/primary_dark" />

在代码中使用¶

基本使用方式¶

// 通过资源路径获取颜色值
COLORREF crPrimary = GETCOLOR("@color/primary");
COLORREF crText = GETCOLOR("@color/text_primary");

高级使用方式（启用 XmlNamedID）¶

如果启用了 XmlNamedID 功能，可以使用更类型安全的方式：

// 通过生成的 ID 常量获取颜色
COLORREF crPrimary = GETCOLOR(R.color.primary);
COLORREF crAccent = GETCOLOR(R.color.accent);

最佳实践¶

设计原则¶

语义化命名：使用描述用途的名称而非具体颜色值
分层管理：基础色 → 语义色 → 组件专用色
统一出口：所有颜色定义集中在资源文件

维护建议¶

版本控制：将颜色资源文件纳入版本管理
文档化：为每个颜色添加注释说明用途
一致性检查：定期审查颜色使用的一致性
工具支持：使用 SOUI 编辑器可视化管理和预览颜色

常见问题解答¶

Q: 为什么我的颜色定义没有生效？ A: 请检查：1) 资源文件是否正确注册；2) 引用语法是否正确；3) 资源文件是否被正确加载。

Q: 颜色命名有什么规范？ A: 建议使用小写字母加下划线的命名方式，如 text_primary、button_hover，避免使用具体颜色值作为名称。