鸿蒙 uni-app x text组件避坑：样式不继承与空格处理

鸿蒙专家

在 uni-app x 的鸿蒙平台开发中，text 组件看起来最简单，实际是高频踩坑点。尤其从 Web 转过来的开发者，习惯在 view 里直接写文字，但在 uni-app x 中，文字必须写在 text 组件里，不能写在 view 的文本区域。鸿蒙平台从 HarmonyOS 4.61 开始支持 text 组件。本文围绕鸿蒙平台的 text 组件用法，梳理属性、场景、适配规则和常见问题。

一、为什么文字必须写在 text 里
在 Web 中，div 里直接写文字没有问题。但 uni-app x 的 view 组件不支持文本区域，文字需要用 text 包裹。编译器虽然会自动包裹一层 text，但自动生成的 text 无法单独设置样式。因为 uni-app x 样式不继承，所以直接写在 view 里的文字，会出现样式不可控的问题。

2. <!-- 错误：文字直接写在 view 里 -->
3. <view>这是一段文字</view>
5. <!-- 正确：文字用 text 包裹 -->
6. <text>这是一段文字</text>

复制代码

2. <!-- 编译器会自动包裹，但无法控制内层 text 样式 -->
3. <view style='color: red;'>这是一段文字</view>
5. <!-- 实际编译后变成 -->
6. <view style='color: red;'>
7.   <text>这是一段文字</text>
8. </view>
10. <!-- 正确做法：直接用 text 设置样式 -->
11. <text style='color: red;'>这是一段文字</text>

复制代码

二、核心属性与点击态
text 组件的核心属性包括样式控制等。点击态方面，hover-class 只在蒸汽模式（Vapor）下生效，非蒸汽模式的 text 组件不支持 hover 相关功能。鸿蒙平台还支持 flatten 属性，用于拍平组件层级，减少渲染节点数量，提升性能。

三、实战场景
1. 基础文本

2. <template>
3.   <text style='font-size: 16px; color: #333;'>这是一段普通文本</text>
4. </template>

复制代码

2. 单行文本省略

2. <template>
3.   <text style='font-size: 14px; white-space: nowrap; text-overflow: ellipsis; lines: 1;'>这是一段很长很长很长很长很长很长很长很长很长很长很长很长很长很长很长的文本</text>
4. </template>

复制代码

3. 多行文本省略
可以用 lines 或 max-lines 控制显示行数，超出显示省略号。

2. <template>
3.   <text style='font-size: 14px; lines: 3; text-overflow: ellipsis;'>这是一段很长的文本，超过三行会显示省略号。</text>
4. </template>
6. <template>
7.   <text :max-lines='3' style='font-size: 14px;'>这是一段很长的文本，超过三行会显示省略号。</text>
8. </template>

复制代码

4. 文本可选
让用户长按选中复制：

2. <template>
3.   <text selectable='true' style='font-size: 14px; color: #333;'>这段文本可以长按选中复制</text>
4. </template>

复制代码

5. 嵌套文本
text 可以嵌套 text，实现同一段落内不同样式。但子 text 不继承父 text 样式，需要单独设置。

2. <template>
3.   <text style='font-size: 16px; color: #333;'>
4.     <text style='font-weight: bold; color: #2196F3;'>加粗蓝色</text>
5.     <text>普通文本</text>
6.     <text style='color: #F44336;'>红色文本</text>
7.   </text>
8. </template>

复制代码

6. 点击态效果
蒸汽模式下支持 hover-class：

2. <template>
3.   <text hover-class='text-hover' hover-start-time='100' hover-stay-time='200' style='font-size: 16px; color: #2196F3; padding: 10px;'>点击我试试</text>
4. </template>
5. <style>
6. .text-hover {
7.   opacity: 0.7;
8.   background-color: #E3F2FD;
9. }
10. </style>

复制代码

7. 连续空格处理
编译期处理时，静态文本中的连续空格会合并。运行期变量中的空格根据 white-space 处理。

2. <template>
3.   <!-- 编译期处理：静态文本连续空格会合并 -->
4.   <text>这 有 多个 空格</text>
6.   <!-- 运行期处理：变量中的空格根据 white-space 处理 -->
7.   <text style='white-space: pre;'>{{textWithSpaces}}</text>
8. </template>
9. <script setup lang='uts'>
10. const textWithSpaces = ref('这 有 多个 空格')
11. </script>

复制代码

8. 实体字符
静态文本实体字符会在编译期解码。变量中的实体字符根据 decode 处理。注意蒸汽模式（Vapor）废弃了 decode 属性，运行期不再解析实体字符。

2. <template>
3.   <text>5 &lt; 10 &amp; 3 &gt; 1</text>
4.   <text decode='true'>{{entityText}}</text>
5. </template>
6. <script setup lang='uts'>
7. const entityText = ref('5 &lt; 10')
8. </script>

复制代码

