HarmonyOS6 ArkTS Span组件使用文档

Span是 HarmonyOS6 中基于 ArkTS 开发的行内文本子组件，需嵌套在Text组件中使用，不支持单独渲染。

完整代码

@Entry @Component struct SpanFullDemo { @State textShadows: ShadowOptions[] = [ { radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 }, { radius: 10, color: Color.Orange, offsetX: 20, offsetY: 0 }, { radius: 10, color: Color.Yellow, offsetX: 30, offsetY: 0 }, { radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 }, { radius: 10, color: Color.Blue, offsetX: 50, offsetY: 0 } ]; build() { Column({ space: 12 }) { // ========== 示例1：设置文本样式 ========== Text("示例1：文本样式、装饰、间距、大小写、点击事件") .fontSize(16) .fontWeight(FontWeight.Bold); Text() { Span("行内文本") Span("组合") Span("演示！") } Text() { Span("下划线波浪").decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }) } Text() { Span("删除线点状").decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED }) } Text() { Span("上划线虚线").decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED }) } Text() { Span("字间距 -2").letterSpacing(-2) Span(" 默认间距").letterSpacing(0) Span(" 间距 3").letterSpacing(3) } Text() { Span("小写").textCase(TextCase.LowerCase) Span(" 大写").textCase(TextCase.UpperCase) } Text() { Span("常规字体").fontStyle(FontStyle.Normal) Span(" 斜体").fontStyle(FontStyle.Italic) } Text() { Span("细体").fontWeight(FontWeight.Lighter) Span(" 粗体").fontWeight(FontWeight.Bold) } Text() { Span("行高默认\n") Span("行高30").lineHeight(30) } Text() { Span("统一字体样式").font({ size: 16, weight: FontWeight.Bolder, style: FontStyle.Italic, family: "HarmonyOS Sans" }) } Text() { Span("普通文本 ") Span("可点击文本").onClick(() => { console.info("Span 被点击了！"); }).fontColor(Color.Blue) } // ========== 示例2：文本阴影 ========== Text("示例2：文本阴影（多重阴影）") .fontSize(16) .fontWeight(FontWeight.Bold) .margin({ top: 10 }); Text() { Span("彩虹阴影文字") .fontSize(30) .textShadow(this.textShadows) .fontColor(Color.White) } // ========== 示例3：文本背景样式 ========== Text("示例3：背景圆角") .fontSize(16) .fontWeight(FontWeight.Bold) .margin({ top: 10 }); Text() { Span(" 带背景圆角的Span ") .fontSize(20) .textBackgroundStyle({ color: "#7F007DFF", radius: 5 }) .fontColor(Color.White) } // ========== 示例4：基线偏移 ✅ 正确官方写法 ✅ ========== Text("示例4：基线偏移 baselineOffset") .fontSize(16) .fontWeight(FontWeight.Bold) .margin({ top: 10 }); } .width('100%') .padding(15) .backgroundColor('#fff') } }

运行效果如图：

使用基础

1 组件嵌套规则

Span为非独立渲染组件，必须作为Text组件的子节点使用，单个Text可嵌套多个Span组件，实现同一行/块内不同文本片段的样式差异化，基础嵌套格式：

Text() { Span("文本片段1") // 单独样式 Span("文本片段2") // 不同样式 }

2 状态管理适配

支持与@State、@Prop等 ArkTS 状态变量配合使用，示例中通过@State定义多重阴影配置数组textShadows，实现阴影样式的统一管理和动态修改。

核心API

1 基础文本样式属性

用于配置Span文本的基础字体和排版样式，支持单独配置，不影响同个Text内其他Span，核心属性如下：

2 文本装饰线属性：decoration

配置文本的装饰线样式，支持下划线、删除线、上划线，传入TextDecorationOptions对象，支持装饰线类型、颜色、样式三重定制，参数如下：

Span("下划线波浪").decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY })

3 文本阴影属性：textShadow

配置文本阴影效果，支持单阴影和多重阴影，入参为ShadowOptions单个对象或数组，ShadowOptions配置项如下：

4 文本背景属性：textBackgroundStyle

为行内文本配置背景色和圆角，实现重点文本高亮效果，传入TextBackgroundStyle对象，配置项如下：

Span(" 带背景圆角的Span ").textBackgroundStyle({ color: "#7F007DFF", radius: 5 })

5 排版控制属性：baselineOffset

设置行内文本相对于基线的偏移量，实现文本上下错位排版，入参为数字类型（单位vp）：

• 正值：文本向上偏移；
• 0：默认基线位置；
• 负值：文本向下偏移。
  基础用法：

Span("上移20").baselineOffset(20); Span("下移20").baselineOffset(-20);

6 交互事件：onClick

为单个Span文本片段绑定点击事件，实现行内文本的精准交互，点击后触发回调函数，支持日志打印、状态修改、路由跳转等操作，使用示例：

Span("可点击文本").onClick(() => { console.info("Span 被点击了！"); }).fontColor(Color.Blue) // 配合颜色区分可点击文本

示例拆解

1 示例1：文本样式、装饰、间距、大小写、点击事件

整合Span基础样式和基础交互能力，实现：

1. 多Span组件组合渲染行内文本；
2. 三种装饰线（下划线/删除线/上划线）+ 四种样式（波浪/点状/虚线/实线）的定制；
3. 字间距正负值调整、文本大小写转换；
4. 字体样式（斜体/常规）、字重（细体/粗体）、行高的单独配置；
5. 字体样式统一配置（font属性）；
6. 行内文本点击事件绑定，区分可点击/普通文本。

2 示例2：文本阴影（多重阴影）

通过@State定义ShadowOptions数组，配置红、橙、黄、绿、蓝五色阴影，实现多重彩虹阴影效果，演示textShadow数组入参的使用方式，适配大字体标题的视觉增强场景。

3 示例3：背景圆角

通过textBackgroundStyle配置半透明背景色和圆角，实现行内文本高亮效果，解决重点文本（如关键词、标签）的视觉突出需求，同时配合fontColor实现背景与文本的颜色对比。

4 示例4：基线偏移

演示baselineOffset属性的核心用法，通过正负值实现文本上下偏移，适用于脚注、上标/下标（如数学公式、单位标注）、行内文本错位排版等场景。

总结

1. 嵌套限制：Span仅能嵌套在Text组件中使用，不支持单独渲染，也不支持嵌套其他容器组件（如Row、Column）；
2. 样式隔离：单个Span的样式配置仅对自身生效，不影响同个Text内其他Span，实现行内样式隔离；
3. 单位规范：所有数值型样式属性（如fontSize、lineHeight、radius）默认单位为vp，无需手动指定；
4. 多重阴影：配置多重阴影时，textShadow入参为ShadowOptions数组，阴影按数组顺序叠加渲染；
5. 透明背景：配置文本背景时，使用八位十六进制颜色值实现透明效果，前两位为透明度（00-FF），后六位为颜色值；
6. 点击事件：为Span绑定点击事件后，建议配合fontColor、decoration等属性做视觉区分，提升用户体验；
7. 版本适配：Span组件的所有高级特性（如多重阴影、文本背景）均基于 API 11+ 实现，需确保项目编译版本不低于 API 11。

HarmonyOS6 ArkTSSpan组件是实现行内文本精细化样式控制的核心子组件，通过与Text组件配合，可轻松实现富文本的行内样式差异化，其提供的装饰线、阴影、背景、基线偏移等能力，覆盖了从基础文本样式到高级视觉增强、精准交互的全场景需求。

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