feat.数字时钟，白板功能修复

2026-06-20 23:54:26 +08:00 · 2026-05-18 08:30:40 +08:00
parent 9404a0b347
commit 93758fc083
28 changed files with 1729 additions and 81 deletions
--- a/.comate/specs/standby-digital-clock/doc.md
+++ b/.comate/specs/standby-digital-clock/doc.md
@@ -0,0 +1,291 @@
+# StandBy Digital Clock - iPhone 待机风格大数字时钟组件
+
+## 1. 需求场景与处理逻辑
+
+### 1.1 需求描述
+新增一个 4×2 尺寸的数字时钟桌面组件，视觉风格参考 iPhone 横屏充电时的 StandBy 待机显示——大面积、粗体、圆润的数字显示当前时间（HH:MM），数字采用不规则的自由排版（有微妙的垂直偏移，不在一条直线上），颜色使用 Monet 主题色而非纯黑/白，伴随数字切换时的流畅垂直滚动/翻转动画，下方显示日期信息。
+
+### 1.2 用户体验目标
+- 大字号、圆润粗体的数字时间，远距离一目了然
+- 数字采用不规则自由排版（微妙垂直偏移），营造 iPhone StandBy 那种有机、散漫的视觉节奏
+- 数字使用 Monet 主题色（跟随壁纸/用户选色的强调色），而非死板的纯黑/白
+- 数字变化时执行垂直滑动动画（旧数字向上滑出，新数字从下方滑入），类似翻页时钟效果
+- 冒号（:）有呼吸闪烁效果
+- 支持夜间/日间模式自动切换
+- 点击组件可打开世界时钟 AirApp
+- 支持时区配置（与现有桌面时钟共享设置体系）
+
+### 1.3 处理逻辑
+1. 组件加载时读取时区设置和秒针模式设置
+2. `DispatcherTimer` 每秒触发一次更新
+3. 当检测到分钟数变化时，触发分钟数字的垂直滑动动画
+4. 当检测到小时数变化时，触发小时数字的垂直滑动动画
+5. 冒号以 1 秒周期做透明度脉冲动画
+6. 每 tick 检查是否需要切换日间/夜间视觉模式
+
+## 2. 架构与技术方案
+
+### 2.1 组件架构
+遵循现有桌面组件架构模式：
+- 继承 `UserControl`，实现 `IDesktopComponentWidget`, `ITimeZoneAwareComponentWidget`, `IComponentPlacementContextAware`, `IComponentRuntimeContextAware`
+- AXAML 定义根布局结构，代码后置处理动画逻辑
+- 通过 `DesktopComponentDefinition` 注册到组件系统
+
+### 2.2 数字滚动动画技术方案
+采用 Avalonia `RenderTransform` + `DoubleTransition` 实现数字滚动：
+
+**核心思路**：每个数位（共 4 位：H1, H2, M1, M2）使用 `ClipToBounds` 的容器，内含一个垂直排列的 `StackPanel`，包含当前数字和下一个数字。切换时通过 `TranslateTransform.Y` 的 `DoubleTransition` 实现平滑滚动。
+
+```
+每位数字的结构：
+┌─ DigitClip (ClipToBounds=true) ──────────┐
+│  ┌─ DigitStack (TranslateTransform.Y) ──┐ │
+│  │  [当前数字 TextBlock]                  │ │
+│  │  [新数字 TextBlock]                    │ │
+│  └───────────────────────────────────────┘ │
+└───────────────────────────────────────────┘
+```
+
+当数字变化时：
+1. 在 StackPanel 底部添加新数字的 TextBlock
+2. 将 `TranslateTransform.Y` 从 0 动画过渡到 `-digitHeight`
+3. 动画完成后移除旧数字，重置 Y 为 0
+
+### 2.3 动画参数
+- 使用项目 `FluttermotionToken` 体系：滚动动画时长 `FluttermotionToken.Standard`（200ms）
+- 缓动函数：`CubicEaseOut`（与项目现有动画风格一致）
+- 冒号呼吸动画：透明度 1.0 → 0.3 → 1.0，周期 2 秒，使用 `DoubleTransition`
+
+### 2.4 尺寸与布局
+- 组件定义：`MinWidthCells = 4, MinHeightCells = 2`
+- 缩放规则：2:1 比例（与 WorldClock 一致）
+- 内部布局采用 `Viewbox` 包裹，确保在不同 cellSize 下自适应缩放
+- 数字字体大小：基准设计为 130px（在 Viewbox 内），实际显示由 Viewbox 缩放
+
+### 2.5 布局风格——不规则自由排版（iPhone StandBy 风格）
+iPhone StandBy 的数字不是规矩地排成一条直线，而是有微妙的垂直偏移和大小差异，营造出自由散漫、有机的视觉节奏：
+
+```
+  H1        H2     :     M1        M2
+  ↗↘       ↘↗           ↗↘       ↘↗
+  ↕+6      ↕+2     :     ↕+4      ↕+2
+  ↖ -3°    ↗ +4°   :     ↖ -1°    ↗ +5°
+  ←+6,↑-10 ←-2,↓+10      →+4,↑-3   ←-2,↓+12
+```
+
+每个数字有三个自由度：
+- **垂直偏移 (Y)**：H1=-10, H2=+10, 冒号=+8, M1=-3, M2=+12
+- **水平偏移 (X)**：H1=+6, H2=-2, 冒号=0, M1=+4, M2=-2  
+- **旋转角度 (Z)**：H1=-4°, H2=+3°, 冒号=-1°, M1=-2°, M2=+5°
+
+### 2.6 视觉风格——圆润粗体 + Monet 主题色
+- **字体**：`FontWeight.Bold`，配合较大的字号，视觉上圆润饱满
+- **颜色**：使用项目 Monet 主题色系统，数字颜色跟随 `AdaptiveAccentBrush` / `SystemAccentColor`，而非纯黑/白
+  - 数字颜色通过 `ComponentColorSchemeHelper.ShouldUseMonetColor()` 判断：
+    - 跟随系统：使用 `AdaptiveAccentBrush`（Monet 提取的强调色）
+    - 原生模式：使用组件自带的特色色彩
+  - 夜间模式：深色渐变背景 + 主题色数字（亮色调）
+  - 日间模式：浅色渐变背景 + 主题色数字（深色调）
+  - 夜间暗光环境：数字过渡到柔和的红色调（`#FF6B4A`），模拟 iPhone StandBy 夜间红色调
+- **冒号颜色**：与数字同色，但有呼吸动画
+- **日期行**：使用 `AdaptiveTextMutedBrush`（跟随主题的弱化文字色），字号约 14-16px 基准
+- **根容器圆角**：`DesignCornerRadiusComponent`（遵循圆角规范）
+
+## 3. 受影响文件
+
+### 3.1 新增文件
+| 文件 | 类型 | 说明 |
+|------|------|------|
+| `LanMountainDesktop/Views/Components/StandbyDigitalClockWidget.axaml` | 新增 | 组件 AXAML 布局 |
+| `LanMountainDesktop/Views/Components/StandbyDigitalClockWidget.axaml.cs` | 新增 | 组件代码后置（动画逻辑、时间更新、模式切换） |
+
+### 3.2 修改文件
+| 文件 | 修改类型 | 受影响函数/区域 |
+|------|----------|-----------------|
+| `LanMountainDesktop/ComponentSystem/BuiltInComponentIds.cs` | 新增常量 | 新增 `DesktopStandbyDigitalClock` 常量 |
+| `LanMountainDesktop/ComponentSystem/ComponentRegistry.cs` | 新增定义 | `CreateDefault()` 中新增组件定义 |
+| `LanMountainDesktop/Views/Components/DesktopComponentRuntimeRegistry.cs` | 新增运行时注册 | `GetDefaultRegistrations()` 中新增运行时注册项 |
+| `LanMountainDesktop/Views/MainWindow.ComponentSystem.cs` | 新增缩放规则 | `NormalizeAspectRatioForComponent()` 中为 StandbyDigitalClock 添加 2:1 缩放规则 |
+
+## 4. 实现细节
+
+### 4.1 BuiltInComponentIds 新增常量
+```csharp
+public const string DesktopStandbyDigitalClock = "DesktopStandbyDigitalClock";
+```
+
+### 4.2 ComponentRegistry 新增定义
+```csharp
+new DesktopComponentDefinition(
+    BuiltInComponentIds.DesktopStandbyDigitalClock,
+    "StandBy Clock",
+    "Clock",
+    "Clock",
+    MinWidthCells: 4,
+    MinHeightCells: 2,
+    AllowStatusBarPlacement: false,
+    AllowDesktopPlacement: true),
+```
+
+### 4.3 DesktopComponentRuntimeRegistry 新增注册
+```csharp
+new DesktopComponentRuntimeRegistration(
+    BuiltInComponentIds.DesktopStandbyDigitalClock,
+    "component.standby_digital_clock",
+    () => new StandbyDigitalClockWidget()),
+```
+
+### 4.4 NormalizeAspectRatioForComponent 缩放规则
+在 `case BuiltInComponentIds.DesktopWorldClock:` 的同一分支中添加 `BuiltInComponentIds.DesktopStandbyDigitalClock`，使用 2:1 比例规则。
+
+### 4.5 AXAML 布局结构
+```xml
+<UserControl x:Class="LanMountainDesktop.Views.Components.StandbyDigitalClockWidget">
+    <Border x:Name="RootBorder"
+            CornerRadius="{DynamicResource DesignCornerRadiusComponent}"
+            ClipToBounds="True"
+            Padding="14">
+        <!-- 背景在代码后置中设置（渐变，与AnalogClockWidget一致） -->
+        <Viewbox Stretch="Uniform">
+            <Grid Width="400" Height="200">
+                <StackPanel VerticalAlignment="Center"
+                            HorizontalAlignment="Center"
+                            Orientation="Horizontal">
+                    <!-- H1 数位 -->
+                    <Border x:Name="H1Clip" ClipToBounds="True" ...>
+                        <Panel x:Name="H1Stack" ...>
+                            <TextBlock x:Name="H1Text" Text="0" ... />
+                        </Panel>
+                    </Border>
+                    <!-- H2 数位 -->
+                    <Border x:Name="H2Clip" ClipToBounds="True" ...>
+                        <Panel x:Name="H2Stack" ...>
+                            <TextBlock x:Name="H2Text" Text="0" ... />
+                        </Panel>
+                    </Border>
+                    <!-- 冒号 -->
+                    <TextBlock x:Name="ColonText" Text=":" ... />
+                    <!-- M1 数位 -->
+                    <Border x:Name="M1Clip" ClipToBounds="True" ...>
+                        <Panel x:Name="M1Stack" ...>
+                            <TextBlock x:Name="M1Text" Text="0" ... />
+                        </Panel>
+                    </Border>
+                    <!-- M2 数位 -->
+                    <Border x:Name="M2Clip" ClipToBounds="True" ...>
+                        <Panel x:Name="M2Stack" ...>
+                            <TextBlock x:Name="M2Text" Text="0" ... />
+                        </Panel>
+                    </Border>
+                </StackPanel>
+                <!-- 日期行 -->
+                <TextBlock x:Name="DateTextBlock"
+                           VerticalAlignment="Bottom"
+                           HorizontalAlignment="Center" ... />
+            </Grid>
+        </Viewbox>
+    </Border>
+</UserControl>
+```
+
+### 4.6 数字滚动动画核心代码（伪代码）
+```csharp
+private void AnimateDigit(Border clip, Panel stack, TextBlock currentText, char newDigit, double digitHeight)
+{
+    var oldText = currentText;
+    var newTextBlock = new TextBlock
+    {
+        Text = newDigit.ToString(),
+        FontSize = oldText.FontSize,
+        FontWeight = oldText.FontWeight,
+        Foreground = oldText.Foreground,
+        Width = oldText.Width,
+        Height = digitHeight,
+        // 复制旧文本的所有样式属性
+    };
+    stack.Children.Add(newTextBlock);
+
+    // 应用 TranslateTransform 过渡动画
+    var transform = new TranslateTransform { Y = 0 };
+    stack.RenderTransform = transform;
+    stack.Transitions = new Transitions
+    {
+        new DoubleTransition(TranslateTransform.YProperty, FluttermotionToken.Standard, new CubicEaseOut())
+    };
+
+    // 触发动画：从当前位置滑到 -digitHeight
+    transform.Y = -digitHeight;
+
+    // 动画完成后清理
+    _ = DispatcherTimer.RunOnce(() =>
+    {
+        stack.Children.Remove(oldText);
+        transform.Y = 0;
+        stack.Transitions = null; // 移除过渡，避免重置时再次动画
+        // 更新引用
+        UpdateCurrentTextReference(newTextBlock);
+    }, FluttermotionToken.Standard);
+}
+```
+
+### 4.7 冒号呼吸动画
+使用 `DispatcherTimer` 每秒切换冒号透明度：
+```csharp
+private void ToggleColonOpacity()
+{
+    _colonVisible = !_colonVisible;
+    ColonText.Opacity = _colonVisible ? 1.0 : 0.3;
+}
+```
+配合 `DoubleTransition` 使透明度变化平滑过渡。
+
+### 4.8 日间/夜间模式
+与 `AnalogClockWidget` 使用完全相同的判断逻辑：
+- 检查 `ActualThemeVariant`
+- 回退到 `AdaptiveSurfaceBaseBrush` 亮度计算
+- 夜间模式：深色渐变背景 + 浅色数字
+- 日间模式：浅色渐变背景 + 深色数字
+
+### 4.9 时区与设置
+- 复用 `AnalogClockWidget` 的时区解析和设置加载逻辑
+- 使用 `ComponentSettingsSnapshot.DesktopClockTimeZoneId` 读取时区配置
+- 点击打开世界时钟 AirApp
+
+## 5. 边界条件与异常处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 组件首次加载时数字尚未初始化 | 在构造函数中初始化所有数字为当前时间，不触发动画 |
+| 快速连续触发数字变化（如时间同步导致跳变） | 在动画完成前忽略新的变化请求，或中断当前动画立即跳转到目标值 |
+| cellSize 极小或极大 | `ApplyCellSize` 中 clamp 缩放因子（0.58-1.95，与 AnalogClockWidget 一致） |
+| 时区切换 | 重新加载设置并更新所有数字（无动画，直接设置） |
+| 主题切换 | 通过 `ApplyModeVisualIfNeeded()` 在下一个 tick 自动检测并切换 |
+| 组件被销毁 | `DetachedFromVisualTree` 停止 timer，清理资源 |
+| 冒号动画在组件不可见时 | timer 仍在运行但 Opacity 变化无性能开销；若需要可结合 `IDesktopPageVisibilityAwareComponentWidget` |
+
+## 6. 数据流路径
+
+```
+DispatcherTimer (1s interval)
+    → OnTimerTick
+        → 计算当前时间 (TimeZoneInfo.ConvertTimeFromUtc)
+        → 比较新旧时间数字
+        → 若有变化: AnimateDigit() 执行滚动动画
+        → ToggleColonOpacity() 切换冒号
+        → ApplyModeVisualIfNeeded() 检查日/夜间切换
+        → UpdateDateText() 更新日期文本
+
+用户点击 → OnPointerReleased → AirAppLauncherServiceProvider.OpenWorldClock()
+
+时区变更 → TimeZoneChanged event → RefreshFromSettings() → 无动画更新所有数字
+```
+
+## 7. 预期成果
+
+- 在桌面组件选择器中新增 "StandBy Clock" 组件，位于 Clock 分类
+- 拖放到桌面后显示 4×2 大数字时钟
+- 数字切换时有流畅的垂直滑动动画
+- 冒号有呼吸闪烁效果
+- 支持日间/夜间自动切换
+- 支持时区配置
+- 支持组件缩放（2:1 比例规则）
--- a/.comate/specs/standby-digital-clock/summary.md
+++ b/.comate/specs/standby-digital-clock/summary.md
@@ -0,0 +1,52 @@
+# StandBy Digital Clock 实现总结
+
+## 完成状态
+全部任务已完成，构建通过（0 错误）。
+
+## 变更清单
+
+### 新增文件
+| 文件 | 说明 |
+|------|------|
+| `LanMountainDesktop/Views/Components/StandbyDigitalClockWidget.axaml` | AXAML 布局：不规则自由排版数字 + 冒号 + 日期，Monet 主题色绑定 |
+| `LanMountainDesktop/Views/Components/StandbyDigitalClockWidget.axaml.cs` | 代码后置：数字滚动动画、冒号呼吸、Monet 主题色、日/夜模式、时区支持 |
+
+### 修改文件
+| 文件 | 改动 |
+|------|------|
+| `LanMountainDesktop/ComponentSystem/BuiltInComponentIds.cs` | 新增 `DesktopStandbyDigitalClock` 常量 |
+| `LanMountainDesktop/ComponentSystem/ComponentRegistry.cs` | 在 `CreateDefault()` 中新增 4×2 Clock 分类组件定义 |
+| `LanMountainDesktop/Views/Components/DesktopComponentRuntimeRegistry.cs` | 新增 `StandbyDigitalClockWidget` 运行时注册 |
+| `LanMountainDesktop/Views/MainWindow.ComponentSystem.cs` | `NormalizeAspectRatioForComponent` 将 StandbyDigitalClock 加入 2:1 缩放规则 |
+
+## 核心设计要点
+
+### 不规则自由排版（iPhone StandBy 风格）
+- 每个数字有独立的垂直 Margin 偏移（H1 上移10, H2 下移8, M1 上移5, M2 下移10）
+- 冒号比数字中心略低（下移6）
+- 数字间距不等，营造自由散漫的视觉节奏
+
+### Monet 主题色
+- 数字和冒号使用 `AdaptiveAccentBrush` / `SystemAccentColor`，跟随壁纸/用户选色的强调色
+- 通过 `ComponentColorSchemeHelper.ShouldUseMonetColor()` 判断：
+  - 跟随系统：使用 Monet 提取的强调色
+  - 原生模式：使用暖橙红色（`#E84530` 日间 / `#FF8A65` 夜间），灵感来自 iPhone StandBy
+- 日期文本使用 `AdaptiveTextMutedBrush`
+
+### 数字滚动动画
+- `TranslateTransform.Y` + `DoubleTransition`（200ms CubicEaseOut）
+- 动画完成后清理旧 TextBlock 并重置 transform
+
+### 冒号呼吸
+- 每秒切换 Opacity（1.0 ↔ 0.25），配合 400ms CubicEaseInOut 平滑过渡
+
+### 日/夜模式
+- 检测 `ActualThemeVariant` + `AdaptiveSurfaceBaseBrush` 亮度计算
+- 夜间：深色渐变背景 + 亮调强调色数字
+- 日间：浅色渐变背景 + 深调强调色数字
+
+### 组件规格
+- 尺寸：4×2 (MinWidthCells=4, MinHeightCells=2)
+- 分类：Clock
+- 缩放：2:1 比例 (Proportional)
+- 字体：FontWeight.Bold, 120px 基准
--- a/.comate/specs/standby-digital-clock/tasks.md
+++ b/.comate/specs/standby-digital-clock/tasks.md
@@ -0,0 +1,25 @@
+# StandBy Digital Clock 任务计划
+
+- [x] Task 1: 注册组件定义与运行时
+    - 1.1: 在 `BuiltInComponentIds.cs` 中新增 `DesktopStandbyDigitalClock` 常量
+    - 1.2: 在 `ComponentRegistry.cs` 的 `CreateDefault()` 中新增 `DesktopComponentDefinition`（4×2, Clock 分类, Proportional）
+    - 1.3: 在 `DesktopComponentRuntimeRegistry.cs` 的 `GetDefaultRegistrations()` 中新增运行时注册项
+    - 1.4: 在 `MainWindow.ComponentSystem.cs` 的 `NormalizeAspectRatioForComponent()` 中为 StandbyDigitalClock 添加 2:1 缩放规则
+
+- [x] Task 2: 创建 StandbyDigitalClockWidget AXAML 布局
+    - 2.1: 创建 `StandbyDigitalClockWidget.axaml`，定义 RootBorder（DesignCornerRadiusComponent）、Viewbox、时间数字区域（4 个 ClipToBounds 数位容器 + 冒号）、日期文本
+    - 2.2: 确保 Viewbox 内基准设计尺寸为 400×200，数字使用 FontWeight.Bold，冒号和日期布局合理
+
+- [x] Task 3: 实现组件代码后置（核心逻辑与动画）
+    - 3.1: 创建 `StandbyDigitalClockWidget.axaml.cs`，实现 `IDesktopComponentWidget`, `ITimeZoneAwareComponentWidget`, `IComponentPlacementContextAware`, `IComponentRuntimeContextAware` 接口
+    - 3.2: 实现 DispatcherTimer 每秒更新逻辑，比较新旧时间数字，触发数位滚动动画
+    - 3.3: 实现数字垂直滚动动画：每位数字使用 TranslateTransform.Y + DoubleTransition，旧数字上滑出新数字滑入，动画完成后清理
+    - 3.4: 实现冒号呼吸动画：每秒切换透明度，配合 DoubleTransition 平滑过渡
+    - 3.5: 实现日间/夜间模式切换：检测 ActualThemeVariant 和亮度，切换背景渐变和数字颜色；夜间暗光环境过渡到红色调
+    - 3.6: 实现 ApplyCellSize 缩放逻辑，clamp 缩放因子，更新圆角和间距
+    - 3.7: 实现时区设置加载（复用 AnalogClockWidget 逻辑），点击打开世界时钟 AirApp
+    - 3.8: 实现日期文本更新逻辑，显示完整日期和星期
+
+- [x] Task 4: 构建验证与调试
+    - 4.1: 执行 `dotnet build` 确保编译通过，修复所有错误
+    - 4.2: 检查圆角规范合规性（根容器使用 DesignCornerRadiusComponent）