npm package: @linker-design-plus/autotooltip
Description: Auto tooltip component with ellipsis functionality
Author: Linker Design Team
Latest version: 1.0.9

# @linker-design-plus/autotooltip

一个 Vue 3 自动省略组件，支持文本超出长度显示省略号，可配置保留开头或末尾的字符数，并提供优雅的 tooltip 提示效果。

## 功能特性

- 🎯 **智能省略**：自动检测文本超出长度，显示省略号
- 🔤 **灵活配置**：支持保留开头或末尾的指定字符数
- 💬 **后缀支持**：可添加不被省略的后缀文本
- 💡 **优雅提示**：带有平滑动画效果的 tooltip 提示
- 📱 **响应式**：随容器宽度变化自动调整显示内容
- 🎨 **轻量级**：无外部依赖，仅依赖 Vue 3

## 安装

```bash
# 推荐使用 pnpm
pnpm add @linker-design-plus/autotooltip

# 或者使用其他包管理工具
npm install @linker-design-plus/autotooltip
yarn add @linker-design-plus/autotooltip
```

## 使用方法

### 引入样式

在使用组件之前，请确保引入了组件的样式文件：

```js
// 在项目入口文件中引入样式
import '@linker-design-plus/autotooltip/dist/ellipsis-tooltip.css';
```

### 基础用法

```vue
<template>
  <EllipsisTooltip
    content="这是一段很长的文本，当它超出容器宽度时会自动截断并显示省略号，鼠标悬停时会显示完整内容。"
  />
</template>

<script setup>
import { EllipsisTooltip } from '@linker-design-plus/autotooltip';
</script>
```

### 保留末尾字符

```vue
<template>
  <EllipsisTooltip
    content="这是一段很长的文本，当它超出容器宽度时会自动截断并显示省略号，但会保留末尾的4个字符。"
    :reserve-count="4"
    reserve-position="end"
  />
</template>

<script setup>
import { EllipsisTooltip } from '@linker-design-plus/autotooltip';
</script>
```

### 保留开头字符

```vue
<template>
  <EllipsisTooltip
    content="这是一段很长的文本，当它超出容器宽度时会自动截断并显示省略号，但会保留开头的4个字符。"
    :reserve-count="4"
    reserve-position="start"
  />
</template>

<script setup>
import { EllipsisTooltip } from '@linker-design-plus/autotooltip';
</script>
```

### 添加后缀

```vue
<template>
  <EllipsisTooltip content="这是一段带有后缀的文本" suffix="(推荐)" />
</template>

<script setup>
import { EllipsisTooltip } from '@linker-design-plus/autotooltip';
</script>
```

### 不同位置的提示框

```vue
<template>
  <EllipsisTooltip content="顶部提示框" tooltip-position="top" />
  <EllipsisTooltip content="底部提示框" tooltip-position="bottom" />
  <EllipsisTooltip content="左侧提示框" tooltip-position="left" />
  <EllipsisTooltip content="右侧提示框" tooltip-position="right" />
</template>

<script setup>
import { EllipsisTooltip } from '@linker-design-plus/autotooltip';
</script>
```

## API

### Props

| 参数              | 说明                                           | 类型   | 默认值 |
| ----------------- | ---------------------------------------------- | ------ | ------ |
| content           | 显示的文本内容                                 | string | -      |
| reserveCount      | 保留字符数                                     | number | 0      |
| reserve-count     | 保留字符数（短横线命名）                       | number | 0      |
| reservePosition   | 保留位置，'start' 或 'end'                     | string | 'end'  |
| reserve-position  | 保留位置（短横线命名）                         | string | 'end'  |
| suffix            | 后缀内容                                       | string | ''     |
| tooltipMaxWidth   | 提示框的最大宽度                               | number | 300    |
| tooltip-max-width | 提示框的最大宽度（短横线命名）                 | number | 300    |
| tooltipPosition   | 提示框位置，'top'、'bottom'、'left' 或 'right' | string | 'top'  |
| tooltip-position  | 提示框位置（短横线命名）                       | string | 'top'  |
| className         | 自定义类名                                     | string | ''     |
| class-name        | 自定义类名（短横线命名）                       | string | ''     |
| style             | 自定义样式                                     | object | {}     |

### 保留字符功能说明

组件支持两种保留字符的方式：

1. **保留末尾字符（默认）**：

   - 设置 `reserve-position="end"`
   - 当文本超出容器宽度时，会显示为 "前面部分...末尾的 N 个字符"
   - 适用于需要展示文件扩展名、ID 末尾等场景

2. **保留开头字符**：
   - 设置 `reserve-position="start"`
   - 当文本超出容器宽度时，会显示为 "开头的 N 个字符..."
   - 适用于需要展示名称前缀、类型标识等场景

### 后缀功能说明

`suffix` 参数允许在文本末尾添加不会被省略的后缀内容，常用场景包括：

- **状态标识**：`(推荐)`、`(新)`、`(热门)` 等
- **类型标识**：`[图片]`、`[视频]`、`[文档]` 等
- **附加信息**：版本号、计数等

后缀内容会始终显示在文本末尾，不会被省略。

## 动画效果

组件内置了平滑的过渡动画效果：

- 提示框显示/隐藏时有淡入淡出效果
- 根据提示框位置有不同的滑入/滑出动画
- 动画持续时间为 0.3 秒，提供流畅的用户体验

## 样式自定义

组件使用以下 CSS 类名，您可以通过覆盖样式来自定义外观：

```css
/* 容器样式 */
.ellipsis-tooltip-container {
  /* 自定义样式 */
}

/* 提示框样式 */
.ellipsis-tooltip {
  /* 自定义提示框样式 */
}

/* 提示框箭头样式 */
.ellipsis-tooltip-arrow {
  /* 自定义箭头样式 */
}
```

## 响应式行为

组件会自动监听容器宽度变化，并根据可用空间动态调整显示内容：

- 当容器变窄时，更多文本会被省略
- 当容器变宽时，更多文本会被显示
- 无需手动处理窗口大小变化事件

## 注意事项

- 组件需要 Vue 3.1.0 或更高版本
- 支持所有原生 HTML 属性
- 使用 CSS Flexbox 布局实现，确保兼容现代浏览器

## 在项目中使用

### Vite 项目

在 Vite 项目中使用时，需要确保 JSX 转换已启用。在 `vite.config.js` 或 `vite.config.ts` 中添加：

```js
import vue from '@vitejs/plugin-vue';
import vueJsx from '@vitejs/plugin-vue-jsx'; // 确保已安装此插件

export default {
  plugins: [
    vue(),
    vueJsx(), // 添加 JSX 支持
  ],
};
```

### Webpack 项目

在 Webpack 项目中，确保已配置 Vue JSX 转换：

```js
module.exports = {
  // ...其他配置
  module: {
    rules: [
      {
        test: /\.(jsx|tsx)$/,
        use: 'babel-loader',
      },
      // ...其他规则
    ],
  },
};
```

同时确保 `.babelrc` 或 `babel.config.js` 中包含：

```json
{
  "plugins": ["@vue/babel-plugin-jsx"]
}
```

## 许可证

MIT