前言

商品标题、评论摘要、通知正文——几乎每个 App 都有「超长文本需要截断显示省略号」的需求。写法看起来很简单：

Text('很长很长很长……')
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

但不少开发者反馈：

「属性都加了，就是没有 …」
「单行可以，改成两行就不行了」
「放在 Row 里整行被撑破，列表布局错乱」

这些问题的根源通常不在 Text 组件本身，而在 省略号生效的前置条件未被满足：maxLines 与 textOverflow 必须配合使用，且 Text 必须拥有有限的布局宽度。在 Flex（Row/Column）和 Stack 中，若未正确约束宽度，文本会按**固有内容宽度（intrinsic width）**测量，截断逻辑根本不会触发。

本文结合项目 Demo，从 API 契约、容器排查、多行截断、无空格长串等维度做系统解析。读完后，你应该能独立排查「省略号不显示」类问题。

---

一、省略号生效的三要素

文本截断不是单一属性行为，而是三个条件同时满足的结果：

┌─────────────────────────────────────────────┐
│  ① maxLines 限制行数                         │
│  ② textOverflow.Ellipsis 指定省略样式        │
│  ③ Text 有有限宽度（layoutWeight / width）   │
└─────────────────────────────────────────────┘
         缺一不可 → 省略号不出现或布局被撑破

要素	作用	缺失后果
maxLines	限制最大行数	文本无限换行或单行裁切无 …
textOverflow	指定溢出表现	只裁切不显示省略号
宽度约束	提供测量上限	按内容宽度排版，截断失效

官方文档明确：textOverflow 为 None、Clip、Ellipsis 时，必须与 maxLines 配合才生效。

---

二、maxLines 与 textOverflow 深度解析

2.1 maxLines：行数上限

Text(longTitle)
  .maxLines(1)   // 单行
  .maxLines(2)   // 最多两行，超出截断

• maxLines(1)：列表标题、标签、单行摘要；
• maxLines(2) 或 3：卡片描述、评论预览；
• 不设 maxLines：文本按宽度自然换行，不受行数限制。

2.2 textOverflow：溢出策略

HarmonyOS 提供多种 TextOverflow 模式：

枚举值	行为	与 maxLines 关系
None	不裁剪（同 Clip）	需配合 maxLines
Clip	硬裁切，无省略号	需配合 maxLines
Ellipsis	末尾显示 …	需配合 maxLines
MARQUEE	跑马灯滚动	与 maxLines 互斥

项目中的标准写法（API 11+）：

Text(longTitle)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

2.3 坑 1：只设 maxLines，不设 textOverflow

Demo 中 WRONG_NO_OVERFLOW 场景故意只写：

Text(this.sampleText())
  .layoutWeight(1)
  .maxLines(1)
  // ❌ 缺少 textOverflow

表现：文本在边界处被硬裁切，通常不出现 …。用户感知为「文字被切断了」，而非「有省略号的长文本」。

修复：补上 .textOverflow({ overflow: TextOverflow.Ellipsis })。

2.4 坑 2：只设 textOverflow，不设 maxLines

Text(longTitle)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
  // ❌ 缺少 maxLines

按官方说明，两者必须同时使用，否则 Ellipsis 不生效。

---

三、Flex 容器中的截断失效

3.1 Row 的测量逻辑

Row 是主轴水平方向的 Flex 容器。子组件默认按自身固有尺寸参与排版。Text 的固有宽度 = 完整文本渲染后的宽度。

这意味着：即使写了 maxLines(1) 和 textOverflow(Ellipsis)，若 Text 没有宽度上限，它会按全文宽度测量，永远不会触发「溢出」。

3.2 坑 3：Row 内 Text 无 layoutWeight

Demo 错误写法 WRONG_FLEX_NO_WEIGHT：

Row({ space: 8 }) {
  Text('标题').width(36)
  Text(this.sampleText())
    .maxLines(1)
    .textOverflow({ overflow: TextOverflow.Ellipsis })
    // ❌ 无 layoutWeight(1)，无固定 width
}
.width('100%')
.clip(true)   // clip 只裁视觉，不能替代宽度约束

表现：文本按固有宽度撑开 Row，省略号不出现，右侧内容可能被挤出屏幕。.clip(true) 裁掉溢出像素，但不是正确的省略号方案。

3.3 正确写法：layoutWeight(1)

Demo 正确场景 CORRECT_SINGLE_LINE：

Row({ space: 8 }) {
  Text('标题').width(36)
  Text(this.sampleText())
    .layoutWeight(1)    // ✅ 占据剩余宽度
    .maxLines(1)
    .textOverflow({ overflow: TextOverflow.Ellipsis })
}
.width('100%')

