# HelpTip 组件文档

## 功能介绍

HelpTip 是一个通用的提示框组件，用于在鼠标悬停时显示提示信息。它具有以下特点：

- 提示框跟随鼠标移动
- 支持多行文本
- 自动防出界
- 平滑的显示/隐藏动画
- 支持在不同页面复用
- 代码标准化，易于维护

## 文件结构

```
/static/
├── css/
│   └── helpTip.css    # 样式文件
└── js/
    └── helpTip.js     # 核心功能文件
```

## 使用方法

### 1. 引入文件

在需要使用 HelpTip 的 HTML 页面中引入以下文件：

```html
<!-- 样式文件 -->
<link rel="stylesheet" href="/static/css/helpTip.css">

<!-- 功能文件 -->
<script src="/static/js/helpTip.js"></script>
```

### 2. 基本用法

```javascript
// 获取需要绑定提示框的元素
const element = document.getElementById('target-element');

// 绑定提示框
attachImmediateTooltip(element, '这是一条提示信息');
```

### 3. 支持换行的提示信息

```javascript
attachImmediateTooltip(element, `这是一条\n多行提示信息\n\n支持换行符`);
```

### 4. 与问号图标配合使用

```html
<!-- HTML -->
<span>这是一个元素<span class="help-icon">?</span></span>
```

```javascript
// JavaScript
const helpIcon = document.querySelector('.help-icon');
attachImmediateTooltip(helpIcon, '这是一条详细的提示信息');
```

## API 说明

### attachImmediateTooltip(anchorEl, text)

绑定提示框到指定元素。

#### 参数

- `anchorEl` (HTMLElement): 触发提示框的元素
- `text` (string): 提示框显示的文本内容，支持换行符 `\n`

#### 返回值

- `Function`: 清理函数，用于移除事件监听器

## 样式说明

### 问号图标样式

| 类名 | 说明 |
|------|------|
| `.help-icon` | 问号图标基础样式 |
| `.help-icon:hover` | 问号图标悬停样式 |

### 提示框样式

| 类名 | 说明 |
|------|------|
| `.tooltip-portal` | 提示框基础样式 |
| `.tooltip-portal.show` | 提示框显示状态 |
| `.tooltip-portal.fade` | 提示框动画效果 |

## 示例场景

### 1. 进度条提示

```javascript
// 为进度条的每个阶段绑定提示框
for (let i = 0; i < progressItems.length; i++) {
    const item = progressItems[i];
    attachImmediateTooltip(item, `阶段 ${i + 1}: ${item.title}`);
}
```

### 2. 表单字段提示

```javascript
// 为表单字段绑定提示框
const formFields = document.querySelectorAll('.form-field');
formFields.forEach(field => {
    const tip = field.getAttribute('data-tip');
    if (tip) {
        attachImmediateTooltip(field, tip);
    }
});
```

### 3. 工具栏图标提示

```javascript
// 为工具栏图标绑定提示框
const toolbarIcons = document.querySelectorAll('.toolbar-icon');
toolbarIcons.forEach(icon => {
    const title = icon.getAttribute('title');
    if (title) {
        attachImmediateTooltip(icon, title);
    }
});
```

## 注意事项

1. 确保在 DOM 加载完成后再调用 `attachImmediateTooltip` 函数
2. 如果元素是动态生成的，需要在元素生成后再绑定提示框
3. 提示框会自动添加到 `document.body` 中，不会被父元素的 `overflow` 属性裁切
4. 提示框的 `z-index` 为 999999，确保它能覆盖所有元素
5. 提示框默认支持多行文本，使用 `white-space: pre-wrap` 样式

## 浏览器兼容性

- Chrome/Edge (最新版)
- Firefox (最新版)
- Safari (最新版)

## 代码优化建议

1. 对于大量元素需要绑定提示框的情况，建议使用事件委托
2. 如果页面中不再需要使用提示框，可以调用返回的清理函数移除事件监听器
3. 提示文本应简洁明了，避免过长

## 更新日志

- v1.0.0: 初始版本，实现了基本的提示框功能
- v1.0.1: 优化了样式，增加了动画效果
- v1.0.2: 支持多行文本，自动防出界

## 贡献指南

如果您发现问题或有改进建议，欢迎提出 Issue 或 Pull Request。