四、鸿蒙平台适配要点
- HarmonyOS 4.61 开始支持 text 组件。
- 鸿蒙平台文字必须写在 text 组件里，不能写在 view 的文本区域。
- 鸿蒙平台 text 的子 text 不继承父 text 样式，需要单独设置。
- 鸿蒙平台蒸汽模式（Vapor）white-space 默认值为 keep，即保留所有空白字符，连续空格不会合并。
- App 平台 white-space 默认值为 keep，Web 平台默认值为 pre-line。
- 鸿蒙平台支持 flatten 属性，用于减少渲染节点。
- 嵌套 text 中，子 text 设置的排版样式（position、display、width、height、margin、padding 等）以及部分 text 独有样式（text-align、lines、white-space、text-overflow）不生效。
- 在 uni-app x 中，text 里的 \n 默认会换行，这点与 Web 不同，Web 中 \n 默认会被忽略。

与鸿蒙原生 Text 组件对比，原生写法如下：

2. // 鸿蒙原生写法
3. Text('这是一段文本')
4.   .fontSize(16)
5.   .fontColor('#333')
6.   .fontWeight(FontWeight.Bold)
7.   .maxLines(3)
8.   .textOverflow({ overflow: TextOverflow.Ellipsis })

复制代码

uni-app x 的 text 组件与原生 Text 几乎一样，都是用 CSS 属性控制样式。

五、常见踩坑记录
坑一：文字不能直接写在 view 里。必须用 text 包裹。
坑二：子 text 不继承父 text 样式。嵌套时需单独设置。
坑三：view 的文本区域会被自动包裹，但无法控制内层 text 样式，建议手动包裹。
坑四：\n 默认会换行，跟 Web 不同。
坑五：连续空格默认会合并。需要保留时，用变量加 white-space: pre。
坑六：蒸汽模式废弃 space 和 decode 属性。推荐用 CSS white-space 处理空格。
坑七：嵌套 text 排版样式不生效。

六、完整示例片段
下面是一个综合页面片段，覆盖基础文本、省略、可选、嵌套、样式和连续空格。

2. <template>
3.   <scroll-view style='flex: 1;'>
4.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
5.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>基础文本</text>
6.       <text style='font-size: 16px; color: #333; margin-top: 10px;'>普通文本</text>
7.       <text style='font-size: 16px; color: #2196F3; font-weight: bold; margin-top: 8px;'>加粗蓝色文本</text>
8.       <text style='font-size: 16px; color: #F44336; font-style: italic; margin-top: 8px;'>斜体红色文本</text>
9.       <text style='font-size: 16px; text-decoration: underline; margin-top: 8px;'>下划线文本</text>
10.       <text style='font-size: 16px; text-decoration: line-through; margin-top: 8px;'>删除线文本</text>
11.     </view>
13.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
14.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>文本省略</text>
15.       <text style='font-size: 14px; lines: 1; text-overflow: ellipsis; white-space: nowrap; margin-top: 10px;'>单行省略：这是一段很长很长很长很长很长很长很长很长很长很长很长很长很长很长很长的文本</text>
16.       <text style='font-size: 14px; lines: 2; text-overflow: ellipsis; margin-top: 10px;'>多行省略：这是一段很长的文本，超过两行会显示省略号。</text>
17.     </view>
19.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
20.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>可选文本</text>
21.       <text selectable='true' style='font-size: 14px; color: #333; margin-top: 10px; background-color: #F5F5F5; padding: 10px; border-radius: 5px;'>长按这段文字可以选中复制，试试看</text>
22.     </view>
24.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
25.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>嵌套文本</text>
26.       <text style='font-size: 16px; margin-top: 10px;'>
27.         <text style='color: #333;'>普通文本 </text>
28.         <text style='color: #2196F3; font-weight: bold;'>加粗蓝色 </text>
29.         <text style='color: #F44336;'>红色文本 </text>
30.         <text style='color: #4CAF50; text-decoration: underline;'>绿色下划线</text>
31.       </text>
32.     </view>
34.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
35.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>文本样式</text>
36.       <text style='font-size: 16px; letter-spacing: 5px; margin-top: 10px;'>字间距 5px</text>
37.       <text style='font-size: 16px; line-height: 2; margin-top: 10px;'>行高 2 倍，这是一段文字用来展示行高效果</text>
38.       <text style='font-size: 16px; text-align: center; margin-top: 10px;'>居中对齐</text>
39.       <text style='font-size: 16px; text-align: right; margin-top: 10px;'>右对齐</text>
40.       <text style='font-size: 16px; text-shadow: 2px 2px 4px rgba(0,0,0,0.3); margin-top: 10px;'>文字阴影</text>
41.     </view>
43.     <view style='padding: 15px; background-color: white; margin-bottom: 10px;'>
44.       <text style='font-size: 18px; font-weight: bold; margin-bottom: 15px;'>连续空格</text>
45.       <text style='font-size: 14px; white-space: pre; margin-top: 10px;'>这 有 多个 空格</text>
46.       <text style='font-size: 14px; margin-top: 10px;'>正常显示：这 有 多个 空格</text>
47.     </view>
48.   </scroll-view>
49. </template>

复制代码

总结：
在鸿蒙平台使用 uni-app x 的 text 组件，关键规则是：文字必须写在 text 组件里，样式设置在 text 上，不要直接写在 view 里；子 text 不继承父 text 样式；\n 默认换行；连续空格在编译期会合并；App 与鸿蒙蒸汽模式 white-space 默认值为 keep，Web 为 pre-line；蒸汽模式废弃 space 和 decode 属性；嵌套 text 的排版样式不生效。养成用 text 包裹文字的习惯，可以避免大量样式和适配问题。