把 Windows 任务栏时钟做成自己的:UCalendar 技术拆解

任务栏时钟看起来只是一个小功能,实际却同时踩中了 Explorer 注入、Win10 原生窗口、Win11 XAML 树、DPI 适配、单文件资源分发这几块硬骨头。
UCalendar v2.8.3 的重点更新,是任务栏自定义时钟。它不是一个悬浮在任务栏上的小窗口,而是直接接管系统时钟的显示:你可以换样式、换字体和颜色、显示农历和节日、把天气塞进任务栏,也可以用自己的格式串拼出一行专属时钟。
这篇文章不写"更新日志",而是拆开看:一个任务栏时钟为什么要分 Win10 / Win11 两套实现,UCalendar 又是怎么把它做成单文件、可回退、可维护的。
一、先看效果:10 种样式,最后一种是自由发挥
v2.8.3 内置 10 种样式:
| 编号 | 样式 | 典型内容 |
|---|---|---|
| 1 | 公历简洁 | 时间 + 星期 + 日期 |
| 2 | 公历双历 | 公历 + 农历 |
| 3 | 星期秒钟 | 带秒时间 + 星期 |
| 4 | 节日倒数 | 距离下一个节日还有几天 |
| 5 | 节日节气 | 节日/节气 + 农历 |
| 6 | 当前天气 | 天气文字 + 温度 |
| 7 | 十二时辰 | 12/24 小时制 + 时辰 |
| 8 | 周数日历 | ISO 周数 + 日期 |
| 9 | 天气详情 | 城市、天气、温度区间、风力/湿度/AQI |
| 10 | 自定义格式 | 变量 + 分隔符 + 换行 |
样式 10 是这次最值得玩的部分。格式串支持时间、日期、星期、周数、农历、节日、节气、时辰、城市、天气和温度等变量,例如:
text
HH:mm 星期W
NL · JJ
\n 可以显式分成两行。设置页提供实时预览,点选变量或把变量拖进输入框即可;切换样式后立即应用,不需要重启 UCalendar,也不需要重启 Explorer。
外观也不是只能换颜色:字体、字号、文字颜色、背景、对齐、行距,以及天气图标的位置和大小都可以调。Win10 上天气图标可以在左/右/关闭之间切换;Win11 则改用 Unicode 字形融入文本,避免 TAP 渲染层无法直接贴 PNG 的问题。
二、技术架构:Rust 做控制面,C++ 做渲染面
任务栏时钟不是一个普通的 Tauri 窗口。它最终要画在 Explorer 的任务栏里,所以 UCalendar 把它拆成了两层:
text
UCalendar.exe / Rust
├─ 读取设置、生成 clock.json
├─ 解压内置 DLL 和天气图标
├─ 定位 Explorer,注入对应的 C++ DLL
├─ 处理任务栏点击 / 右键菜单
└─ 退出时恢复系统时钟、停止渲染器
Explorer.exe / C++ DLL
├─ Win10:接管 TrayClockWClass,GDI+ 绘制
└─ Win11:通过 XAML diagnostics TAP 改写 TextBlock
核心入口在 src-tauri/src/taskbar_clock.rs,渲染器在 tools/taskbar-clock-probe/。Rust 负责"什么时候画、画什么配置",C++ 负责"在 Explorer 进程里怎么画"。
为什么需要两个 DLL
| 系统 | DLL | 渲染方式 |
|---|---|---|
| Windows 10 | UCalendarClockOverlay.dll |
接管原生 TrayClockWClass,必要时用 layered window + GDI+ 绘制 |
| Windows 11 | UCalendarClock.dll |
通过 XAML diagnostics TAP 找到任务栏文本,直接改 TextBlock |
这两条路不能简单合并:Win10 没有 Win11 的 XAML diagnostics endpoint,Win11 也没有可以稳定接管的 TrayClockWClass。与其做一个到处是条件分支的巨型 DLL,不如按系统拆成两个职责明确的渲染器,由 Rust 根据系统版本选择注入。
三、四个真正的难点
1. 注入之后,还要能停下来
注入 Explorer 只是开始。DLL 加载后要创建隐藏窗口、启动渲染线程,并且必须支持"切换回系统时钟"和"退出应用"时干净地停止。
UCalendar 的做法是:
- 按窗口类名找到
UCalendarTaskbarWin11HookWnd/UCalendarTaskbarProbeWnd; - 发送
WM_CLOSE,让渲染器自己退出; - 必要时远程释放 DLL;
- 如果 DLL 已被 Explorer 锁住,不强行覆盖,而是先改名再写入新文件;
- 注入失败只记录局部错误,回退系统原生时钟,不 panic、不拉起新的 Explorer。
这是"可回退"比"能注入"更难的地方。
2. Win10:原生宿主和任务栏布局
Win10 的任务栏时钟是原生 TrayClockWClass。UCalendar 不是简单盖一层透明窗口,而是接管这个时钟窗口的绘制:保留原生窗口的位置和交互,在其上画自己的内容。
一旦自定义内容比原生时钟宽,就会碰到任务栏左侧布局:
- 时钟向左扩展时,
SysPager、输入法、DynamicContent2等内容也要同步左移; - 任务栏高度、图标区域高度要按当前
Shell_TrayWnd重排; - 用户切换"小任务栏按钮"时,Rust 通过
RegNotifyChangeKeyValue监听TaskbarSmallIcons,等 Explorer 重排后自动重新注入; - 自定义时钟自己画日期和天气时,不再强制关闭小任务栏按钮,尊重用户原来的选择。
这些细节不在任何公开 API 里,只能靠实际窗口结构和 Win10 沙箱回归一点点校准。
3. Win11:TAP 改写 XAML 文本
Win11 的任务栏时钟在 XAML 树里。UCalendar 通过 XAML diagnostics 的 TAP 接口拿到 TextBlock,把原生时间文本替换成自己的内容。
这条路的限制更明显:
- 不能直接往 TAP 里贴 PNG,天气改用 Unicode 字形;
- 需要处理 XAML 回调线程和 UI 线程的边界;
- 文本长度、换行、对齐都要在任务栏窄带里重新计算;
- 系统更新可能改变 XAML 结构,因此必须保留原生时钟回退路径。
换句话说,Win11 的"自定义时钟"更像是在系统的界面树上做一次受控改写,而不是画一个自己的窗口。
4. 输入:点击和右键仍然是系统时钟
如果只是画上去,用户点时钟打不开日历、右键没有菜单,体验会立刻穿帮。
UCalendar 在 Rust 侧保留了任务栏时钟的鼠标钩子:识别时钟区域后,左键继续走系统 flyout,右键走 UCalendar 的菜单。时钟区域通过 UIA 和窗口矩形组合定位,并处理 DPI 缩放、任务栏重建和 5 秒心跳重装,避免低级鼠标钩子被系统静默摘除。
这部分看起来不"炫",但它决定了自定义时钟是"一张贴图",还是"一个真正能用的系统时钟"。
四、单文件发行:DLL 和天气图标不能散落
UCalendar 一直坚持单文件 exe。任务栏时钟需要两个 DLL 和 11 个天气图标,如果让用户手动放置,就失去了单文件的意义。
构建时,src-tauri/build.rs 扫描 src-tauri/resources/taskbar-clock/,把 DLL 和图标通过 include_bytes! 嵌入 exe。运行时再解压到固定的数据目录:
text
<数据目录>/taskbar-clock/
├─ UCalendarClock.dll
├─ UCalendarClockOverlay.dll
└─ tbweather/
├─ 100.png
├─ 101.png
└─ ...
这里有两个关键设计:
- 固定目录,不使用版本号子目录。升级时覆盖同一路径,避免旧版本目录越积越多。
- 原子写入 + 锁定兜底。Explorer 正在使用 DLL 时直接覆盖会失败,此时先把旧文件改名,再写入新文件;下次注入使用新路径。
天气图标只保留 11 个规范码(100/101/104/150/302/304/305/400/501/503/999),由 Rust 把不同数据源的图标码归并到规范码,必要时再按天气文字兜底。这样既控制了体积,也避免天气接口换一套图标就整包膨胀。
五、天气和格式:把信息塞进任务栏窄带
天气部分这次也做了收口:
- 支持城市、区县、省份搜索,也保留热门城市;
- 区县结果显示为"市 · 区",避免只显示"玄武"这种脱离上下文的地名;
- 实况优先使用当前小时数据,天气文字、图标、风向和温度更贴近"现在";
- 请求失败时可以使用旧缓存,不让任务栏时钟因为网络问题变成空白。
格式引擎则把时间、日期、农历、节日、节气、时辰、城市、天气和温度统一成变量。设置页预览和实际渲染共用同一套格式语义,用户看到的预览不会和任务栏结果"两套逻辑"。
六、Pro 和 Lite 的边界
任务栏时钟是 Pro 功能。UCalendar 没有用运行时开关假装区分,而是在构建层面用 lite feature 做隔离:
- Pro 构建编译
taskbar_clock,嵌入 DLL 和图标,启动注入; - Lite 不编译任务栏时钟模块,不注入 DLL,不写时钟注册表,继续使用系统原生时钟;
- Lite 发布脚本不再构建任务栏 DLL,
check-lite会扫描构建产物,确认没有UCalendarClock相关资源。
这样做的好处是边界清晰:Lite 包更小,也不会因为"功能隐藏了但代码还在"产生误触和维护负担。Pro 用户则得到完整的自定义时钟能力。
七、质量验证
v2.8.3 发布前跑完了完整检查:
- 46 个前端自检;
- 316 个 Rust 测试(313 passed / 3 ignored);
- 菜单、设置页浏览器自检;
cargo clippy -D warnings;- Lite 构建与
check-lite扫描; - Win10 / Win11 两条渲染链路的回归检查,包括小任务栏按钮、天气图标位置和注入失败回退。
Pro / Lite 发布 exe 均使用 CN=UCalendar Studio 代码签名。
八、升级
- Pro 版:https://github.com/tobaba/UCalendar/releases/tag/v2.8.3
- Lite 版:https://github.com/tobaba/ucalendar-lite/releases/tag/v2.8.3
- 项目主页:https://tobaba.github.io/ucalendar-site/
如果你也在做 Windows 桌面常驻工具,欢迎把这篇当作一个参考:任务栏不是一个普通窗口,注入不是一个动作,而是一整套"能进去、能画出来、能点、还能退回来"的工程。