uni-app x 的 CSS white-space 属性完全指南：空白字符处理、换行规则与跨端兼容

uni-app x 的 CSS white-space 属性完全指南空白字符处理、换行规则与跨端兼容【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本文以 docs/css/white-space.md 为核心系统讲解 uni-app x 中white-space属性的语法、全部属性值语义、默认值差异与平台兼容性并结合仓库内的示例源码 src/pages/CSS/text/white-space.uvue、text 组件空白字符处理规则docs/component/text.md以及自动化测试用例深度剖析其底层实现与 HBuilderX 5.0 的行为调整。读完本文你将掌握如何精确控制 AppAndroid/iOS/HarmonyOS与 Web 端文本的空格合并、换行符保留、行末空白裁剪与自动换行行为理解keep这一 uni-app x 特有的高性能属性值并能在真实项目中正确使用white-space与space属性、flatten拍平模式的组合规则。属性概述white-space属性用于设置如何处理元素中的空白字符空格、换行符、制表符以及文本是否自动换行。在 uni-app x 中这一属性主要作用于 text 和 button 两个组件。由于 uni-app x 存在text组件Web 没有的组件且非 Web 平台包括小程序平台都不支持br换行因此 uni-app x 专门设计了text组件中的\n默认不忽略、直接换行的行为——无论 App 平台默认值keep还是 Web 平台默认值pre-line都保持这一表现。这也使得white-space在 uni-app x 中成为控制多行文本渲染的关键样式。uni-app x 兼容性| Web | Android | iOS | HarmonyOS | | :- | :- | :- | :- | | 4.0 | 4.0 | 4.11 | 4.61 |上表为属性基础兼容性版本要求对应 HBuilderX 相关版本。App 平台拍平flatten兼容性 flatten_compatibility| Android(Vapor) | iOS(Vapor) | HarmonyOS(Vapor) | | :- | :- | :- | | 5.21 | 5.11 | 5.0 |该表反映 App 端 Vapor 引擎在拍平flatten渲染模式下的兼容版本。语法与取值语法white-space: normal | pre | nowrap | pre-wrap | pre-line | break-spaces | [ white-space-collapse || text-wrap || white-space-trim ];值限制enum枚举值取值为下方属性值表中的名称其中keep为 uni-app x 平台扩展值不属于 W3C 标准枚举。white-space 的属性值| 名称 | 兼容性 | 描述 | | :- | :- | :- | | normal | Web: 4.0; Android: 4.0; iOS: 4.11; HarmonyOS: 4.61 | 换行符\n当做空白符处理连续的多个空白字符会合并为一个空格文本遇到边界会自动换行行末空白字符移除。 | | nowrap | Web: 4.0; Android: 4.0; iOS: 4.11; HarmonyOS: 4.61 | 换行符\n当做空白符处理连续的多个空白字符会合并为一个空格文本遇到边界不会自动换行行末空白字符移除。 | | pre | Web: 4.0; Android: 4.81; iOS: 4.81; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界不会自动换行行末空白字符保留。 | | pre-wrap | Web: 4.0; Android: 4.81; iOS: 4.81; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界会自动换行行末空白字符保留但不占位置。 | | pre-line | Web: 4.0; Android: 4.81; iOS: 4.81; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 换行符\n保留并换行显示连续的多个空白字符会合并为一个空格文本遇到边界会自动换行行末空白字符移除。 | | break-spaces | Web: 4.0; Android: 4.81; iOS: 4.81; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界会自动换行行末空白字符换行处理。 | | keep | Web: x; Android: 5.0; iOS: 5.0; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 不对空白字符处理保持原始值。换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界会自动换行行末空白字符保留。 |七个取值可从三个维度快速记忆换行符\n是否保留normal/nowrap将\n当作普通空白符合并其余取值均保留并换行显示连续空白字符是否合并normal/nowrap/pre-line合并为单个空格pre/pre-wrap/break-spaces/keep全部保留边界处是否自动换行仅nowrap与pre不自动换行其余均自动换行。默认值 default-value| 平台 | 默认值 | | :- | :- | | uvue-app | keep | | uvue-web | pre-line |注意W3C 规范默认值为normal。uni-app x 之所以在 App 端默认采用keep是为了避免对连续空白字符做合并处理从而提升 text 组件的渲染性能详见下文HBuilderX 5.0 版本调整。适用组件 unix-tagstextbutton空白字符处理不止由 white-space 决定编译期模板静态文本先行处理对于写在模板中的 text 组件里的空白字符在编译阶段会由编译器先行处理。以 docs/component/text.md 中的示例为准template text idt1 a bc def g hi /text /template编译期间会将 template 中静态文本的所有空白字符转换为空格并将多个连续空格合并为一个空格首尾空格保留。如上示例编译后 text 组件中的文本内容为 a bc def g hi 。注意编译期间不会处理变量中的空白字符。变量文本交由各平台运行环境根据white-space样式处理并渲染例如template text{{text}}/text /template script languts setup let text a bc def\tg\nhi /script上面代码中的\t和\n是转义字符\t表示制表符Tab\n表示换行符Line Feed。运行期space 属性与 white-space 样式共同决定运行期的空白字符处理由space属性与white-space样式共同决定space属性仅处理空格字符white-space样式处理所有空白字符空格、换行符、制表符。如果 text 组件配置了space属性值会先根据space属性值处理文本中的空格再根据white-space样式处理。蒸汽模式Vapor已废弃space属性推荐统一改用 CSSwhite-space来处理空白字符。各平台存在如下差异App-Android 平台配置了space属性后将只处理空格转换忽略white-space样式值即按white-space: keep处理App-iOS 平台配置了space属性后将先处理空格转换再根据white-space属性值处理空白字符后续版本将统一废弃space属性推荐统一改用 CSSwhite-space。与 text-overflow 的组合使用white-space: nowrap常与text-overflow配合实现单行省略号效果。仓库示例 src/pages/CSS/text/text-overflow.uvue 中大量使用这一组合如text classfont-size-20 styletext-overflow: ellipsis;white-space: nowrap;{{data.singleLineText}}/text text classfont-size-20 styletext-overflow: ellipsis;white-space: nowrap;width: 100px;{{data.multiLineText}}/text当需要实现任意宽度单行截断 省略号时white-space: nowrap是必不可少的前提——它保证文本不换行配合width与text-overflow: ellipsis完成截断显示。HBuilderX 5.0 版本调整app 平台、web 平台在 HBuilderX 5.0 版本调整了white-space属性的实现之前接近小程序的表现之后按 W3C 标准规范执行。同时为了 text 组件性能考虑app 平台新增支持keep属性值且默认为keep。默认值调整app-android、app-ios 平台新增支持取值keep默认值由normal调整为keepapp-harmony 平台蒸汽模式Vapor支持取值keep默认值为keepweb 平台默认值由normal调整为pre-line。调整前实现规范旧行为对照调整前的实现与小程序表现接近各取值行为如下注意与上表新规范的差异normal与调整后的 pre-line 效果一致换行符\n保留并换行显示连续的多个空白字符会合并为一个空格文本遇到边界会自动换行行末空白字符移除nowrap换行符\n保留并换行显示连续的多个空白字符会合并为一个空格文本遇到边界不会自动换行行末空白字符移除pre换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界不会自动换行行末空白字符保留pre-wrap换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界会自动换行行末空白字符保留pre-line换行符\n保留并换行显示连续的多个空白字符会合并为一个空格文本遇到边界会自动换行行末空白字符移除break-spaces换行符\n保留并换行显示连续的多个空白字符保留文本遇到边界会自动换行行末空白字符保留。关键差异点调整前normal与nowrap会保留\n换行接近小程序表现调整后按 W3C 规范normal与nowrap将\n当作普通空白符处理合并为一个空格。若你的旧项目依赖normal保留换行升级到 HBuilderX 5.0 后需改用pre-line或keep以获得一致效果。各平台当前实现要点App-Android、App-iOS自 HBuilderX 5.0 起white-space控制空白字符处理逻辑与 W3C 规范一致默认值为keep。如示例 a bc def\tg\nhi 将保留所有空格连续空格不会合并、制表符、换行符进行渲染a 和 b 之间有 3 个空格App-Harmony蒸汽模式Vapor下white-space控制空白字符处理逻辑与 W3C 规范一致默认值为keepWeb自 HBuilderX 5.0 起逻辑与 W3C 规范一致默认值为pre-line。同一示例将合并空格连续空格合并为 1 个空格制表符转换为空格保留换行符进行渲染a 和 b 之间只有 1 个空格。Web 与 App 的本质差异Web 默认值pre-line虽然支持\n换行同时会把\n以外的多个连续空白字符合并为 1 个App 为了提升性能默认值为keep即默认不会合并连续的空白字符。实战示例动态切换 white-space仓库内置了完整的演示页面 src/pages/CSS/text/white-space.uvue同时演示普通渲染与拍平flatten渲染下 7 个枚举值含空字符串与自定义值的设置/获取可直接在 hello uni-app x 中运行查看效果。核心逻辑如下template scroll-view stylepadding: 10px 0px; background-color: gray;justify-content: center; directionhorizontal !-- 普通版本 -- text classtext :style{ whiteSpace: data.whiteSpace }{{data.multiLineText}}/text /scroll-view text拍平/text scroll-view stylepadding: 10px 0px; background-color: gray;justify-content: center; directionhorizontal !-- 拍平版本 -- text classtext :style{ whiteSpace: data.whiteSpace } flatten{{data.multiLineText}}/text /scroll-view /template关键点说明枚举数据脚本中定义了完整的枚举列表其中包含空字符串空值情况与keepconst whiteSpaceEnum: ItemType[] [ { value: 0, name: }, { value: 1, name: normal }, { value: 2, name: nowrap }, { value: 3, name: pre }, { value: 4, name: pre-wrap }, { value: 5, name: pre-line }, { value: 6, name: break-spaces }, { value: 7, name: keep } ]多行测试文本文本同时包含 Tab 缩进、换行符与单行长段落便于肉眼对比各取值差异const data reactive({ multiLineText: HBuilderX 轻巧、 极速 极客编辑器 uni-app x 终极跨平台方案 uts 大一统语言 HBuilderX轻巧、极速极客编辑器uni-app x终极跨平台方案uts大一统语言, whiteSpace: normal, whiteSpaceActual: , whiteSpaceActualFlat: })setProperty 设置与 getPropertyValue 获取通过UniTextElement类型引用 text 节点动态设置并读取样式值配合nextTick确保样式应用后再取值const textRef ref(null as UniTextElement | null) const textRefFlat ref(null as UniTextElement | null) const getPropertyValues () { data.whiteSpaceActual textRef.value?.style.getPropertyValue(white-space) ?? data.whiteSpaceActualFlat textRefFlat.value?.style.getPropertyValue(white-space) ?? } const changeWhiteSpace (value: string) { data.whiteSpace value textRef.value?.style.setProperty(white-space, value) textRefFlat.value?.style.setProperty(white-space, value) // 使用 nextTick 确保样式已应用后再获取值 nextTick(() { getPropertyValues() }) }样式细节示例中.text设置了font-size: 16px; align-self: flex-start;注释明确说明需要设置 align-selftext 组件才会自适应宽度directionhorizontal的横向 scroll-view 便于观察不换行文本的溢出效果。拍平flatten模式示例中普通版本与拍平版本带flatten属性各渲染一份文本可对比两种渲染模式下的空白处理一致性。flatten是 App 端的一种渲染优化拍平将组件样式合并为原生层绘制。从拍平兼容性表可见Vapor 引擎下 Android 5.21 / iOS 5.11 / HarmonyOS 5.0 起支持。在实际开发中若同时使用white-space与flatten建议在真机上对两种渲染模式分别验证显示效果。自动化测试验证仓库的自动化测试 src/pages/CSS/set-css.test.js约第 792-802 行覆盖了该示例页面的行为断言{ path: /pages/CSS/text/white-space, method: radioChangeWhiteSpace, valueIndex: 3, styleName: white-space, expectedValue: { whiteSpace: pre, whiteSpaceActual: pre, whiteSpaceActualFlat: pre, } }该用例通过radioChangeWhiteSpace方法选择第 3 个枚举值pre并断言设置值whiteSpace、普通渲染实际值whiteSpaceActual、拍平渲染实际值whiteSpaceActualFlat三者均为pre从侧面印证了通过setProperty(white-space, value)设置后getPropertyValue(white-space)可以原样读回且普通模式与拍平模式下行为一致。注意事项与最佳实践性能优先选 keepApp 端默认keep意味着不做空白合并处理渲染性能最优。若业务不需要折叠连续空格保持默认即可跨端一致性需要换行符保留 连续空格保留 自动换行时App 用pre-wrap或默认keepWeb 用pre-wrap需要换行符保留 空格折叠 自动换行时统一使用pre-lineWeb 默认值即为此需要单行不换行时统一使用nowrap避免依赖 space 属性蒸汽模式Vapor已废弃space属性且 Android 平台配置space后会忽略white-space样式按keep处理后续版本将统一废弃应统一改用 CSSwhite-space模板静态文本 vs 变量文本模板中静态文本的空白字符在编译期已被合并处理white-space主要作用于变量文本的运行期渲染若需要精确控制静态文本的空白请通过变量传入文本内容\n 换行设计uni-app x 非 Web 平台不支持br换行text 组件中的\n默认换行是框架设计行为各取值下均不会被当作普通空格忽略仅normal/nowrap按 W3C 新规范合并升级注意从旧版本HBuilderX 5.0 之前升级时normal/nowrap对\n的处理从保留换行变为按空格合并旧项目需评估文本渲染差异与 text-overflow 联动单行省略号text-overflow: ellipsis必须搭配white-space: nowrap使用参见 src/pages/CSS/text/text-overflow.uvue。参见text 组件空白字符处理详解含space属性与各平台差异说明text-overflow 属性示例white-space 演示页面源码white-space 自动化测试用例button 组件文档【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考