uni-app x 中的 UniTextElement 详解text 组件 DOM 对象、文本测量与富文本布局实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appUniTextElement 是 uni-app xuvue中 text 组件的 DOM 元素对象它继承自所有组件共有的 UniElement 基类为开发者提供了程序化读写文本内容、测量文本宽高、以及用代码直接编排多段带样式的富文本布局的能力。本文以 docs/api/dom/unitextelement.md 为骨架结合仓库内真实示例 src/pages/component/text/text-layout.uvue 与其自动化测试 src/pages/component/text/text-layout.test.js完整讲解 UniTextElement 的属性、UniTextLayout 的全部设置方法、measure 测量流程与嵌套文本实现读者学完后可以直接在 App 端Android VDOM落地代码驱动文本布局的实战方案。UniTextElement 是什么在 uni-app x 的 uvue 体系中页面模板里的每个组件在运行时都对应一个 DOM 元素对象可以通过uni.getElementById()获取并对它进行读写。UniTextElement 就是 text 组件 对应的 DOM 元素类型官方文档定位为text 组件的 DOM 元素对象。它与 UniElement 的继承关系可以用下面的类图表示通用能力来自 UniElement 基类如id、isConnected、attributes、classList、dataset、children、firstChild、lastChild、parentElement、offsetWidth、offsetHeight、scrollWidth、scrollHeight、tagName、style等只读属性以及appendChild、insertBefore、getBoundingClientRect等通用方法。文本专属能力由 UniTextElement 自身提供只读的value属性和setTextLayout()、getContentSize()两个核心方法。兼容性一览| Web | 微信小程序 | Android | iOS | iOS(VDOM) UTS 插件 | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 4.0 | x | 4.0 | 4.11 | 4.25 | 4.61 |其中x表示该平台不支持。可以看到 UniTextElement 在 Web、Android、iOS、HarmonyOS 上从较早期版本即已可用而微信小程序平台MP目前不提供该 DOM 对象setTextLayout系列能力则仅限 Android 的 VDOM 渲染模式详见下文。UniTextElement 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | value | string | 是 | Web: x; 微信小程序: x; Android: 4.0; iOS: 4.11; iOS(VDOM) UTS 插件: 4.25; HarmonyOS: 4.61 | 只读属性text 元素的文案内容 |value是 UniTextElement 唯一专属的属性类型为string只读用来读取 text 元素当前显示的文案内容。它不需要额外获取直接通过元素对象访问即可。仓库示例 examples/hello-uvue/pages/component-instance/nextTick/nextTick-composition.uvue 展示了在 nextTick 前后读取文本内容的典型写法const pageText uni.getElementById(page-text)! dataInfo.beforeNextTickTitle (pageText as UniTextElement).value // nextTick 之后再次读取 dataInfo.afterNextTickTitle (pageText as UniTextElement).value注意在 uts/ts 中需要对getElementById的返回值做类型断言as UniTextElement因为getElementById返回的是通用的元素类型只有 text 组件的元素才能安全断言为 UniTextElement。同样写法也出现在 examples/hello-uvue/pages/component-instance/nextTick/nextTick-options.uvue 等文件中用于验证 DOM 更新时机同一 text 元素在 nextTick 回调前后读取到的value不同说明 DOM 修改是异步提交的。UniTextElement 的方法UniTextElement 提供两个专属方法setTextLayout(layout)用于整体设置文本布局getContentSize()用于获取内容宽高。其中setTextLayout接收的UniTextLayout对象是整个文本排版能力的核心。setTextLayout(layout: UniTextLayout): void设置文本内容。它接收一个UniTextLayout文本对象作为参数一次性把文案内容、颜色、字体、对齐、溢出、阴影等排版信息应用到 text 元素上。兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | x | 4.81 | x | x |参数说明| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | layout | UniTextLayout | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 文本对象 |返回值与使用方式setTextLayout无返回值。典型调用链是先new UniTextLayout()构建并配置再setTextLayout()应用到元素与measure()配合时则是先测量、后应用见下文实战示例。getContentSize(): UniLayoutSize获取内容宽高。它返回一个UniLayoutSize对象描述当前 text 元素实际内容而非元素盒子的宽度与高度单位是逻辑像素。兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | x | 4.81 | x | x |返回值| 类型 | 描述 | | :- | :- | | UniLayoutSize | 布局大小 |UniLayoutSize 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | width | number | 是 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素宽度逻辑像素值 | | height | number | 是 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素高度逻辑像素值 |getContentSize()与measure()的区别measure()是预测性测量在布局尚未应用前根据约束估算尺寸getContentSize()是实际内容尺寸读取的是元素应用布局后的真实内容宽高。在 text-layout.uvue 示例中二者被组合使用先用measure()算出宽高并写回元素 style再调用getContentSize()读取并展示最终内容尺寸。UniTextLayout代码驱动的文本排版对象UniTextLayout是setTextLayout()与append()的参数类型可以把它理解为用代码创建的一段带样式的文本。它不是一个现成组件而是通过new UniTextLayout()构造的普通对象构造后依次调用各set*方法配置文案与样式。setText(text: string): void设置文本。兼容性| Web | 微信小程序 | Android(VDOM) | Android(Vapor) | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | x | x | 4.81 | x | x | x |参数| 名称 | 类型 | 必填 | 兼容性 | | :- | :- | :- | :-: | | text | string | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x |setColor(color: string): void设置文本颜色参数为颜色字符串如red、#ff0000、rgba(255,0,0,0.5)。兼容性仅 Android(VDOM) 4.81 起支持Web、微信小程序、iOS、HarmonyOS 均为 x参数color: string必填。setFontFamily(family: string): void设置字体名称。参数为字体族名称字符串可配合uni.loadFontFace()加载的自定义字体使用。示例 text-layout.uvue 中先通过uni.loadFontFace({ family: AlimamaDaoLiTiTTF, source: url(/static/font/AlimamaDaoLiTi.otf) })加载字体再在setFontFamily(AlimamaDaoLiTiTTF)中引用。兼容性仅 Android(VDOM) 4.81 起支持参数family: string必填。setFontSize(size: string): void设置字体大小参数为带单位的字符串如30px示例中使用30px、25px、20px。兼容性仅 Android(VDOM) 4.81 起支持参数size: string必填。setFontStyle(style: string): void设置字体样式典型取值为italic斜体、normal。示例中传入italic。兼容性仅 Android(VDOM) 4.81 起支持参数style: string必填。setFontWeight(weight: string): void设置字体粗细典型取值为bold、normal或数值字符串如700。示例中传入bold。兼容性仅 Android(VDOM) 4.81 起支持参数weight: string必填。setLineHeight(height: string): void设置行高。参数既可以是带单位的像素值字符串如30px也可以是无单位倍数如3表示 3 倍字体大小。示例中两种写法均有使用。兼容性仅 Android(VDOM) 4.81 起支持参数height: string必填。setTextAlign(align: string): void设置文字水平对齐方式典型取值为left、center、right。示例的约束多行场景中传入center。兼容性仅 Android(VDOM) 4.81 起支持参数align: string必填。setTextOverflow(overflow: string): void设置文字溢出裁剪方式典型取值为ellipsis省略号或clip。示例的单行约束场景中传入ellipsis。兼容性仅 Android(VDOM) 4.81 起支持参数overflow: string必填。setWhiteSpace(whiteSpace: string): void设置空白字符处理方式典型取值为nowrap不换行、normal正常换行。示例的单行约束场景中传入nowrap配合setTextOverflow(ellipsis)实现单行省略。兼容性仅 Android(VDOM) 4.81 起支持参数whiteSpace: string必填。setTextShadow(shadow: string): void设置文字阴影参数为阴影声明字符串示例中为2px 4px rgba(202,207,17,0.5)即水平偏移 2px、垂直偏移 4px、颜色为半透明黄的阴影。兼容性仅 Android(VDOM) 4.81 起支持参数shadow: string必填。setTextDecorationLine(decorationLine: string): void设置文本修饰类型典型取值为underline下划线、line-through删除线、none。示例中传入underline。兼容性仅 Android(VDOM) 4.81 起支持参数decorationLine: string必填。append(layout: UniTextLayout): void添加子文本对象。可以把多个 UniTextLayout 拼接到一个父布局上从而在一段文本中混合不同的文案与样式实现富文本效果如父段红色 25px追加的子段蓝色 20px。兼容性| Web | 微信小程序 | Android(VDOM) | Android(Vapor) | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | x | x | 4.81 | x | x | x |参数| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | layout | UniTextLayout | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 文本对象 |measure(constraint: UniLayoutConstraintSize): UniLayoutSize测量文本大小。在约束最大/最小宽高下预测文本将占据的布局尺寸返回值用于回写元素宽高或判断是否溢出。兼容性| Web | 微信小程序 | Android(VDOM) | Android(Vapor) | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | x | x | 4.81 | x | x | x |参数| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | constraint | UniLayoutConstraintSize | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 布局约束大小 |返回值UniLayoutSize布局大小width、height均为逻辑像素值必备。UniLayoutConstraintSize 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | minWidth | number | 否 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素最小宽度逻辑像素值。可选值不设置则认为没有最小宽度 | | maxWidth | number | 否 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素最大宽度逻辑像素值。可选值不设置则认为可以无限宽 | | minHeight | number | 否 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素最小高度逻辑像素值。可选值不设置则认为没有最小高度 | | maxHeight | number | 否 | Web: x; 微信小程序: x; Android(VDOM): 4.81; Android(Vapor): x; iOS: x; HarmonyOS: x | 元素最大高度逻辑像素值。可选值不设置则认为可以无限高 |四个约束字段均为可选。实际调用时可以直接传空对象{}示例中写为{} as UniLayoutConstraintSize表示无约束测量也可以只传需要的字段如{ maxWidth: 300 }、{ maxWidth: 300, minHeight: 100 }。实战从测量到渲染的完整示例仓库页面 src/pages/component/text/text-layout.uvue 是 UniTextElement 最完整的官方示例覆盖了无约束、约束多行、约束单行、嵌套富文本四种场景。下面是其核心逻辑已按主题拆解。场景一无约束宽高 全样式不传任何约束测量出文本自然大小后回写到元素再应用布局const element uni.getElementById(text) as UniTextElement; const layout new UniTextLayout(); layout.setText(HBuilderX轻巧、极速极客编辑器uni-app x终极跨平台方案uts大一统语言); layout.setColor(red); layout.setFontFamily(AlimamaDaoLiTiTTF); layout.setFontSize(30px); layout.setFontStyle(italic); layout.setFontWeight(bold); layout.setLineHeight(3); layout.setTextShadow(2px 4px rgba(202,207,17,0.5)); layout.setTextDecorationLine(underline); const measureSize layout.measure({} as UniLayoutConstraintSize); element.style.setProperty(width, measureSize.width); element.style.setProperty(height, measureSize.height); element.setTextLayout(layout); const size element.getContentSize(); info.value width: size.width px height: size.height px;注意这里元素初始是空的text idtext classtext/text模板里没有任何内容与样式约束完全由代码驱动文本的渲染。场景二约束宽高 多行居中给定maxWidth: 300、minHeight: 100让文本在 300px 宽度内自动换行并保证内容高度至少 100pxconst layout new UniTextLayout(); layout.setText(HBuilderX轻巧、极速极客编辑器uni-app x终极跨平台方案uts大一统语言); layout.setColor(red); layout.setLineHeight(3); layout.setTextAlign(center); const measureSize layout.measure({ maxWidth: 300, minHeight: 100 } as UniLayoutConstraintSize); element.style.setProperty(width, measureSize.width); element.style.setProperty(height, measureSize.height); element.setTextLayout(layout);场景三约束宽高 单行省略用maxWidth: 300setWhiteSpace(nowrap)setTextOverflow(ellipsis)实现单行超长文本显示省略号这是列表标题、标签类 UI 的常见需求const layout new UniTextLayout(); layout.setText(HBuilderX轻巧、极速极客编辑器uni-app x终极跨平台方案uts大一统语言); layout.setColor(red); layout.setLineHeight(30px); layout.setTextOverflow(ellipsis); layout.setWhiteSpace(nowrap); const measureSize layout.measure({ maxWidth: 300 } as UniLayoutConstraintSize); element.style.setProperty(width, measureSize.width); element.style.setProperty(height, measureSize.height); element.setTextLayout(layout);场景四嵌套子文本实现富文本通过append()在父布局下挂多个子布局实现同一 text 元素内混排不同内容与样式——例如父段红色 25px追加子段蓝色 20pxconst layout new UniTextLayout(); layout.setText(HBuilderX轻巧、极速极客编辑器uts大一统语言); layout.setColor(red); layout.setFontSize(25px); const child new UniTextLayout(); child.setText(uni-app x终极跨平台方案); layout.append(child); const child2 new UniTextLayout(); child2.setText(uts大一统语言); child2.setColor(blue); child2.setFontSize(20px); layout.append(child2); const measureSize layout.measure({ maxWidth: 300 } as UniLayoutConstraintSize); element.style.setProperty(width, measureSize.width); element.style.setProperty(height, measureSize.height); element.setTextLayout(layout);触发时机与测试验证示例在onLoad中加载自定义字体在onReadyDOM 已就绪中依次执行四种布局保证getElementById能取到元素onLoad(() { uni.loadFontFace({ family: AlimamaDaoLiTiTTF, source: url(/static/font/AlimamaDaoLiTi.otf) }); }); onReady(() { setTextLayout(); setTextLayout2(); setTextLayout3(); setTextLayout4(); });自动化测试 src/pages/component/text/text-layout.test.js 印证了该功能的平台边界测试仅当运行平台为 Android非 iOS、HarmonyOS、Web、小程序、App-WebView时才真正执行页面跳转与整页截图断言其余平台直接跳过——这与文档中setTextLayout/getContentSize等接口仅 Android(VDOM) 4.81的兼容性声明完全一致。与 text 组件属性的关系及平台边界text 组件的元素类型即 UniTextElement见 text 组件文档。模板中通过selectable、user-select、space、decode、max-lines、hover-class等属性声明的行为属于组件层能力而 UniTextElement / UniTextLayout 提供的是运行时用代码直接构建与测量文本布局的能力。兼容性上需要特别注意value属性覆盖面较广Android 4.0、iOS 4.11、HarmonyOS 4.61、Web 4.0 等但setTextLayout、getContentSize及 UniTextLayout 的全部方法目前仅 Android VDOM 渲染模式4.81可用Android Vapor、iOS、HarmonyOS、Web、微信小程序均为 x使用前应先做平台判断如// #ifdef APP-ANDROID条件编译避免在其他平台调用时报错。UniTextLayout 构造对象本身并不代表页面上的元素它只是文本排版的配方必须通过element.setTextLayout(layout)应用到真实元素后才生效。小结UniTextElement 把 text 组件的文本能力从模板声明扩展到了代码编排用value读取文案用UniTextLayout的十余个set*方法配置内容与样式用measure()在约束下预测尺寸用setTextLayout()落地渲染用getContentSize()读取实际内容尺寸再用append()实现多段混排的富文本。这套能力当前聚焦于 Android VDOM4.81平台是 uni-app x 中实现动态文本排版、文本尺寸预计算等高级 UI 需求的重要工具。想深入底层通用 DOM 能力可继续阅读 UniElement 文档 与 CSSStyleDeclaration 文档并在 text-layout.uvue 基础上自行扩展演练。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考