# 桌面日历挂件

**Repository Path**: deepin20/desktop_calendar

## Basic Information

- **Project Name**: 桌面日历挂件
- **Description**: 桌面日历挂件：一个专为统信 UOS / Deepin 25 设计的桌面日历挂件，基于 PyQt5 开发。它集成了农历、节气、节日、新闻热搜等功能，并支持紧凑/完整模式切换、窗口置顶、透明度调节，是您桌面的贴心助手。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桌面日历挂件 (Desktop Calendar Widget)

[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue)](https://www.python.org/)
[![PyQt5](https://img.shields.io/badge/PyQt5-5.15-green)](https://riverbankcomputing.com/software/pyqt/)
[![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
[![UOS](https://img.shields.io/badge/Deepin/UOS-25%2B-orange)](https://www.deepin.org/)

一个专为 **统信 UOS / Deepin 25 不可变系统** 设计的桌面日历挂件，基于 PyQt5 开发。它集成了农历、节气、节日、新闻热搜等功能，并支持紧凑/完整模式切换、窗口置顶、透明度调节，是您桌面的贴心助手。

---

## ✨ 功能亮点

- **📅 日历展示**：公历日期，支持按年/月/周/日切换（默认月视图）。
- **🌙 农历 & 节气**：自动显示农历日期和二十四节气（使用 `cnlunar` 动态计算，支持 1900–2100 年）。
- **🎉 节日提醒**：支持公历节日（如元旦、国庆）和农历节日（如春节、中秋），可自定义 `festivals.json`。
- **📰 新闻热搜**：集成聚合数据“全网热搜榜”，每小时自动刷新，了解最新热点。
- **🖱️ 智能折叠**：鼠标悬停自动展开为完整日历，移出后自动折叠为紧凑模式，节省桌面空间。
- **🎨 自定义外观**：窗口置顶、透明度调节（0.0~1.0），支持拖拽移动。
- **💾 配置持久化**：窗口位置、大小、置顶、透明度、新闻 API Key 保存在 `config/settings.json`，无需重复设置。
- **📋 高效运行**：采用异步网络请求，避免 UI 卡顿；日志系统记录运行状态，便于调试。

---

## 📸 界面预览

![紧凑模式](screenshots/compact.png)  
*紧凑模式：仅显示当前日期和星期*

![完整模式](screenshots/full.png)  
*完整模式：月历 + 农历/节气/节日 + 新闻*

> 注：请将实际截图文件放入 `screenshots/` 目录，并替换上述链接。

---

## 📦 安装方法

### 方式一：使用 .deb 包安装（推荐 Deepin/UOS 用户）

我们提供了一键构建脚本，您可以自行生成 `.deb` 包，或下载已构建的包。

**手动构建 `.deb` 包**（详见 [打包指南](#-打包为-deb-包)）：

```bash
chmod +x build-deb.sh
./build-deb.sh
```

生成的 `.deb` 包位于 `dist/` 目录，使用以下命令安装：

```bash
sudo dpkg -i dist/desktop-calendar_1.0.0_amd64.deb
sudo apt install -f   # 修复可能缺少的依赖
```

安装后，应用会自动注册到系统菜单，您可以在“工具”或“附件”类别中找到“桌面日历挂件”。

### 方式二：从源码运行（开发或测试）

确保已安装 Python 3.7+ 和 pip，然后克隆项目并安装依赖：

```bash
git clone https://github.com/yourname/desktop-calendar.git
cd desktop-calendar
pip3 install -r requirements.txt
```

运行：

```bash
python3 -m src.main
```

或使用提供的启动脚本：

```bash
./start.sh
```

---

## ⚙️ 配置说明

配置文件位于 `config/settings.json`（首次运行自动生成）。您可以根据需要调整以下参数：

```json
{
    "window_pos": { "x": 100, "y": 100 },      // 窗口位置
    "window_size": { "width": 800, "height": 600 }, // 完整模式窗口大小
    "always_on_top": true,                       // 是否置顶
    "opacity": 1.0,                             // 透明度 0.0~1.0
    "api_key": "your_juhe_api_key"              // 新闻API Key（聚合数据）
}
```

- **api_key**：请前往[聚合数据](https://www.juhe.cn)注册并申请“全网热搜榜”接口，替换为自己的 Key。若留空，新闻功能将不可用。
- 修改配置后，**重启应用**即可生效。

---

## 🖥️ 使用指南

- **展开/折叠**：鼠标悬停自动展开，移出 1 秒后自动折叠。
- **切换月份**：点击日历上方的 `<` `>` 按钮，或“今天”快速回到当前月。
- **拖拽移动**：在窗口任意位置按住左键并拖动即可移动（无边框）。
- **查看新闻**：在完整模式左侧栏显示热搜标题，下方显示详细列表。

---

## 🔧 构建与打包

### 打包为 .deb 包

项目根目录提供了 `build-deb.sh` 一键打包脚本，它会在 `dist/` 目录生成适用于 Deepin/UOS 的 `.deb` 包。

```bash
./build-deb.sh
```

打包脚本会自动：
- 生成 `DEBIAN/control` 和 `DEBIAN/postinst` 等控制文件。
- 将应用安装到 `/opt/desktop-calendar`（可写目录，适配不可变系统）。
- 安装系统依赖（`python3-pyqt5` 等）和 Python 依赖（`zhdate`, `cnlunar`）。
- 创建桌面入口文件（`.desktop`）。

详细打包原理请参阅 [打包脚本](#) 注释。

### 使用 PyInstaller 生成独立可执行文件

如果您想分发一个无需 Python 环境的独立程序：

```bash
pip install pyinstaller
pyinstaller --onefile --windowed \
            --name "桌面日历挂件" \
            --icon resources/icons/app_icon.svg \
            --add-data "festivals.json:." \
            --add-data "config:config" \
            --add-data "resources:resources" \
            --hidden-import cnlunar \
            --hidden-import zhdate \
            src/main.py
```

可执行文件将生成在 `dist/` 目录。

---

## 🐛 故障排查

- **运行时提示 `ModuleNotFoundError: No module named 'zhdate'`**：请使用 `pip3 install zhdate cnlunar` 安装缺失的 Python 包。
- **新闻无法加载**：检查网络连接，确认 `api_key` 是否有效，查看日志 `logs/calendar.log` 获取详细信息。
- **窗口置顶失效**：编辑 `settings.json`，将 `always_on_top` 设置为 `true` 并重启。
- **日志文件**：所有运行日志保存在 `logs/calendar.log`，有助于定位问题。

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！在贡献代码前，请确保：

1. 代码遵循 PEP 8 规范。
2. 新功能或修复包含相应的测试和文档。
3. 提交前运行 `python3 -m src.main` 确保不引入新错误。

---

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)，您可以自由使用、修改和分发。

---

## 🙏 致谢

- [PyQt5](https://riverbankcomputing.com/software/pyqt/) — 跨平台 GUI 框架
- [zhdate](https://pypi.org/project/zhdate/) — 农历转换库
- [cnlunar](https://pypi.org/project/cnlunar/) — 节气计算库
- [聚合数据](https://www.juhe.cn) — 全网热搜榜 API

---

## 📧 联系方式

如有问题或建议，请通过 [Issue](https://github.com/yourname/desktop-calendar/issues) 或邮件联系：your.email@example.com。

---

**🎉 感谢使用 桌面日历挂件！**  
如果觉得不错，请给我们一个 ⭐️ Star，您的支持是我们最大的动力！