layoutWeight(1) 让 Text 获得 Row 内剩余空间作为最大宽度，超出部分触发 Ellipsis。

3.4 Flex 排查对照表

容器	错误写法	正确写法
Row	Text(long) 无约束	Text(long).layoutWeight(1)
Row	依赖 .clip(true)	宽度约束 + Ellipsis
Column	Text(long) 无 width	Text(long).width('100%')
Row	多个 Text 抢空间	关键 Text 设 layoutWeight(1)，其余固定 width

3.5 替代方案：固定 width

若不想用 layoutWeight，可直接指定宽度：

Text(longTitle)
  .width(200)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

适合宽度确定的场景（如固定卡片宽 180vp）。

---

四、Stack 容器中的截断失效

4.1 Stack 的测量特点

Stack 子组件默认不参与 Flex 分配，按自身尺寸叠加。Text 未设 width 时，仍以内容固有宽度测量。

4.2 坑 4：Stack 内 Text 无 width

Demo WRONG_STACK_NO_WIDTH：

Stack({ alignContent: Alignment.TopStart }) {
  Text(this.sampleText())
    .maxLines(2)
    .textOverflow({ overflow: TextOverflow.Ellipsis })
    // ❌ 无 width('100%')
}
.width('100%')
.height(72)

表现：多行截断失效，文本可能超出 Stack 边界，或只显示一行无 …。

4.3 正确写法：width(‘100%’)

Demo CORRECT_MULTI_LINE（放在 Column 中，原理相同）：

Text(this.sampleText())
  .width('100%')       // ✅ 贴合父容器宽度
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
  .lineHeight(20)

4.4 Stack / Column 排查要点

容器	关键约束	说明
Stack	width('100%')	Text 贴合 Stack 边界
Column	width('100%')	或 alignSelf(ItemAlign.Stretch)
父容器	自身也需 width('100%')	约束链不能断

---

五、多行截断实战

5.1 两行描述的标准模板

商品卡片、Feed 流摘要常见需求：「最多显示 2 行，超出显示 …」。

Column({ space: 6 }) {
  Text('商品描述').fontSize(11).fontColor('#6B7280')
  Text(longDesc)
    .width('100%')
    .maxLines(2)
    .textOverflow({ overflow: TextOverflow.Ellipsis })
    .lineHeight(20)
}
.width('100%')

要点：

• maxLines(2) 限制行数；
• Ellipsis 在最后一行末尾显示 …；
• lineHeight 保证行高一致，避免截断行显示异常。

5.2 多行 vs 单行对比

场景	maxLines	宽度约束	典型用途
列表标题	1	layoutWeight(1) in Row	商品名、用户名
卡片描述	2~3	width('100%') in Column	简介、评论
标签	1	固定 width	短标签

---

六、无空格长串的特殊处理

6.1 问题现象

URL、订单号、连续英文等无空格长串，默认在单词边界换行。单行 maxLines(1) 时，整串被视为一个「单词」，可能直接溢出而不显示 …。

Demo 测试文本：

export const LONG_NO_SPACE: string =
  '超长无空格连续字符串abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'

6.2 解法：wordBreak(BREAK_ALL)

Demo CORRECT_WORD_BREAK：

Text(this.sampleText())
  .layoutWeight(1)
  .maxLines(1)
  .wordBreak(WordBreak.BREAK_ALL)   // ✅ 允许在任意字符间断行
  .textOverflow({ overflow: TextOverflow.Ellipsis })

官方说明：设置 Ellipsis 时，WordBreak.BREAK_ALL 可在单词中间断行，使省略号正常显示。

6.3 中文 vs 英文

文本类型	是否需要 BREAK_ALL	说明
中文	通常不需要	按字换行
英文单词	不需要	按空格断词
URL / 哈希 / SKU	需要	无自然断点

---

七、MARQUEE 模式补充

TextOverflow.MARQUEE 启用跑马灯，文本单行滚动显示。

注意：

• 与 maxLines 互斥，设置 MARQUEE 后 maxLines 不生效；
• 适合固定宽度标题栏，不适合列表大量条目（性能与视觉干扰）；
• 列表场景优先 Ellipsis。

---

八、Demo 代码走读

8.1 场景配置

TextClipTypes.ets 定义 6 种场景，覆盖错误与正确写法：

