CakeCN/hsa

Fork 0

Files

CakeCN ac74c28f64 提示helpTip的标准化

2025-12-12 16:58:27 +08:00

3.9 KiB

Raw Blame History

HelpTip 组件文档

功能介绍

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

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

文件结构

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

使用方法

1. 引入文件

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

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

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

2. 基本用法

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

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

3. 支持换行的提示信息

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

4. 与问号图标配合使用

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

// 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. 进度条提示

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

2. 表单字段提示

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

3. 工具栏图标提示

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

注意事项

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

浏览器兼容性

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

代码优化建议

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

更新日志

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

贡献指南

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

3.9 KiB Raw Blame History Unescape Escape