AntdClock 时钟控件使用说明

一个纯 GDI+ 自绘的 WinForms 圆形时钟控件（AntdUIClock.AntdClock）， 支持透明异形叠加、渐变/背景图表盘、内嵌日历、铭牌 LOGO、拖动与双击交互， 并可通过 app.config 在不改代码的前提下更换铭牌。

说明：下载附件为应用示例，含控件dll，非源码！

目标框架：.NET 8 Windows（net8.0-windows）

属性示例

BDClock.exe运行效果（示例）

一、目录结构

AntdUIClock.dll是控件
BDClock.exe是实例（可换logo或铭牌信息）

二、核心特点

1. 纯 GDI+ 自绘，零第三方绘制依赖

控件本体（AntdClock）只依赖 System.Drawing，所有表盘、刻度、指针、日历、铭牌全部代码绘制。 AntdUI 包只被控件自带的演示窗体用到，业务项目引用 AntdUIClock.dll 时不需要引入 AntdUI。

2. 真·圆形异形控件

OnHandleCreated / OnResize 中用 GraphicsPath.AddEllipse + Region 裁剪窗口区域， 控件是真正的圆形，圆外区域不响应鼠标、不遮挡下层内容。 SetBoundsCore 强制等比正方形（边长取 max(宽, 高)），拖放拉伸不会变形。

3. 三级表盘背景，优先级清晰

4. 分层指针绘制

• 时针 / 分针：前 1/3 用一半线宽、后 2/3 用正常线宽的双段画法（DrawHourHand / DrawMinuteHand），带圆角线帽，立体感更强。
• 秒针：丝滑模式（角度含毫秒，100ms 刷新），可开启箭头（SecondArrow）。
• 三层同心中心圆：时针 7 / 分针 5 / 秒针 3（半径 px），颜色自动跟随对应指针色。

5. 表盘刻度

• 12 个整点文字：阿拉伯数字 / 罗马数字（Ⅰ-Ⅻ）/ 无文字，罗马数字自动切 Segoe UI Symbol 字体。
• 60 格短刻度，每 5 格自动加长加粗。
• 可通过 ClockNumbers 自定义 12 个刻度文本（代码赋值，属性窗口隐藏）。

6. 内嵌日历窗

不是独立控件，直接画在表盘内部，可 8 向定位： Top / Bottom / Left / Right / TopLeft / TopRight / BottomLeft / BottomRight， 支持"月-日"单行或"月-日 + 星期"双行、实线/虚线边框、独立前景/背景色。

7. 铭牌 LOGO（图片优先于文本）

• 有 nameplate.png 或配置了 NameplateImage → 显示图片（支持 DPI 缩放 + 0~255 透明度）。
• 无图片 → 显示 NameplateText 文本（12 点正下方，NameplateOffsetY 调上下位置）。
• 图片尺寸/透明度/偏移均可在属性窗口直接调。

8. 丰富的交互

9. 4 套预置主题（双击表芯循环切换）

10. DPI 感知

所有尺寸（指针宽度、刻度线宽、日历框、字体、铭牌）统一走 GetDpiScaledSize()， dpiScale = DpiX / 96 并钳制在 0.8 ~ 1.1，高 DPI 下不会糊也不会过度放大。 铭牌额外提供 NameplateDpiAware / NameplateImageDpiAware 独立开关。

11. 配置外置

铭牌文本、铭牌图片名、铭牌偏移、日历距离可从 app.config 读取， 换 LOGO 只改配置文件 + 换 png，无需重新编译。

12. 资源管理

Dispose 中统一释放 Timer、SoundPlayer、表盘背景图、铭牌图、日历字体； NameplateImage setter 也会自动释放旧图，避免频繁换图内存泄漏。

三、快速开始

方式 A：引用 DLL（推荐，业务项目无需 AntdUI）

<!-- BDClock.csproj -->
<ItemGroup>
  <Reference Include="AntdUIClock">
    <HintPath>bin\Debug\net8.0-windows\AntdUIClock.dll</HintPath>
  </Reference>
</ItemGroup>

方式 B：设计器拖放

编译 AntdUIClock 项目 → 在目标窗体设计器中右键工具箱 → "选择项" → 浏览 AntdUIClock.dll → AntdClock 会出现在工具箱，直接拖到窗体上，然后在属性窗口按分类调节 （表盘样式 / 指针样式 / 日历样式 / 铭牌样式 / 交互控制 / 秒针音效）。

方式 C：纯代码创建（桌面时钟）

using AntdUIClock;

var clock = new AntdClock
{
    Size              = new Size(250, 250),
    DragTarget        = DragTarget.ParentForm,               // 拖动整个窗口
    CalDblClickAction = DoubleClickCalendarAction.CloseParentForm, // 双击日历退出
    ClockNumberStyle  = ClockNumberStyles.Arabic,
    ClockGradientMode = ClockGradientMode.EdgeToCenter,
    ClockBorderWidth  = 0,
    SecondColor       = Color.Orange,
    CalDistance       = 65f,
    NameplateOffsetY  = 10f,
    NameplateImageSize= new Size(64, 64),
    NameplateText     = "JIUAI",        // 无图片时生效
    Parent            = this,
};
Controls.Add(clock);
clock.BringToFront();

做成桌面透明时钟（关键 4 行）

FormBorderStyle = FormBorderStyle.None;
TopMost         = true;
ShowInTaskbar   = false;
BackColor       = Color.Magenta;   // 透明键色
TransparencyKey = Color.Magenta;   // 与 BackColor 同色 → 该色全透明
Opacity         = 0.7;             // 可选：整体半透明

四、属性参考

表盘样式

BackColor 已重写为强制透明并在属性窗口隐藏，请统一使用 ClockBackColor。

指针样式

只读同步属性：HourCenterColor / MinuteCenterColor / SecondCenterColor，自动等于对应指针色。

日历样式

铭牌样式

交互控制 / 音效

五、配置文件（BDClock.dll.config）

宿主程序编译后，App.config 会输出为 BDClock.dll.config（与 exe 同目录）。 控件启动时通过内部 ClockConfig 读取，只覆盖"用户配置过的项"，其余保持默认值。

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <!-- 铭牌文本 -->
    <add key="NameplateText" value="JIUAI" />
    <!-- 铭牌图片名（放在exe同目录，不需要路径） -->
    <add key="NameplateImage" value="nameplate.png" />
    <!-- 铭牌垂直偏移（纯数字，不要带 f 后缀） -->
    <add key="NameplateOffsetY" value="10" />
    <!-- 日历距离中心（纯数字，不要带 f 后缀） -->
    <add key="CalDistance" value="65" />
    <!-- 表盘数字样式：Arabic（数字 1-12）/ Roman（罗马数字 Ⅰ-Ⅻ）/ None（无刻度文字） -->
    <add key="ClockNumberStyle" value="Arabic" />
  </appSettings>
</configuration>