Files
LanMountainDesktop/.trae/specs/avalonia-12-migration/spec.md
lincube abfa64b3d7 Avalonia12 (#7)
* ava12升级

* Enable centralized package versioning

Add <Project> and <PropertyGroup> with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to Directory.Packages.props to enable centralized package version management across the repository. This allows package versions to be controlled from this single file instead of individual project files.

* Migrate codebase to Avalonia 12 APIs

Apply Avalonia 12 migration changes: replace SystemDecorations with WindowDecorations and remove ExtendClientAreaChromeHints/ExtendClientAreaTitleBarHeightHint usages; update BindingPlugins removal logic (no-op); switch clipboard usage to ClipboardExtensions.SetTextAsync; update Bitmap.CopyPixels calls to the new signature. Replace TextBox.Watermark with PlaceholderText, convert NumberBox styles to FANumberBox and adjust templates, change Checked/Unchecked handlers to IsCheckedChanged, and adapt FluentIcons usages (SymbolIconSource -> FASymbol/FAFont/FluentIcon equivalents). Fix MainWindow partial classes to inherit Window and correct missing variables/fields/usings. Add migration docs/specs/tasks under .trae and include a small TestFluentIcons project for icon testing.

* 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.

* Update icon glyphs and symbol mappings

Replace and refine icon sources across settings pages and controls: many FAFontIconSource glyphs were updated to specific Seagull Fluent Icons codepoints, some FASymbolIconSource usages were replaced with FAFontIconSource, and a number of symbol-to-Symbol enum mappings were adjusted (e.g. "Bell" -> AlertOn, "Shield" -> ShieldLock). Also clarified a comment in SettingsWindow and fixed a trailing newline in StudySettingsPage. Changes standardize icon visuals and bridge FluentIcons glyphs into FluentAvalonia icon sources.

* fix.修复合并产生的问题。
2026-04-29 12:14:29 +08:00

2.3 KiB

Avalonia 12 Full Stack Migration

Summary

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.

Requirements

Requirement: Centralized Avalonia 12 dependency baseline

The solution SHALL use central package management for direct Avalonia-facing projects and keep the core UI dependency baseline on Avalonia 12.0.1.

Required package baseline:

  • 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: Official WebView

The host SHALL use Avalonia.Controls.NativeWebView for the browser widget and SHALL NOT reference WebView.Avalonia, AvaloniaWebView, or .UseDesktopWebView().

Windows WebView2 user data configuration SHALL be supplied through EnvironmentRequested using WindowsWebView2EnvironmentRequestedEventArgs.UserDataFolder.

Requirement: Plugin SDK v5

The Plugin SDK API baseline SHALL be 5.0.0. SDK v4 plugins are treated as incompatible until rebuilt.

The SDK SHALL keep the existing public UI extension shape, including SettingsPageBase and Avalonia Control based desktop components.

Requirement: Launcher data location stability

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.

Requirement: OOBE state compatibility

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.