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

把 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 代码签名。

八、升级

如果你也在做 Windows 桌面常驻工具,欢迎把这篇当作一个参考:任务栏不是一个普通窗口,注入不是一个动作,而是一整套"能进去、能画出来、能点、还能退回来"的工程。

相关推荐
ucfar5 天前
任务栏时钟"点开"那件事:Tauri 2 + Rust 多窗口架构复盘
ucalendar