uni-app x CSS 颜色（color）全解析：颜色表达方式、跨端兼容性与配置实践-港品优选

uni-app x CSS 颜色（color）全解析：颜色表达方式、跨端兼容性与配置实践

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

颜色是界面样式中最高频的属性之一。在 uni-app x 中，CSS 颜色属性（color、background-color、border-color等）支持多种表达方式，但不同表达方式在 Web、微信小程序、Android、iOS、HarmonyOS 各端的兼容性差异很大。本文以 docs/css/common/color.md 为骨架，系统梳理 uni-app x 支持的全部颜色数据类型及其兼容版本，深入讲解 hex-color 各语法变体、rgb()/rgba()等颜色函数在 App 平台的行为边界，并结合 CSS 概述、CSS 方法与 pages.json 配置说明 App 平台的默认值重置规则与pages.json中仅支持十六进制颜色的特殊约束，帮助开发者写出跨端表现一致的颜色代码。

颜色值类型总览与兼容性矩阵

uni-app x 的 CSS 颜色体系以 CSS Color Module 为参照，在 App 平台实现了其中的子集。下表是 docs/css/common/color.md 给出的完整颜色类型兼容性清单，其中“兼容性”列的版本号表示该能力可用的最低 HBuilderX 版本，x表示当前平台不支持。

从表中可以提炼出三条关键规律：

App 全端通用（Android/iOS/HarmonyOS 均可）的颜色表达方式只有 4 类：颜色名（named-color）、十六进制（hex-color）、transparent关键字、rgb()/rgba()函数。这构成了 uni-app x App 端颜色写法的“安全区”。
currentColor在 App 端（Android、iOS、HarmonyOS）标记为x（不支持），仅 Web 与微信小程序可用，这一点与 uni-app x CSS 与标准 CSS 的差异中“App 平台不把currentcolor作为可依赖的通用颜色值”的说明相互印证。
hsl/hsla、hwb、lab/oklab、lch/oklch、color()、color-mix()及所有“relative 相对颜色”语法均仅限 Web 与微信小程序，App 原生渲染端当前不提供支持。把现代浏览器的颜色写法直接迁移到 App 端会静默失效。

hex-color 十六进制颜色的四种语法变体

十六进制是 uni-app x 中兼容面最广、也是pages.json中唯一允许的颜色写法。<hex-color>将颜色的红（R）、绿（G）、蓝（B）主分量及其透明度（A）写成十六进制数，支持 3、4、6、8 位四种变体：

使用要点：

#RGB与#RRGGBB是简写与全写关系：#FFF等价于#FFFFFF，每个十六进制位会被复制展开，这是从 CSS Color 规范继承的行为，各端保持一致。
透明度位（A）取值同样是十六进制数：#FFFA中的AA是 alpha 通道的十六进制表示（00完全透明，FF完全不透明），因此#FFFFFFAA表示“不透明度约为 66.7%（AA/FF ≈ 0.667）”的白色，而非“透明度值为 AA 就完全透明”。
带 alpha 的四值与八值写法在 App 端版本要求更高：#RGBA、#RRGGBBAA在 Android/iOS/HarmonyOS 需要 HBuilderX 4.41 及以上，而三值、六值写法在 Android 3.9、iOS 4.11、HarmonyOS 4.61 即可使用。低版本 App 端项目如需半透明效果，建议改用rgba()函数（Android 3.9/iOS 4.11/HarmonyOS 4.61 即支持）。
App 平台省略单位不影响颜色：颜色值与长度值不同，十六进制写法始终以#开头、无须担心单位问题；而 CSS 概述提到 App 端长度值可省略单位按 px 处理，颜色值则无此歧义。

rgb() 与 rgba() 颜色函数

rgb()和rgba()是 App 端与 hex 并列的主力颜色函数，兼容性与 hex-color 完全一致（Web 4.0、微信小程序 4.41、Android 3.9、iOS 4.11、HarmonyOS 4.61），详见 CSS 方法 - rgb 与 CSS 方法 - rgba。

rgb()根据红色、绿色和蓝色值创建颜色，三个通道的取值范围为 0-255（或百分比）。
rgba()在 RGB 基础上增加 alpha 透明度通道，取值 0-1，0 表示完全透明，1 表示完全不透明。
transparent是rgba(0,0,0,0)的简写，其计算值即完全透明，因此在需要透明背景时两者等价，但transparent写法更简洁。

仓库示例工程中提供了完整可运行的演示页：rgb.uvue 与 rgba.uvue。其中 rgb 示例以红（rgb(255, 0, 0)）、绿（rgb(0, 255, 0)）、蓝（rgb(0, 0, 255)）三原色及黄（rgb(255, 255, 0)）、品红（rgb(255, 0, 255)）、青（rgb(0, 255, 255)）展示通道组合；rgba 示例则固定红色与蓝色，通过rgba(255, 0, 0, 0.1)、rgba(255, 0, 0, 0.5)、rgba(255, 0, 0, 1)直观对比 10%、50%、100% 三档透明度下的视觉差异。这两个页面也是 CSS 方法文档中 rgb/rgba 章节所引用的官方示例，可与文档配合阅读。

/* 不透明色 */ .title { color: rgb(255, 0, 0); } /* 半透明背景，alpha 0.5 */ .mask { background-color: rgba(0, 0, 0, 0.5); } /* transparent 等价于 rgba(0,0,0,0) */ .clear { background-color: transparent; }

