3.1.1 Text组件 原创 精华

本节讲解文本组件Text和Span的基本使用方法，同时讲解第一个声明式语法 @Extend装饰器 ，通过该装饰器重构示例代码。

由于本节展示的组件效果较多，一屏无法展示完，我们可以将默认Hello World页面的布局改为使用Scroll布局组件支持纵向滚动，改造后代码如下：

/**
 * 3.1 Text组件和Span组件
 */
@Entry
@Component
struct Index {
  build() {
    Stack({ alignContent: Alignment.TopStart }){
      Scroll() {
        Column({space:16}){
          Text('Hello World')
            .fontSize(50)
            .fontWeight(FontWeight.Bold)
        }.padding({left: $r('app.float.spaceLeft'), right: $r('app.float.spaceRight')}).alignItems(HorizontalAlign.Start)
      }
    }.width('100%').height('100%').backgroundColor($r("app.color.appBg")).padding({top:$r('app.float.spaceTop'), bottom:$r('app.float.spaceBottom')})
  }
}

3.1.1 Text组件

文本组件(Text):用于呈现一段信息。可以包含Span子组件。

1.接口:Text(content?: string)

示例代码：

Text('鸿蒙开发ArkUI最佳实践') // 接口:Text(content?: string)
            .fontColor($r("app.color.fgLevel1")) // 文字颜色
            .fontSize($r("app.float.fontSizeBody1")) // 文字字号
            .fontWeight(Number($r("app.float.fontWeightBody1"))) // 文字字重
            .border({ width: 1,color:$r("app.color.fgLevel1") }) // 边框设置(非必须)
            .padding(10) // 内边距（非必须）

效果如下：

2.文本对齐方式：.textAlign(TextAlign)

