mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-22 09:14:25 +08:00
Migrate to Avalonia 12 and Plugin SDK v5
Upgrade project to the Avalonia 12 baseline and Plugin SDK v5: centralize Avalonia packages, remove legacy WebView.Avalonia usage (use NativeWebView/WebView2 EnvironmentRequested), and update Fluent/Material icon/package usages. Bump multiple package/project versions to 5.0.0 and Avalonia 12.0.1, update plugin template and README/docs to SDK v5, and add PLUGIN_SDK_V5_MIGRATION.md. Also fix runtime/behavior bugs: make DataLocationResolver use a fixed bootstrap launcher data path and avoid recursive ResolveDataRoot; add legacy-state handling and extraction in OobeStateService; and update component settings tests to reflect migrated storage (DB/backup) and reset cache for test reloads. Various csproj, tests, and docs updated to reflect the migration and ensure build/test compatibility.
This commit is contained in:
lincube
@@ -1,14 +1,21 @@
|
||||
# Checklist
|
||||
|
||||
- [ ] `SettingsWindow.ApplyChromeMode()` 不再使用 `ExtendClientAreaChromeHints` 和 `SystemDecorations`
|
||||
- [ ] `ComponentEditorWindow.ApplyChromeMode()` 不再使用 `ExtendClientAreaChromeHints` 和 `SystemDecorations`
|
||||
- [ ] 所有 `.axaml` 文件中的 `SystemDecorations` 已替换为 `WindowDecorations`
|
||||
- [ ] `MainWindow.ComponentSystem.cs` 中 `centerLeft` 和 `positions` 变量已正确定义
|
||||
- [ ] `MainWindow.DesktopPaging.cs` 中 `child` 和 `_isThreeFingerOrRightDragSwipeActive` 变量已正确定义
|
||||
- [ ] `App.axaml.cs` 中 `BindingPlugins.DataValidators` 代码已移除
|
||||
- [ ] `DesktopComponentFailureView.cs` 使用 `ClipboardExtensions.SetTextAsync`
|
||||
- [ ] `MonetColorService.cs` 使用正确的 `Bitmap.CopyPixels` 签名
|
||||
- [ ] `SettingsWindow.axaml.cs` 使用 `FluentIcons.Avalonia.FluentIcon` 替代 `SymbolIconSource`
|
||||
- [ ] 所有 `TextBox.Watermark` 已替换为 `PlaceholderText`
|
||||
- [ ] `dotnet build LanMountainDesktop.slnx -c Debug` 0 errors, 0 warnings（过时 API 警告）
|
||||
- [ ] `dotnet test LanMountainDesktop.slnx -c Debug` 全部通过
|
||||
- [x] `Directory.Packages.props` contains the Avalonia 12 dependency baseline.
|
||||
- [x] Main host references `Avalonia.Controls.WebView`.
|
||||
- [x] Source no longer references `WebView.Avalonia`, `AvaloniaWebView`, or `.UseDesktopWebView()`.
|
||||
- [x] `BrowserWidget` uses `NativeWebView.Source`, `Navigate`, `Refresh()`, `NavigationStarted`, and `EnvironmentRequested`.
|
||||
- [x] WebView blanking navigates to `about:blank`.
|
||||
- [x] Plugin SDK package version is `5.0.0`.
|
||||
- [x] `PluginSdkInfo.ApiVersion` is `5.0.0`.
|
||||
- [x] Plugin template package version default is `5.0.0`.
|
||||
- [x] Plugin template manifest `apiVersion` is `5.0.0`.
|
||||
- [x] Launcher data location config resolution cannot recurse through `ResolveDataRoot()`.
|
||||
- [x] `OobeStateServiceTests` pass.
|
||||
- [x] `dotnet build LanMountainDesktop.slnx -c Debug` has 0 errors.
|
||||
- [x] `dotnet test LanMountainDesktop.slnx -c Debug` completes without a test host stack overflow.
|
||||
- [ ] Windows host smoke test completed.
|
||||
- [ ] Windows Launcher smoke test completed.
|
||||
- [ ] Settings window FluentAvalonia 3 smoke test completed.
|
||||
- [ ] Component editor Material smoke test completed.
|
||||
- [ ] BrowserWidget navigation/refresh/page activation smoke test completed.
|
||||
- [ ] WebView2 missing-runtime diagnostic smoke test completed.
|
||||
|
||||
@@ -1,63 +1,49 @@
|
||||
# Avalonia 12 迁移规格
|
||||
# Avalonia 12 Full Stack Migration
|
||||
|
||||
## Why
|
||||
## Summary
|
||||
|
||||
Avalonia 12 带来性能改进（SkiaSharp 3.0、编译绑定默认开启）、新的窗口装饰体系（WindowDrawnDecorations）和更简洁的 API 设计。项目当前已升级包引用，但存在 18 个编译错误和若干过时 API 警告，需要系统性修复以确保构建通过。
|
||||
LanMountainDesktop has moved its desktop stack to the Avalonia 12 baseline. The migration covers the main host, Launcher, Plugin SDK, plugin runtime loading policy, official WebView usage, ClassIsland Markdown, FluentAvalonia, FluentIcons, and Material-related dependencies.
|
||||
|
||||
## What Changes
|
||||
## Requirements
|
||||
|
||||
- **BREAKING**: 移除 `ExtendClientAreaChromeHints` 和 `SystemDecorations` 的使用，迁移到 `WindowDecorations`
|
||||
- **BREAKING**: 移除 `BindingPlugins.DataValidators` 的使用（v12 已移除绑定插件体系）
|
||||
- **BREAKING**: 替换 `IClipboard.SetTextAsync` 为 `ClipboardExtensions.SetTextAsync`
|
||||
- **BREAKING**: 更新 `Bitmap.CopyPixels` 调用签名（移除 `AlphaFormat` 参数）
|
||||
- **BREAKING**: 替换 `FluentIcons.Avalonia.SymbolIconSource` 为 v3 等效 API
|
||||
- 修复 `MainWindow.ComponentSystem.cs` 和 `MainWindow.DesktopPaging.cs` 中缺失的字段/变量
|
||||
- 批量替换 `TextBox.Watermark` → `PlaceholderText`
|
||||
### Requirement: Centralized Avalonia 12 dependency baseline
|
||||
|
||||
## Impact
|
||||
The solution SHALL use central package management for direct Avalonia-facing projects and keep the core UI dependency baseline on Avalonia `12.0.1`.
|
||||
|
||||
- 受影响代码：
|
||||
- `LanMountainDesktop/Views/SettingsWindow.axaml.cs`
|
||||
- `LanMountainDesktop/Views/ComponentEditorWindow.axaml.cs`
|
||||
- `LanMountainDesktop/Views/MainWindow.ComponentSystem.cs`
|
||||
- `LanMountainDesktop/Views/MainWindow.DesktopPaging.cs`
|
||||
- `LanMountainDesktop/App.axaml.cs`
|
||||
- `LanMountainDesktop/Views/Components/DesktopComponentFailureView.cs`
|
||||
- `LanMountainDesktop/Services/MonetColorService.cs`
|
||||
- 13 个 `.axaml` 文件（`SystemDecorations` → `WindowDecorations`）
|
||||
- 7 个 `.cs` 文件 + 7 个 `.axaml` 文件（`Watermark` → `PlaceholderText`）
|
||||
- 受影响规格：无现有规格直接关联
|
||||
Required package baseline:
|
||||
|
||||
## ADDED Requirements
|
||||
- `Avalonia*` `12.0.1`
|
||||
- `Avalonia.Controls.WebView` `12.0.0`
|
||||
- `ClassIsland.Markdown.Avalonia` `12.0.0`
|
||||
- `FluentAvaloniaUI` `3.0.0-preview1`
|
||||
- `FluentIcons.Avalonia` `2.1.325`
|
||||
- `Material.Avalonia` `3.16.0`
|
||||
- `Material.Icons.Avalonia` `3.0.2`
|
||||
|
||||
### Requirement: 窗口装饰 API 迁移
|
||||
系统 SHALL 使用 Avalonia 12 的 `WindowDecorations` 属性替代已移除的 `SystemDecorations` 和 `ExtendClientAreaChromeHints`。
|
||||
### Requirement: Official WebView
|
||||
|
||||
#### Scenario: SettingsWindow 无边框模式
|
||||
- **WHEN** `ApplyChromeMode(false)` 被调用
|
||||
- **THEN** `WindowDecorations = WindowDecorations.BorderOnly` 且 `ExtendClientAreaToDecorationsHint = true`
|
||||
The host SHALL use `Avalonia.Controls.NativeWebView` for the browser widget and SHALL NOT reference `WebView.Avalonia`, `AvaloniaWebView`, or `.UseDesktopWebView()`.
|
||||
|
||||
#### Scenario: SettingsWindow 系统 Chrome 模式
|
||||
- **WHEN** `ApplyChromeMode(true)` 被调用
|
||||
- **THEN** `WindowDecorations = WindowDecorations.Full` 且 `ExtendClientAreaToDecorationsHint = true`
|
||||
Windows WebView2 user data configuration SHALL be supplied through `EnvironmentRequested` using `WindowsWebView2EnvironmentRequestedEventArgs.UserDataFolder`.
|
||||
|
||||
### Requirement: 剪贴板 API 迁移
|
||||
系统 SHALL 使用 Avalonia 12 的 `ClipboardExtensions.SetTextAsync` 替代已移除的 `IClipboard.SetTextAsync`。
|
||||
### Requirement: Plugin SDK v5
|
||||
|
||||
### Requirement: Bitmap.CopyPixels 签名更新
|
||||
系统 SHALL 使用新的 `CopyPixels` 签名，不再传入 `AlphaFormat` 参数。
|
||||
The Plugin SDK API baseline SHALL be `5.0.0`. SDK v4 plugins are treated as incompatible until rebuilt.
|
||||
|
||||
### Requirement: FluentIcons v3 API 适配
|
||||
系统 SHALL 使用 `FluentIcons.Avalonia.FluentIcon` 替代已移除的 `SymbolIconSource`。
|
||||
The SDK SHALL keep the existing public UI extension shape, including `SettingsPageBase` and Avalonia `Control` based desktop components.
|
||||
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Launcher data location stability
|
||||
|
||||
### Requirement: 编译绑定验证
|
||||
- **修改前**：`BindingPlugins.DataValidators.RemoveAt(0)` 移除默认数据注解验证插件
|
||||
- **修改后**：v12 默认禁用数据注解验证插件，无需手动移除
|
||||
Launcher data location configuration SHALL be read from a fixed bootstrap Launcher data directory so resolving the selected data root cannot recursively require resolving itself.
|
||||
|
||||
## REMOVED Requirements
|
||||
### Requirement: OOBE state compatibility
|
||||
|
||||
### Requirement: ExtendClientAreaChromeHints 配置
|
||||
**Reason**: Avalonia 12 移除此属性，由 `WindowDecorations` 统一管理
|
||||
**Migration**: 删除所有 `ExtendClientAreaChromeHints` 赋值代码
|
||||
The Launcher SHALL read current OOBE state from the resolved `Launcher/state` directory and SHALL continue to migrate the legacy `.launcher/state/first_run_completed` marker.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- `dotnet build LanMountainDesktop.slnx -c Debug` completes with 0 errors.
|
||||
- `OobeStateServiceTests` pass.
|
||||
- Full `dotnet test LanMountainDesktop.slnx -c Debug` no longer aborts from `DataLocationResolver` recursion.
|
||||
- Plugin template defaults to SDK package version `5.0.0` and manifest `apiVersion` `5.0.0`.
|
||||
- Current developer documentation points to SDK v5 and Avalonia 12.
|
||||
|
||||
@@ -1,39 +1,18 @@
|
||||
# Tasks
|
||||
|
||||
- [ ] Task 1: 修复窗口装饰 API（Phase 1）
|
||||
- [x] SubTask 1.1: 重写 `SettingsWindow.ApplyChromeMode()` 移除 `ExtendClientAreaChromeHints`
|
||||
- [x] SubTask 1.2: 重写 `ComponentEditorWindow.ApplyChromeMode()` 移除 `ExtendClientAreaChromeHints`
|
||||
- [x] SubTask 1.3: 批量替换所有 `.axaml` 中的 `SystemDecorations` → `WindowDecorations`
|
||||
- [ ] SubTask 1.4: 验证构建错误减少
|
||||
|
||||
- [ ] Task 2: 修复 MainWindow 编译错误（Phase 2）
|
||||
- [ ] SubTask 2.1: 修复 `MainWindow.ComponentSystem.cs` 中 `centerLeft` 和 `positions` 未定义错误
|
||||
- [ ] SubTask 2.2: 修复 `MainWindow.DesktopPaging.cs` 中 `child` 和 `_isThreeFingerOrRightDragSwipeActive` 未定义错误
|
||||
- [ ] SubTask 2.3: 验证构建错误减少
|
||||
|
||||
- [ ] Task 3: 修复 Avalonia 12 API 变更（Phase 3）
|
||||
- [ ] SubTask 3.1: 移除 `App.axaml.cs` 中 `BindingPlugins.DataValidators` 代码
|
||||
- [ ] SubTask 3.2: 替换 `DesktopComponentFailureView.cs` 中 `IClipboard.SetTextAsync` 为 `ClipboardExtensions.SetTextAsync`
|
||||
- [ ] SubTask 3.3: 更新 `MonetColorService.cs` 中 `Bitmap.CopyPixels` 调用签名
|
||||
- [ ] SubTask 3.4: 验证构建错误减少
|
||||
|
||||
- [ ] Task 4: 修复第三方库变更（Phase 4）
|
||||
- [ ] SubTask 4.1: 替换 `SettingsWindow.axaml.cs` 中 `FluentIcons.Avalonia.SymbolIconSource` 为 `FluentIcon`
|
||||
- [ ] SubTask 4.2: 验证构建错误减少
|
||||
|
||||
- [ ] Task 5: 清理过时属性（Phase 5）
|
||||
- [ ] SubTask 5.1: 批量替换 `.cs` 文件中 `Watermark` → `PlaceholderText`
|
||||
- [ ] SubTask 5.2: 批量替换 `.axaml` 文件中 `Watermark` → `PlaceholderText`
|
||||
- [ ] SubTask 5.3: 验证无过时警告
|
||||
|
||||
- [ ] Task 6: 最终验证
|
||||
- [ ] SubTask 6.1: `dotnet build LanMountainDesktop.slnx -c Debug` 0 errors
|
||||
- [ ] SubTask 6.2: `dotnet test LanMountainDesktop.slnx -c Debug` 通过
|
||||
|
||||
# Task Dependencies
|
||||
|
||||
- Task 2 不依赖 Task 1（可并行）
|
||||
- Task 3 不依赖 Task 1/2（可并行）
|
||||
- Task 4 不依赖 Task 1/2/3（可并行）
|
||||
- Task 5 依赖 Task 1/2/3/4（低优先级，最后执行）
|
||||
- Task 6 依赖所有前置任务
|
||||
- [x] Centralize Avalonia 12 package versions in `Directory.Packages.props`.
|
||||
- [x] Move the host, Launcher, Plugin SDK, DesktopHost, Shared.Contracts, and Avalonia-facing projects onto central package versions.
|
||||
- [x] Replace third-party `WebView.Avalonia` usage with official `NativeWebView`.
|
||||
- [x] Configure WebView2 user data through `EnvironmentRequested`.
|
||||
- [x] Move FluentAvalonia usages to the FA3 control names and package baseline.
|
||||
- [x] Move FluentIcons usage to `FluentIcons.Avalonia` and remove the old `.Fluent` package.
|
||||
- [x] Update Plugin SDK package version and API baseline to `5.0.0`.
|
||||
- [x] Update plugin runtime shared assembly policy for Avalonia 12 / FluentAvalonia / FluentIcons / Material.
|
||||
- [x] Fix Avalonia 12 compile breaks in window chrome, binding plugin access, clipboard, bitmap copy, and icon source usage.
|
||||
- [x] Fix Launcher data location recursion by using a fixed bootstrap config path.
|
||||
- [x] Fix OOBE state tests and legacy marker compatibility.
|
||||
- [x] Update PluginTemplate defaults to SDK v5.
|
||||
- [x] Add SDK v5 migration documentation.
|
||||
- [x] Update current docs from SDK v4 / Avalonia 11 examples to SDK v5 / Avalonia 12.
|
||||
- [x] Run full solution tests and record any remaining non-upgrade failures.
|
||||
- [ ] Perform Windows manual smoke test for host, Launcher, settings, component editor, BrowserWidget, and WebView2 missing-runtime handling.
|
||||
|
||||
Reference in New Issue
Block a user