Vant 4 TextEllipsis 文本省略组件完全指南多行省略、展开/收起与自定义省略位置【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读本文围绕 Vant 4 移动端组件库中的 TextEllipsis文本省略组件展开系统讲解如何对长文本进行多行省略并支持展开/收起交互。你将掌握该组件的引入方式、全部 Props / Events / 插槽 / 实例方法用法、底层基于二分逼近 克隆容器测量的省略算法原理以及通过 CSS 变量进行主题定制的方法可直接在真实 Vue 3 项目中落地使用。组件完整源码位于 packages/vant/src/text-ellipsis/TextEllipsis.tsx示例与测试分别位于 demo/index.vue 与 test/index.spec.tsx。组件介绍与引入TextEllipsis 用于对超出指定行数的长文本进行省略展示并支持点击展开/收起切换完整内容。该组件自vant 4.1.0版本起提供。通过以下方式全局注册组件更多注册方式参见 组件注册文档import { createApp } from vue; import { TextEllipsis } from vant; const app createApp(); app.use(TextEllipsis);注册后即可在模板中使用van-text-ellipsis标签。从 index.ts 可以看到组件通过withInstall包装后导出并同时声明了VanTextEllipsis全局组件类型方便 TypeScript 用户获得完整的模板类型提示。代码演示基础用法默认展示1行超过1行时在末尾显示省略号van-text-ellipsis :contenttext /export default { setup() { const text 慢慢来不要急生活给你出了难题可也终有一天会给出答案。; return { text }; }, };当文本本身不超过设定行数时组件会直接展示完整文本且不渲染操作按钮——这一点由源码中的高度判断保证见下文省略状态判定。展开/收起文本超过行数后通过设置expand-text与collapse-text展示可点击的展开/收起按钮van-text-ellipsis :contenttext expand-text展开 collapse-text收起 /export default { setup() { const text 似水流年是一个人所有的一切只有这个东西才真正归你所有。其余的一切都是片刻的欢娱和不幸转眼间就已跑到那似水流年里去了。; return { text }; }, };自定义展示行数通过rows属性限制展示行数例如展示 3 行van-text-ellipsis rows3 :contenttext expand-text展开 collapse-text收起 /export default { setup() { const text 那一天我二十一岁在我一生的黄金时代。我有好多奢望。我想爱想吃还想在一瞬间变成天上半明半暗的云。后来我才知道生活就是个缓慢受锤的过程人一天天老下去奢望也一天天消失最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去什么也锤不了我。; return { text }; }, };rows的类型为number | string默认值为1。从 TextEllipsis.tsx 的 props 定义可以看到rows使用makeNumericProp(1)声明——即接受数字或数字字符串如3该工具函数定义于 utils/props.ts。自定义省略位置通过position属性控制省略号的位置可选值为start头部省略与middle中部省略默认省略在末尾end。头部省略——保留文本尾部内容省略号出现在最前面van-text-ellipsis rows1 :contenttext expand-text展开 collapse-text收起 positionstart /中部省略——保留文本首尾两端内容省略号出现在中间van-text-ellipsis rows2 :contenttext expand-text展开 collapse-text收起 positionmiddle /以上示例的text变量同前王小波《黄金时代》选段。position属性自v4.6.2起提供。实现原理position不同底层计算分支也不同。源码calcEllipsisText中end与start共用calcEllipse二分函数根据 position 决定从头部还是尾部截取而middle走独立的middleTail函数同时从左右两端向中间二分逼近直至截断后的文本高度满足行数要求见 TextEllipsis.tsx。自定义操作内容使用action插槽完全自定义展开/收起操作区域。插槽参数expanded为布尔值表示当前是否处于展开状态van-text-ellipsis :contenttext template #action{ expanded }{{ expanded ? 收起 : 展开 }}/template /van-text-ellipsisexport default { setup() { const text 慢慢来不要急生活给你出了难题可也终有一天会给出答案。; return { text }; }, };action插槽自v4.8.3起提供。源码 renderAction 在存在该插槽时优先渲染插槽内容否则渲染expand-text/collapse-text文案且使用插槽时组件会在onMounted后的nextTick中重新计算省略文本以保证把操作元素的实际尺寸纳入高度预算见 TextEllipsis.tsx。APIProps参数说明类型默认值rows展示的行数number | string1content需要展示的文本string-expand-text展开操作的文案string-collapse-text收起操作的文案string-dotsv4.2.0省略号的文本内容string...positionv4.6.2省略位置可选值为start、middlestringend其中dots默认值为...可通过设置dots…等自定义省略号样式如使用中文省略号content、expand-text、collapse-text均由makeStringProp声明默认值为空字符串见 TextEllipsis.tsx。Events事件名说明回调参数click-action点击展开/收起时触发event: MouseEvent从源码 onClickAction 可以看到点击操作区会先调用toggle()切换状态再向外派发clickAction事件kebab-case 写为click-action。TextEllipsis 方法通过 ref 获取组件实例并调用实例方法详见 组件实例方法方法名说明参数返回值toggle切换文本的展开状态传true为展开false为收起不传参为切换expanded?: boolean-实例方法通过useExpose({ toggle })暴露见 TextEllipsis.tsxtoggle实现为expanded.value isExpanded其中isExpanded默认取当前状态的取反值因此不传参时即为状态切换TextEllipsis.tsx。Slots名称说明参数actionv4.8.3自定义操作{ expanded: boolean }类型定义组件导出以下类型定义import type { TextEllipsisProps, TextEllipsisInstance, TextEllipsisThemeVars, } from vant;TextEllipsisInstance是组件实例的类型配合 ref 使用时写法如下import { ref } from vue; import type { TextEllipsisInstance } from vant; const textEllipsisRef refTextEllipsisInstance(); textEllipsisRef.value?.toggle();这些类型在 index.ts 中统一导出TextEllipsisProps来自组件本身TextEllipsisInstance与TextEllipsisThemeVars定义于 types.ts其中实例类型由ComponentPublicInstanceTextEllipsisProps, TextEllipsisExpose组合而来TextEllipsisExpose描述了toggle(expanded?: boolean): void的方法签名。底层原理克隆容器 二分逼近的省略计算TextEllipsis 的核心并不依赖 CSS-webkit-line-clamp而是采用克隆容器测量 二分逼近的 JS 方案这使得它天然支持展开/收起、头部省略与中部省略等 CSS 难以实现的能力。整体流程如下克隆容器cloneContainer读取根元素getComputedStyle的全部计算样式逐一复制到一个position: fixed; top: -9999px; z-index: -9999的离屏div中并把高度相关属性重置为auto随后把完整文本innerText写入其中并挂到document.body见 TextEllipsis.tsx。计算最大高度calcEllipsised读取克隆容器的line-height与上下padding按公式maxHeight ceil((rows 0.5) * lineHeight paddingTop paddingBottom)换算出行数对应的像素高度TextEllipsis.tsx。省略状态判定若maxHeight container.offsetHeight说明文本确实超行进入省略计算并显示操作按钮hasAction true否则直接展示完整文本、不渲染操作区TextEllipsis.tsx。rows 0.5中的0.5行余量用于容纳操作按钮的半行空间这是展开/收起按钮能与省略文本同处最后一行而不错位的关键。二分逼近截取end位置对[0, content.length]区间二分middle位置则对左右两个区间同步二分每次试探都向克隆容器写入截断文本 省略号 操作区 HTML测量offsetHeight是否超出maxHeight不断收缩区间直至找到恰好放得下的截断点TextEllipsis.tsx。测量完成后克隆容器即被移除不会影响页面布局与性能。响应式重算组件通过watch([windowWidth, () [props.content, props.rows, props.position]], calcEllipsised)监听视口宽度以及content、rows、position的变化并自动重算windowWidth来自 utils/dom.ts 的useWindowSize响应式宽度。此外当组件在KeepAlive中因挂载时机导致首次计算失败时会置位needRecalculate并在onActivated再次触发时重算——这一点有专门的测试用例覆盖对应 issue #12445见 test/index.spec.tsx。测试验证仓库在 test/index.spec.tsx 中为该组件提供了完整的行为测试可作为使用时的行为契约参考操作插槽渲染挂载含action插槽的组件后连续调用实例toggle()快照依次断言收起态与展开态的渲染结果展开/收起生效点击.van-text-ellipsis__action后文本中的...消失index.spec.tsx事件派发点击操作区会触发一次click事件index.spec.tsx未超行场景短文本不出现省略号、不渲染操作按钮index.spec.tsx。主题定制样式变量组件提供以下 CSS 变量用于自定义样式使用方法参考 ConfigProvider 组件名称默认值描述--van-text-ellipsis-action-colorvar(--van-blue)操作按钮的颜色--van-text-ellipsis-line-height1.6文本的行高变量的实际消费点在样式文件 index.less 中.van-text-ellipsis通过line-height: var(--van-text-ellipsis-line-height)控制文本行高操作区.van-text-ellipsis__action通过color: var(--van-text-ellipsis-action-color)控制颜色并按--van-active-opacity呈现按压缩放反馈。由于行高直接影响最大高度 (rows 0.5) × lineHeight的计算结果调整该变量后无需刷新即可让省略判定自动适配。自定义示例:root { --van-text-ellipsis-line-height: 1.8; --van-text-ellipsis-action-color: #1989fa; }使用注意事项组件基于真实 DOM 测量getComputedStyle、offsetHeight因此只在浏览器环境中工作不适用于 SSR 服务端渲染首屏的文本截断计算仓库同样提供了 demo-ssr.spec.ts 对 SSR 场景的渲染做快照校验但省略计算本身依赖客户端挂载后的onMounted钩子rows接受number | string字符串数字如3会被正常解析非法输入会在高度计算中被安全兜底为0省略号默认...如需中文省略号可设置dots…使用action插槽自定义操作区时记得利用插槽参数expanded区分展开/收起两种状态下的文案或样式若文本未超行组件不会渲染操作按钮click-action事件也不会触发。总结TextEllipsis 是 Vant 4 中处理长文本展示的高频组件默认单行省略、支持展开/收起、rows自定义行数、position自定义省略位置end/start/middle并提供action插槽与toggle()实例方法满足定制化交互需求。其克隆容器测量 二分逼近的实现方案兼顾了省略精度与多场景灵活性配合两个 CSS 变量即可完成外观定制。以上 API、源码与测试均可直接在 packages/vant/src/text-ellipsis 目录下继续深入查阅。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考