# 时钟日历

**Repository Path**: deepin20/shiz

## Basic Information

- **Project Name**: 时钟日历
- **Description**: 桌面时钟日历 (Clock Calendar)：一个基于 PyQt5 的全功能桌面时钟日历工具，集成农历、节日、宜忌、备注、倒计时、番茄钟和个性化主题。适用于 Linux 桌面环境（如 Deepin、Ubuntu）。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桌面时钟日历 (Clock Calendar)

一个基于 PyQt5 的全功能桌面时钟日历工具，集成农历、节日、宜忌、备注、倒计时、番茄钟和个性化主题。适用于 Linux 桌面环境（如 Deepin、Ubuntu）。

[应用分享] 桌面时钟（开发者：🐖¹².₁₃高老庄的书生℘࿐）：https://bbs.deepin.org/post/301338

![界面预览](screenshot.png) *(请自行添加截图)*

---

## ✨ 主要功能

- **实时时钟**：显示时、分、秒，支持整点报时。
- **农历与节气**：公历与农历对照，自动标注二十四节气、传统节日（春节、端午、中秋等）和公历节日（元旦、劳动节等）。
- **每日宜忌**：基于日期随机生成“宜”“忌”事项（非传统黄历，仅供参考）。
- **日历视图**：按月显示，每个日期格包含公历日期、农历/节日缩写；周末、调休（补班/放假）颜色区分。
- **备注管理**：每个日期可添加/编辑/删除备注（支持多行文本），导出为 `.txt` 或 `.json` 文件。
- **倒计时/纪念日**：自定义事件（名称+日期），在日历中标记并显示距离最近事件的天数。
- **番茄钟（Pomodoro）**：专注（25分钟）、短休（5分钟）、长休（15分钟）模式，自动轮转，统计每日/每周/累计专注次数，近7天走势图。
- **系统托盘与全局快捷键**：托盘图标显示当日日期，单击切换窗口；`Ctrl+Alt+C` 全局显示/隐藏。
- **个性化定制**：
  - 7 套主题（深空灰、星际蓝、极光紫、薄荷青、樱花粉、暗夜金、海洋蓝）
  - 背景透明度 6 档可调
  - 时间字体颜色自定义（预设色板+拾色器）
  - 字体与字号自由设置
- **窗口管理**：无边框、可拖动、窗口置顶、开机自启（Linux）。

---

## 📦 系统要求

- **操作系统**：Linux（推荐 Deepin、Ubuntu 等基于 Debian 的发行版）
- **Python**：3.6 及以上
- **桌面环境**：支持 X11（Wayland 未完全测试）

---

## 🔧 安装与运行

### 方法一：使用虚拟环境（推荐，避免污染系统）

1. **克隆或下载本项目** 到本地目录，例如 `~/Downloads/桌面时钟日历`。

2. **进入项目目录**：
   ```bash
   cd ~/Downloads/桌面时钟日历
   ```

3. **安装系统依赖**（确保系统有 Qt 平台插件）：
   ```bash
   sudo apt update
   sudo apt install libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 \
       libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
       libxcb-shape0 libxcb-xfixes0 libxcb-xkb1 libxkbcommon-x11-0
   ```
   *如果系统提示依赖问题，运行 `sudo apt --fix-broken install` 修复。*

4. **安装系统 PyQt5**（Deepin/Ubuntu 已自带，若无则安装）：
   ```bash
   sudo apt install python3-pyqt5 python3-pyqt5.qtsvg python3-pyqt5.qtmultimedia
   ```

5. **创建虚拟环境并安装纯 Python 依赖**：
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   pip install zhdate keyboard
   deactivate
   ```

6. **运行程序**：
   - 直接激活虚拟环境后运行：
     ```bash
     source venv/bin/activate
     export PYTHONPATH=/usr/lib/python3/dist-packages:$PYTHONPATH   # 确保系统 PyQt5 优先
     python shiz.py
     ```
   - 或使用提供的启动脚本 `run.sh`（已包含上述步骤）：
     ```bash
     chmod +x run.sh
     ./run.sh
     ```

### 方法二：系统级安装（不推荐）

若不想使用虚拟环境，可直接安装所有依赖到系统（注意可能破坏系统 Python 环境）：
```bash
sudo apt install python3-pyqt5 python3-pyqt5.qtsvg python3-pyqt5.qtmultimedia
pip install zhdate keyboard --break-system-packages
python shiz.py
```

---

## 📂 数据与配置

所有用户数据保存在家目录下，以 JSON 格式存储：

| 文件 | 内容 |
|------|------|
| `~/.clock_calendar_notes.json` | 日期备注 |
| `~/.clock_calendar_countdowns.json` | 倒计时事件 |
| `~/.clock_calendar_pomodoro.json` | 番茄钟统计 |
| `~/.clock_calendar_settings.json` | 整点报时、开机自启开关 |

- 备注导出：右键菜单 → “导出备注” 可选择 `.txt` 或 `.json` 格式。
- 开机自启：右键菜单开启后，会在 `~/.config/autostart/` 生成 `.desktop` 文件。

---

## ⌨️ 使用指南

- **单击日期**：选中并更新顶部信息（农历、宜忌等）。
- **双击日期**：编辑该日备注。
- **右键日期**：复制日期或编辑备注（快捷入口）。
- **滚动滚轮**（在日期区域）：切换月份。
- **右键空白区域**：弹出主菜单，包含主题、透明度、时间颜色、番茄钟统计、倒计时管理等。
- **托盘图标单击**：显示/隐藏窗口。
- **全局快捷键**：`Ctrl+Alt+C` 显示/隐藏窗口。

---

## 🐛 故障排除

### 1. 运行提示 `Could not find the Qt platform plugin "xcb"`
- **原因**：PyQt5 无法加载 X11 插件。
- **解决**：
  - 确保已安装系统库（见安装步骤第3步）。
  - 如果使用虚拟环境，请使用系统 PyQt5（参考“安装与运行”方法一）。
  - 设置环境变量 `QT_PLUGIN_PATH` 指向正确插件路径，或在 `run.sh` 中调整 `PYTHONPATH`。

### 2. 提示 `缺少 zhdate 库`
- 安装：`pip install zhdate`（在虚拟环境中）。

### 3. 窗口显示异常或高 DPI 字体过大
- 程序启动前已强制关闭高 DPI 缩放，若仍有问题，尝试设置：
  ```bash
  export QT_SCALE_FACTOR=1.0
  export QT_SCREEN_SCALE_FACTORS=1.0
  ```

### 4. 全局热键 `Ctrl+Alt+C` 不生效
- 确认已安装 `keyboard` 库（`pip install keyboard`）。
- 某些桌面环境可能拦截全局热键，尝试使用本地快捷键（程序内置 `QShortcut`，在窗口激活时有效）。

---

## 🛠️ 技术栈

- **Python 3** + **PyQt5**（图形界面）
- **zhdate**（农历转换）
- **keyboard**（全局热键，可选）
- JSON 数据存储
- Linux 桌面集成（托盘、开机自启）

---

## 🤝 贡献与许可

本项目为个人作品，欢迎提交 Issue 或 Pull Request。  
许可证：**MIT**（可自由使用、修改、分发，请保留版权信息）。

---

## 📝 致谢

- [zhdate](https://github.com/zhangyitian/zhdate) 提供农历支持。
- [keyboard](https://github.com/boppreh/keyboard) 提供全局热键支持。

---

*享受你的桌面时钟日历！如有问题，请及时反馈。*