HarmonyOS6 背景设置：background 基础属性全解析

文章目录

- 一、本篇涉及的属性总览
- [二、backgroundColor 背景色](#二、backgroundColor 背景色)
- - [2.1 函数签名](#2.1 函数签名)
  - [2.2 示例代码](#2.2 示例代码)
- [三、backgroundImage 背景图片](#三、backgroundImage 背景图片)
- - [3.1 函数签名](#3.1 函数签名)
  - [3.2 ImageRepeat 枚举](#3.2 ImageRepeat 枚举)
  - [3.3 示例代码](#3.3 示例代码)
- [四、backgroundImageSize 背景图片尺寸](#四、backgroundImageSize 背景图片尺寸)
- - [4.1 函数签名](#4.1 函数签名)
  - [4.2 示例代码](#4.2 示例代码)
  - [4.3 Cover 与 Contain 的对比](#4.3 Cover 与 Contain 的对比)
- [五、backgroundImagePosition 背景图片位置](#五、backgroundImagePosition 背景图片位置)
- - [5.1 函数签名](#5.1 函数签名)
  - [5.2 示例代码](#5.2 示例代码)
- 六、完整示例代码
- 七、属性联动关系
- 总结

一、本篇涉及的属性总览

本篇介绍 ArkUI 背景设置的基础四个通用属性，适用于所有组件：

属性	函数签名	API 版本	作用
`backgroundColor`	`backgroundColor(value: ResourceColor): T`	API 8+	设置组件背景色
`backgroundImage`	`backgroundImage(src: ResourceStr, repeat?: ImageRepeat): T`	API 8+	设置背景图片及平铺方式
`backgroundImageSize`	`backgroundImageSize(value: SizeOptions	ImageSize): T`	API 8+
`backgroundImagePosition`	`backgroundImagePosition(value: Position	Alignment): T`	API 8+

二、backgroundColor 背景色

2.1 函数签名

typescript 复制代码

backgroundColor(value: ResourceColor): T

ResourceColor 支持多种写法：

写法	示例	说明
Color 枚举	`Color.Red`	系统预定义颜色
十六进制数字	`0xE5E5E5`	不带 `#` 的十六进制数
十六进制字符串	`'#FF0000'`	带 `#` 的颜色字符串
rgba 字符串	`'rgba(255,0,0,0.5)'`	带透明度的颜色
资源引用	`$r('app.color.xxx')`	引用 `resources` 中定义的颜色

2.2 示例代码

typescript 复制代码

Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC)
Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 })

这里使用十六进制数字 0xE5E5E5 设置浅灰色背景。等价写法还有：

typescript 复制代码

.backgroundColor('#E5E5E5')       // 十六进制字符串
.backgroundColor(Color.Gray)      // Color 枚举（接近色）

三、backgroundImage 背景图片

3.1 函数签名

typescript 复制代码

backgroundImage(src: ResourceStr, repeat?: ImageRepeat): T

参数	类型	必填	说明
`src`	`ResourceStr`	是	图片资源，支持 `$r()` 资源引用或网络 URL
`repeat`	`ImageRepeat`	否	平铺方式，默认 `ImageRepeat.NoRepeat`

3.2 ImageRepeat 枚举

枚举值	说明
`ImageRepeat.NoRepeat`	不平铺（默认）
`ImageRepeat.X`	仅沿 X 轴（水平）平铺
`ImageRepeat.Y`	仅沿 Y 轴（垂直）平铺
`ImageRepeat.XY`	沿 X、Y 两个方向平铺

3.3 示例代码

沿 X 轴平铺：

typescript 复制代码

Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC)
Row()
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.X)
  .backgroundImageSize({ width: '250px', height: '140px' })
  .width('90%')
  .height(70)
  .border({ width: 1 })

ImageRepeat.X 表示图片在水平方向上重复排列，直到填满组件宽度。图片高度方向仅显示一张。

沿 Y 轴平铺：

typescript 复制代码

Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC)
Row()
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.Y)
  .backgroundImageSize({ width: '500px', height: '120px' })
  .width('90%')
  .height(100)
  .border({ width: 1 })

ImageRepeat.Y 表示图片在垂直方向上重复排列，直到填满组件高度。图片水平方向仅显示一张。

注意：backgroundImage 的第二个参数 repeat 是可选的，省略时等同于 ImageRepeat.NoRepeat。

四、backgroundImageSize 背景图片尺寸

4.1 函数签名

typescript 复制代码

backgroundImageSize(value: SizeOptions | ImageSize): T

支持两种传参方式：

方式一：SizeOptions 对象（自定义宽高）

typescript 复制代码

{ width: number | string, height: number | string }

数值单位为 vp，字符串可带单位（如 '250px'、'50%'）。

方式二：ImageSize 枚举（预设缩放模式）

枚举值	说明
`ImageSize.Auto`	保持图片原始尺寸
`ImageSize.Cover`	等比缩放铺满容器，超出部分裁剪（不保证图片完整）
`ImageSize.Contain`	等比缩放完整显示，容器可能留白（保证图片完整）

4.2 示例代码

自定义尺寸（像素值）：

typescript 复制代码

Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC)
Row()
  .width('90%')
  .height(150)
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
  .backgroundImageSize({ width: 1000, height: 500 })
  .border({ width: 1 })

此处将背景图设为 1000×500 vp，远大于组件本身，因此只显示图片的局部区域。

ImageSize.Cover（铺满裁剪）：

typescript 复制代码

Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC)
// 不保证图片完整的情况下占满盒子
Row()
  .width(200)
  .height(50)
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
  .backgroundImageSize(ImageSize.Cover)
  .border({ width: 1 })

Cover 模式下，图片等比缩放直到宽或高与容器对齐，另一边超出容器则被裁剪。结果：图片一定铺满容器，但可能看不到图片边缘。

ImageSize.Contain（完整显示）：

typescript 复制代码

Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC)
// 保证图片完整的情况下放到最大
Row()
  .width(200)
  .height(50)
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
  .backgroundImageSize(ImageSize.Contain)
  .border({ width: 1 })

Contain 模式下，图片等比缩放直到宽和高都不超出容器，可能在容器内留出空白区域。结果：图片一定完整显示，但容器可能有空白。

4.3 Cover 与 Contain 的对比

复制代码

容器（宽 > 高的矩形）+ 正方形图片：

Cover 模式：
┌──────────────────────────┐
│  [  图片铺满，两侧被裁剪 ]│
└──────────────────────────┘

Contain 模式：
┌──────────────────────────┐
│        ┌──────┐          │
│  空白  │ 图片 │  空白    │
│        └──────┘          │
└──────────────────────────┘

五、backgroundImagePosition 背景图片位置

5.1 函数签名

typescript 复制代码

backgroundImagePosition(value: Position | Alignment): T

支持两种传参方式：

方式一：Position 对象（坐标偏移）

typescript 复制代码

{ x: number, y: number }

以组件左上角为原点，单位 px。负值表示图片向左/向上偏移，即图片超出组件左/上边界。

方式二：Alignment 枚举（预设对齐位置）

枚举值	位置
`Alignment.TopStart`	左上角
`Alignment.Top`	顶部居中
`Alignment.TopEnd`	右上角
`Alignment.Start`	左侧居中
`Alignment.Center`	正中央（默认）
`Alignment.End`	右侧居中
`Alignment.BottomStart`	左下角
`Alignment.Bottom`	底部居中
`Alignment.BottomEnd`	右下角

5.2 示例代码

typescript 复制代码

Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC)
Row()
  .width(100)
  .height(50)
  // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
  .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
  .backgroundImageSize({ width: 1000, height: 560 })
  .backgroundImagePosition({ x: -500, y: -300 })
  .border({ width: 1 })

解析：

背景图被设置为 1000×560 vp 的大尺寸（远超容器的 100×50）
{ x: -500, y: -300 } 表示图片左上角向左偏移 500px、向上偏移 300px
等效于：将图片的中心区域"窗口"显示在容器中，是一种手动实现"雪碧图"定位的经典技巧

图片（1000×560）向左上方偏移后，容器"窗口"显示的是图片中间偏右下的区域：

图片坐标系：
(0,0)──────────────────────(1000,0)
│ │
│ [容器窗口] │
│ (500,300)──(600,350) │
│ │
(0,560)─────────────────────(1000,560)

六、完整示例代码

typescript 复制代码

@Entry
@Component
struct BackgroundExample {
  build() {
    Column({ space: 5 }) {
      Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC)
      Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 })

      Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC)
      Row()
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.X)
        .backgroundImageSize({ width: '250px', height: '140px' })
        .width('90%')
        .height(70)
        .border({ width: 1 })

      Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC)
      Row()
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.Y)
        .backgroundImageSize({ width: '500px', height: '120px' })
        .width('90%')
        .height(100)
        .border({ width: 1 })

      Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC)
      Row()
        .width('90%')
        .height(150)
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
        .backgroundImageSize({ width: 1000, height: 500 })
        .border({ width: 1 })

      Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC)
      // 不保证图片完整的情况下占满盒子
      Row()
        .width(200)
        .height(50)
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
        .backgroundImageSize(ImageSize.Cover)
        .border({ width: 1 })

      Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC)
      // 保证图片完整的情况下放到最大
      Row()
        .width(200)
        .height(50)
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
        .backgroundImageSize(ImageSize.Contain)
        .border({ width: 1 })

      Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC)
      Row()
        .width(100)
        .height(50)
        // $r('app.media.startIcon') 需要替换为开发者所需的图像资源文件。
        .backgroundImage($r('app.media.startIcon'), ImageRepeat.NoRepeat)
        .backgroundImageSize({ width: 1000, height: 560 })
        .backgroundImagePosition({ x: -500, y: -300 })
        .border({ width: 1 })
    }
    .width('100%').height('100%').padding({ top: 5 })
  }
}

