TextEllipsis 文本省略 - Vant 4

TextEllipsis 文本省略

介绍

📝 智能文本省略组件 - 长文本的贴心管家！就像一个聪明的编辑器，能够自动处理超长文本，用优雅的省略号代替冗长内容，还支持展开/收起功能，让用户按需查看完整内容。让你的界面既简洁又实用！ ✨

💡 版本要求：请升级 vant 到 >= 4.1.0 版本来使用该组件。

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { TextEllipsis } from'vant'; const app = createApp(); app.use(TextEllipsis);

代码演示

基础用法

📏 单行省略展示 - 默认展示 1 行文本，超过部分自动用省略号代替，就像给长句子戴上了"面具"，既保持美观又节省空间！

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis :content="text" />
  </div>
</template>

<script>
export default {
  setup() {
    const text = '慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

展开/收起

🔄 智能展开收起 - 超过行数限制时，自动显示展开按钮，就像一个可伸缩的手风琴！用户可以自由控制查看完整内容还是保持简洁显示。

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis 
      :content="text" 
      expand-text="展开" 
      collapse-text="收起"
    />
  </div>
</template>

<script>
export default {
  setup() {
    const text = '似水流年是一个人所有的一切，只有这个东西，才真正归你所有。其余的一切，都是片刻的欢娱和不幸，转眼间就已跑到那似水流年里去了。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

自定义展示行数

📊 灵活行数控制 - 通过设置 rows 属性自由控制展示行数，就像调节显示器的分辨率一样！可以根据内容重要性和界面空间来决定显示多少行。

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis 
      :content="text" 
      :rows="3"
      expand-text="展开" 
      collapse-text="收起"
    />
  </div>
</template>

<script>
export default {
  setup() {
    const text = '那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

自定义省略位置

📍 精准省略定位 - 通过设置 position 属性控制省略位置，就像选择"剪切"的位置一样灵活！支持头部、中部、尾部三种省略方式。

头部省略

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis 
      :content="text" 
      :rows="2"
      position="start"
      expand-text="展开" 
      collapse-text="收起"
    />
  </div>
</template>

<script>
export default {
  setup() {
    const text = '那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

中部省略

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis 
      :content="text" 
      :rows="2"
      position="middle"
      expand-text="展开" 
      collapse-text="收起"
    />
  </div>
</template>

<script>
export default {
  setup() {
    const text = '那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

自定义操作内容

🎨 个性化操作按钮 - 通过 action 插槽自定义操作内容，就像为按钮换上个性化的外衣！可以添加图标、改变样式，让操作更加生动有趣。

<template>
  <div class="demo-text-ellipsis">
    <van-text-ellipsis :content="text" :rows="2">
      <template #action="{ expanded, toggle }">
        <van-button 
          type="primary" 
          size="mini" 
          @click="toggle"
          style="margin-left: 8px;"
        >
          {{ expanded ? '收起 ⬆️' : '展开 ⬇️' }}
        </van-button>
      </template>
    </van-text-ellipsis>
  </div>
</template>

<script>
export default {
  setup() {
    const text = '那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。';
    
    return {
      text,
    };
  },
};
</script>

<style>
.demo-text-ellipsis {
  padding: 16px;
}
</style>

API

Props

参数	说明	类型	默认值
rows	📏 展示的行数 - 控制文本显示的最大行数	*number	string*
content	📝 需要展示的文本内容 - 支持任意长度的文本	string	-
expand-text	🔍 展开操作的文案 - 自定义"展开"按钮的显示文字	string	-
collapse-text	📁 收起操作的文案 - 自定义"收起"按钮的显示文字	string	-
dots v4.2.0	✂️ 省略号的文本内容 - 自定义省略符号样式	string	'...'
position v4.6.2	📍 省略位置 - 可选值为 start(头部) middle(中部) end(尾部)	string	'end'

Events

事件名	说明	回调参数
click-action	🖱️ 点击展开/收起时触发 - 用户交互时的回调事件	event: MouseEvent

TextEllipsis 方法

通过 ref 可以获取到 TextEllipsis 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
toggle	🔄 切换文本的展开状态 - 编程式控制展开/收起，传 true 为展开，false 为收起，不传参为切换	expanded?: boolean	-

Slots

名称	说明	参数
action v4.8.3	🎨 自定义操作内容 - 完全自定义展开/收起按钮的样式和行为	{ expanded: boolean, toggle: Function }

类型定义

🔧 TypeScript 支持 - 组件导出以下类型定义，为开发提供完整的类型提示和检查：

importtype { TextEllipsisProps, TextEllipsisInstance, TextEllipsisThemeVars, } from'vant';

TextEllipsisInstance 是组件实例的类型，用法如下：

import { ref } from'vue'; importtype { TextEllipsisInstance } from'vant'; const textEllipsisRef = ref<TextEllipsisInstance>(); textEllipsisRef.value?.toggle();

主题定制

样式变量

🎨 个性化样式定制 - 组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-text-ellipsis-action-color	var(--van-blue)	🔗 操作按钮颜色 - 控制展开/收起按钮的文字颜色
--van-text-ellipsis-line-height	1.6	📏 文本行高 - 控制文本内容的行间距

相关文档

📱 展示组件

• Cell 单元格 - 📋 列表项展示，常与文本省略搭配使用
• List 列表 - 📜 长列表展示，文本省略优化阅读体验
• Card 卡片 - 🃏 卡片容器，文本省略保持布局整洁

🎯 反馈组件

• Loading 加载 - ⏳ 加载状态提示，文本加载时的占位
• Skeleton 骨架屏 - 💀 内容加载占位，文本区域预览

🔧 工具组件

• ConfigProvider 全局配置 - ⚙️ 全局配置提供者，统一主题定制