HarmonyOS开发｜ArkTS UI颜色API通用规则

鸿蒙应用开发工程师在日常写 UI 时，常误以为字体色、背景色、边框色要分开记。其实，在 HarmonyOS开发 中，HarmonyOS ArkTS 所有接收 color 参数的 API，入参规则完全通用------不管是文字、背景、边框，还是阴影、填充，传参逻辑一模一样。学会本篇这组基础用法，就能搞定绝大多数静态配色，省去反复查文档的功夫。​

一、核心知识点：颜色参数统一类型

所有颜色修饰方法支持 4 种入参，类型定义如下：

颜色参数: Color | string | number | Resource

修饰方法	作用	基础示例
.fontColor()	文字字体颜色	Text('文字').fontColor(颜色值)
.backgroundColor()	组件背景色	Column().backgroundColor(颜色值)
.borderColor()	组件边框色	Button().borderColor(颜色值)
.shadowColor()	阴影颜色	Image().shadowColor(颜色值)
.strokeColor()	线条绘制描边色	Shape().strokeColor(颜色值)
.fillColor()	图形填充色	Circle().fillColor(颜色值)

二、两种简易颜色写法（快速开发首选）

1. Color 内置枚举（零色值，快速调试）

鸿蒙官方封装基础纯色枚举，直接调用，无格式错误风险，适合快速写 demo、临时调试页面。

常用枚举： Color.Black 黑色 / Color.White 白色 / Color.Red 红色 / Color.Green 绿色 / Color.Blue 蓝色 / Color.Yellow 黄色 / Color.Transparent 透明

代码示例：

// 文字绿色
Text('测试文本').fontColor(Color.Green)
// 容器蓝色背景
Column().backgroundColor(Color.Blue)
// 红色按钮边框
Button('按钮').border({width:3}).borderColor(Color.Red)
// 灰色文字阴影
Text('阴影文字').shadow({radius:5}).shadowColor(Color.Gray)

2. String 字符串色值（自定义精准配色）

日常开发最常用，支持 RGB、RGBA、十六进制 3 种格式，支持透明度自定义。

1. rgb (0-255,0-255,0-255)：无透明纯色
2. rgba (0-255,0-255,0-255,0~1)：带透明度，0 完全透明，1 不透明
3. #RRGGBB 纯色 / #AARRGGBB 带透明（AA 代表透明度）
   代码示例：

// 十六进制字体色
.fontColor('#008000')
// RGB背景色
.backgroundColor('rgb(0,128,0)')
// RGBA半透明边框
.borderColor('rgba(0,128,0,0.5)')
// 带透明十六进制阴影
.shadowColor('#80808080')

三、实战综合示例

下面是一个完整的 ArkTS 组件示例，它在一个 Column 容器中综合运用了 .fontColor()、.backgroundColor()、.borderColor()、.shadowColor() 等多种颜色修饰方法，并混合使用了 Color 枚举 和字符串色值，直观展示统一颜色参数的实际应用。

// 综合示例：展示多种颜色修饰方法的统一参数用法
@Entry
@Component
struct ColorDemoPage {
  build() {
    Column({ space: 20 }) {
      // 1. 标题文本 - 使用 Color 枚举设置字体颜色
      Text('鸿蒙 ArkTS 颜色实战')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Blue) // 使用 Color 枚举设置蓝色文字

      // 2. 信息卡片 - 混合使用字符串色值设置背景、边框和阴影
      Column() {
        Text('颜色参数统一类型：Color | string | number | Resource')
          .fontSize(18)
          .fontColor('#333333') // 使用十六进制字符串设置深灰色文字
          .margin({ top: 15, bottom: 10 })
        
        Text('本卡片演示了背景色、边框色、阴影色的混合写法。')
          .fontSize(16)
          .fontColor('rgb(100, 100, 100)') // 使用 RGB 字符串设置灰色文字
          .margin({ bottom: 15 })
      }
      .width('90%')
      .padding(20)
      .backgroundColor('#F0F8FF') // 使用十六进制字符串设置浅蓝色背景
      .border({
        width: 2,
        color: 'rgba(0, 100, 200, 0.7)' // 使用 RGBA 字符串设置半透明蓝色边框
      })
      .borderRadius(15)
      .shadow({
        radius: 10,
        color: '#80808080', // 使用带透明度的十六进制字符串设置灰色阴影
        offsetX: 5,
        offsetY: 5
      })

      // 3. 按钮组 - 使用 Color 枚举和字符串色值对比
      Row({ space: 15 }) {
        Button('枚举色按钮')
          .fontColor(Color.White) // 使用 Color 枚举设置白色文字
          .backgroundColor(Color.Red) // 使用 Color 枚举设置红色背景
          .borderColor('#8B0000') // 使用十六进制字符串设置深红色边框
          .border({ width: 1 })
          .padding(10)

        Button('字符串色按钮')
          .fontColor('#FFFFFF') // 使用十六进制字符串设置白色文字
          .backgroundColor('rgb(0, 128, 0)') // 使用 RGB 字符串设置绿色背景
          .borderColor(Color.Green) // 使用 Color 枚举设置绿色边框
          .border({ width: 1 })
          .padding(10)
      }
      .margin({ top: 10 })

      // 4. 底部提示文本 - 使用 Color 枚举设置字体和阴影
      Text('提示：Color 枚举适合快速原型，字符串色值适合精准设计还原。')
        .fontSize(14)
        .fontColor(Color.Gray) // 使用 Color 枚举设置灰色文字
        .shadowColor('rgba(0,0,0,0.1)') // 使用 RGBA 字符串设置浅黑色阴影
        .shadow({ radius: 2 })
        .margin({ top: 30 })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor(Color.White) // 使用 Color 枚举设置白色页面背景
  }
}

代码关键点说明：

1. 参数统一性 ：所有 .fontColor()、.backgroundColor()、.borderColor()、.shadowColor() 方法都接受相同的颜色参数类型，本例中混合使用了 Color 枚举和 string 字符串。
2. Color 枚举应用 ：Color.Blue、Color.Red、Color.White、Color.Green、Color.Gray 等用于快速设置标准颜色。
3. 字符串色值应用 ：
   • 十六进制格式：'#333333'、'#F0F8FF'、'#8B0000'、'#FFFFFF'
   • RGB 格式：'rgb(100, 100, 100)'、'rgb(0, 128, 0)'
   • RGBA 格式：'rgba(0, 100, 200, 0.7)'、'rgba(0,0,0,0.1)'
   • 带透明度十六进制：'#80808080'
4. 实际页面效果：该组件构建了一个完整的演示页面，包含标题、卡片、按钮组和提示文本，可直接运行查看视觉效果。

通过这个示例，你可以直观地看到：无论使用哪种颜色写法，所有颜色 API 的传参方式完全一致，只需掌握 Color 和 string 两种基础写法，就能应对绝大多数 UI 配色场景。

四、本篇小结

1. 鸿蒙全部颜色 API 共用一套参数规则，不用单独记忆；
2. 快速原型开发优先用 Color 枚举，精准自定义配色选用 string 字符串；
3. 所有组件、图形、阴影、边框均可直接套用上述两种写法。

---

💡 想获取更多鸿蒙 ArkTS 开发实战技巧？

本文介绍的颜色参数统一规则 是构建精美 UI 的基础。在 CSDN 社区，还有海量 HarmonyOS 开发者分享的组件封装、动效实现、性能优化等进阶实战内容。点击下方卡片，探索更多优质教程与资源，加速你的鸿蒙应用开发之旅！