文本显示 (Text/Span)
================

Text是文本组件，用于展示用户视图，如显示文章的文字内容。该组件支持绑定自定义文本选择菜单，用户可根据需要选择不同功能。此外，还可以扩展自定义菜单，丰富可用选项，进一步提升用户体验。Span则用于展示行内文本。

具体用法请参考[Text](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text)和[Span](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-span)组件的API文档。

常见问题请参考[文本显示（Text/Span）常见问题](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-text-faq#文本显示textspan常见问题)。

#### 创建文本

Text可通过以下两种方式来创建：

*   string字符串。
    
    Text('我是一段文本')
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4f/v3/qn2vtyckRsia1ANYV_sWGg/zh-cn_image_0000002633848480.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=3C889F458295E40D94FC95BFC5300879BB5116EFB68A3CE4164F439026F722AF)

*   引用Resource资源。
    
    资源引用类型可以通过$r创建Resource类型对象，文件位置为/resources/base/element/string.json，具体内容如下：
    
    {
      "string": \[
        {
          "name": "module\_desc",
          "value": "模块描述"
        }
      \]
    }
    
    // 请将$r('app.string.module\_desc')替换为实际资源文件，在本示例中该资源文件的value值为"模块描述"
    Text($r('app.string.module\_desc'))
      .baselineOffset(0)
      .fontSize(30)
      .border({ width: 1 })
      .padding(10)
      .width(300)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e0/v3/LZaKzkCQThSwRkp3FMpobQ/zh-cn_image_0000002634008384.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=AC3FED848BB757465B3F3061388590D863944A9CA631A2537D634DE9F578D834)
    

#### 添加子组件

[Span](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-span)只能作为[Text](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text)和[RichEditor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-richeditor)组件的子组件显示文本内容。可以在一个Text内添加多个Span来显示一段信息，例如产品说明书、承诺书等。

*   创建Span。
    
    Span组件需嵌入在Text组件中才能显示，单独使用时不会显示任何内容。Text与Span同时配置文本内容时，Span内容将覆盖Text内容。
    
    // 请将$r('app.string.TextSpan\_textContent\_text')替换为实际资源文件，在本示例中该资源文件的value值为"我是Text"
    Text($r('app.string.TextSpan\_textContent\_text')) {
      // 请将$r('app.string.TextSpan\_textContent\_span')替换为实际资源文件，在本示例中该资源文件的value值为"我是Span"
      Span($r('app.string.TextSpan\_textContent\_span'))
    }
    .padding(10)
    .borderWidth(1)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3d/v3/DqylbiK8QkWGEJld7S67rw/zh-cn_image_0000002664207533.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=A218F7F861E1E4FB645559ED6D8510851E6A3CC8DD257362F98E703381BBB1D7)
    
*   设置文本装饰线及颜色。
    
    通过[decoration](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-span#decoration)设置文本装饰线及颜色。
    
    Text() {
      // 请将$r('app.string.TextSpan\_textContent\_span\_one')替换为实际资源文件，在本示例中该资源文件的value值为"我是Span1，"
      Span($r('app.string.TextSpan\_textContent\_span\_one'))
        .fontSize(16)
        .fontColor(Color.Grey)
        .decoration({ type: TextDecorationType.LineThrough, color: Color.Red })
      // 请将$r('app.string.TextSpan\_textContent\_span\_two')替换为实际资源文件，在本示例中该资源文件的value值为"我是Span2"
      Span($r('app.string.TextSpan\_textContent\_span\_two'))
        .fontColor(Color.Blue)
        .fontSize(16)
        .fontStyle(FontStyle.Italic)
        .decoration({ type: TextDecorationType.Underline, color: Color.Black })
      // 请将$r('app.string.TextSpan\_textContent\_span\_three')替换为实际资源文件，在本示例中该资源文件的value值为"，我是Span3"
      Span($r('app.string.TextSpan\_textContent\_span\_three'))
        .fontSize(16)
        .fontColor(Color.Grey)
        .decoration({ type: TextDecorationType.Overline, color: Color.Green })
    }
    .borderWidth(1)
    .padding(10)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/03/v3/NcUN7EHmRDqj6SFtj1kQ2Q/zh-cn_image_0000002664327593.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=B2A089717356552A1168A0DB26BB316E7F5436E5D064E2E5AEA85C3B06B48EED)
    
*   通过[textCase](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-span#textcase)设置文字一直保持大写或者小写状态。
    
    Text() {
      Span('I am Upper-span').fontSize(12)
        .textCase(TextCase.UpperCase)
    }
    .borderWidth(1)
    .padding(10)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f2/v3/823lA16eRg-LWLbUzD05Bw/zh-cn_image_0000002633848482.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=4EFE254DC6DC7EC755E03141F68E101CB9C475320EA5192DDC6F6E9E8BEDFEE3)
    