export const TEXT_CLIP_SCENARIOS: TextClipScenario[] = [
  { id: WRONG_NO_OVERFLOW,     title: '❌ 仅 maxLines', ... },
  { id: WRONG_FLEX_NO_WEIGHT, title: '❌ Flex Row 无宽度约束', ... },
  { id: WRONG_STACK_NO_WIDTH,  title: '❌ Stack 无 width', ... },
  { id: CORRECT_SINGLE_LINE,   title: '✅ 单行省略', ... },
  { id: CORRECT_MULTI_LINE,   title: '✅ 多行截断', ... },
  { id: CORRECT_WORD_BREAK,   title: '✅ 无空格断行', ... },
]

8.2 并排对比

TextClipPitfallDemo.ets 对错误场景自动配对正确方案：

错误场景	配对正确方案
仅 maxLines	单行省略（补 textOverflow）
Flex 无约束	单行省略（补 layoutWeight）
Stack 无 width	多行截断（补 width 100%）

8.3 体验步骤

1. 打开 App，保持「并排对比」；
2. 选 ❌ Flex Row 无宽度约束，观察左侧文本撑破卡片；
3. 对比右侧 ✅ 单行省略 的 … 效果；
4. 切换 ❌ Stack 无 width，看多行截断失效；
5. 切换 ✅ 无空格断行，观察 SKU 长串的省略号。

---

九、系统性排查流程

当省略号不显示时，按以下顺序排查：

省略号没出现？
  │
  ├─ 是否同时设置了 maxLines 和 textOverflow.Ellipsis？
  │     └─ 否 → 补上两个属性
  │
  ├─ Text 是否有有限宽度？
  │     ├─ 在 Row 中 → 加 layoutWeight(1) 或固定 width
  │     ├─ 在 Stack 中 → 加 width('100%')
  │     └─ 在 Column 中 → 加 width('100%')
  │
  ├─ 父容器宽度约束是否断裂？
  │     └─ 检查 Column/Row 是否 width('100%')
  │
  ├─ 是否无空格长串？
  │     └─ 加 wordBreak(WordBreak.BREAK_ALL)
  │
  └─ 是否误用 MARQUEE？
        └─ MARQUEE 与 maxLines 互斥

---

十、常见错误速查表

错误代码	问题	修复
.maxLines(1) only	无 …	加 textOverflow(Ellipsis)
.textOverflow(...) only	不生效	加 maxLines
Row 内无 layoutWeight	撑破布局	layoutWeight(1)
Stack 内无 width	多行失效	width('100%')
用 .clip(true) 代替	硬裁切	宽度约束 + Ellipsis
无空格 URL 溢出	无断点	wordBreak(BREAK_ALL)
MARQUEE + maxLines	互斥	二选一

---

十一、生产环境 Checklist

• maxLines 与 textOverflow({ overflow: TextOverflow.Ellipsis }) 成对出现
• Row 内截断 Text 使用 layoutWeight(1)
• Stack/Column 内截断 Text 使用 width('100%')
• 父容器宽度约束链完整（width('100%') 传递到 Text）
• 多行截断设置合理 lineHeight
• URL/SKU 等无空格文本加 wordBreak(BREAK_ALL)
• 列表不用 MARQUEE，避免性能问题
• 真机验证中英文混排、超长无空格场景

---

十二、总结

文本省略号「不显示」，几乎从来不是 Text 组件的 bug，而是布局约束 + 属性配合问题。

核心结论	说明
属性配合	maxLines 与 textOverflow.Ellipsis 必须同时使用
宽度前提	Text 必须有有限宽度，截断才会触发
Flex Row	layoutWeight(1) 获取剩余宽度
Stack	width('100%') 贴合容器
多行截断	maxLines(N) + Ellipsis，末行显示 …
无空格串	wordBreak(BREAK_ALL) 辅助断行
MARQUEE	与 maxLines 互斥，列表慎用

记住一句话：

省略号不是「加两个属性」就有，Text 得先「知道」自己有多宽。

---

附录：Demo 文件结构

文件	职责
TextClipTypes.ets	场景枚举、长文本样例、要点
TextClipSamples.ets	6 种场景可视化卡片
TextClipPitfallDemo.ets	主交互页、并排对比
pages/Index.ets	入口

---

附录：快速参考卡

// ✅ 列表标题（Row 内单行）
Text(title)
  .layoutWeight(1)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

// ✅ 卡片描述（Column 内多行）
Text(desc)
  .width('100%')
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
  .lineHeight(20)

// ✅ 无空格长串（SKU / URL）
Text(sku)
  .layoutWeight(1)
  .maxLines(1)
  .wordBreak(WordBreak.BREAK_ALL)
  .textOverflow({ overflow: TextOverflow.Ellipsis })