【ArkUI 文本展示系列】四：Text组件属性详解

Text组件自身有设置文本样式、布局风格、配置自适应布局策略的方法，由不同的接口完成，对Text整体的所有字符生效。这些接口分为三类：

类别	包含内容
字体样式	字体、字号、字重、斜体、字体颜色、渐变色、背景色、阴影效果、装饰线、文字描边
文本布局风格	对齐方式、垂直居中、首行缩进、行尾空格、字符间距、行间距、行高
自适应布局	最大字号、最小字号、最大行数、超长文本显示方式

一、设置字体样式

1.1、设置字体大小、字体粗细、字体族、字体风格

有两种方式，可以选择调用fontSize,fontWeight,fontfamily,fontStyle接口，分别设置字体大小、字体粗细、字体族、字体风格；也可以调用font接口，在入参中单独配置。字体风格实际上就是斜体。

@Entry
@Component
struct demo {
  build() {
    Column() {
      Text("字体样式")
        .fontSize(16)
        .fontWeight(FontWeight.Normal)
        .fontFamily('HarmonyOS Sans')
        .fontStyle(FontStyle.Normal)
      Text("字体样式")
        .font({
          size: 32,
          weight: FontWeight.Bolder,
          family: 'HarmonyOS Sans SC',
          style: FontStyle.Italic
        })
    }
  }
}

效果图如下

1.2、设置字体的颜色、添加渐变色、添加背景色、

fontColor接口可以设置纯色的字体颜色，shaderStyle接口可以设置渐变色，并且会覆盖fontColor的效果。backgroundColor属于通用属性，用来设置背景颜色。背景渐变色可以通过linearGradient接口实现。

Text('字体颜色')
    .fontColor(Color.Red)

Text('字体渐变色')
    .shaderStyle({
        angle: 45,
        colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]]
    })

Text('背景颜色')
    .backgroundColor(Color.Blue)

Text('背景渐变色')
    .linearGradient({
        angle: 45,
        colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]],
    })

1.3、装饰线

接口decoration，可以设置装饰线的位置，如上划线、中划线、下除线，可以设置波浪线、实线，也可以配置装饰线颜色。其他的场景，如多条下划线、自定义装饰线的线段样式，无法直接实现。如果想要自定义装饰线位置、多段装饰线，需要配合overlay实现。

1.3.1、下划线避让

当文字的下边缘轮廓与装饰线位置相交时，会触发下划线避让规则，下划线将在这些字符处避让文字。常见“gjyqp”等英文字符。注意，下划线避让会导致空隙出现。

如果不想要下划线避让，可以通过overlay+border绘制下划线。

1.3.2、透明色下划线

为避免开发者遗漏设置颜色，当前规格中设置color为Color.Transparent或“#00000000”时，装饰线颜色跟随每行第一个字的字体颜色。故需要设置装饰线颜色值为字符串格式，即透明色16进制对应值“#00FFFFFF”，实现装饰线为透明的效果。

1.3.3、自定义下划线位置

自定义下划线实现，可以通过在Text上堆叠overlay实现。下划线用overlayNode中的border、decoration等方式实现，绘制出线条后通过offset调整位置。

1.3.4、多段装饰线

Api 19及以下版本也是通过ovelay实现。
Api 20以上支持通过属性字符串设置多段装饰线，参考DecorationOptions接口说明。
下划线的示例代码

@Entry
@Component
struct demo {
  @State messageBorder: string = 'overlay中border绘制下划线'
  @State messageDecoration: string = 'overlay中decoration绘制下划线'
  @State messageTwoLine: string = '绘制2条装饰线'

  build() {
    Column({ space: 20 }) {
      Text('上划线')
        .decoration({ type: TextDecorationType.Overline })

      Text('中划线')
        .decoration({ type: TextDecorationType.LineThrough })

      Text('下划线')
        .decoration({ type: TextDecorationType.Underline })

      Text('装饰线颜色跟随fontColor')
        .fontColor(Color.Green)
        .decoration({ type: TextDecorationType.Underline, color: Color.Transparent })

      Text('透明装饰线')
        .fontColor(Color.Green)
        .decoration({ type: TextDecorationType.Underline, color: '#00FFFFFF' })

      // overlay中decoration绘制下划线，注意y的位置有下划线避让
      Text(this.messageDecoration)
        .overlay(this.OverlayNodeDecoration(), {
          align: Alignment.Start,
          offset: { x: 0, y: 0 }
        })

      // overlay中border绘制下划线，注意y的位置没有下划线避让
      Text(this.messageBorder)
        .overlay(this.OverlayNodeBorder(), {
          align: Alignment.Start,
          offset: { x: 0, y: -2 }
        })

      Text(this.messageTwoLine)
        .decoration({ type: TextDecorationType.Underline })
        .overlay(this.OverlayNodeTwoLine(), {
          align: Alignment.Start,
          offset: { x: 0, y: -10 }
        })

      // 字体放大后，下划线避让非常明显
      Text('下划线避让 gjyqp')
        .fontColor(Color.Green)
        .fontSize(25)
        .decoration({ type: TextDecorationType.Underline})

      // border 绘制的下划线，位置更靠下
      Text('border绘制下划线 gjyqp')
        .fontColor(Color.Green)
        .fontSize(25)
        .borderWidth({bottom:1})
    }
    .padding(20)
  }

