# DeskTool **Repository Path**: ccubee/desk-tool ## Basic Information - **Project Name**: DeskTool - **Description**: 简易桌面工具 windows 上使用的 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-09 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DeskIcon · 桌面图标分类工具 把 Windows 快捷方式收进"分类分组",固定在面板里,双击即启动、拖拽即归类。 **只做引用与索引:不移动、不修改、不删除你的任何文件。** 当前版本 **v1.2.7**(2026-11-13):修自动更新——发行版接口只回附件名、不回下载地址时,不再误判"没有 exe 附件";替换脚本改用绝对路径并留 `apply_update.log`。此前 v1.2.6 去掉了时钟区天气的悬停提示条(悬停详情浮层照旧)。 ![主界面](docs/images/ui_main_panel.png) ## 功能(V1.0) | 能力 | 说明 | |---|---| | 分组管理 | 新建 / 重命名 / 换色(8 色)/ 上移下移 / 删除;锁定后禁止拖入拖出 | | 添加图标 | 拖入 `.lnk` `.exe` `.url` `.bat` `.cmd`、文件夹或任意文件;也可点 + 选择文件 | | 图标提取 | Shell 256px 高清图标(IImageList JUMBO),按需缩放 32/48/64/96,PNG 磁盘缓存 | | 启动 | 双击或右键打开;支持"以管理员身份打开"、打开所在位置 | | 归类 | 图标可在分组之间拖拽移动;拖到窗口空白处归入第一个分组 | | 搜索 | 按名称 / 目标路径实时过滤 | | 固定 | 分组锁定、面板置顶、窗口几何持久化(重启还原) | | 托盘与热键 | 关闭窗口收进托盘,`Ctrl+Alt+Space` 全局唤出 | | 导入 | 一键把桌面上的 `.lnk` 导入"桌面快捷方式"分组(去重,不动文件) | | **桌面小组件** | 时间/日期 + 分组图标直接贴在桌面上(压在桌面之上、被普通窗口盖住),双击图标即启动、拖动可换位置 | | **待办提醒** | 时钟左栏「本周」待办摘要(周一~周日),点开是清单:默认看今天、可翻看本周前几天,勾选完成 / 删除 / 选日期添加,跨天自动重排 | | **喝水提示** | 可设间隔(默认 60 分钟)与每日目标杯数(默认 8 杯),到点在屏幕底部弹卡片「已经 X 没喝水了」;点「我喝了」记一杯并显示今天第几杯 / 还差几杯,达标那天庆祝一次 | | **下班提醒** | 工作日到点必弹「快下班啦 / 快要下班了哦,收拾收拾,好好休息~」;明天要是降温 ≥5℃、有雨雪、周五或节前,同一张卡里再加一句 | | 自启 | 托盘菜单一键开关(仅写 `HKCU\...\Run` 一项) | | **背景图** | 主面板 `⋯` →「外观设置…」换一张图做底:虚化 0–40px、暗色蒙版 0–90%,取景位置**直接在预览图上按住拖动**(四向箭头光标),铺满裁切统一留 10% 余量,上下左右都挪得动;只换“底”,卡片和文字仍是原来的深色面,换什么图都不影响可读性 | | **动效强度** | 四档(安静 / 标准 / 轻快 / 关闭),和背景图在同一个对话框:图标格悬停抬升、浮层淡入上移、选中脉冲都跟着档位走 | | 失效检测 | 目标被删除/移走时图标置灰并提示 | | 数据安全 | 启动前自动备份 db(保留 7 份),WAL 模式 | ## 界面预览 | | | |---|---| | **主面板**:分组卡片 + 图标网格,双击启动、拖拽归类,底部显示「已固定几个分组 / 几个图标」
![主面板](docs/images/ui_main_panel.png) | **桌面小组件**:贴在桌面上,按 Win+D 也不消失;左侧大号时钟 + 日期农历 + 待办摘要,右侧是当前分类的图标,滑动换分类
![桌面小组件](docs/images/ui_desktop_widget.png) | | **天气浮层**:鼠标悬停(或点一下)时钟右边的天气,弹出当前详情(体感、湿度、风向风力)+ 今天 / 明天 / 后天预报
![天气浮层](docs/images/ui_weather_popup.png) | **待办清单**:点时钟下方的待办卡片展开,本周日期条默认停在今天、可翻看周一起的前几天;**点文字看完整内容**(详情卡里可标记完成/删除)、勾圆圈勾选、× 删除,顶部选日期添加
![待办清单](docs/images/ui_todo_panel.png) | | **⋯ 菜单**:小组件开关、显示哪个分组、**置顶(F4)**、待办 / 喝水 / 下班提醒、天气城市、每行图标数、时钟字体、开机自启都在这里
![⋯ 菜单](docs/images/ui_menu.png) | **时钟字体**:导入 .ttf / .otf / .ttc(只登记字体,不动你磁盘上的文件)+ 字号 14~72pt,带 00:00:00 实时预览
![时钟字体](docs/images/ui_clock_font.png) | | **喝水提示设置**:自绘蓝色开关(深色底上系统勾选框几乎看不见)、间隔 / 目标 / 每杯毫升 / 工作时段 / 全屏静默 / 提示音,下方直接写「下一次提醒」
![喝水提示设置](docs/images/ui_water_setting.png) | **下班提醒设置**:工作日到点必弹「快下班啦」;天气/周末节假日只决定卡片里那句附注,可各自开关
![下班提醒设置](docs/images/ui_advice_setting.png) | | **外观设置(背景图)**:选图 / 用当前壁纸 / 不使用;虚化、暗色蒙版、动效强度三行;中间预览图**直接按住拖动**就是取景 —— 不再有上下、左右两条位置滑杆
![外观设置](docs/images/ui_backdrop_setting.png) | **待办详情卡**:条目文字太长会被省略号截断,点一下弹这张卡看全文 + 归属日期 + 完成状态,卡里能直接标记完成 / 取消完成 / 删除
![待办详情](docs/images/ui_todo_detail.png) | ![喝水提示 · 提醒卡片](docs/images/water_toast_remind.png) 天气浮层(正常态 / 加载失败态,点天气图标即可立即重刷): ![天气浮层 · 正常态](docs/images/weather_popup_ok.png) ![天气浮层 · 加载失败](docs/images/weather_popup_failed.png) ## 外观设置(背景图 / 虚化 / 蒙版 / 动效) 入口:主面板右上 `⋯` →「外观设置…」。主面板和桌面小组件共用同一张底图。 | 项 | 说明 | |---|---| | 选择图片 / 用当前壁纸 / 不使用 | 「用当前壁纸」直接把系统墙纸路径登记进来,不复制文件;「不使用」回到原来的纯色深底 | | 虚化 | 0–40px,默认 16。0 就是原图直铺 | | 暗色蒙版 | 0–90%,默认 45。越浓图标和文字越清楚;只盖在“底”上,卡片本身另有底色 | | 动效强度 | 安静 / 标准 / 轻快 / 关闭 四档,全局生效(图标格悬停抬升、浮层淡入上移、选中脉冲都跟着变) | ### 取景:直接拖图,没有位置滑杆 预览图就是取景框,**按住鼠标拖**就能上下左右挪动背景图: - 光标平时是四向箭头,按下去变抓手;往右拖 = 图往右走 = 露出左边 - 拖满一整个预览高度,取景就从最上走到最下(按预览尺寸成比例换算,不是按像素 1:1 跟手——按像素的话余量只有几十像素,拖一点点就到头) - 滚轮在预览上滚可以微调上下 - 哪边顶到头了,那个方向就挪不动了,预览的悬停提示会说明 **为什么以前“上下滑动无效”**:铺满裁切(cover)按最大比例缩放,16:9 的壁纸放进接近 16:9 的窗口时,纵向可移动像素正好是 0,位置调节和拖动都会静默失效。现在统一多留 10% 的裁切余量(`ui/backdrop.py` 的 `OVERSCAN = 1.10`),两个方向都有几十像素可挪;代价是四周各多裁掉约 5%。 设置都落在 `deskicon.db`:`ui.bg_image` / `ui.bg_blur` / `ui.bg_dim` / `ui.bg_pos_y` / `ui.bg_pos_x` / `ui.motion`。点「保存」立即生效,不用重启;升级新版时旧的取景位置会沿用,不会跳。 ## 运行(开发态) ```powershell cd D:\ruoyi\DeskIcon .\.venv\Scripts\python.exe main.py ``` 首次运行会自动创建 `%LOCALAPPDATA%\DeskIcon\deskicon.db` 与默认分组「未分类」。 ## 打包 ```powershell .\.venv\Scripts\python.exe build.py # 产物:dist\DeskIcon.exe(单文件,无需 Python) ``` ## 桌面小组件(贴在桌面上) 主面板右上 ⋯ 菜单里: - **显示桌面小组件(时间/日期/图标)** —— 勾选后,桌面右下角出现一块面板:大号时钟 + 日期 + 快捷方式 - **桌面小组件显示哪个分组** —— 可选「显示全部分类(上下滚动)」或某一个分类 - **一屏一个分类** —— 桌面小组件右侧一次只显示一个分类:分类名 + 图标数,下面一行图标(默认每行 5 个,可设置 3~8 个) - **时钟 + 农历** —— 大号时间(默认 32pt)+ 公历日期 + 农历(含干支年与生肖,如「农历十月初一 丙午年·马」) - **上下滑动换分类** —— 鼠标滚轮上下滚,或在面板上按住上下拖,就切到上一个/下一个分类(带滑动动画,底部小圆点显示当前是第几个分类) - **左右滑动看更多** —— 某个分类图标超过「每行个数」时,按住图标行左右拖(或用触摸板左右划)就能看到后面的;滑动会吸附到整格,松手后右边永远是完整图标,不会出现半个;分类名右侧的小三角提示还能往哪边看 - **设置每行图标数…** —— ⋯ 菜单里可改一行显示几个(3~8),面板宽度跟着变;在桌面上直接右键小组件同样有这一项 - **时钟字体…** —— 只要两件事:**导入字体文件**(.ttf / .otf / .ttc,只登记字体、不动你磁盘上的原文件)+ **字号**(14~72pt,带 00:00:00 实时预览);导入的字体自带字重,不再叠叠加粗;文件没了或认不出会回落到系统默认字体。面板宽度与高度按字号自动重算,字号调大不会溢出;桌面上右键小组件也能直接进这个对话框 - **天气** —— 时钟右边是自绘的天气图标 + 当前温度(晴/多云/阴/雨/雪/雾/雷各一套图形,夜间晴天变月亮);**鼠标悬停**弹出浮层:当前天气详情(体感、湿度、风向风力)+ 今天 / 明天 / 后天预报。**点一下天气图标 = 立即重新拉取**(不走 30 分钟缓存,图省事不用加按钮),浮层底部会先显示「刷新中…」再变成「更新于 14:24」;刷新失败但有旧数据时继续显示旧数据,不会把温度抹成「—」 - **设置天气城市…** —— 默认泰安,可改成任意城市(中文或拼音) - **待办提醒(本周 周一~周日)** —— 时钟左栏底部一张待办小卡片:「N 项未完成」+ 最靠前的两条(今天/明天的用中文提示,过期未勾的显示为「逾期N天」并标红);**点卡片**展开待办清单浮层:顶部是本周日期条(周一~周日),**默认停在今天**,点前面几天(周一/周二)就能回看那天的待办;下面按「逾期未完成 / 今天 周三 11-11」分组列出,本周内已过去的日子不算逾期,可勾选完成、点 × 删除;**点条目文字弹出详情卡**,显示完整内容(条目太长会被省略号截断)+ 归属日期 + 完成状态,卡里能直接标记完成 / 取消完成 / 删除;浮层顶部输入框 + 日期下拉(本周七天)**像日历一样选日期添加**,回车即保存。卡片右上角 + 直接进入添加输入框;点面板其他地方自动收起浮层。待办只存在本地 `deskicon.db` 的 `todos` 表;跨周自动整块滑到下一周,跨天自动重算「今天/明天」与逾期 - **待办提醒开关** —— ⋯ 菜单里「桌面小组件显示待办提醒」可关掉卡片;「待办提醒…(本周)」不显示小组件也能打开同一张清单 - 双击图标即启动;按住面板空白处可拖动换位置(位置会记住);右键可打开主面板或隐藏 - **F4 置顶切换** —— 按 `F4` 在「贴在桌面层」和「浮在所有窗口最前面」之间切换(键位被别的程序占了会自动退到 `Ctrl+F4`,并写回设置里);主面板 ⋯ 菜单里也有「桌面小组件置顶(F4)」,勾选状态与热键同步。切到置顶后 Win+D 也不再把它压回桌面层,它就一直在最前面 ### 换时钟字体 / 改字号(三步) 1. **打开设置**:桌面上**右键小组件** →「设置时钟字体…」;或主面板右上 ⋯ →「设置时钟字体…」。主面板缩到托盘时也能用,对话框会自己弹到前台。 2. **选字体**:点「导入字体文件…」,挑一个 `.ttf / .otf / .ttc`。程序只把这个字体**登记进当前进程**,不复制、不移动、不改名你磁盘上的原文件;想退回系统字体点「用系统默认字体」。 3. **调字号**:拖「字号」(14~72pt),上面的 `00:00:00` 是实时预览,满意了点「确定」。小组件立刻按新字体重建,左栏宽度和一屏高度跟着字号自动重算,字号调大不会把文字或图标挤出去。 字体从哪来: - **系统自带就够用**:`C:\Windows\Fonts` 里直接拿——楷体 `simkai.ttf`、宋体 `simsun.ttc`、黑体 `simhei.ttf`、等线、Consolas、Segoe UI……把这些文件本身导入即可,不用下载。 - **免费可商用**:思源黑体/宋体(GitHub `adobe-fonts/source-han-sans`、`source-han-serif` 的 Release)、阿里巴巴普惠体(alibabafonts.com)、得意黑 Smiley Sans(GitHub `atelier-anchor/smiley-sans`)、MiSans(小米)、HarmonyOS Sans(华为)、OPPO Sans、站酷系列(站酷字体专区)、Google Fonts 里的 Inter / Orbitron 等数字字体。 - 只下**单个字体文件**,别下 `.exe` 安装包(容易捆广告);商用项目别用来源不明的网盘合集,授权说不清。 几个注意点: - 导入的字体一般自带字重,程序**不再叠叠加粗**;用回系统默认字体时会自动恢复加粗。 - 字体文件被删/挪走,或者格式 Qt 认不出来,会自动回落到微软雅黑,面板不会崩。 - 字号太大觉得「头重脚轻」,调回 30 左右即可;每行图标数(3~8)也在同一个右键菜单里改。 - 改完不需要重启:保存后小组件当场重建,来源字体和字号记在 `deskicon.db` 的 `clock.font_file` / `clock.pt`。 ### 下班提醒(每天一句「快下班啦」) 工作日到点(默认 **17:30**)必定弹一张深色卡片,不抢焦点;周末和节日当天不弹: ``` 🔔 快下班啦 快要下班了哦,收拾收拾,好好休息~ [ 知道了 ] ``` 明天要真有变化,就在同一张卡里多一句(下面这几项可以单独开关): ``` 🔔 快下班啦 快要下班了哦,收拾收拾,好好休息~ 明天最低 1℃,比今天低 8℃,记得多穿件衣服哦。 [ 知道了 ] ``` | 附注条件 | 追加的那句 | |---|---| | 明天最高温比今天低 ≥ 阈值(默认 5℃) | 明天最低 X℃,比今天低 Y℃,记得多穿件衣服哦。 | | 明天有雨/雪 | 明天 X~Y℃。出门记得带伞。 | | 明天是节假日(元旦/春节/清明/劳动节/端午/中秋/国庆) | 明天是中秋节,假期到了,好好休息哦~ | | 今天周五(明天周六) | 周五啦,明天就是周末,好好休息哦~ | - **每天必弹**:主文案固定是「快下班啦 / 快要下班了哦,收拾收拾,好好休息~」,不再等天气变化,也不会因为「昨天已经用掉名额」而整天静默。 - **拉不到天气也弹**:天气只用来决定那句附注,网络挂了照样弹主文案,只是没有附注。 - **一天只弹一次**:弹完就把日期记在 `advice.last`,重启也不会重弹;只在工作日说,周六周日和节日当天不打扰。 - **入口**:主面板 `⋯` →「下班提醒…」;桌面小组件右键也有这一项。设置项:开关 / 提醒时间 / 降温阈值(2~20℃)/ 明天雨雪附注 / 周末节假日附注 / 卡片停留(和喝水提示共用,默认 30 秒),还有「先看一眼效果」按钮,改完不用重启。 - 开关和喝水提示是同一个自绘滑块(关掉时下面的时间、阈值、两个勾选项一起置灰);卡片弹在**屏幕右下角、任务栏上方**,带附注时卡片会自动长高一行;两张卡片碰在一起时后弹的会往上叠、不会糊成一团。 - 天气和桌面小组件同源(wttr.in,30 分钟缓存);节日里清明按 4 月 5 日近似,调休补班的工作日暂不识别。 ### 喝水提示(独立于桌面小组件) 到点在**屏幕右下角、任务栏上方**弹一张深色卡片(右侧距边 16px、底边贴任务栏 12px),不抢焦点、不进 Alt+Tab,**强制置顶**(前台铺满的浏览器也不会盖住它)。**默认停留 30 秒**,不点按钮就自动淡出(鼠标移入会暂停倒计时,移开继续);停留时长可在设置里改(5–120 秒,喝水提示和下班提醒共用这一个值): ``` 💧 已经 1 小时 2 分钟没喝水了 今天第 3 杯 · 还差 5 杯 · 记得喝水哦~ ●●●○○○○○ [ 稍后 10 分钟 ] [ 我喝了 ] ``` ![喝水提示 · 提醒态](docs/images/water_toast_remind.png) - **点「我喝了」不会直接关窗**:卡片原地变成确认态「今天第 4 杯啦,已经喝了 1000 毫升 · 还差 4 杯 · 也要继续加油哦~」,1.8 秒后才淡出 - **达标那天**:凑满当日目标时卡片换成强调色「今天 8 杯全部达标,太棒啦!」,一天只庆祝一次 - **入口**:主面板 `⋯` → **喝水提示…**;桌面小组件右键也能进。设置项:开关 / 间隔(30·45·60·90·120 或自定义 5–480 分钟)/ 每日目标(4·6·8·10·12 杯)/ 每杯毫升 / 工作时段(默认 09:00–21:00)/ 卡片停留(默认 30 秒,5–120 秒)/ 全屏静默 / 提示音,另有「−1 杯(我点错了)」「现在就算我喝了」和「现在提醒一次(只是看效果)」 - **开关是自绘的蓝色滑块**(深色底上系统勾选框几乎看不见),关掉时下面所有参数一起置灰;开关下方会直接写出「下一次提醒:10:47(约 42 分钟后)」,不用猜它到底有没有在工作 - **「现在提醒一次」只弹卡片看效果**:不改变计时、不记杯数、不算顺延次数,用来确认卡片长什么样、位置对不对 - **计时口径**:用「上次喝水时间 + 间隔」的绝对时间戳做差,所以合盖休眠 2 小时、系统校时、程序重启都不会算错;重启时若距上次喝水超过 2 倍间隔会**静默重置**,不会一开机就弹「已经 14 小时没喝水了」 - **默认关闭**(避免升级后毫无预兆地弹),需要你在设置里勾选「开启喝水提醒」 - 全屏应用(看视频/开会)时静默,**退出全屏后补弹一次**;顺延最多 3 次;连点「我喝了」5 秒内只算一杯 技术说明(本机 Win11 26200 实测结论): 1. 经典 `0x052C` 让 Explorer 派生 `WorkerW` 的壁纸层做法**在这台机器上已失效**(`SendMessageTimeout` 返回 0,枚举不到 WorkerW)。 2. 360 桌面助手是把窗口(`360DirectUICls`)挂进 `SHELLDLL_DefView`;**Qt 窗口挂进去后不渲染**(异源父窗口 Qt 不支持),这条路不通。 3. 最终采用等效且稳定的方案:无边框工具窗 + 持续"压在 Progman 正上方"(`SetWindowPos` 插到 Progman 上方那个窗口之后,必要时用 `HWND_BOTTOM`),并加 `WS_EX_NOACTIVATE` 保证点击不把窗口提到前台。 **常驻桌面机制(Win+D 不再闪一下)**:实测 Win+D 并不会真的最小化这个工具窗(`IsIconic` 始终为 0),而是把所有窗口最小化一遍、让桌面层盖上来。所以改成三路即时纠正: - `SetWinEventHook` 监听"最小化开始/结束"事件(Win+D 会挨个触发):开始事件立刻压底,并在 250ms、600ms 各补压一次(桌面层是在最小化动画结束后才抬升的);最小化结束事件再压一次; - 50ms 看门狗(最小化事件后的 1.2 秒里自动切到 15ms,约一帧):用 `WindowFromPoint` 在面板中心判断桌面层(`Progman` / `SHELLDLL_DefView` / `SysListView32`)是不是盖在自己上面,是就立即压回;被普通应用窗口正常盖住时不做任何动作。 → 效果:桌面上常驻可见、被普通应用窗口盖住、**Win+D / 显示桌面时不再先消失再冒出来**(连续采样 40+ 帧、0 帧丢失,实测空档 ≤50ms)、点击不抢焦点、拖动位置会记住;只有退出程序或手动隐藏才不显示。 ## 自动更新(托盘) 程序自己盯着 Gitee 上的最新发行版,不用你手动去看有没有新版。 - **什么时候查**:启动 30 秒后查一次(错开启动高峰),之后每 6 小时一次。断网、接口异常都只是静默跳过,不会弹错误框打扰你。 - **有新版本时**:托盘弹气泡「发现新版本 vX」,同时托盘右键菜单里那一项变成「发现新版本 vX(点此更新)」并**一直留着**——气泡错过了也不会漏。 - **点它之后**:进应用内更新对话框,能看到当前版本 → 最新版本、完整更新说明、下载进度条、已下载/总大小。 - **下载完会校验**:自动比对发行版说明里「校验」表格中的 SHA256,不一致就拒绝替换(并提示你去发行版页面重新下载);说明里没写校验值时按未校验处理,会在对话框里标出来。 - **点「立即重启更新」后**:程序退出,交给 `%LOCALAPPDATA%\DeskIcon\update\apply_update.bat` 收尾——等旧进程退出 → `copy /Y` 覆盖 exe → 启动新版;旧进程 60 秒还不退就 `taskkill /IM DeskIcon.exe /T /F` 兜底(onefile 有父+子两个进程,必须连子进程一起结束);万一覆盖失败,也会把旧版重新拉起来,不会把桌面弄成空的。 - **不需要令牌**:查版本走 Gitee 公开接口 `releases/latest`,客户端里没有也不该有 token。 - **哪些情况不会自动替换**:源码运行(`python main.py`)、或者 exe 放在只读目录(如 `Program Files`,需要管理员权限)——这两种只把安装包下载到 `update\` 目录,由你自己手动替换,对话框里会写清路径。 - **想立刻查一次**:托盘菜单「检查更新…」(没发现新版会提示「已经是最新版本 vX」)。 - 更新成功后重启的是新 exe,托盘菜单会自动回到「检查更新…」——因为新进程是全新启动,`reported` 标记不跨进程。 ## 数据目录 ``` %LOCALAPPDATA%\DeskIcon\ ├─ deskicon.db # 分组/图标/设置/待办(todos 表) ├─ icons\*.png # 256px 图标缓存 ├─ backups\ # 启动前滚动备份(保留 7 份) ├─ update\ # 自动更新:下载中的新 exe、一次性替换脚本 └─ logs\app.log ``` 想换位置(绿色版)可设置环境变量 `DESKICON_HOME=D:\DeskIconData`。 ## 测试 ```powershell .\.venv\Scripts\python.exe tests\test_core.py # 数据层 / 图标 / 快捷方式解析 .\.venv\Scripts\python.exe tests\test_ui.py # offscreen 渲染冒烟 + 截图 .\.venv\Scripts\python.exe tests\test_todos.py # 待办:本周窗口/默认今天/翻看前几天/增删改(隔离数据目录) .\.venv\Scripts\python.exe tests\test_todo_focus.py # 待办浮层:键盘焦点、控件不溢出 .\.venv\Scripts\python.exe tests\test_todo_detail.py # 待办详情卡:点文字看全文、卡内完成/删除/Esc .\.venv\Scripts\python.exe tests\test_water.py # 喝水提示逻辑:计时/顺延/杯数/跨天/历史(假时钟) .\.venv\Scripts\python.exe tests\test_water_ui.py # 喝水提示接线:菜单入口、设置对话框落库(offscreen) .\.venv\Scripts\python.exe tests\test_toast_hold.py # 提醒卡片停留:默认 30 秒、可改、脏数据回默认、两个提醒共用 .\.venv\Scripts\python.exe tests\verify_water_toast.py # 真机:卡片位置/文案/点击反馈/不抢焦点 .\.venv\Scripts\python.exe tests\test_font_dialog.py # 时钟字体:导入 ttf 后族名生效、字号落地 .\.venv\Scripts\python.exe tests\test_menu_clock.py # 小组件右键菜单:时钟字体/每行图标数两项在且能触发 .\.venv\Scripts\python.exe tests\test_win_d.py # 真机:连按 Win+D,小组件始终可见、不被最小化 .\.venv\Scripts\python.exe tests\test_win_d_src.py # 同上(源码态,隔离数据目录) .\.venv\Scripts\python.exe tests\test_advice.py # 下班提醒逻辑:节日/降温/雨雪/周末与"该不该弹" .\.venv\Scripts\python.exe tests\test_advice_rest.py # 下班提醒「每天必弹」:没变化也弹、断网也弹、一天只一次 .\.venv\Scripts\python.exe tests\test_advice_ui.py # 下班提醒接线:卡片渲染、设置落库、到点触发与去重 .\.venv\Scripts\python.exe tests\test_update.py # 自动更新:版本比较/校验表解析/下载进度/替换脚本真跑一遍 .\.venv\Scripts\python.exe tests\test_motion.py # 动效:四档强度、悬停抬升不推挤网格、浮层淡入上移 .\.venv\Scripts\python.exe tests\test_widget_motion.py # 小组件选中动效:图标格悬停/按下、分页圆点滑动、日期胶囊脉冲 .\.venv\Scripts\python.exe tests\test_backdrop_cover.py # 背景图取景:16:9 壁纸在各框比例下两方向都留余量 ``` ## 常见问题 **从资源管理器拖不进来?** 如果资源管理器是以管理员身份运行的,Windows 的 UIPI 会拦截拖拽到普通权限窗口。 改成"点 + 选择文件"或在托盘以管理员身份启动本工具即可。 **图标显示成首字母方块?** 说明该目标不存在或没有可读图标,工具会退化为占位图标,不影响使用。 **会不会动我的桌面?** 不会。面板里的每一项只是"目标路径 + 名称"的记录;删除图标只删数据库记录。 **导入了字体,时钟看着没变?** 先看字号是不是没调(14~72pt,32 左右才有明显效果);再看导入的那个文件是不是 `.ttf/.otf/.ttc`(`.exe` 安装包不能导入)。 还是没变就点「用系统默认字体」再重开一次对话框——对话框里那行 `00:00:00` 预览就是最终效果,预览变了、小组件没变才算异常。 (底层原因:主窗口的全局样式表同时写了 `font-size` 和 `font-family`,只改字号会被吃掉,所以字体族也写进了时钟标签自己的样式表。) **背景图只能左右挪、上下挪不动?** 那是老版本的问题(铺满裁切时纵向余量为 0),v1.2.4 起不会了:铺满统一多留 10% 裁切余量, 两个方向都有几十像素可挪。升级后如果还是挪不动,先确认跑的是新包(托盘 →「检查更新…」看当前版本), 再看这张图的宽高比是不是和窗口差太多——极端长的图(比如 4:1)在那个方向上仍可能被裁到几乎没有余量。 **桌面小组件被别的桌面美化软件(360 桌面助手、桌面栅栏类工具)挡住?** 这类工具会在 `SHELLDLL_DefView` 里塞全屏覆盖窗。本工具的小组件固定在 `Progman` 正上方, 实测与 360 桌面助手共存时可正常显示;若某个工具把自己置为最顶层全屏覆盖,小组件会被它盖住, 这种情况需要在该工具里关掉它的"桌面层覆盖",或改用本工具的小组件。 **按 Win+D 显示桌面后小组件会消失一下?** 不会了(V1.0.1 起)。它常驻在"桌面之上、应用之下"这一层;Win+D 时系统会把所有窗口最小化一遍,程序监听到最小化开始/结束就立刻把自己压回桌面层(并错开补压两次),同时还有 50ms 兜底检测,实测显示桌面全程 0 帧丢失。 只有这两种情况它才不显示:右键菜单里"隐藏桌面小组件",或退出程序。 **天气不显示 / 显示"—"?** 天气走 `wttr.in` 免费接口(无需 Key),需要联网。取不到时图标显示"—",每 30 分钟自动重试;**点一下这个天气图标可以立即重试**(不用等); 城市可在 ⋯ → **设置天气城市…** 里改。数据为 30 分钟缓存,不会频繁请求。 ## 目录结构 ``` DeskIcon/ ├─ main.py # 入口:单实例 → 托盘 → 主窗 → 全局热键 ├─ build.py # 生成 ico + PyInstaller 打包 ├─ core/constants.py # 常量、配色、类型 ├─ infra/ │ ├─ db.py # SQLite(分组/图标/设置/备份) │ ├─ icons.py # HICON → PNG 缓存 │ ├─ shellink.py # .lnk/.url 解析、ShellExecute 启动 │ ├─ weather.py # 天气取数 + 中文映射(wttr.in,标准库实现) │ ├─ todos.py # 待办「本周 周一~周日」窗口与中文日期标签 │ ├─ water.py # 喝水提示:计时/杯数/30 天历史(纯逻辑,无 Qt) │ ├─ advice.py # 下班提醒:节日表/降温幅度/必弹主文案/该不该弹(纯逻辑,无 Qt) │ ├─ paths.py # 数据目录 │ └─ win32/ # autostart、hotkey ├─ ui/ │ ├─ main_window.py # 主窗口 │ ├─ desktop_widget.py # 桌面小组件(时钟/日期/天气/图标) │ ├─ water_reminder.py # 喝水提示调度(1 秒一拍 + 全屏静默判定) │ ├─ water_toast.py # 底部卡片(提醒 / 已记录 / 达标 三态) │ ├─ advice_reminder.py # 下班提醒调度(每秒一拍、天气回调绕回主线程) │ ├─ advice_toast.py # 下班提醒卡片(铃铛图标 + 标题 + 正文 + 知道了) │ ├─ flow_layout.py # 自动换行布局 │ ├─ theme.py # 深色 QSS │ ├─ branding.py # 代码生成的图标 │ ├─ dialogs/ # item_edit、clock_font、water_setting、advice_setting │ └─ widgets/ # group_card、icon_tile └─ tests/ # 自检脚本 ``` ## 后续(V1.1 计划) - 资源管理器右键"添加到分类" - 分组导入/导出 JSON、批量替换图标、多屏独立布局 - 图标异步加载(当前为同步 + 磁盘缓存,100+ 图标时可优化) - 桌面小组件接入天气 / 农历(对齐 360 桌面助手那行小字) 设计与排期详见 `..\桌面图标分类工具开发设计文档.md`。