设置多行文本的文本对齐方式，通常配合设置Text的宽度(width)属性。示例代码：

		  /**
           * .textAlign(TextAlign) 默认值Start，设置多行文本的文本对齐方式。
           *    TextAlign.Center 文本居中对齐。
           *    TextAlign.Start 根据文字书写相同的方向对齐。
           *    TextAlign.End 根据文字书写相反的方向对齐。
           */
          Text('1.文本对齐方式')
            .fontColor($r("app.color.fgLevel1"))
            .fontSize($r("app.float.fontSizeH8"))
            .fontWeight(Number($r("app.float.fontWeightH8")))
          Text('根据文字书写相同的方向对齐：鸿蒙开发ArkUI最佳实践。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.Start) // 文本对齐方式
            .fontColor($r("app.color.fgLevel1"))
            .fontSize($r("app.float.fontSizeBody1"))
            .fontWeight(Number($r("app.float.fontWeightBody1")))
            .border({ width: 1,color:$r("app.color.fgLevel1") })
            .padding(10)
          Text('文本居中对齐：鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.Center) // 文本对齐方式
            .fontColor($r("app.color.fgLevel1"))
            .fontSize($r("app.float.fontSizeBody1"))
            .fontWeight(Number($r("app.float.fontWeightBody1")))
            .border({ width: 1,color:$r("app.color.fgLevel1") })
            .padding(10)
          Text('根据文字书写相反的方向对齐：鸿蒙开发ArkUI最佳实践。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.End) // 文本对齐方式
            .fontColor($r("app.color.fgLevel1"))
            .fontSize($r("app.float.fontSizeBody1"))
            .fontWeight(Number($r("app.float.fontWeightBody1")))
            .border({ width: 1,color:$r("app.color.fgLevel1") })
            .padding(10)

效果如下：

3.太多重复代码，我受不了了！

上述示范代码中总共用到了两种字号大小，一个是标题，一个是正文。每个文本组件都要设置其样式属性，太多重复的代码，后面还有很多演示代码，这样写下去，我有点受不了了，是时候对上述代码进行重构了！

这里提前讲解第一个声明式语法 @Extend装饰器 ，通过该装饰器重构示例代码。更多的声明式语法在《第8章 基于TS扩展的声明式开发规范》中讲解。

@Extend装饰器将新的属性函数添加到内置组件上，如Text、Column、Button等。通过@Extend装饰器可以快速定义并复用组件的自定义样式。这里定义两个@Extend装饰器，分别用来快速定义标题和正文的样式。标题文本样式装饰器写法如下：

// 标题文本样式
@Extend(Text) function title1() {
  .fontColor($r("app.color.fgLevel1"))
  .fontSize($r("app.float.fontSizeH8"))
  .fontWeight(Number($r("app.float.fontWeightH8")))
}

注意：@Extend装饰器的注释，只能使用单行注释，如果使用多行注释会导致编译异常，如下代码会有问题：

/**
 * 标题文本样式
 * 多行注释会导致编译异常。这应该是个Bug，我已向华为社区论坛提交了该Bug。
 */
@Extend(Text) function title1() {
  .fontColor($r("app.color.fgLevel1"))
  .fontSize($r("app.float.fontSizeH8"))
  .fontWeight(Number($r("app.float.fontWeightH8")))
}

重构后，代码如下：

// 正文文本样式
//    @Extend装饰器将新的属性函数添加到内置组件上，如Text、Column、Button等。
//    通过@Extend装饰器可以快速定义并复用组件的自定义样式。
@Extend(Text) function body() {
  .fontColor($r("app.color.fgLevel1")) // 文字颜色
  .fontSize($r("app.float.fontSizeBody1")) // 文字字号
  .fontWeight(Number($r("app.float.fontWeightBody1"))) // 文字字重
  .border({ width: 1,color:$r("app.color.fgLevel1") })
  .padding(10)
}

// 标题文本样式
@Extend(Text) function title() {
  .fontColor($r("app.color.fgLevel1"))
  .fontSize($r("app.float.fontSizeH8"))
  .fontWeight(Number($r("app.float.fontWeightH8")))
}

/**
 * 3.1 Text组件和Span组件
 */
@Entry
@Component
struct Index {
  build() {
    Stack({ alignContent: Alignment.TopStart }){
      Scroll() {
        Column({space:16}){
          /**
           * 文本组件(Text):用于呈现一段信息。可以包含Span子组件。
           * 接口:Text(content?: string)
           *    content: string 文本内容，包含子组件Span时不生效，显示Span内容。
           */
          Text('鸿蒙开发ArkUI最佳实践') // 接口:Text(content?: string)
            .body()

          /**
           * .textAlign(TextAlign) 默认值Start，设置多行文本的文本对齐方式。
           *    TextAlign.Center 文本居中对齐。
           *    TextAlign.Start 根据文字书写相同的方向对齐。
           *    TextAlign.End 根据文字书写相反的方向对齐。
           */
          Text('1.文本对齐方式')
            .title()
          Text('根据文字书写相同的方向对齐：鸿蒙开发ArkUI最佳实践。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.Start) // 文本对齐方式
            .body()
          Text('文本居中对齐：鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.Center) // 文本对齐方式
            .body()
          Text('根据文字书写相反的方向对齐：鸿蒙开发ArkUI最佳实践。')
            .width('100%') // Text的宽度
            .textAlign(TextAlign.End) // 文本对齐方式
            .body()
        }.padding({left: $r('app.float.spaceLeft'), right: $r('app.float.spaceRight')}).alignItems(HorizontalAlign.Start)
      }
    }.width('100%').height('100%').backgroundColor($r("app.color.appBg")).padding({top:$r('app.float.spaceTop'), bottom:$r('app.float.spaceBottom')})
  }
}

嗯，代码干净多了。不过，不要高兴太早，@Extend装饰器还有点小缺点：

它只能应用在定义该装饰器的页面里，无法通过export共享给其它页面调用。同时，如果在其它页面定义了同名的装饰器，如，另一个页面也定义了一个名为"title"或"body"的装饰器，会编译异常，提示重复的定义。

下节我会演示更好的解决方案。

4.设置文本的文本行高：.lineHeight(Length)

注意：文本行高设置值不大于0时，不限制文本行高，自适应字体大小。Length为number类型时单位为fp。

示例代码：

          /**
           * .lineHeight(Length) 设置文本的文本行高。
           * 设置值不大于0时，不限制文本行高，自适应字体大小。
           * Length为number类型时单位为fp。
           */
          Text('2.设置文本的文本行高').title()
          Text('鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .lineHeight(30) // 行高大于字号大小
            .body()
          Text('鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .lineHeight(10) // 行高小于字号大小，但大于0，文字会重叠
            .body()
          Text('鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .lineHeight(0) // 行高小于等于0，不限制文本行高，自适应字体大小。
            .body()

效果如下：

5.设置文本的最大行数和文本超长时的显示方式：.maxLines(number)，.textOverflow:({overflow: TextOverflow})

设置文本的最大行数和文本超长时的显示方式通常配合使用。限定最大显示行数后，超出的内容通过.textOverflow属性设置超长的显示方式。

示例代码：

          /**
           * .maxLines(number) 默认值Infinity，设置文本的最大行数。
           *
           * .textOverflow:({overflow: TextOverflow}) 设置文本超长时的显示方式。
           * 默认值{overflow: TextOverflow.Clip}
           *    TextOverflow.Clip 文本超长时进行裁剪显示。
           *    TextOverflow.Ellipsis 文本超长时显示不下的文本用省略号代替。
           *    TextOverflow.None 文本超长时不进行裁剪。
           */
          Text('3.设置行数和文本超长时的显示方式').title()
          Text('文本超长时进行裁剪显示：鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .maxLines(2) // 最多显示2行
            .textOverflow({ overflow: TextOverflow.Clip }) // 文本超长时进行裁剪显示
            .body()
          Text('文本超长时显示不下的文本用省略号代替：鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .maxLines(2)
            .textOverflow({ overflow: TextOverflow.Ellipsis }) // 文本超长时显示不下的文本用省略号代替
            .body()
          Text('文本超长时不进行裁剪：鸿蒙开发ArkUI最佳实践，基于HarmonyOS 3.0，采用方舟开发框架eTS语言。')
            .maxLines(2)
            .textOverflow({ overflow: TextOverflow.None }) // 文本超长时不进行裁剪
            .body()

效果如下：

6.设置文本基线的偏移量：.baselineOffset(Length)

示例代码：

          /**
           * .baselineOffset(Length) 设置文本基线的偏移量。
           */
          Text('4.设置文本基线的偏移量').title()
          Text('文本基线的偏移量10')
            .baselineOffset(10) // 文本基线的偏移量为正数
            .body()
          Text('文本基线的偏移量30')
            .baselineOffset(30) // 更大的偏移量
            .body()
          Text('文本基线的偏移量-10')
            .baselineOffset(-10) // 文本基线的偏移量为负数
            .body()

效果如下：

7.设置文本装饰线样式及其颜色：.decoration:({type: TextDecorationType,color?: Color})

默认值{type: TextDecorationType.None,color：Color.Black}，即，默认不使用文本装饰线，如果使用装饰线，默认颜色为黑色。考虑到“浅色模式/深色模式”适配，当然不能使用这个默认颜色，我们可以使用资源里的颜色。示例代码：

          /**
           * 设置文本装饰线样式及其颜色
           * .decoration:({type: TextDecorationType,color?: Color})
           * 默认值{type: TextDecorationType.None,color：Color.Black}
           *    TextDecorationType.Underline 文字下划线修饰。
           *    TextDecorationType.LineThrough 穿过文本的修饰线。
           *    TextDecorationType.Overline 文字上划线修饰。
           *    TextDecorationType.None 不使用文本装饰线。
           */
          Text('5.设置文本装饰线样式').title()
          Text('文字下划线修饰')
            .decoration({ type: TextDecorationType.Underline, color: $r("app.color.fgLevel1") })
            .body()
          Text('穿过文本的修饰线')
            .decoration({ type: TextDecorationType.LineThrough, color: $r("app.color.danger") })
            .body()
          Text('文字上划线修饰')
            .decoration({ type: TextDecorationType.Overline, color: $r("app.color.fgLevel1") })
            .body()
          Text('不使用文本装饰线')
            .decoration({ type: TextDecorationType.None, color: $r("app.color.fgLevel1") })
            .body()

效果如下：

8.设置文本大小写：.textCase(TextCase)

对于英文文本，可以设置保持文本原有大小写、文本采用全小写和文本采用全大写。

示例代码：

          /**
           * .textCase(TextCase) 默认值Normal，设置文本大小写。
           *    TextCase.Normal 保持文本原有大小写。
           *    TextCase.LowerCase 文本采用全小写。
           *    TextCase.UpperCase 文本采用全大写。
           */
          Text('6.设置文本大小写').title()
          Text('HarmonyOS ArkUI For eTS.')
            .textCase(TextCase.Normal) // 保持文本原有大小写
            .body()
          Text('HarmonyOS ArkUI For eTS.')
            .textCase(TextCase.LowerCase) // 文本采用全小写
            .body()
          Text('HarmonyOS ArkUI For eTS.')
            .textCase(TextCase.UpperCase) // 文本采用全大写
            .body()

效果如下：

至此，文本组件Text的接口和属性已演示完毕。

【源码地址：https://gitee.com/cloudev/harmonyos3/tree/master/3.0/BaseComponent 】