  @Builder
  OverlayNodeDecoration() {
    Text(this.messageDecoration)
    //decoration绘制下划线，下划线避让，会导致y的位置出现一段空白
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Blue,
        style: TextDecorationStyle.SOLID
      })
      .fontColor(Color.Transparent)
      .hitTestBehavior(HitTestMode.Transparent) // 配置浮层不阻塞交互
  }

  @Builder
  OverlayNodeBorder() {
    Text(this.messageBorder)
      .borderWidth({ bottom: 1 })
      .borderColor(Color.Red)
      .fontColor(Color.Transparent)
      .hitTestBehavior(HitTestMode.Transparent) // 配置浮层不阻塞交互
  }

  @Builder
  OverlayNodeTwoLine() {
    Text(this.messageTwoLine)
      .borderWidth({ bottom: 1 })
      .borderColor(Color.Yellow)
      .fontColor(Color.Transparent)
      .hitTestBehavior(HitTestMode.Transparent) // 配置浮层不阻塞交互
  }
}

效果图如下：

1.4、文字阴影

通过textShadow接口实现，示例代码如下

      Text('textShadow')
        .textShadow({
          radius: 10,
          color: Color.Green,
          offsetX: 0,
          offsetY: 0
        })

阴影效果图：

1.5、文字描边

Text没有接口直接实现，需要通过属性字符串设置。属性字符串的API参考提供了示例： 示例11属性字符串的文本描边。

二、文本布局风格

2.1、设置文本的对齐方式

Text有textAlign、textVerticalAlign和halfLeading接口，这三个接口的作用是确定一行内的文字放置在哪个位置。

• textAlign，设置文本段落在水平方向的对齐方式，包括：水平对齐首部、水平居中对齐、水平对齐尾部、、双端对齐。
• textVerticalAlign，设置文本段落在垂直方向的对齐方式，包括：对齐文本顶部、垂直居中对齐、对齐文本底部、对齐文本基线。
• halfLeading，设置文本是否将行间距平分至行的顶部与底部。

2.2、设置间距

Text有letterSpacing、lineSpacing和lineHeight接口，这三个接口的作用是确定字符之间上下左右的空隙是多大。

• letterSpacing，设置文本字符间距。影响两个字符之间左右的间隔。
• lineSpacing，设置文本的行间距，影响两个字符之间上下的间隔。
• lineHeight，设置行高，一个文本行占据的高度，影响两个字符之间上下的间隔。

2.3、特殊字符布局

一个常见问题是，一行文本中存在一个特殊字符，导致整行文本的位置向下偏移，像是“沉降下落”，和下一行的文本重叠在一起。解决方案是设置halfLeading+lineHeight。

@Entry
@Component
struct demo {
  @State message: string = '测试\ud808\ude6d'

  build() {
    Row({ space: 20 }) {
      Text('测试')
        .borderWidth(1)
        .height(20)

      Text(this.message)
        .height(20)
        .borderWidth(1)

      Text(this.message)
        .height(20)
        .borderWidth(1)
        .halfLeading(true)
        .lineHeight(16)
    }
    .padding(20)
  }
}

效果图如下

三、自适应布局

自适应布局解决以下问题：

1. 不知道文本长度，但是预期最多只展示三行文本
2. 字体大小跟随系统缩放，但是不能放的太大

3.1、跟随系统缩放时，如何自适应布局

Text有以下接口，控制字体大小缩放

1. minFontSize，设置文本最小显示字号
2. maxFontSize，设置文本最大显示字号
3. minFontScale，设置文本最小的字体缩放倍数
4. maxFontScale，设置文本最大的字体缩放倍数

Text的API参考中提供了示例设置文本自适应和缩放倍数限制范围。

3.2、超长文本显示时，如何自适应布局

Text有以下接口，控制文本超长时的绘制效果

1. maxLines，设置文本的最大行数。
2. textOverflow，设置文本超长时的显示方式。可以选择截断文本、显示省略号、跑马灯。
3. wordBreak，设置断行规则。影响截断文本时，是否在末尾留有空白。
4. lineBreakStrategy，设置折行规则。影响每行显示字符数量的多寡。

Text的API参考中提供了示例设置文本超长省略。