一、先看效果总览

我们最终会实现以下背景效果：

• 纯色背景
• 本地图片背景
• 背景图位置控制（居中、自定义坐标）
• 背景图缩放模式（Contain / Cover / 自定义尺寸）
• 背景图平铺模式（不平铺 / 水平 / 垂直 / 全平铺）
• 跨设备适配（vp 与 px 转换）

---

二、基础：给 Text 加个纯色背景

1. 核心属性：backgroundColor

语法：

Text('纯色背景文本')
  .width(200)
  .height(80)
  .backgroundColor(Color.Pink)

• 支持 Color 枚举（Color.Red / Color.Blue）、十六进制颜色（'#FF00FF'）、RGB 颜色。
• 背景色会填充整个 Text 组件区域，包括 padding 部分。

2. 完整代码示例

@Entry
@Component
struct BackgroundDemo {
  build() {
    Column({ space: 20 }) {
      Text('纯色背景文本')
        .width(200)
        .height(80)
        .backgroundColor(Color.Pink)
        .fontColor(Color.White)
        .fontSize(18)
    }
    .padding(20)
  }
}

---

三、进阶：给 Text 加本地背景图

1. 核心属性：backgroundImage

1.1 资源准备

本地图片需要放在 resources/base/media 目录下，比如放一张 flower.png，引用方式为 $r('app.media.flower')。

1.2 基础语法

Text('带背景图的文本')
  .width(300)
  .height(150)
  .backgroundColor(Color.Pink) // 背景色会被背景图覆盖透明部分
  .backgroundImage($r('app.media.flower'))

• backgroundImage 会覆盖在 backgroundColor 之上，如果图片有透明区域，会透出背景色。

---

四、控制背景图位置：backgroundImagePosition

1. 两种设置方式

方式 1：Alignment 枚举（推荐）

支持 9 种预设位置，自动适配组件尺寸：

Text('背景图居中')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.flower'))
  .backgroundImagePosition(Alignment.Center) // 居中

常用枚举值：

枚举值	效果
Alignment.TopStart	左上角
Alignment.Top	顶部居中
Alignment.TopEnd	右上角
Alignment.Start	左侧居中
Alignment.Center	正中间
Alignment.End	右侧居中
Alignment.BottomStart	左下角
Alignment.Bottom	底部居中
Alignment.BottomEnd	右下角

方式 2：自定义坐标 {x, y}

背景图左上角的位置，单位为 px，固定位置，不随组件尺寸变化：

Text('背景图自定义位置')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.flower'))
  .backgroundImagePosition({ x: 100, y: 50 }) // 图片左上角在(100,50)位置

---

五、背景图缩放控制：backgroundImageSize

1. 两种设置方式

方式 1：ImageSize 枚举（推荐）

Text('Contain模式')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.flower'))
  .backgroundImageSize(ImageSize.Contain)

三种模式对比：

枚举值	效果	适用场景
ImageSize.Contain	等比缩放，完整显示图片，可能留白	图标、Logo，需要完整显示
ImageSize.Cover	等比缩放，完全覆盖组件，可能裁切	背景横幅、轮播图，需要填满区域
ImageSize.Auto	保持原图尺寸	固定大小的装饰图

方式 2：自定义宽高

Text('自定义背景图大小')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.flower'))
  .backgroundImageSize({ width: 100, height: 80 }) // 图片固定为100×80

---

六、背景图平铺控制：ImageRepeat

1. 核心参数

backgroundImage 支持第二个参数设置平铺模式：

Text('XY全平铺')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.pattern'), ImageRepeat.XY)

四种模式对比：

枚举值	效果	适用场景
ImageRepeat.NoRepeat	不平铺，仅显示一次（默认）	单张背景图
ImageRepeat.X	水平方向重复	横向纹理背景
ImageRepeat.Y	垂直方向重复	纵向纹理背景
ImageRepeat.XY	水平 + 垂直全重复	棋盘格、纹理背景

---

七、跨设备适配：vp 与 px 转换

1. 为什么要转换？

• 组件宽高、圆角等属性推荐用 vp（虚拟像素），跨设备自动适配。
• 背景图位置 backgroundImagePosition 只支持 px（物理像素），需要用 vp2px() 转换。

2. 正确用法

Text('适配背景图位置')
  .width(300)
  .height(150)
  .backgroundImage($r('app.media.flower'))
  .backgroundImagePosition({
    x: vp2px(150), // 组件宽的一半
    y: vp2px(75)   // 组件高的一半
  })

• vp2px(150) 会根据当前设备分辨率自动转换为对应的物理像素值，保证背景图在不同设备上都居中。

八、常见坑点与解决方案

1. 背景图不显示

   • 检查图片路径是否正确，是否放在 resources/base/media 目录。
   • 组件是否设置了 width 和 height，没有尺寸的组件无法渲染背景图。

2. 背景图位置不对

   • 自定义坐标时，注意 backgroundImagePosition 单位是 px，需要用 vp2px() 转换。
   • 组件有 padding 时，背景图位置是相对于内容区（不含 padding）的，需要调整坐标。

3. 背景图变形 / 裁切

   • 想要完整显示：用 ImageSize.Contain，可能留白。
   • 想要填满组件：用 ImageSize.Cover，可能裁切。
   • 想要自定义比例：用 backgroundImageSize({width, height})。

4. 背景图平铺有缝隙

   • 检查图片是否有透明边框，建议使用无白边的纹理图。
   • 设置 backgroundImagePosition(Alignment.TopStart)，确保从左上角开始平铺。