*   添加事件。
    
    由于Span组件无尺寸信息，仅支持添加点击事件[onClick](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-events-click#onclick)、悬浮事件[onHover](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-events-hover#onhover)。
    
    // xxx.ets
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
    @Entry
    @Component
    struct TextSpanOnHover {
      @State textStr1: string = '';
      @State textStr2: string = '';
    
      build() {
        NavDestination() {
          Row() {
            Column() {
              Text() {
                Span('I am Upper-span')
                  .textCase(TextCase.UpperCase)
                  .fontSize(30)
                  .onClick(() => {
                    hilog.info(0x0000, 'Sample\_TextComponent', 'Span onClick is triggering');
                    this.textStr1 = 'Span onClick is triggering';
                  })
                  .onHover(() => {
                    hilog.info(0x0000, 'Sample\_TextComponent', 'Span onHover is triggering');
                    this.textStr2 = 'Span onHover is triggering';
                  })
              }
    
              Text('onClick：' + this.textStr1)
                .fontSize(20)
              Text('onHover：' + this.textStr2)
                .fontSize(20)
            }.width('100%')
          }
          .height('100%')
        }
        // ···
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/27/v3/U1ZNsUqHRgyXdXSx3JXDIw/zh-cn_image_0000002634008386.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=CE4C44D6FFF602B9516B4D71C4EDEAC77A2BE051B527727335F3044EA76837E3)
    

#### 创建自定义文本样式

Text组件支持创建自定义文本样式，以下为修改文本样式的主要属性。

| 属性名称 | 功能描述 |
| :-- | :-- |
| baselineOffset | 设置文本基线的偏移量。 |
| contentTransition | 设置数字翻牌效果。 |
| copyOption | 设置文本是否可复制粘贴。 |
| decoration | 设置文本装饰线样式，如类型、颜色及其粗细。 |
| enableAutoSpacing | 设置是否开启中文与西文的自动间距。 |
| enableDataDetector | 设置是否进行文本特殊实体识别。 |
| font | 设置文本字体相关属性。 |
| fontColor | 设置文本字体颜色。 |
| fontFamily | 设置文本字体族。 |
| fontFeature | 设置文字特性效果，比如数字等宽的特性。 |
| fontSize | 设置文本字体大小。 |
| fontStyle | 设置文本字体风格。 |
| fontWeight | 设置文本字体粗细。 |
| halfLeading | 设置文本是否将行间距平分至行的顶部与底部。 |
| heightAdaptivePolicy | 设置文本自适应布局调整字号的方式。 |
| letterSpacing | 设置文本字符间距。 |
| lineHeight | 设置文本行高。 |
| lineSpacing | 设置文本的行间距。 |
| marqueeOptions | 设置跑马灯配置项，如开关、步长、循环次数、方向等。 |
| maxFontSize | 设置自适应字体最大尺寸。 |
| maxLines | 设置文本最大显示行数。 |
| minFontSize | 设置自适应字体最小尺寸。 |
| optimizeTrailingSpace | 控制每行末尾空格的优化。 |
| privacySensitive | 设置是否支持卡片敏感隐私信息。 |
| shaderStyle | 设置文本渐变色样式。 |
| textCase | 设置文本大小写转换。 |
| textAlign | 设置文本段落在水平方向的对齐方式。 |
| textIndent | 设置首行文本缩进。 |
| textOverflow | 控制文本超长处理方式。 |
| textSelectable | 设置文本是否可选择。 |
| textVerticalAlign | 设置文本段落在垂直方向的对齐方式。 |
| wordBreak | 设置断行规则。 |

下面对常用的接口进行举例说明。

*   通过[textAlign](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textalign)属性设置文本对齐样式。
    
    // 请将$r('app.string.TextAlign\_Start')替换为实际资源文件，在本示例中该资源文件的value值为"左对齐"
    Text($r('app.string.TextAlign\_Start'))
      .width(300)
      .textAlign(TextAlign.Start)
      .border({ width: 1 })
      .padding(10)
    // 请将$r('app.string.TextAlign\_Center')替换为实际资源文件，在本示例中该资源文件的value值为"中间对齐"
    Text($r('app.string.TextAlign\_Center'))
      .width(300)
      .textAlign(TextAlign.Center)
      .border({ width: 1 })
      .padding(10)
    // 请将$r('app.string.TextAlign\_End')替换为实际资源文件，在本示例中该资源文件的value值为"右对齐"
    Text($r('app.string.TextAlign\_End'))
      .width(300)
      .textAlign(TextAlign.End)
      .border({ width: 1 })
      .padding(10)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7/v3/R3QlDYqeQ6edDatJptAHGg/zh-cn_image_0000002664207535.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=1469B7D41740CB783D243566472C23A157576ED8673F5B8352BAB9AD98631149)
    
*   通过[textOverflow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textoverflow)属性控制文本超长处理，textOverflow需配合[maxLines](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#maxlines)一起使用（默认情况下文本自动折行）。从API version 18开始，文本超长时设置跑马灯的方式展示时，支持设置跑马灯的配置项，比如开关、步长、循环次数、方向等。
    
    Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow ' +
      'to None text content. This is the setting of textOverflow to Clip text content This is the setting ' +
      'of textOverflow to None text content.')
      .width(250)
      .textOverflow({ overflow: TextOverflow.None })
      .maxLines(1)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
    // 'app.string.CustomTextStyle\_textContent\_epsis'资源文件中的value值为
    // '我是超长文本，超出的部分显示省略号 I am an extra long text, with ellipses displayed for any excess。'
    Text($r('app.string.CustomTextStyle\_textContent\_epsis'))
      .width(250)
      .textOverflow({ overflow: TextOverflow.Ellipsis })
      .maxLines(1)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
    // 'app.string.CustomTextStyle\_textContent\_marq'资源文件中的value值为
    // '当文本溢出其尺寸时，文本将滚动显示
    // When the text overflows its dimensions,the text will scroll for displaying.'
    Text($r('app.string.CustomTextStyle\_textContent\_marq'))
      .width(250)
      .textOverflow({ overflow: TextOverflow.MARQUEE })
      .maxLines(1)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
    // 'app.string.CustomTextStyle\_textContent\_marq\_def'资源文件中的value值为
    // '当文本溢出其尺寸时，文本将滚动显示，支持设置跑马灯配置项
    // When the text overflows its dimensions, the text will scroll for displaying.'
    Text($r('app.string.CustomTextStyle\_textContent\_marq\_def'))
      .width(250)
      .textOverflow({ overflow: TextOverflow.MARQUEE })
      .maxLines(1)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .marqueeOptions({
        start: true,
        fromStart: true,
        step: 6,
        loop: -1,
        delay: 0,
        fadeout: false,
        marqueeStartPolicy: MarqueeStartPolicy.DEFAULT
      })
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8a/v3/Bko_jKXdQ5OJqa6YoHgPaQ/zh-cn_image_0000002664327595.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=B23EF27684B7FA46B7538BC4D0208E4E1C586A84A00719F67375F37B28F3FCB9)
    
*   通过[lineHeight](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#lineheight)属性设置文本行高。
    
    Text('This is the text with the line height set. This is the text with the line height set.')
      .width(300).fontSize(12).border({ width: 1 }).padding(10)
    Text('This is the text with the line height set. This is the text with the line height set.')
      .width(300)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .lineHeight(20)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/97/v3/H3W9QfT0R4Oo97_TpqWP-w/zh-cn_image_0000002633848484.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=7F008D4212536FF76DFA4D9EA20038E2E4FECBE022A35A0D4B31870CAF2C794C)
    
*   通过[decoration](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#decoration)属性设置文本装饰线样式、颜色及其粗细。
    
    Text('This is the text')
      .decoration({
        type: TextDecorationType.LineThrough,
        color: Color.Red
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Overline,
        color: Color.Red
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Red
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Blue,
        style: TextDecorationStyle.DASHED
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Blue,
        style: TextDecorationStyle.DOTTED
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Blue,
        style: TextDecorationStyle.DOUBLE
      })
      .borderWidth(1).padding(15).margin(5)
    Text('This is the text')
      .decoration({
        type: TextDecorationType.Underline,
        color: Color.Blue,
        style: TextDecorationStyle.WAVY,
        thicknessScale: 4
      })
      .borderWidth(1).padding(15).margin(5)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/16/v3/9E6wxJ-bTpW0xBaQmFbgbw/zh-cn_image_0000002634008388.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=77D69CDF72C436A7BC32B537C25CB1AAF0BBD7456645C37C8E39770B5C5E7DDE)
    
*   通过[baselineOffset](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#baselineoffset)属性设置文本基线的偏移量。
    
    Text('This is the text content with baselineOffset 0.')
      .baselineOffset(0)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    Text('This is the text content with baselineOffset 30.')
      .baselineOffset(30)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    Text('This is the text content with baselineOffset -20.')
      .baselineOffset(-20)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8e/v3/XmMclFS_Sd-kXK6W3Y96ZQ/zh-cn_image_0000002664207537.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=8BE55307939473FB54D2EE3E8D3B97CC9BCA85E4450E5D942AAF0DAA7726F98A)
    
