# BottomTip

**Repository Path**: qt-adventure-works/bottom-tip

## Basic Information

- **Project Name**: BottomTip
- **Description**: 一个轻量级的 Qt Toast 提示框组件，支持多种提示样式、自动消失、鼠标悬停暂停等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BottomTip - Qt Toast 提示框组件

一个轻量级的 Qt Toast 提示框组件，支持多种提示样式、自动消失、鼠标悬停暂停等功能。

## 项目框架

```
BottomTip/
├── bottomTipText/                 # 核心组件模块
│   ├── bottomTipText/             # 资源文件
│   │   ├── alarm.png              # 信息图标
│   │   ├── error.png              # 错误图标
│   │   ├── success.png            # 成功图标
│   │   ├── warning.png            # 警告图标
│   │   └── qty_delete.png         # 关闭按钮图标
│   ├── bottomTipText.h            # 组件头文件
│   ├── bottomTipText.cpp          # 组件实现
│   ├── bottomTipText.pri          # Qt 包含文件
│   └── bottomTipText_rc.qrc       # 资源文件
├── widget.h / widget.cpp          # 示例窗口
├── main.cpp                       # 程序入口
└── BottomTip.pro                  # Qt 项目文件
```

### 技术栈

- **Qt 5.x** - GUI 框架
- **QPropertyAnimation** - 淡入淡出动画
- **QGraphicsOpacityEffect** - 透明度效果

### 核心特性

| 特性 | 说明 |
|------|------|
| 多种样式 | 支持 INFO、SUCCESS、WARN、ERROR 四种样式 |
| 自动消失 | 可设置显示时长，自动淡出消失 |
| 悬停暂停 | 鼠标悬停时暂停计时，移开后继续 |
| 堆叠显示 | 支持多条提示堆叠，自动调整位置 |
| 数量限制 | 可设置最大显示数量，超出自动关闭最早的 |
| 位置对齐 | 支持居中、底部居中两种对齐方式 |

---

## API 调用

### 1. 显示 Toast 提示

```cpp
static bool showToastTip(
    const QString &text,      // 提示文本
    ToastStyle style,         // 提示样式
    QWidget *parent = nullptr, // 父窗口（nullptr 则相对于屏幕）
    int duration = 3000,      // 显示时长（毫秒）
    Alignment ali = CenterBottom  // 对齐方式
);
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `text` | QString | 提示框显示的文本内容 |
| `style` | ToastStyle | 提示样式枚举 |
| `parent` | QWidget* | 父窗口指针，为 nullptr 时相对于屏幕定位 |
| `duration` | int | 显示时长，单位毫秒，默认 3000ms |
| `ali` | Alignment | 对齐方式，默认底部居中 |

### 2. 设置最大显示数量

```cpp
static void setMaxToast(int num);
```

### 3. 枚举类型

**ToastStyle - 提示样式：**

```cpp
typedef enum : quint8 {
    TOAST_INFO = 0,      // 信息（蓝色）
    TOAST_SUCCEED,       // 成功（绿色）
    TOAST_WARN,          // 警告（橙色）
    TOAST_ERROR          // 错误（红色）
} ToastStyle;
```

**Alignment - 对齐方式：**

```cpp
enum Alignment : quint8 {
    Center = 0,          // 居中
    CenterBottom,        // 底部居中
};
```

---

## 使用示例

### 基础用法

```cpp
#include "bottomTipText/bottomTipText.h"

// 显示信息提示
BottomTipText::showToastTip("这是一条信息", BottomTipText::TOAST_INFO);

// 显示成功提示
BottomTipText::showToastTip("操作成功！", BottomTipText::TOAST_SUCCEED);

// 显示警告提示
BottomTipText::showToastTip("请注意！", BottomTipText::TOAST_WARN);

// 显示错误提示
BottomTipText::showToastTip("操作失败！", BottomTipText::TOAST_ERROR);
```

### 完整参数示例

```cpp
// 设置最大显示数量
BottomTipText::setMaxToast(4);

// 相对于屏幕显示，持续 5 秒，底部居中
BottomTipText::showToastTip(
    "文件保存成功",
    BottomTipText::TOAST_SUCCEED,
    nullptr,           // 相对于屏幕
    5000,              // 5秒
    BottomTipText::CenterBottom
);

// 相对于窗口显示，居中位置
BottomTipText::showToastTip(
    "正在处理中...",
    BottomTipText::TOAST_INFO,
    this,              // 相对于当前窗口
    3000,
    BottomTipText::Center
);
```

### 集成到项目

**方式一：使用 .pri 文件**

在项目的 .pro 文件中添加：

```qmake
include(bottomTipText/bottomTipText.pri)
```

**方式二：手动添加**

```qmake
SOURCES += bottomTipText/bottomTipText.cpp
HEADERS += bottomTipText/bottomTipText.h
RESOURCES += bottomTipText/bottomTipText_rc.qrc
```

---

## 效果展示

### 提示样式

| 样式 | 图标 | 背景色 |
|------|------|--------|
| TOAST_INFO | ![alarm](bottomTipText/bottomTipText/alarm.png) | 深蓝色 `rgb(0, 64, 128)` |
| TOAST_SUCCEED | ![success](bottomTipText/bottomTipText/success.png) | 深绿色 `rgb(0, 128, 64)` |
| TOAST_WARN | ![warning](bottomTipText/bottomTipText/warning.png) | 橙色 `rgb(210, 145, 22)` |
| TOAST_ERROR | ![error](bottomTipText/bottomTipText/error.png) | 红色 `rgb(180, 0, 0)` |

### 界面效果

```
┌─────────────────────────────────────────┐
│  ℹ️  这是一条信息提示              ✕  │  ← TOAST_INFO (蓝色)
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  ✓  操作成功完成                   ✕  │  ← TOAST_SUCCEED (绿色)
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  ⚠  请注意检查输入                ✕  │  ← TOAST_WARN (橙色)
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  ✕  操作失败，请重试              ✕  │  ← TOAST_ERROR (红色)
└─────────────────────────────────────────┘
```

### 堆叠效果

当同时显示多条提示时，会自动堆叠排列：

```
         ┌─────────────────────────┐
         │  ✓  保存成功        ✕  │  ← 第3条
         └─────────────────────────┘
         ┌─────────────────────────┐
         │  ℹ️  正在处理...     ✕  │  ← 第2条
         └─────────────────────────┘
         ┌─────────────────────────┐
         │  ⚠  请注意          ✕  │  ← 第1条
         └─────────────────────────┘
              ↓ 屏幕底部 ↓
```

---

## 许可证

MIT License