ArkUI 入门：Text 组件背景属性

一、先看效果总览

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

• 纯色背景
• 本地图片背景
• 背景图位置控制（居中、自定义坐标）
• 背景图缩放模式（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) // 居中

常用枚举值：

方式 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)

三种模式对比：

方式 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)

四种模式对比：

七、跨设备适配：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)，确保从左上角开始平铺。