需要注意，rgb relative（相对颜色语法，如rgb(from red r g b)）在 App 端标记为x，仅 Web 与微信小程序可用，App 端应直接写出明确通道值。

App 平台颜色默认值的重置差异

uni-app x 在 App 平台实现的是 Web CSS 的子集（ucss），编译器会对部分默认值进行 CSS reset 以保证各端一致性，颜色相关默认值也在此列。根据 CSS 概述 - css样式重置的重置清单：

由此可以得出三个对实战有直接影响的结论：

App 端文字颜色默认值是#000000（纯黑），而 Web 端标准默认值是canvastext（通常渲染为黑色）。两者视觉上通常接近，但语义不同，跨端比对颜色时不要依赖“默认值即黑色”的假设。
App 端边框颜色默认值是#000000，而不是标准 CSS 的currentcolor。这意味着标准 Web 中“边框颜色跟随文字颜色自动变化”的行为在 App 端不存在——uni-app x CSS 与标准 CSS 的差异明确指出：如果希望边框颜色跟随文字颜色，应显式设置边框颜色，例如：

.tag { color: #007aff; border-color: #007aff; /* 不能依赖 currentcolor 自动跟随 */ }

currentColor关键字在 App 端不可依赖：既然 App 端样式默认值不基于currentcolor，在 App 端使用currentColor取值并不会像 Web 端那样解析为当前元素的color计算值。跨端场景下应直接书写具体颜色值。

此外，App 平台“样式不继承”的规则与颜色密切相关：color、font-size等文本样式不会从父级 view 继承到子级 text。把color: red写在父 view 上，子 text 的文字颜色并不会变红；必须把颜色写到 text 组件自身上。这也是 CSS 概述中“样式不继承”章节的核心示例，迁移 Web 页面时需特别注意。

pages.json 中的颜色约束：仅支持十六进制

在pages.json（页面与全局配置）中，颜色字段有其专属约束，这一点在 docs/css/common/color.md 的末尾以“注意”形式强调：

在 pages.json 中，仅支持设置 16 进制颜色 hex-color。

也就是说，导航栏背景、页面背景、tabBar 等原生配置的颜色值只能写#RGB/#RRGGBB/#RGBA/#RRGGBBAA形式的十六进制，不能写rgb(255, 0, 0)、red或transparent。结合 pages.json 配置文档可以梳理出涉及颜色的主要配置项：

导航栏背景色navigationBarBackgroundColor：类型为字符串，默认值 App/Web 端为#F8F8F8，微信小程序等平台为#000000，支付宝/快手小程序为#ffffff；手机顶部状态栏的背景色与前景色（white/black）与此配置及navigationBarTextStyle保持一致。
页面容器背景色backgroundColorContent：默认#ffffff，支持#RRGGBB写法，是页面内容的容器背景。
下拉刷新窗口背景色backgroundColor：默认#ffffff，被页面容器背景色覆盖，仅在页面开启下拉刷新时才可能看到此颜色。
iOS 回弹区域背景色backgroundColorTop/backgroundColorBottom：默认#ffffff，仅 iOS 平台生效。
tabBar 背景色（tabBar下的backgroundColor）：默认值为空（必填项），支持十六进制写法，此外tabBar的color、selectedColor、borderStyle等同样按各平台约束取值。

{ "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页", "navigationBarBackgroundColor": "#007AFF", "backgroundColorContent": "#F2F2F2" } } ], "globalStyle": { "navigationBarBackgroundColor": "#F8F8F8", "backgroundColor": "#ffffff" } }

一个小程序平台的补充约束：pages.json 中各个颜色的设置在小程序平台仅支持普通的 16 进制数值；App 和 Web 端支持设置为transparent（透明）。这与 pages.json 配置文档中“状态栏”一节的说明一致，跨端配置时需要区分对待。

跨端颜色写法实践建议

综合以上兼容性矩阵、函数支持范围与默认值差异，在 uni-app x 中编写颜色样式可遵循以下建议：

App 端优先使用 hex 与 rgb()/rgba()：这是 Android、iOS、HarmonyOS 三端从低版本起即全量支持的颜色表达方式；transparent关键字同样安全。
Web 端可以放开使用现代颜色语法，但要意识到端差异：hsl()、hwb()、lab()、oklab()、lch()、oklch()、color()、color-mix()及各类 relative 相对颜色语法仅在 Web 与微信小程序可用（微信小程序从 4.41 起支持），App 原生渲染端不支持。若页面需同时运行在 App 与 Web，避免在 App 端依赖这些写法。
显式书写颜色值，不依赖继承与 currentcolor：App 端样式不继承、currentColor不可用、边框默认色为#000000，因此文字颜色、边框颜色都应直接写到目标组件上。
pages.json 中只写十六进制：涉及原生导航栏、页面背景、tabBar 等配置项时，颜色值统一使用#RRGGBB（或带 alpha 的#RRGGBBAA），不要使用函数或颜色关键字。
半透明场景注意版本门槛：带 alpha 的四位/八位 hex 在 App 端要求 HBuilderX 4.41+，低版本项目可改用rgba()函数（Android 3.9 / iOS 4.11 / HarmonyOS 4.61 即支持）。
参考官方示例工程：仓库的 src/pages/CSS/function/ 目录下提供了 rgb.uvue、rgba.uvue 等可直接运行的演示页，是验证颜色跨端表现的第一手素材。

企业官网建设流程全解析