提示helpTip的标准化

Html/apps/_docs/前端/helpTip.md

@@ -0,0 +1,165 @@
+# 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。