*   通过[letterSpacing](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#letterspacing)属性设置文本字符间距。
    
    Text('This is the text content with letterSpacing 0.')
      .letterSpacing(0)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    Text('This is the text content with letterSpacing 3.')
      .letterSpacing(3)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    Text('This is the text content with letterSpacing -1.')
      .letterSpacing(-1)
      .fontSize(12)
      .border({ width: 1 })
      .padding(10)
      .width('100%')
      .margin(5)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/be/v3/h7ffvVBxTIKju7fQ8o76oQ/zh-cn_image_0000002664327597.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=A197850C8EBF50B099448A90118DA94878412542A1A573EF912E93C6ADFCBE84)
    
*   通过[minFontSize](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#minfontsize)与[maxFontSize](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#maxfontsize)自适应字体大小。
    
    minFontSize用于设置文本的最小显示字号，maxFontSize用于设置文本的最大显示字号。这两个属性必须同时设置才能生效，并且需要与[maxLines](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#maxlines)属性或布局大小限制配合使用，单独设置任一属性将不会产生效果。
    
    /\* 请将$r('app.string.CustomTextStyle\_textContent\_one\_style')替换为实际资源文件，
     \* 在本示例中该资源文件的value值为"我的最大字号为30，最小字号为5，宽度为250，maxLines为1"
     \*/
    Text($r('app.string.CustomTextStyle\_textContent\_one\_style'))
      .width(250)
      .maxLines(1)
      .maxFontSize(30)
      .minFontSize(5)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    /\* 请将$r('app.string.CustomTextStyle\_textContent\_two\_style')替换为实际资源文件，
     \* 在本示例中该资源文件的value值为"我的最大字号为30，最小字号为5，宽度为250，maxLines为2"
     \*/
    Text($r('app.string.CustomTextStyle\_textContent\_two\_style'))
      .width(250)
      .maxLines(2)
      .maxFontSize(30)
      .minFontSize(5)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    /\* 请将$r('app.string.CustomTextStyle\_textContent\_no\_max')替换为实际资源文件，
     \* 在本示例中该资源文件的value值为"我的最大字号为30，最小字号为15，宽度为250,高度为50"
     \*/
    Text($r('app.string.CustomTextStyle\_textContent\_no\_max'))
      .width(250)
      .height(50)
      .maxFontSize(30)
      .minFontSize(15)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    /\* 请将$r('app.string.CustomTextStyle\_textContent\_high')替换为实际资源文件，
     \* 在本示例中该资源文件的value值为"我的最大字号为30，最小字号为15，宽度为250,高度为100"
     \*/
    Text($r('app.string.CustomTextStyle\_textContent\_high'))
      .width(250)
      .height(100)
      .maxFontSize(30)
      .minFontSize(15)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f8/v3/WU3piieETbKxn__WslSFjw/zh-cn_image_0000002633848486.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=69F7E74F890DFED21CB683CC39EA4B3F032DCAE7F321C69F2968BD5257BE3360)
    
*   通过[textCase](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textcase)属性设置文本大小写。
    
    Text('This is the text content with textCase set to Normal.')
      .textCase(TextCase.Normal)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    
    // 文本全小写展示
    Text('This is the text content with textCase set to LowerCase.')
      .textCase(TextCase.LowerCase)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    
    // 文本全大写展示
    Text('This is the text content with textCase set to UpperCase.')
      .textCase(TextCase.UpperCase)
      .border({ width: 1 })
      .padding(10)
      .margin(5)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ee/v3/myhgw1NcQ12Rb5yrXAUQtw/zh-cn_image_0000002634008390.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=581FDDB68C0778DEC302AB79902C41DEE31F97365AD126F8F0ED20CEFBB4793B)
    
*   通过[copyOption](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#copyoption9)属性设置文本是否可复制粘贴。
    
    // 请将$r('app.string.CustomTextStyle\_textContent\_incopy')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段可复制文本。"
    Text($r('app.string.CustomTextStyle\_textContent\_incopy'))
      .fontSize(30)
      .copyOption(CopyOptions.InApp)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ac/v3/DIxCHzjKSY-gfSTTJx4FUQ/zh-cn_image_0000002664207539.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=1BB4A6BEAF82C487E50A7E0771EDF9957B2053D11677C9D4C3B6EB487C93274C)
    
*   通过[fontFamily](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#fontfamily)属性设置字体列表。应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-font)。
    
    Text('This is the text content with fontFamily')
      .fontSize(30)
      .fontFamily('HarmonyOS Sans')
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3a/v3/7g_3qOJzSqKhvDtW9F01iw/zh-cn_image_0000002664327599.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=D4C01EE826994C73CD546E73208A4D182DD6563FB3B0E24DF0BBD3DDEB9357BE)
    
*   从API version 20开始，支持通过[contentTransition](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#contenttransition20)属性设置数字翻牌效果。
    
    @Entry
    @Component
    struct ContentTransitionDemo {
      private static readonly INITIAL\_SCORE: number = 98;
      @State number: number = ContentTransitionDemo.INITIAL\_SCORE;
      @State numberTransition: NumericTextTransition =
        new NumericTextTransition({ flipDirection: FlipDirection.DOWN, enableBlur: false });
      build() {
        NavDestination() {
          Column() {
            Text(this.number + '')
              .borderWidth(1)
              .fontSize(40)
              .contentTransition(this.numberTransition)
            Button('chang number')
              .onClick(() => {
                this.number++
              })
              .margin(10)
          }
          .width('100%')
          .height('100%')
        }
        // ···
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3a/v3/9z3M239NSpGCdJGLgOdi9Q/zh-cn_image_0000002633848488.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=8D359AD8A50BA60350F27EDDF66B1384E795BBA7F9D10534911F1A9E3A493D73)
    
*   从API version 20开始，支持通过[optimizeTrailingSpace](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#optimizetrailingspace20)设置是否在文本布局过程中优化每行末尾的空格，可解决行尾空格影响对齐显示效果问题。
    
    Column() {
      // 启用优化行尾空格功能
      Text('Trimmed space enabled     ')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })
        .optimizeTrailingSpace(true)
        .textAlign(TextAlign.Center)
      // 不启用优化行尾空格功能
      Text('Trimmed space disabled     ')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })
        .optimizeTrailingSpace(false)
        .textAlign(TextAlign.Center)
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/80/v3/TlCDcCe7QriGw7EbqQr40g/zh-cn_image_0000002634008392.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=5E9FE31B0104FD98F153B664E6EFDF0CDD5E5C68BBA7B2071421D5F5FD4E0198)
    
