Merge pull request 'docs: 添加操作手册' (#3) from main into master

Reviewed-on: http://192.168.3.32:3000/xiaji/countdown/pulls/3

.gitignore

@@ -7,7 +7,6 @@ __pycache__/
 build/
 dist/
 *.spec
-!dist/*.exe
 
 # IDE
 .idea/

README.md

@@ -1,65 +1,65 @@
-# 述职计时器
-
-一个使用 PySide6 构建的倒计时应用程序，美观大方，支持多种倒计时模式。
-
-## 功能特点
-
-### 界面状态
-程序有两种界面状态：
-
-#### 1. 正常状态
-- 显示倒计时时间和完整的按钮区域
-- 可以通过拖动窗口的任何位置来移动窗口
-- 显示按钮区域
-- 窗口大小：500×300像素
-
-#### 2. 微缩状态
-- 点击"5分钟"或"6分钟"按钮开始倒计时后，延迟2秒自动切换到微缩状态
-- 只显示倒计时时间
-- 窗口大小：200×80像素
-- 位置：距离屏幕上边缘50像素，距离右边缘200像素
-- 双击界面后暂停倒计时，并切换回正常状态
-
-### 快捷按钮
-- **5分钟**：开始5分钟倒计时
-- **6分钟**：开始6分钟倒计时
-- **其它**：打开配置对话框
-
-### 配置功能
-点击"其它"按钮可以打开配置对话框：
-- **自定义倒计时**：设置自定义倒计时时间（秒）
-- **提前告警**：设置倒计时结束前多少秒播放告警提示音，默认30秒
-- **窗口置顶**：设置窗口是否置顶
-- **窗口透明度**：设置窗口透明度（10%-100%）
-- **测试告警**：测试告警提示音
-- **退出**：退出程序（唯一退出方式）
-
-### 告警功能
-- 倒计时结束前设置的秒数时播放告警提示音
-- 循环播放3次
-- 倒计时结束时显示"时间已到"文字，带有跳动和闪动效果
-
-## 使用说明
-
-1. 运行程序后，默认显示正常状态
-2. 点击"5分钟"或"6分钟"按钮开始倒计时
-3. 2秒后自动切换到微缩状态，只显示时间
-4. 在微缩状态下双击可以暂停并回到正常状态
-5. 需要退出程序时，点击"其它"→"退出"
-
-## 技术栈
-- Python 3.11
-- PySide6 (Qt 6)
-- PyInstaller（打包）
-
-## 打包命令
-```bash
-python -m PyInstaller --onefile --windowed --icon=Timer.ico --name=述职计时器 countdown.py
-```
-
-## 文件说明
-- `countdown.py` - 主程序代码
-- `Timer.ico` - 程序图标
-- `要求.txt` - 功能需求文档
-- `clean.py` - 清理打包残留文件
-- `SKILL.md` - 打包技巧说明
+# 述职计时器
+
+一个使用 PySide6 构建的倒计时应用程序，美观大方，支持多种倒计时模式。
+
+## 功能特点
+
+### 界面状态
+程序有两种界面状态：
+
+#### 1. 正常状态
+- 显示倒计时时间和完整的按钮区域
+- 可以通过拖动窗口的任何位置来移动窗口
+- 显示按钮区域
+- 窗口大小：500×300像素
+
+#### 2. 微缩状态
+- 点击"5分钟"或"6分钟"按钮开始倒计时后，延迟2秒自动切换到微缩状态
+- 只显示倒计时时间
+- 窗口大小：200×80像素
+- 位置：距离屏幕上边缘50像素，距离右边缘200像素
+- 双击界面后暂停倒计时，并切换回正常状态
+
+### 快捷按钮
+- **5分钟**：开始5分钟倒计时
+- **6分钟**：开始6分钟倒计时
+- **其它**：打开配置对话框
+
+### 配置功能
+点击"其它"按钮可以打开配置对话框：
+- **自定义倒计时**：设置自定义倒计时时间（秒）
+- **提前告警**：设置倒计时结束前多少秒播放告警提示音，默认30秒
+- **窗口置顶**：设置窗口是否置顶
+- **窗口透明度**：设置窗口透明度（10%-100%）
+- **测试告警**：测试告警提示音
+- **退出**：退出程序（唯一退出方式）
+
+### 告警功能
+- 倒计时结束前设置的秒数时播放告警提示音
+- 循环播放3次
+- 倒计时结束时显示"时间已到"文字，带有跳动和闪动效果
+
+## 使用说明
+
+1. 运行程序后，默认显示正常状态
+2. 点击"5分钟"或"6分钟"按钮开始倒计时
+3. 2秒后自动切换到微缩状态，只显示时间
+4. 在微缩状态下双击可以暂停并回到正常状态
+5. 需要退出程序时，点击"其它"→"退出"
+
+## 技术栈
+- Python 3.11
+- PySide6 (Qt 6)
+- PyInstaller（打包）
+
+## 打包命令
+```bash
+python -m PyInstaller --onefile --windowed --icon=Timer.ico --name=述职计时器 countdown.py
+```
+
+## 文件说明
+- `countdown.py` - 主程序代码
+- `Timer.ico` - 程序图标
+- `要求.txt` - 功能需求文档
+- `clean.py` - 清理打包残留文件
+- `SKILL.md` - 打包技巧说明

SKILL.md

@@ -0,0 +1,13 @@
+## 元数据
+name: pyinstaller个性化打包
+description: 打包的时候，要求生成为一个exe文件，使用ico等等
+
+## 概述
+此 Skill 用于给有GUI界面的python代码，打包的时候，生成一个统一的要求：生成一个exe文件，去掉控制台窗口，使用本目录下的ico文件作为程序的图标。打包时，如果之前有打包过的文件（dist/build 文件夹），自动覆盖旧文件，不用手动确认，一键打包到底。
+
+## 打包命令示例
+python -m PyInstaller --onefile --windowed --icon=图标文件名.ico --name=guba-indicator --exclude-module PyQt5 --exclude-module PyQt5.QtCore --exclude-module PyQt5.QtGui --exclude-module PyQt5.QtWidgets --exclude-module PyQt6 --exclude-module PyQt6.QtCore --exclude-module PyQt6.QtGui --exclude-module PyQt6.QtWidgets python程序名.py
+
+
+## 清除多余文件
+在windows环境下，执行clean.py

clean.py

@@ -0,0 +1,17 @@
+import os
+import shutil
+import glob
+import subprocess
+
+# 2. 清理打包残留文件 等价：rd /s /q build + del /f *.spec
+print("开始清理打包残留文件...")
+# 删除build文件夹
+if os.path.exists("build") and os.path.isdir("build"):
+    shutil.rmtree("build")
+# 删除所有.spec文件
+spec_files = glob.glob("*.spec")
+for spec_file in spec_files:
+    if os.path.exists(spec_file):
+        os.remove(spec_file)
+
+print("✅ 打包完成 + 残留文件清理完毕！exe文件已生成在当前目录")

countdown.py

@@ -17,6 +17,18 @@ class ConfigDialog(QDialog):
         self.init_ui()
 
     def init_ui(self):
+        self.setStyleSheet("""
+            QDialog {
+                background-color: #f5f5f5;
+            }
+            QLabel {
+                color: #333333;
+                font-size: 14px;
+            }
+            QSpinBox, QCheckBox {
+                padding: 5px;
+            }
+        """)
         layout = QFormLayout(self)
         
         # 自定义倒计时
@@ -181,11 +193,23 @@ class TimerApp(QWidget):
 
     def setup_audio(self):
         self.sound = QSoundEffect()
+        
+        # 优先从外部目录加载音频文件
         if getattr(sys, 'frozen', False):
-            base_path = sys._MEIPASS
+            # exe所在目录
+            external_path = os.path.dirname(sys.executable)
         else:
-            base_path = os.path.dirname(__file__)
-        alarm_file = os.path.join(base_path, "alarm.wav")
+            # 当前工作目录
+            external_path = os.getcwd()
+        
+        alarm_file = os.path.join(external_path, "alarm.wav")
+        if not os.path.exists(alarm_file):
+            # 外部没有则从打包的临时目录加载
+            if getattr(sys, 'frozen', False):
+                alarm_file = os.path.join(sys._MEIPASS, "alarm.wav")
+            else:
+                alarm_file = os.path.join(os.path.dirname(__file__), "alarm.wav")
+        
         if os.path.exists(alarm_file):
             self.sound.setSource(QUrl.fromLocalFile(alarm_file))
         self.sound.setLoopCount(3)

操作手册.md

@@ -0,0 +1,78 @@
+# 述职计时器 操作手册
+
+## 一、概述
+
+述职计时器是一款专为述职演讲设计的倒计时工具，支持快捷计时、提前告警、微缩悬浮窗口等功能。
+
+## 二、快速开始
+
+1. 双击 `countdown.exe` 启动程序
+2. 点击 **5分钟** 或 **6分钟** 按钮开始倒计时
+3. 2秒后窗口自动缩小为悬浮模式
+
+## 三、功能说明
+
+### 3.1 主界面
+
+| 按钮 | 说明 |
+|------|------|
+| 5分钟 | 开始5分钟（300秒）倒计时 |
+| 6分钟 | 开始6分钟（360秒）倒计时 |
+| 其它 | 打开配置窗口 |
+
+### 3.2 配置功能
+
+点击 **其它** 按钮打开配置窗口，可设置以下选项：
+
+| 配置项 | 说明 |
+|--------|------|
+| 自定义秒数 | 设置自定义倒计时时长（1-3600秒） |
+| 提前告警(秒) | 设置提前播放告警音的时间（0-300秒） |
+| 窗口置顶 | 勾选后窗口始终保持在其他窗口上方 |
+| 透明度 | 调节窗口透明度（10%-100%） |
+| 距离右边缘 | 微缩窗口距离屏幕右边缘的像素值 |
+| 距离上边缘 | 微缩窗口距离屏幕上边缘的像素值 |
+
+### 3.3 窗口操作
+
+| 操作 | 功能 |
+|------|------|
+| 拖拽标题栏区域 | 移动窗口位置 |
+| 双击微缩窗口 | 暂停倒计时，恢复正常窗口大小 |
+
+### 3.4 告警与提醒
+
+- **提前告警**：倒计时剩余时间达到"提前告警"设定值时，播放3次提示音
+- **倒计时结束**：
+  - 微缩模式：文字红黄闪烁
+  - 正常模式：文字跳动 + 透明度闪烁
+
+## 四、音频配置
+
+程序支持自定义告警音效：
+
+- 将 `alarm.wav` 音频文件放置在 **exe 同目录** 或 **当前工作目录**
+- 程序会优先从外部目录加载，若未找到则使用内置音频
+
+## 五、打包说明
+
+### 5.1 打包命令
+
+```bash
+pyinstaller --onefile --windowed --noconsole --icon=Timer.ico countdown.py
+```
+
+参数说明：
+- `--onefile`：打包成单个exe文件
+- `--windowed` / `--noconsole`：不显示控制台窗口
+- `--icon`：指定程序图标
+
+### 5.2 清理残留文件
+
+运行 `clean.py` 可自动清理打包残留文件并重新生成exe。
+
+## 六、注意事项
+
+1. 首次运行请确保 `alarm.wav` 与 exe 在同一目录，否则告警功能不可用
+2. 微缩窗口位置可在配置中自定义
+3. 窗口支持拖拽，可放置在屏幕任意位置

要求.txt

@@ -1,18 +1,18 @@
-目的：写一个python语言的，pyside6库作为界面的应用程序。
-功能：倒计时显示和提醒。
-界面需求：整体要美观大方。
-1. 窗口无标题栏，可以通过点击并拖动任何位置移动窗口
-2. 倒计时显示区域：显示分和秒的倒计时，字体大且醒目
-3. 界面分为2个状态：
-   a. 正常状态：显示时间，点击箭头，显示按钮区域，再点击箭头，按钮区域折叠
-   b. 微缩状态：点击"5分钟"后，延迟2秒，界面改为微缩状态，只有时间区域和向下箭头
-4. 微缩状态详情：
-   - 窗口长为200px，高为60px
-   - 距离top为50px，距离屏幕右边留出空白200px的距离
-   - 点击向下箭头，回到正常状态的位置和大小
-5. 快捷按钮：第一个按钮是"5分钟"，第二个按钮是"6分钟"，第三个按钮是"其它"
-6. 其它按钮功能：打开配置页面，可以设置自定义倒计时时间、提前告警时间、窗口置顶选项、透明度设置
-7. 告警功能：倒计时结束前设置的秒数时播放告警提示音，循环3次
-8. 倒计时结束后：显示"时间已到"文字，带有跳动和闪动效果
-9. 配置对话框：增加退出按钮，只有通过此按钮才能退出程序
+目的：写一个python语言的，pyside6库作为界面的应用程序。
+功能：倒计时显示和提醒。
+界面需求：整体要美观大方。
+1. 窗口无标题栏，可以通过点击并拖动任何位置移动窗口
+2. 倒计时显示区域：显示分和秒的倒计时，字体大且醒目
+3. 界面分为2个状态：
+   a. 正常状态：显示时间，点击箭头，显示按钮区域，再点击箭头，按钮区域折叠
+   b. 微缩状态：点击"5分钟"后，延迟2秒，界面改为微缩状态，只有时间区域和向下箭头
+4. 微缩状态详情：
+   - 窗口长为200px，高为60px
+   - 距离top为50px，距离屏幕右边留出空白200px的距离
+   - 点击向下箭头，回到正常状态的位置和大小
+5. 快捷按钮：第一个按钮是"5分钟"，第二个按钮是"6分钟"，第三个按钮是"其它"
+6. 其它按钮功能：打开配置页面，可以设置自定义倒计时时间、提前告警时间、窗口置顶选项、透明度设置
+7. 告警功能：倒计时结束前设置的秒数时播放告警提示音，循环3次
+8. 倒计时结束后：显示"时间已到"文字，带有跳动和闪动效果
+9. 配置对话框：增加退出按钮，只有通过此按钮才能退出程序
 10. 测试要求：使用pyqt-test库作为gui程序的测试工具。