Element Plus Text 文本组件完全指南类型、尺寸、截断检测与自定义标签【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 的Textel-text组件用于在页面上渲染文本内容支持语义化类型、尺寸档位、单行/多行截断、原生标签覆盖以及与其他组件的自由混合。本文以 docs/en-US/component/text.md 文档为骨架结合 text.vue、text.ts、text.scss 与 text.test.tsx 等仓库源码完整讲解每个属性Attributes、插槽Slots与暴露Exposes的使用方式及其底层实现原理。读完后你将能够熟练使用el-text的 5 种语义类型与 3 档尺寸基于truncated/line-clamp实现单行与多行省略并借助isTruncated只在文本真正被截断时展示 Tooltip通过tag将文本渲染为任意原生 HTML 标签以兼顾语义化与无障碍。组件定位与整体结构Text是 Element Plus 中最轻量的基础组件之一文档中的定位非常直接“Used for text.”用于渲染文本。它没有复杂的交互逻辑核心能力集中在三点通过type/size快速套用主题色与字号通过truncated/line-clamp提供单行与多行省略号并自动检测截断状态通过tag动态渲染成任意原生元素便于编写符合语义的 HTML。从源码结构看组件源码非常精简src/text.ts集中定义全部 props 及其类型、默认值src/text.vue组件模板与截断检测逻辑index.ts通过withInstall注册为可全局使用的ElTextstyle/index.ts引入对应的 theme-chalk/src/text.scss 样式。其中 text.ts 中的textProps与TextPropsPublic均已标记为deprecated Removed after 3.0.0建议使用新的TextProps类型定义源码内也已改为withDefaults(definePropsTextProps(), ...)的写法。基础用法用type定义文本类型type属性用于定义文本的语义类型可选值为primary | success | warning | danger | info不传则使用默认正文色。官方示例 basic.vue 展示了全部类型template el-text classmx-1Default/el-text el-text classmx-1 typeprimaryPrimary/el-text el-text classmx-1 typesuccessSuccess/el-text el-text classmx-1 typeinfoInfo/el-text el-text classmx-1 typewarningWarning/el-text el-text classmx-1 typedangerDanger/el-text /template源码级实现在 text.ts 中type被定义为带白名单的字符串校验type: { type: String, values: [primary, success, info, warning, danger, ], default: , },样式层在 text.scss 中通过遍历$types将全局色板映射为文本色each $type in $types { .#{bem(text, , $type)} { include css-var-from-global((text, color), (color, $type)); } }生成的类名规则为el-text--{type}例如typesuccess会得到el-text--success。这一点在 text.test.tsx 的type测试用例中得到验证test(type, () { const wrapper mount(() Text typesuccess /) expect(wrapper.classes()).toContain(el-text--success) })尺寸控制size属性与表单尺寸继承size用于设置文本字号可选large | default | small默认default。官方示例 sizes.vue 用法如下template el-text classmx-1 sizelargeLarge/el-text el-text classmx-1Default/el-text el-text classmx-1 sizesmallSmall/el-text /template源码级实现text.ts 中size的合法值直接复用了常量componentSizessize: { type: String, values: componentSizes, default: , },需要注意的是组件内部并不是直接使用props.size而是调用useFormSize()来自element-plus/components/form获取最终尺寸const textSize useFormSize()这意味着当el-text位于设置了size的el-form/el-form-item中时会自动继承表单的尺寸上下文显式传入的props.size优先级最高。类名生成逻辑为ns.m(textSize.value)对应el-text--large/el-text--small等类。样式层在 text.scss 中为每种尺寸定义了对应的字号变量each $size in (large, default, small) { include m($size) { include set-css-var-value( (text, font-size), map.get($text-font-size, $size) ); } }测试用例同样验证了尺寸类名test(size, () { const wrapper mount(() Text sizelarge /) expect(wrapper.classes()).toContain(el-text--large) })截断与省略truncated单行省略truncated布尔值默认false开启单行省略当文本超出容器宽度viewport 或max-width时以省略号...结尾。官方示例 truncated.vue 展示了两种触发场景——自身设置固定宽度以及被父容器挤压template el-text classw-150px mb-2 truncated Self element set width 100px /el-text el-row classw-150px mb-2 el-text truncatedSqueezed by parent element/el-text /el-row ... /template底层样式text.scss 中is-truncated修饰类实现了标准的单行省略三件套include when(truncated) { display: inline-block; max-width: 100%; text-overflow: ellipsis; white-space: nowrap; overflow: hidden; }模板中通过ns.is(truncated, props.truncated)输出is-truncated类见 text.vue。多行截断line-clamp属性line-clamp字符串或数字^(2.4.0) 起支持用于渲染多行省略指定最多显示的行数。示例el-text line-clamp2 The -webkit-line-clamp CSS propertybr / allows limiting of the contents ofbr / a block to the specified number of lines. /el-text底层样式当lineClamp传入且不为undefined时模板输出is-line-clamp类对应样式基于 WebKit 的-webkit-line-clamp实现多行截断include when(line-clamp) { display: -webkit-inline-box; -webkit-box-orient: vertical; overflow: hidden; }同时模板通过行内样式注入行数:style{ -webkit-line-clamp: lineClamp }line-clamp的取值由 text.ts 声明为type: [String, Number]因此既可写line-clamp2也可写:line-clamp2。测试用例也确认了line-clamp2会生成is-line-clamp类test(line-clamp, () { const wrapper mount(() Text line-clamp2 /) expect(wrapper.classes()).toContain(is-line-clamp) })提示-webkit-line-clamp是 WebKit 系浏览器的特性但现代主流浏览器Chrome / Edge / Firefox / Safari均已支持实际项目中可直接使用。截断状态检测isTruncated与按需 Tooltip从 ^(2.14.6) 版本开始组件通过defineExpose暴露了isTruncated类型Refboolean用于指示文本当前是否处于被截断状态。文档给出的典型场景是只在真正发生截断时才显示 Tooltip官方示例 truncated.vueel-tooltip contentShow tooltip only when the text is truncated :disabled!textRef?.isTruncated el-text reftextRef classw-150px truncated title Show tooltip only when the text is truncated /el-text /el-tooltipimport { ref } from vue const textRef ref()当文本被完整展示未截断时isTruncated为falsedisabled让 Tooltip 不出现一旦内容溢出被截断isTruncated变为trueTooltip 随即生效。检测机制与 title 自动回填text.vue 中的检测逻辑非常巧妙单行truncated模式比较offsetWidth与scrollWidth当scrollWidth offsetWidth判定为截断多行line-clamp模式比较offsetHeight与scrollHeight当内容实际高度超出容器高度判定为截断判定通过rAF下一帧执行并通过cAF做防抖合并通过watch监听width/height/truncated/lineClamp变化与useMutationObserver监听class、style、childList、characterData变化在尺寸或内容变动后重新检测截断状态除了暴露给外部还会自动回填到原生title属性上方便鼠标悬停查看完整内容:title$attrs.title ?? (isTruncated ? textRef?.textContent : undefined)即如果用户没有手动传title且文本被截断组件会自动把完整文本作为title手动传入的title优先级更高。text.test.tsx 中用ResizeObservermock 完整覆盖了这条链路truncated title updates after resize、truncated title updates after prop changes两个用例验证了“宽度不足 → 截断 →title与isTruncated同步更新 → 恢复宽度后解除”的完整行为offsetWidthSpy.mockReturnValue(50) scrollWidthSpy.mockReturnValue(100) resizeObserverCallback?.(...) await rAF() expect(wrapper.attributes(title)).toBe(AXIOM) expect(wrapper.vm.isTruncated).toBe(true)覆盖渲染标签tag属性tag字符串默认span用于覆盖渲染的 HTML 元素。由于el-text内部使用 Vue 的动态组件component :istag因此可以渲染为任意原生标签官方示例 override.vue 展示了丰富的语义化组合template el-space directionvertical el-textspan/el-text el-text tagpThis is a paragraph./el-text el-text tagbBold/el-text el-text tagiItalic/el-text el-text This is el-text tagsub sizesmallsubscript/el-text /el-text el-text This is el-text tagsup sizesmallsuperscript/el-text /el-text el-text taginsInserted/el-text el-text tagdelDeleted/el-text el-text tagmarkMarked/el-text /el-space /template其中sub/sup还配合了sizesmall来缩小字号实现真正的上标/下标效果。测试用例验证了标签确实被替换为原生元素test(tag, () { const wrapper mount(() Text tagdel /) expect(wrapper.vm.$el.tagName).toEqual(DEL) })与原生文本元素的边界从 text.scss 看组件还设置了align-self: center、margin: 0、padding: 0、font-size、color以及overflow-wrap: break-word并对内部的el-icon做了vertical-align: -2px的微调保证与行内元素混排时的视觉对齐。因此在p、b、i等块级/行内语义标签上切换视觉样式依然统一。混合使用Text 与图标、其他组件的组合Text的default插槽接受任意内容可以轻松嵌入图标、评分组件、按钮等官方示例 mixed.vuetemplate el-space directionvertical el-text el-icon ElementPlus / /el-icon Element-Plus /el-text el-row el-textRate/el-text el-rate classml-1 / /el-row el-text This is text mixed icon el-icon Bell / /el-icon and component el-buttonButton/el-button /el-text /el-space /template script langts setup import { Bell, ElementPlus } from element-plus/icons-vue /script从实现上看模板仅有slot /不限制插槽内容类型text.test.tsx 的default slot用例确认插槽内容会原样渲染。此外type与size产生的el-text系列类名天然复用 Element Plus 的设计令牌design token因此在el-space、el-row等布局组件中混排时无需额外样式即可保持对齐。API 完整参考以下为文档 text.md 中的完整 API 表格并结合源码补充了默认值与取值说明。Attributes名称说明类型默认值type文本类型^[enum]primary \| success \| warning \| danger \| info—size文本尺寸^[enum]large \| default \| smalldefaulttruncated渲染省略号单行^[boolean]falseline-clamp ^(2.4.0)最大行数多行省略^[string] / ^[number]—tag自定义元素标签^[string]span补充说明依据 text.ts 源码type校验白名单中还包含空字符串等价于默认正文样式size复用componentSizes常量并与表单上下文联动useFormSizelineClamp通过isUndefined(props.lineClamp)判断是否启用多行截断传0不会触发tag默认span通过动态组件渲染。Slots名称说明default默认内容Exposes名称说明类型isTruncated ^(2.14.6)文本是否被截断^[object]Refboolean小结el-text是一个“小而精”的组件对外只需掌握type、size、truncated、line-clamp、tag五个属性与isTruncated一个暴露状态即可覆盖从语义化文本着色、尺寸档位、单行/多行省略到“按需 Tooltip”的完整业务场景。若想深入探究推荐按以下路径阅读仓库源码docs/examples/text/五个官方示例basic / sizes / truncated / override / mixed是上手最快的参照packages/components/text/src/text.vue截断检测、title 回填与useFormSize尺寸继承的实现核心packages/components/text/src/text.tsprops 类型定义与校验白名单packages/theme-chalk/src/text.scssis-truncated/is-line-clamp的样式实现与主题变量映射packages/components/text/tests/text.test.tsx对类型、尺寸、截断检测、标签覆盖与插槽的完整测试用例可作为行为契约参考。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考