输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
指南与API参考API参考应用框架ArkUI（方舟UI框架）ArkTS组件文本与输入ContainerSpan

ContainerSpan

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
更新时间: 2026-08-29 09:41
本文导读
展开章节

Text组件的子组件，用于统一管理多个Span、ImageSpan的背景色及圆角弧度，适用于需要为文本片段和图片组合设置统一背景样式的场景。

说明

  • 该组件从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

  • 本模块接口仅可在Stage模型下使用。

子组件

可以包含Span、ImageSpan 子组件。

接口

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

ContainerSpan()

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

仅支持以下属性：

textBackgroundStyle

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textBackgroundStyle(style: TextBackgroundStyle)

设置文本背景样式。子组件在不设置该属性时，将继承此属性值。未通过该接口设置时，默认背景颜色为Color.Transparent，圆角弧度为0。

说明

从API version 12开始，该接口支持在attributeModifier中调用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
style TextBackgroundStyle 是 文本背景样式，用于设置ContainerSpan组件内Span和ImageSpan的文本背景颜色和圆角弧度。子组件不设置该属性时将继承此样式。

attributeModifier12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

attributeModifier(modifier: AttributeModifier<ContainerSpanAttribute>)

设置组件的动态属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
modifier AttributeModifier<ContainerSpanAttribute> 是 动态设置组件的属性。开发者需自定义类继承AttributeModifier接口，在applyNormalAttribute方法中接收ContainerSpanAttribute实例并动态修改ContainerSpan的属性值。

事件

不支持通用事件。

示例

示例1（设置背景样式）

从API version 11开始，该示例通过textBackgroundStyle属性展示了文本设置背景样式的效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Component
  3. @Entry
  4. struct Index {
  5.   build() {
  6.     Column() {
  7.       Text() {
  8.         ContainerSpan() {
  9.           // $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。
  10.           ImageSpan($r('app.media.app_icon'))
  11.             .width('40vp')
  12.             .height('40vp')
  13.             .verticalAlign(ImageSpanAlignment.CENTER)
  14.           Span('   Hello World !   ').fontSize('16fp').fontColor(Color.White)
  15.         }
  16.         .textBackgroundStyle({
  17.           color: '#7F007DFF',
  18.           radius: {
  19.             topLeft: 12,
  20.             topRight: 12,
  21.             bottomLeft: 12,
  22.             bottomRight: 12
  23.           }
  24.         })
  25.       }
  26.     }.width('100%').alignItems(HorizontalAlign.Center)
  27.   }
  28. }

示例2（通过attributeModifier设置背景样式）

从API version 12开始，该示例通过attributeModifier属性展示了文本设置背景样式的效果。

收起
自动换行
深色代码主题
复制
  1. import { ContainerSpanModifier } from '@kit.ArkUI';
  2. 

  3. class MyContainerSpanModifier extends ContainerSpanModifier {
  4.   applyNormalAttribute(instance: ContainerSpanAttribute): void {
  5.     super.applyNormalAttribute?.(instance);
  6.     this.textBackgroundStyle({ color: '#7F007DFF', radius: '12vp' });
  7.   }
  8. }
  9. 

  10. @Entry
  11. @Component
  12. struct ContainerSpanModifierExample {
  13.   @State containerSpanModifier: ContainerSpanModifier = new MyContainerSpanModifier();
  14. 

  15.   build() {
  16.     Column() {
  17.       Text() {
  18.         ContainerSpan() {
  19.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  20.           ImageSpan($r('app.media.startIcon'))
  21.             .width('40vp')
  22.             .height('40vp')
  23.             .verticalAlign(ImageSpanAlignment.CENTER)
  24.           Span(' I\'m ContainerSpan attributeModifier ').fontSize('16fp').fontColor(Color.White)
  25.         }.attributeModifier(this.containerSpanModifier as MyContainerSpanModifier)
  26.       }
  27.     }.width('100%').alignItems(HorizontalAlign.Center)
  28.   }
  29. }

ImageSpan
SelectionContainer
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明