运行效果如图所示：

七、属性联动关系

在实际使用中，backgroundImage、backgroundImageSize、backgroundImagePosition 三个属性通常配合使用：

复制代码

backgroundImage        → 指定图片资源和平铺方式
       ↓
backgroundImageSize    → 控制图片的展示尺寸（拉伸/裁剪/原尺寸）
       ↓
backgroundImagePosition → 控制图片在组件内的起始偏移位置

典型搭配场景：

场景	backgroundImageSize	backgroundImagePosition	backgroundImage repeat
背景铺满卡片	`ImageSize.Cover`	默认居中	`NoRepeat`
完整展示图标	`ImageSize.Contain`	`Alignment.Center`	`NoRepeat`
水平花纹背景	`{ width: 100, height: 100 }`	`{ x: 0, y: 0 }`	`ImageRepeat.X`
雪碧图截取	`{ width: 大值, height: 大值 }`	`{ x: 负偏移, y: 负偏移 }`	`NoRepeat`

总结

属性	核心用途	常用值
`backgroundColor`	纯色背景	十六进制数字、Color 枚举、rgba 字符串
`backgroundImage`	图片背景 + 平铺控制	`$r()` 资源引用 + `ImageRepeat` 枚举
`backgroundImageSize`	图片缩放方式	`Cover`（铺满裁剪）/ `Contain`（完整显示）/ 自定义尺寸
`backgroundImagePosition`	图片起始位置	`Alignment` 枚举对齐 / `{x,y}` 精确偏移（雪碧图）

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！