*   从API version 20开始，支持通过[lineSpacing](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#linespacing20)设置文本的行间距。当不配置[LineSpacingOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-text-common#linespacingoptions20对象说明)时，首行上方和尾行下方默认会有行间距，当onlyBetweenLines设置为true时，行间距仅适用于行与行之间，首行上方无额外的行间距。
    
    import { LengthMetrics } from '@kit.ArkUI';
    
    @Extend(Text)
    function style() {
      .width(250)
      .height(100)
      .maxFontSize(30)
      .minFontSize(15)
      .border({ width: 1 })
    }
    
    @Entry
    @Component
    struct LineSpacing {
      build() {
        NavDestination() {
          Column() {
            Text('The line spacing of this context is set to 20\_px, and the spacing is effective only between the lines.')
              .lineSpacing(LengthMetrics.px(20), { onlyBetweenLines: true })
              .style()
          }
        }
        // ···
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ea/v3/rtWprJphS8aR3924SguNSg/zh-cn_image_0000002664207541.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=99A896C94B1155BA828BFE0F6BD2447ED99ABCA0B46F326A2B2BBE476B5B079D)
    
*   从API version 20开始，支持通过[enableAutoSpacing](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#enableautospacing20)设置是否开启中文与西文的自动间距。
    
    @Entry
    @Component
    struct EnableAutoSpacing {
      @State enableSpacing: boolean = false;
    
      build() {
        NavDestination() {
        Column() {
          Row({ space: 20 }) {
            // 请将$r('app.string.Enable\_automatic\_spacing')替换为实际资源文件，在本示例中该资源文件的value值为"开启自动间距"
            Button($r('app.string.Enable\_automatic\_spacing'))
              .onClick(() => this.enableSpacing = true)
              .backgroundColor(this.enableSpacing ? '#4CAF50' : '#E0E0E0')
              .fontColor(this.enableSpacing ? Color.White : Color.Black)
            // 请将$r('app.string.off\_automatic\_spacing')替换为实际资源文件，在本示例中该资源文件的value值为"关闭自动间距"
            Button($r('app.string.off\_automatic\_spacing'))
              .onClick(() => this.enableSpacing = false)
              .backgroundColor(!this.enableSpacing ? '#F44336' : '#E0E0E0')
              .fontColor(!this.enableSpacing ? Color.White : Color.Black)
          }
          .width('100%')
          .justifyContent(FlexAlign.Center)
          .margin({ top: 30, bottom: 20 })
          // 请将$r('app.string.Automatic\_spacing\_has\_been\_enabled')替换为实际资源文件，在本示例中该资源文件的value值为"当前状态:已开启自动间距"
          // 请将$r('app.string.Automatic\_spacing\_has\_been\_turned\_off')替换为实际资源文件，在本示例中该资源文件的value值为"当前状态:已关闭自动间距"
          Text(this.enableSpacing ? $r('app.string.Automatic\_spacing\_has\_been\_enabled') : $r('app.string.Automatic\_spacing\_has\_been\_turned\_off'))
            .fontSize(16)
            .fontColor(this.enableSpacing ? '#4CAF50' : '#F44336')
            .margin({ bottom: 20 })
    
          // 设置是否应用中西文自动间距
          /\* 请将$r('app.string.Chinese\_and\_Western\_Auto\_Spacing\_automatic\_spacing')替换为实际资源文件，
           \* 在本示例中该资源文件的value值为"中西文Auto Spacing自动间距"
           \*/
          Text($r('app.string.Chinese\_and\_Western\_Auto\_Spacing\_automatic\_spacing'))
            .fontSize(24)
            .padding(15)
            .backgroundColor('#F5F5F5')
            .width('90%')
            .enableAutoSpacing(this.enableSpacing)
        }
        .width('100%')
        .height('100%')
        .padding(20)
        }
        // ...
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/24/v3/p4xNcuYVRZCp5LP1fm3e2g/zh-cn_image_0000002664327601.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=F0D90E539E8C28AABE73DF21D16689641F5CDF8D2DBED06725BB84396F97477A)
    
*   从API version 20开始，支持通过[shaderStyle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#shaderstyle20)设置渐变色。
    
    @Entry
    @Component
    struct ShaderStyle {
      @State message: string = 'Hello World';
      @State linearGradientOptions: LinearGradientOptions =
        {
          direction: GradientDirection.LeftTop,
          colors: \[\[Color.Red, 0.0\], \[Color.Blue, 0.3\], \[Color.Green, 0.5\]\],
          repeating: true,
        };
    
      build() {
        NavDestination() {
          Column({ space: 5 }) {
            // 请将$r('app.string.direction\_LeftTop')替换为实际资源文件，在本示例中该资源文件的value值为"direction为LeftTop的线性渐变"
            Text($r('app.string.direction\_LeftTop')).fontSize(18).width('90%').fontColor(0xCCCCCC)
              .margin({ top: 40, left: 40 })
            Text(this.message)
              .fontSize(50)
              .width('80%')
              .height(50)
              .shaderStyle(this.linearGradientOptions)
          }
          .height('100%')
          .width('100%')
        }
        // ...
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f1/v3/c9Bs49Y2RfuVEp-Y9Jr2xg/zh-cn_image_0000002633848490.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=8213CA7C19D6D4BB026911F8823ECEE4F62BD5CD4DE00EC8384A7F7F77C44060)
    

#### 添加事件

Text组件可以添加通用事件，可以绑定[onClick](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-events-click#onclick)、[onTouch](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-events-touch#ontouch)等事件来响应操作。

// xxx.ets
import { hilog } from '@kit.PerformanceAnalysisKit';
@Entry
@Component
struct GeneralEvents {
  @State textStr1: string = '';
  @State textStr2: string = '';

  build() {
    NavDestination() {
      Row() {
        Column() {
          Text('This is a text component.')
            .fontSize(30)
            .onClick(() => {
              hilog.info(0x0000, 'Sample\_TextComponent', 'Text onClick is triggering');
              this.textStr1 = 'Text onClick is triggering';
            })
            .onTouch(() => {
              hilog.info(0x0000, 'Sample\_TextComponent', 'Text onTouch is triggering');
              this.textStr2 = 'Text onTouch is triggering';
            })
          Text('onClick：' + this.textStr1)
            .fontSize(20)
          Text('onTouch：' + this.textStr2)
            .fontSize(20)
        }.width('100%')
      }
      .height('100%')
    }
    // ···
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/r_-dbhE0Tf-LT1YUFnq00Q/zh-cn_image_0000002634008394.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=01F4E449D11926D3F7875A9E3F276B9D8EC75B7250FA69CF01F5D437F82F8E57)

#### 设置垂直居中

从API version 20开始，Text组件支持通过[textVerticalAlign](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textverticalalign20)属性实现文本段落在垂直方向的对齐。

*   以下示例展示了如何通过textVerticalAlign属性设置文本垂直居中对齐效果。
    
    // 请将$r('app.media.startIcon')替换为实际资源文件
    Text() {
      Span('Hello')
        .fontSize(50)
      ImageSpan($r('app.media.startIcon'))
        .width(30).height(30)
        .verticalAlign(ImageSpanAlignment.FOLLOW\_PARAGRAPH)
      Span('World')
    }
    .textVerticalAlign(TextVerticalAlign.CENTER)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0/v3/QNNkDuFsTIa8x6QG9i7w_w/zh-cn_image_0000002664207543.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=920E1BA1CDD60A8FDD1CD592FAB39E43B52BE38E0BE6295185A56CF8C2E859BB)
    

#### 设置选中菜单

#### \[h2\]弹出选中菜单

*   设置Text被选中时，会弹出包含复制、翻译、搜索的菜单。
    
    Text组件需要设置[copyOption](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#copyoption9)属性才可以被选中。
    
    // 请将$r('app.string.selected\_menu')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段文本，用来展示选中菜单"
    Text($r('app.string.selected\_menu'))
      .fontSize(30)
      .copyOption(CopyOptions.InApp)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/63/v3/SaRAmOhHQuym-dskMVfULQ/zh-cn_image_0000002664327603.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=096BBBAA589C28C495D92D49DC4163EFE81EBE0A119202201645E6870A334530)
    
*   Text组件通过设置[bindSelectionMenu](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#bindselectionmenu11)属性绑定自定义选择菜单。
    
    controller: TextController = new TextController();
    options: TextOptions = { controller: this.controller };
    
    // 请将$r('app.string.show\_selected\_menu')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段文本，用来展示选中菜单"
    Text($r('app.string.show\_selected\_menu'), this.options)
      .fontSize(30)
      .copyOption(CopyOptions.InApp)
      .bindSelectionMenu(TextSpanType.TEXT, this.RightClickTextCustomMenu, TextResponseType.RIGHT\_CLICK, {
        onAppear: () => {
          // 请将$r('app.string.SelectMenu\_Text\_Ejected')替换为实际资源文件，在本示例中该资源文件的value值为"自定义选择菜单弹出时触发该回调"
          hilog.info(0x0000, 'Sample\_TextComponent',
            this.getUIContext()
              .getHostContext()!.resourceManager.getStringSync($r('app.string.SelectMenu\_Text\_Ejected').id));
        },
        onDisappear: () => {
          // 'SelectMenu\_Text\_Close'资源文件中的value值为'自定义选择菜单关闭时触发该回调'
          hilog.info(0x0000, 'Sample\_TextComponent',
            this.getUIContext()
              .getHostContext()!.resourceManager.getStringSync($r('app.string.SelectMenu\_Text\_Close').id));
        }
      })
    
    // 定义菜单项
    @Builder
    RightClickTextCustomMenu() {
      Column() {
        Menu() {
          MenuItemGroup() {
            // 请将$r('app.media.app\_icon')替换为实际资源文件
            MenuItem({ startIcon: $r('app.media.app\_icon'), content: 'CustomMenu One', labelInfo: '' })
              .onClick(() => {
                // 使用closeSelectionMenu接口关闭菜单
                this.controller.closeSelectionMenu();
              })
            MenuItem({ startIcon: $r('app.media.app\_icon'), content: 'CustomMenu Two', labelInfo: '' })
            MenuItem({ startIcon: $r('app.media.app\_icon'), content: 'CustomMenu Three', labelInfo: '' })
          }
        }.backgroundColor('#F0F0F0')
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cd/v3/zLjL7QQDRqO5-k8LZVP7Ew/zh-cn_image_0000002633848492.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=2620C2DAF762D72F7177D15433D3EDE1909C8A1E4D5A6FA02E5A09C0BACE0F13)
    
*   Text组件通过设置[editMenuOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#editmenuoptions12)属性扩展自定义选择菜单，可以设置扩展项的文本内容、图标以及回调方法。
    
    // 请将$r('app.string.show\_selected\_menu')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段文本，用来展示选中菜单"
    Text($r('app.string.show\_selected\_menu'))
      .fontSize(20)
      .copyOption(CopyOptions.LocalDevice)
      .editMenuOptions({
        onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick
      })
    
    // 定义onCreateMenu，onMenuItemClick
    // 请将$r('app.media.app\_icon')替换为实际资源文件
    onCreateMenu = (menuItems: Array<TextMenuItem>) => {
      let item1: TextMenuItem = {
        content: 'customMenu1',
        icon: $r('app.media.app\_icon'),
        id: TextMenuItemId.of('customMenu1'),
      };
      let item2: TextMenuItem = {
        content: 'customMenu2',
        id: TextMenuItemId.of('customMenu2'),
        icon: $r('app.media.app\_icon'),
      };
      menuItems.push(item1);
      menuItems.unshift(item2);
      return menuItems;
    }
    onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => {
      if (menuItem.id.equals(TextMenuItemId.of('customMenu2'))) {
        // 请将$r('app.string.SelectMenu\_Text\_customMenu')替换为实际资源文件，在本示例中该资源文件的value值为"拦截 id: customMenu2 start:"
        hilog.info(0x0000, 'Sample\_TextComponent',
          this.getUIContext().getHostContext()!.resourceManager.getStringSync($r('app.string.SelectMenu\_Text\_customMenu')
            .id) + textRange.start + '; end:' +
          textRange.end);
        return true;
      }
      if (menuItem.id.equals(TextMenuItemId.COPY)) {
        // 请将$r('app.string.SelectMenu\_Text\_copy')替换为实际资源文件，在本示例中该资源文件的value值为"拦截 COPY start:"
        hilog.info(0x0000, 'Sample\_TextComponent',
          this.getUIContext().getHostContext()!.resourceManager.getStringSync($r('app.string.SelectMenu\_Text\_copy').id) +
          textRange.start + '; end:' + textRange.end);
        return true;
      }
      if (menuItem.id.equals(TextMenuItemId.SELECT\_ALL)) {
        // 请将$r('app.string.SelectMenu\_Text\_SelectionAll')替换为实际资源文件，在本示例中该资源文件的value值为"不拦截 SELECT\_ALL start:"
        hilog.info(0x0000, 'Sample\_TextComponent',
          this.getUIContext()
            .getHostContext()!.resourceManager.getStringSync($r('app.string.SelectMenu\_Text\_SelectionAll').id) +
          textRange.start + '; end:' +
          textRange.end);
        return false;
      }
      return false;
    };
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6d/v3/QJzX69pFTfK7XWIp02ofAA/zh-cn_image_0000002634008396.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=BBDD6FD326234E60EF18C9441F1AD2C5879E870B3A065ED7F1B8B0166ADB6633)
    

#### \[h2\]关闭选中菜单

使用Text组件时，若需要实现点击空白处关闭选中的场景，分为以下两种情况：

*   在Text组件区域内点击空白处，会正常关闭选中态和菜单；
    
*   在Text组件区域外点击空白处，前提是Text组件设置[selection](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#selection11)属性，具体示例如下：
    
    // xxx.ets
    @Entry
    @Component
    struct SelectionChange {
      @State text: string =
        'This is set selection to Selection text content This is set selection to Selection text content.';
      @State start: number = 0;
      @State end: number = 20;
    
      build() {
        NavDestination() {
          Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.Start }) {
            Text(this.text)
              .fontSize(12)
              .border({ width: 1 })
              .lineHeight(20)
              .margin(30)
              .copyOption(CopyOptions.InApp)
              .selection(this.start, this.end)
              .onTextSelectionChange((selectionStart, selectionEnd) => {
                // 更新选中态位置
                this.start = selectionStart;
                this.end = selectionEnd;
              })
          }
          .height(600)
          .width(335)
          .borderWidth(1)
          .onClick(() => {
            // 监听父组件的点击事件，将选中首尾位置均设置为-1，即可清除选中
            this.start = -1;
            this.end = -1;
          })
        }
        // ···
      }
    }
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f3/v3/__ZzHDwMTTqY6_mYEmhnaw/zh-cn_image_0000002664207545.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=0807982DC4654C3A25A90095E1B22DF114C0875CD39A353A153946F5FF45EEFB)

#### \[h2\]屏蔽系统菜单回调和自定义扩展菜单

从API version 12开始，支持通过[editMenuOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#editmenuoptions12)屏蔽系统菜单回调和自定义扩展菜单项。

// xxx.ets
@Entry
@Component
struct CustomAndBlockMenus {
  private static readonly CREATE\_MENU\_ITEM\_ID\_1: string = 'create1';
  private static readonly CREATE\_MENU\_ITEM\_ID\_2: string = 'create2';
  private static readonly PREPARE\_MENU\_ITEM\_ID: string = 'prepare1';
  private controller: TextController = new TextController();
  @State private text: string = 'Text editMenuOptions';
  @State private endIndex: number = 0;
  @State blockCallbackText: string = '';

  // 创建菜单项辅助方法
  private createMenuItem(id: string, content: string): TextMenuItem {
    // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件
    return {
      content: content,
      icon: $r('app.media.startIcon'),
      id: TextMenuItemId.of(id)
    };
  }

  // 查找菜单项索引
  private findMenuItemIndex(menuItems: Array<TextMenuItem>, menuItemId: TextMenuItemId): number {
    return menuItems.findIndex((item: TextMenuItem) => item.id.equals(menuItemId));
  }

  // 创建菜单回调
  private onCreateMenu = (menuItems: Array<TextMenuItem>): Array<TextMenuItem> => {
    const createItem1: TextMenuItem = this.createMenuItem(
      CustomAndBlockMenus.CREATE\_MENU\_ITEM\_ID\_1,
      'create1'
    );

    const createItem2: TextMenuItem = this.createMenuItem(
      CustomAndBlockMenus.CREATE\_MENU\_ITEM\_ID\_2,
      'create2'
    );

    // 添加自定义菜单项
    menuItems.push(createItem1);
    menuItems.unshift(createItem2);

    // 移除不需要的系统菜单项
    this.removeMenuItemById(menuItems, TextMenuItemId.AI\_WRITER);
    this.removeMenuItemById(menuItems, TextMenuItemId.TRANSLATE);

    return menuItems;
  }

  // 移除指定菜单项
  private removeMenuItemById(menuItems: Array<TextMenuItem>, menuItemId: TextMenuItemId): void {
    const targetIndex: number = this.findMenuItemIndex(menuItems, menuItemId);
    if (targetIndex !== -1) {
      menuItems.splice(targetIndex, 1);
    }
  }

  // 菜单项点击回调
  private onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange): boolean => {
    const menuItemId: TextMenuItemId = menuItem.id;

    // 处理自定义菜单项，return false，点击自定义菜单项后菜单会关闭
    if (menuItemId.equals(TextMenuItemId.of(CustomAndBlockMenus.CREATE\_MENU\_ITEM\_ID\_2))) {
      let msg = '拦截 id: create2 start:' + textRange.start + '; end:' + textRange.end;
      this.blockCallbackText = msg;
      return false;
    }
    // 处理自定义菜单项，return true，点击自定义菜单项后菜单不会关闭
    if (menuItemId.equals(TextMenuItemId.of(CustomAndBlockMenus.PREPARE\_MENU\_ITEM\_ID))) {
      let msg = '拦截 id: prepare1 start:' + textRange.start + '; end:+' + textRange.end;
      this.blockCallbackText = msg;
      return true;
    }

    // 处理系统菜单项，return true，拦截系统默认逻辑，此时点击复制菜单不会关闭
    if (menuItemId.equals(TextMenuItemId.COPY)) {
      let msg = '拦截 COPY start:' + textRange.start + '; end:' + textRange.end;
      this.blockCallbackText = msg;
      // 可以通过文本控制器关闭菜单，手柄也会消失，仅保持选中区域，点击可消失
      this.controller.closeSelectionMenu();
      return true;
    }
    // 处理系统菜单项，return false，不拦截系统默认逻辑，自定义逻辑亦会被执行
    if (menuItemId.equals(TextMenuItemId.SELECT\_ALL)) {
      let msg = '不拦截 SELECT\_ALL start:' + textRange.start + '; end:' + textRange.end;
      this.blockCallbackText = msg;
      return false;
    }

    return false;
  }
  // 准备菜单回调
  private onPrepareMenu = (menuItems: Array<TextMenuItem>): Array<TextMenuItem> => {
    const prepareItem: TextMenuItem = this.createMenuItem(
      CustomAndBlockMenus.PREPARE\_MENU\_ITEM\_ID,
      \`prepare1\_${this.endIndex}\`
    );

    menuItems.unshift(prepareItem);
    return menuItems;
  }
  // 编辑菜单选项
  @State private editMenuOptions: EditMenuOptions = {
    onCreateMenu: this.onCreateMenu,
    onMenuItemClick: this.onMenuItemClick,
    onPrepareMenu: this.onPrepareMenu
  };
  // 文本选择变化回调
  private onTextSelectionChange = (selectionStart: number, selectionEnd: number): void => {
    this.endIndex = selectionEnd;
  }

  build() {
    NavDestination() {
      Column() {
        Text(this.text, { controller: this.controller })
          .fontSize(20)
          .copyOption(CopyOptions.LocalDevice)
          .editMenuOptions(this.editMenuOptions)
          .margin({ top: 100 })
          .onTextSelectionChange(this.onTextSelectionChange)
        Text(this.blockCallbackText).borderWidth(1)
      }
      .width('90%')
      .margin('5%')
    }
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/74/v3/0TclxvlhQN-KgcnLzlpV1Q/zh-cn_image_0000002664327605.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=7100755E5FC8A55D3250CF872FB25FD1FC352F619CD1CA3B55006846144F830C)

#### \[h2\]屏蔽系统服务类菜单

*   从API version 20开始，支持通过[disableSystemServiceMenuItems](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-textmenucontroller#disablesystemservicemenuitems20)屏蔽文本选择菜单内所有系统服务菜单项。更多详见[disableSystemServiceMenuItems](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-textmenucontroller#disablesystemservicemenuitems20)的API文档接口说明。以下示例只是完整示例工程中的一个示例，为了不影响工程其他页面示例效果，仅在页面的出现和消失生命周期中进行系统服务菜单的禁用和恢复，实际场景可自行选择其他时机，比如[UIAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability)的[onCreate](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability#oncreate)和[onDestroy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability#ondestroy)。
    
    import { TextMenuController } from '@kit.ArkUI';
    // xxx.ets
    @Entry
    @Component
    struct ServiceMenuItems {
      aboutToAppear(): void {
        // 禁用所有系统服务菜单
        TextMenuController.disableSystemServiceMenuItems(true);
      }
    
      aboutToDisappear(): void {
        // 页面消失恢复系统服务菜单
        TextMenuController.disableSystemServiceMenuItems(false);
      }
      build() {
        NavDestination() {
          Row() {
            Column() {
              // 请将$r('app.string.Service\_MenuItems\_Text')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段文本，长按弹出文本选择菜单。"
              Text($r('app.string.Service\_MenuItems\_Text'))
                .height(60)
                .fontStyle(FontStyle.Italic)
                .fontWeight(FontWeight.Bold)
                .textAlign(TextAlign.Center)
                .copyOption(CopyOptions.InApp)
                .editMenuOptions({
                  onCreateMenu: (menuItems: Array<TextMenuItem>) => {
                    // menuItems不包含被屏蔽的系统菜单项
                    return menuItems;
                  },
                  onMenuItemClick: (menuItem: TextMenuItem, textRange: TextRange) => {
                    return false;
                  }
                })
            }.width('100%')
          }
          .height('100%')
        }
        // ...
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d4/v3/UCzY2OJmT1CFiBEbojD5Bg/zh-cn_image_0000002633848494.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=6736C17AC1F0217AFA1691FB756CDA22A2508113E38719918142BFA06022FE05)
    
*   从API version 20开始，支持通过[disableMenuItems](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-textmenucontroller#disablemenuitems20)屏蔽文本选择菜单内指定的系统服务菜单项。更多详见[disableMenuItems](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-textmenucontroller#disablemenuitems20)的API文档接口说明。以下示例只是完整示例工程中的一个示例，为了不影响工程其他页面示例效果，仅在页面的出现和消失生命周期中进行系统服务菜单的禁用和恢复，实际场景可自行选择其他时机，比如[UIAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability)的[onCreate](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability#oncreate)和[onDestroy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability#ondestroy)。
    
    import { TextMenuController } from '@kit.ArkUI';
    
    // xxx.ets
    @Entry
    @Component
    struct DisableMenuItems {
      aboutToAppear(): void {
        // 禁用搜索菜单
        TextMenuController.disableMenuItems(\[TextMenuItemId.SEARCH\])
      }
    
      aboutToDisappear(): void {
        // 恢复系统服务菜单
        TextMenuController.disableMenuItems(\[\])
      }
    
      build() {
        NavDestination() {
          Row() {
            Column() {
              // 请将$r('app.string.Service\_MenuItems\_Text')替换为实际资源文件，在本示例中该资源文件的value值为"这是一段文本，长按弹出文本选择菜单。"
              Text($r('app.string.Service\_MenuItems\_Text'))
                .height(60)
                .fontStyle(FontStyle.Italic)
                .fontWeight(FontWeight.Bold)
                .textAlign(TextAlign.Center)
                .copyOption(CopyOptions.InApp)
                .editMenuOptions({
                  onCreateMenu: (menuItems: Array<TextMenuItem>) => {
                    // menuItems不包含搜索
                    return menuItems;
                  },
                  onMenuItemClick: (menuItem: TextMenuItem, textRange: TextRange) => {
                    return false
                  }
                })
            }.width('100%')
          }
          .height('100%')
        }
        // ...
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e0/v3/9gVEmg_AQwGo-39D2lpeng/zh-cn_image_0000002634008398.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=613709460120709F6F272EEFD825F9B6807CDD56C86664382EF6AE5C76446659)
    

#### \[h2\]默认菜单支持自定义刷新能力

从API version 20开始，当文本选择区域变化后显示菜单之前触发[onPrepareMenu](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-text-common#属性-1)回调，可在该回调中进行菜单数据设置。

// 请将$r('app.media.xxx')替换为实际资源文件
// xxx.ets
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0000;
@Entry
@Component
struct PrepareMenu {
  @State text: string = 'Text editMenuOptions';
  @State endIndex: number = 0;
  onCreateMenu = (menuItems: Array<TextMenuItem>) => {
    let item1: TextMenuItem = {
      content: 'create1',
      icon: $r('app.media.startIcon'),
      id: TextMenuItemId.of('create1'),
    };
    let item2: TextMenuItem = {
      content: 'create2',
      id: TextMenuItemId.of('create2'),
      icon: $r('app.media.startIcon'),
    };
    menuItems.push(item1);
    menuItems.unshift(item2);
    return menuItems;
  }
  onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => {
    if (menuItem.id.equals(TextMenuItemId.of('create2'))) {
      hilog.info(DOMAIN, 'testTag', '%{public}s', 'intercept id: create2 start:' + textRange.start + '; end:' + textRange.end);
      return true;
    }
    if (menuItem.id.equals(TextMenuItemId.of('prepare1'))) {
      hilog.info(DOMAIN, 'testTag', '%{public}s', 'intercept id: prepare1 start:' + textRange.start + '; end:' + textRange.end);
      return true;
    }
    if (menuItem.id.equals(TextMenuItemId.COPY)) {
      hilog.info(DOMAIN, 'testTag', '%{public}s', 'intercept COPY start:' + textRange.start + '; end:' + textRange.end);
      return true;
    }
    if (menuItem.id.equals(TextMenuItemId.SELECT\_ALL)) {
      hilog.info(DOMAIN, 'testTag', '%{public}s', 'No interception SELECT\_ALL start:' + textRange.start + '; end:' + textRange.end);
      return false;
    }
    return false;
  }
  onPrepareMenu = (menuItems: Array<TextMenuItem>) => {
    let item1: TextMenuItem = {
      content: 'prepare1\_' + this.endIndex,
      icon: $r('app.media.startIcon'),
      id: TextMenuItemId.of('prepare1'),
    };
    menuItems.unshift(item1);
    return menuItems;
  }
  @State editMenuOptions: EditMenuOptions = {
    onCreateMenu: this.onCreateMenu,
    onMenuItemClick: this.onMenuItemClick,
    onPrepareMenu: this.onPrepareMenu
  };

  build() {
    NavDestination() {
    Column() {
      Text(this.text)
        .fontSize(20)
        .copyOption(CopyOptions.LocalDevice)
        .editMenuOptions(this.editMenuOptions)
        .margin({ top: 100 })
        .onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
          this.endIndex = selectionEnd;
        })
    }
    .width('90%')
    .margin('5%')
    }
    // ...
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c4/v3/h3HVqmmLRLOzpwea_KYt0Q/zh-cn_image_0000002664207547.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=4D153821F2DFB3C43977B32D61389E6708C21D5C885FAC544A1D1D8609044C28)

#### 设置AI菜单

Text组件通过[enableDataDetector](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#enabledatadetector11)和[dataDetectorConfig](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#datadetectorconfig11)属性实现AI菜单的显示。AI菜单的表现形式包括：单击AI实体（指可被识别的内容，包括地址、邮箱等）弹出菜单的实体识别选项，选中文本后，文本选择菜单与鼠标右键菜单中显示的实体识别选项。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a/v3/TIBnABBOTGy1bLuJ7aUXcg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=CD16135D17ECB6330AE0E4EBAD9BEEB43817DFF95EFDD224E2FD74E64F168545)

从API version 20开始，支持在文本选择菜单与鼠标右键菜单中显示实体识别选项。当[enableDataDetector](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#enabledatadetector11)设置为true，且[copyOption](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#copyoption9)设置为CopyOptions.LocalDevice时，该功能生效。菜单选项包括[TextMenuItemId](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-text-common#textmenuitemid12)中的url(打开链接)、email(新建邮件)、phoneNumber(呼叫)、address(导航至该位置)、dateTime(新建日程提醒)。

该功能生效时，需选中范围内，包括一个完整的AI实体，才能展示对应的选项。

*   如果需要单击AI实体弹出菜单的实体识别选项，可以配置[enableDataDetector](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#enabledatadetector11)为true。具体示例如下所示：
    
    // 'app.string.AIMenu\_Text\_One'资源文件中的value值为'电话号码：(86) (755) \*\*\*\*\*\*\*\*  \\n \\n 链接：www.\*\*\*\*\*\*\*\*.com
    // \\n \\n 邮箱：\*\*\*@example.com\\n \\n 地址：XX省XX市XX区XXXX \\n \\n 时间：XX年XX月XX日XXXX'
    Text($r('app.string.AIMenu\_Text\_One'))
      .fontSize(16)
      .copyOption(CopyOptions.LocalDevice)
      .enableDataDetector(true)// 使能实体识别
      .dataDetectorConfig({
        // 配置识别样式
        // types可支持PHONE\_NUMBER电话号码、URL链接、EMAIL邮箱、ADDRESS地址、DATE\_TIME时间
        // types设置为null或者\[\]时，识别所有类型的实体
        types: \[\], onDetectResultUpdate: (result: string) => {
        }
      })
    
*   如果需要调整识别出的样式，可以通过[dataDetectorConfig](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#datadetectorconfig11)实现，具体可以参考[TextDataDetectorConfig](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-text-common#textdatadetectorconfig11对象说明)配置项。
    
*   如果需要调整菜单的位置，可以通过[editMenuOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#editmenuoptions12)实现，具体可以参考示例[文本扩展自定义菜单](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#示例12文本扩展自定义菜单)。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5c/v3/1PQ8ejCCTHe3SiBRdo3qqQ/zh-cn_image_0000002664327607.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=FB9B24681918521218406EC1541C92A1C661842E0673A48291069E1D60094038)
    

#### 实现热搜榜

该示例通过[maxLines](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#maxlines)、[textOverflow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textoverflow)、[textAlign](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textalign)、[constraintSize](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-size#constraintsize)属性展示了热搜榜的效果。

@Entry
@Component
struct TextHotSearch {
  build() {
    NavDestination() {
      Column({ space: 12 }) {
        // ...
          Column() {
            Row() {
              Text('1').fontSize(14).fontColor(Color.Red).margin({ left: 10, right: 10 })
              // 请将$r('app.string.TextHotSearch\_textContent\_one')替换为实际资源文件，在本示例中该资源文件的value值为"我是热搜词条1"
              Text($r('app.string.TextHotSearch\_textContent\_one'))
                .fontSize(12)
                .fontColor(Color.Blue)
                .maxLines(1)
                .textOverflow({ overflow: TextOverflow.Ellipsis })
                .fontWeight(300)
              // 请将$r('app.string.TextHotSearch\_textContent\_two')替换为实际资源文件，在本示例中该资源文件的value值为"爆"
              Text($r('app.string.TextHotSearch\_textContent\_two'))
                .margin({ left: 6 })
                .textAlign(TextAlign.Center)
                .fontSize(10)
                .fontColor(Color.White)
                .fontWeight(600)
                .backgroundColor(0x770100)
                .borderRadius(5)
                .width(15)
                .height(14)
            }.width('100%').margin(5)

            Row() {
              Text('2').fontSize(14).fontColor(Color.Red).margin({ left: 10, right: 10 })
              /\* 请将$r('app.string.TextHotSearch\_textContent\_three')替换为实际资源文件，
               \* 在本示例中该资源文件的value值为"我是热搜词条2 我是热搜词条2 我是热搜词条2 我是热搜词条2 我是热搜词条2"
               \*/
              Text($r('app.string.TextHotSearch\_textContent\_three'))
                .fontSize(12)
                .fontColor(Color.Blue)
                .fontWeight(300)
                .constraintSize({ maxWidth: 200 })
                .maxLines(1)
                .textOverflow({ overflow: TextOverflow.Ellipsis })
              // 请将$r('app.string.TextHotSearch\_textContent\_four')替换为实际资源文件，在本示例中该资源文件的value值为"热"
              Text($r('app.string.TextHotSearch\_textContent\_four'))
                .margin({ left: 6 })
                .textAlign(TextAlign.Center)
                .fontSize(10)
                .fontColor(Color.White)
                .fontWeight(600)
                .backgroundColor(0xCC5500)
                .borderRadius(5)
                .width(15)
                .height(14)
            }.width('100%').margin(5)

            Row() {
              Text('3').fontSize(14).fontColor(Color.Orange).margin({ left: 10, right: 10 })
              // 请将$r('app.string.TextHotSearch\_textContent\_five')替换为实际资源文件，在本示例中该资源文件的value值为"我是热搜词条3"
              Text($r('app.string.TextHotSearch\_textContent\_five'))
                .fontSize(12)
                .fontColor(Color.Blue)
                .fontWeight(300)
                .maxLines(1)
                .constraintSize({ maxWidth: 200 })
                .textOverflow({ overflow: TextOverflow.Ellipsis })
              // 请将$r('app.string.TextHotSearch\_textContent\_four')替换为实际资源文件，在本示例中该资源文件的value值为"热"
              Text($r('app.string.TextHotSearch\_textContent\_four'))
                .margin({ left: 6 })
                .textAlign(TextAlign.Center)
                .fontSize(10)
                .fontColor(Color.White)
                .fontWeight(600)
                .backgroundColor(0xCC5500)
                .borderRadius(5)
                .width(15)
                .height(14)
            }.width('100%').margin(5)

            Row() {
              Text('4').fontSize(14).fontColor(Color.Grey).margin({ left: 10, right: 10 })
              /\* 请将$r('app.string.TextHotSearch\_textContent\_six')替换为实际资源文件，
               \* 在本示例中该资源文件的value值为"我是热搜词条4 我是热搜词条4 我是热搜词条4 我是热搜词条4 我是热搜词条4"
               \*/
              Text($r('app.string.TextHotSearch\_textContent\_six'))
                .fontSize(12)
                .fontColor(Color.Blue)
                .fontWeight(300)
                .constraintSize({ maxWidth: 200 })
                .maxLines(1)
                .textOverflow({ overflow: TextOverflow.Ellipsis })
            }.width('100%').margin(5)
          }.width('100%')
        // ...
      }
      .width('100%')
      .height('100%')
      .padding({ left: 12, right: 12 })
    }
    // ...
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4b/v3/T1nIQDCYSkGTJjtYHS_boA/zh-cn_image_0000002633848496.png?HW-CC-KV=V1&HW-CC-Date=20260709T132300Z&HW-CC-Expire=86400&HW-CC-Sign=D2F8AD9CE8D5E6FB9AAD158A1F78D56E6C640AD12D0DED0FCB44AF405D65ADF6)

#### 示例代码

*   [文字特效合集](https://gitcode.com/HarmonyOS_Samples/text-effects)