WeatherQuest - 天气查询小工具

基于 PyQt5 的桌面天气查询应用程序，调用和风天气 (HeWeather) API 提供实时天气数据、预警信息和天气预报。

功能特点

• 🌤️ 实时天气查询：输入城市名称获取当前天气（温度、湿度、风速、气压等）
• ⚠️ 天气预警显示：自动显示该地区的天气预警（如有）
• 📅 5 天天气预报：未来 5 天每日天气概览
• 🎨 精美动画界面：淡入淡出、滑动、脉冲等平滑动画效果
• 🖥️ 现代化 GUI：采用 Fusion 样式，支持高 DPI 显示
• 🔄 异步数据加载：避免界面卡顿，提升用户体验
• 📍 城市历史记录：自动保存查询过的城市，支持快速选择

项目结构

WeatherQuest/
├── main.py                 # 程序入口
├── weather_api.py          # 和风天气 (HeWeather) API 客户端
├── config.py               # 配置管理（API 密钥、单位制等）
├── requirements.txt        # Python 依赖包列表
├── .env.example            # 环境变量示例文件
├── gui/                    # GUI 模块
│   ├── __init__.py
│   ├── main_window.py     # 主窗口
│   ├── widgets.py         # 自定义组件（天气卡片、预警组件等）
│   └── animations.py      # 动画工具类
├── assets/                 # 静态资源
│   └── icons/             # 天气图标（可自行添加）
└── README.md               # 项目说明

快速开始

1. 安装依赖

确保已安装 Python 3.8+，然后运行：

pip install -r requirements.txt

2. 配置 API 密钥

1. 前往 和风天气开发者平台 注册账号并获取 API 密钥。
2. 复制 .env.example 为 .env：

   copy .env.example .env

3. 在 .env 文件中填入您的 API 密钥，并设置 个人专属域名（控制台-设置中查看，形如 xxx.qweatherapi.com）：

   API_KEY=your_api_key_here
   API_HOST=your_personal_domain_here
   

3. 运行程序

python main.py

使用说明

1. 启动程序后，在主窗口顶部输入城市名称（支持中文，如“北京”）
2. 点击“查询”按钮或按回车键获取天气数据
3. 查看当前天气详情、预警信息（如有）和未来 5 天预报
4. 之前查询过的城市会自动保存到下拉列表中，方便下次快速选择

自定义配置

可通过修改 .env 文件调整以下设置：

变量名	说明	默认值
API_KEY	和风天气 (HeWeather) API 密钥	必填
LANGUAGE	显示语言（如 zh_cn）	zh_cn
UNITS	温度单位（metric/imperial/standard）	metric
CITY	默认查询城市	Beijing

开发指南

添加新的天气图标

1. 将 PNG 格式的图标放入 assets/icons/ 目录
2. 文件名格式：<weather_code>.png（如 01d.png 表示晴天白天）
3. 在 gui/widgets.py 中修改 ForecastCard 类的图标映射逻辑

扩展功能建议

• 多语言支持：添加更多语言翻译文件
• 主题切换：实现深色/浅色模式
• 系统托盘：常驻系统托盘，显示实时温度
• 通知功能：重要预警时发送桌面通知
• 数据导出：将天气数据导出为 CSV/JSON

技术栈

• Python 3.8+：核心编程语言
• PyQt5：GUI 框架
• Requests：HTTP 客户端
• python-dotenv：环境变量管理

故障排除

常见问题

1. “API 密钥未设置”错误

   • 检查 .env 文件是否存在且包含正确的 API_KEY
   • 确保文件名是 .env 而不是 .env.txt

2. 查询失败，提示“未找到城市”

   • 确认城市名称拼写正确
   • 尝试使用英文城市名

3. 界面显示异常或字体模糊

   • 程序支持高 DPI 缩放，可在系统显示设置中调整缩放比例
   • 确保已安装微软雅黑字体

4. 网络连接超时

   • 检查网络连接是否正常
   • 尝试使用代理或调整 config.py 中的 TIMEOUT 值

5. 返回 401/403 或提示 Invalid Host

   • 新版和风天气强制使用个人专属域名：请在控制台-设置中复制 API_HOST（形如 xxx.qweatherapi.com），不要使用通用域名
   • 城市查询接口路径为 /geo/v2/city/lookup（项目已按此配置）

调试模式

如需查看详细日志，可在 config.py 中启用调试输出：

DEBUG = True

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

致谢

• 天气数据由 和风天气 (HeWeather) 提供
• 图标资源使用系统表情符号，如需真实天气图标可自行添加

---

欢迎贡献代码、提交问题或提出改进建议！