更新客户端渲染，更新了壳

2026-07-06 23:05:40 +08:00
parent e7dd87bf7e
commit 31d778710b
1311 changed files with 172662 additions and 1582 deletions
@@ -0,0 +1,289 @@
+# Architecture Diagrams Index
+
+This directory serves as an index of all architecture diagrams used throughout the WPF UI documentation.
+
+## Architecture Views
+
+### Context Diagram
+
+**NuGet Package Distribution Flowchart**
+- **Location:** [views/context.md](../../views/context.md#nuget-package-distribution)
+- **Type:** Mermaid flowchart
+- **Purpose:** Shows the NuGet package distribution flow from GitHub Actions CD through NuGet.org to developer machines
+- **Key Components:** GitHub Actions CD, NuGet.org, Developer Machine
+
+### Logical Architecture
+
+**Module/Package Dependency Diagram**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#1-modulepackage-dependency-diagram)
+- **Type:** Mermaid graph TD
+- **Purpose:** Shows dependencies between all 10 solution projects
+- **Key Components:** Abstractions, Core, DI, Tray, SyntaxHighlight, Toast, Gallery, FlaUI, FontMapper, Extension
+
+**Core Library Internal Structure (Layer Diagram)**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#2-core-library-internal-structure-layer-diagram)
+- **Type:** Mermaid graph TB
+- **Purpose:** Six-layer architecture of the core Wpf.Ui library
+- **Layers:** Controls, Appearance/Theming, Services, Infrastructure, Win32 Interop, Resources
+
+**Control Architecture Class Diagram**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#3-control-architecture-pattern)
+- **Type:** Mermaid classDiagram
+- **Purpose:** Shows control inheritance and interface implementation patterns
+- **Key Components:** WPF base classes, capability interfaces (IAppearanceControl, IIconControl), concrete controls
+
+**Target Framework Matrix**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#5-target-framework-matrix)
+- **Type:** Mermaid gantt chart
+- **Purpose:** Visualizes TFM coverage across all modules
+- **Key Components:** All solution projects with their target frameworks
+
+**Service Registration & DI Integration**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#6-service-registration--di-integration)
+- **Type:** Mermaid sequenceDiagram
+- **Purpose:** Shows Generic Host DI registration flow and runtime page resolution
+- **Key Components:** IHostBuilder, IServiceCollection, IServiceProvider, NavigationView, INavigationViewPageProvider
+
+**Control Lifecycle State Diagram**
+- **Location:** [views/logical-architecture.md](../../views/logical-architecture.md#7-control-lifecycle)
+- **Type:** Mermaid stateDiagram-v2
+- **Purpose:** Documents the complete lifecycle of WPF UI controls from construction through GC
+- **States:** Constructed, Loaded, Template Applied, Themed, Unloaded, GC
+
+## Cross-Cutting Concerns
+
+### Navigation
+
+**Navigation System Lifecycle Sequence Diagram**
+- **Location:** [cross-cutting/navigation.md](../../cross-cutting/navigation.md#navigation-lifecycle)
+- **Type:** Mermaid sequenceDiagram
+- **Purpose:** Complete flow from NavigationService.Navigate() through page resolution, caching, INavigationAware callbacks, and transition animation
+- **Key Components:** Consumer Code, NavigationService, NavigationView, INavigationViewPageProvider, Page Cache, Frame, TransitionAnimationProvider
+
+**Page Cache Mode State Diagram**
+- **Location:** [cross-cutting/navigation.md](../../cross-cutting/navigation.md#page-cache-mode)
+- **Type:** Mermaid stateDiagram-v2
+- **Purpose:** Illustrates the three caching strategies (Disabled, Enabled, Required) and their decision logic
+- **Key States:** PageRequested, CheckCacheMode, CacheDisabled, CacheEnabled, CacheRequired, PageDisplayed
+
+### Theming and Appearance
+
+**Theme Change Flow Sequence Diagram**
+- **Location:** [cross-cutting/theming-and-appearance.md](../../cross-cutting/theming-and-appearance.md#theme-change-flow)
+- **Type:** Mermaid sequence diagram
+- **Purpose:** Illustrates the complete flow of a theme change from OS event to UI update
+- **Key Components:** User, App, SystemThemeWatcher, WndProc, ApplicationThemeManager, ResourceDictionaryManager, UI
+
+**Theme System Architecture**
+- **Location:** [cross-cutting/theming-and-appearance.md](../../cross-cutting/theming-and-appearance.md#architecture-components)
+- **Type:** Component description with code examples
+- **Purpose:** Documents the five core manager classes and their responsibilities
+- **Key Components:** ApplicationThemeManager, ApplicationAccentColorManager, SystemThemeWatcher, WindowBackgroundManager, ResourceDictionaryManager
+
+### Win32 Interop
+
+**Win32 Interop Component Diagram**
+- **Location:** [cross-cutting/win32-interop.md](../../cross-cutting/win32-interop.md#component-diagram)
+- **Type:** Mermaid graph TB with subgraphs
+- **Purpose:** Three-layer component diagram showing all Win32 interop participants from controls through managed wrappers to CsWin32-generated P/Invoke
+- **Layers:** High-Level Utilities & Controls, Managed Wrappers (Interop/), CsWin32 Source Generation
+
+**Three-Layer Architecture Diagram**
+- **Location:** [cross-cutting/win32-interop.md](../../cross-cutting/win32-interop.md#three-layer-architecture)
+- **Type:** Mermaid graph diagram
+- **Purpose:** Shows the layered architecture for Win32 API access
+- **Layers:**
+  - Layer 1: CsWin32 Generated Code (Windows.Win32 namespace)
+  - Layer 2: Managed Wrappers (UnsafeNativeMethods, Custom PInvoke)
+  - Layer 3: High-Level Utilities (Win32/Utilities, Appearance Managers)
+
+**WndProc Message Flow**
+- **Location:** [cross-cutting/win32-interop.md](../../cross-cutting/win32-interop.md#wndproc-message-interception)
+- **Type:** Code example with explanation
+- **Purpose:** Documents window message interception pattern used by SystemThemeWatcher and TitleBar
+- **Key Messages:** WM_DWMCOLORIZATIONCOLORCHANGED, WM_THEMECHANGED, WM_SYSCOLORCHANGE, WM_NCHITTEST
+
+## Architectural Decisions
+
+### ADR-002: Control Library Architecture
+
+**Control Folder Structure**
+- **Location:** [decisions/ADR-002-control-library-architecture.md](../../decisions/ADR-002-control-library-architecture.md#folder-per-control-structure)
+- **Type:** Directory tree visualization
+- **Purpose:** Shows the folder-per-control organization pattern
+- **Examples:** Button/, NavigationView/, ContentDialog/
+
+**Partial Class Decomposition**
+- **Location:** [decisions/ADR-002-control-library-architecture.md](../../decisions/ADR-002-control-library-architecture.md#partial-class-decomposition)
+- **Type:** Directory structure with annotations
+- **Purpose:** Demonstrates how complex controls split into partial classes by concern
+- **Example:** NavigationView with 6 partial files (Base, Properties, Events, Navigation, TemplateParts, AttachedProperties)
+
+### ADR-003: Win32 Interop via CsWin32
+
+**Handle Validation Pattern Flowchart**
+- **Location:** [decisions/ADR-003-win32-interop-via-cswin32.md](../../decisions/ADR-003-win32-interop-via-cswin32.md#handle-validation-pattern)
+- **Type:** Code example with step-by-step comments
+- **Purpose:** Documents the mandatory three-step validation pattern for all Win32 calls
+- **Steps:**
+  1. Check for zero handle
+  2. Verify window exists (IsWindow)
+  3. Perform operation with exception handling
+
+### ADR-005: Feature Folder Organization
+
+**Feature Folder Patterns**
+- **Location:** [decisions/ADR-005-feature-folder-controls.md](../../decisions/ADR-005-feature-folder-controls.md#structure-patterns)
+- **Type:** Multiple directory tree visualizations
+- **Purpose:** Shows three organization patterns: Simple controls, Complex controls with partials, Controls with related types
+- **Examples:**
+  - Simple: Badge/ (2 files)
+  - Complex: NavigationView/ (7+ files)
+  - With Related Types: NavigationView/ with NavigationViewItem, NavigationViewItemHeader, etc.
+
+### Module Interfaces
+
+**Module Dependency Graph (Public/Internal)**
+- **Location:** [MODULE-INTERFACES.md](../../MODULE-INTERFACES.md#module-dependency-graph)
+- **Type:** Mermaid graph TD with subgraphs
+- **Purpose:** Shows module dependencies with public/internal type counts per module
+- **Key Components:** All distributable and non-distributable modules with API surface annotations
+
+## Data Flow Diagrams
+
+### Theme Change Flow
+**Diagram:** Sequence diagram showing theme change propagation
+```
+User → OS Settings → WndProc → SystemThemeWatcher → ApplicationThemeManager →
+ResourceDictionaryManager → Application.Resources → UI Update
+```
+
+### Win32 Call Stack
+**Diagram:** Layer diagram showing Win32 interop call flow
+```
+High-Level Code → UnsafeNativeMethods (validation) → PInvoke (CsWin32) → Win32 API
+```
+
+### Navigation Flow
+**Diagram:** (Not yet created) Could be added to show:
+```
+NavigationService → NavigationView → PageProvider → Page Resolution →
+Frame Navigation → INavigationAware Callbacks
+```
+
+## Component Diagrams
+
+### Theming System Components
+**Components:**
+- ApplicationThemeManager (theme selection)
+- ApplicationAccentColorManager (accent colors)
+- SystemThemeWatcher (OS sync)
+- WindowBackgroundManager (window appearance)
+- ResourceDictionaryManager (resource swapping)
+
+**Relationships:**
+- SystemThemeWatcher → ApplicationThemeManager (triggers Apply)
+- ApplicationThemeManager → ResourceDictionaryManager (delegates swapping)
+- ApplicationAccentColorManager → ResourceDictionaryManager (updates dynamic resources)
+
+### Control Architecture Components
+**Components:**
+- Control Class (.cs file)
+- Implicit Style (.xaml file)
+- Dependency Properties
+- Routed Events
+- Capability Interfaces (IAppearanceControl, IIconControl, IThemeControl)
+
+**Relationships:**
+- Control Class → Dependency Properties (registers)
+- Control Class → Capability Interfaces (implements)
+- XAML Style → Control Class (targets via TargetType)
+
+## Future Diagram Additions
+
+### Recommended Additions
+1. **Content Dialog Lifecycle** - Async ShowAsync() flow with cancellation and result handling
+2. **Icon System Hierarchy** - IconElement inheritance tree (FontIcon, SymbolIcon, ImageIcon)
+3. **Accent Color Derivation** - How 20+ accent resources are computed from system accent
+4. **Gallery App Architecture** - MVVM structure with ViewModels, Views, Services, and Models
+
+### Recently Added (2026-02-10)
+- ~~Navigation System Flow~~ — Added in [cross-cutting/navigation.md](../../cross-cutting/navigation.md)
+- ~~DI Integration Flow~~ — Added in [views/logical-architecture.md](../../views/logical-architecture.md#6-service-registration--di-integration)
+- ~~Service Layer Architecture~~ — Covered by DI Integration and Module Interfaces diagrams
+
+## Diagram Guidelines
+
+### Mermaid Syntax
+All diagrams use Mermaid for easy maintenance and version control:
+
+**Sequence Diagram:**
+```mermaid
+sequenceDiagram
+    participant A
+    participant B
+    A->>B: Message
+    B-->>A: Response
+```
+
+**Graph Diagram:**
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+
+    style A fill:#e1f5e1
+    style B fill:#fff4e1
+```
+
+**Class Diagram:**
+```mermaid
+classDiagram
+    class Button {
+        +Icon IconElement
+        +Appearance ControlAppearance
+    }
+    Button --|> IAppearanceControl
+    Button --|> IIconControl
+```
+
+### Diagram Best Practices
+1. Keep diagrams focused (single concern per diagram)
+2. Use consistent styling across related diagrams
+3. Include legend when colors/shapes have meaning
+4. Maintain diagram source in markdown (not separate image files)
+5. Update diagrams when architecture changes
+
+## Diagram Tools
+
+### Recommended Tools
+- **Mermaid Live Editor** - https://mermaid.live/
+- **VS Code Extensions:**
+  - Markdown Preview Mermaid Support
+  - Mermaid Editor
+
+### Generating PNG/SVG
+For presentations or external documentation:
+```bash
+# Using mmdc (Mermaid CLI)
+npm install -g @mermaid-js/mermaid-cli
+mmdc -i diagram.mmd -o diagram.png
+```
+
+## Maintenance
+
+### Ownership
+Architecture diagram maintenance is part of architecture documentation updates. When making architectural changes:
+
+1. Identify affected diagrams
+2. Update diagram source in markdown
+3. Verify rendering in preview
+4. Update this index if adding new diagrams
+
+### Review Checklist
+- [ ] Diagram accurately reflects current architecture
+- [ ] All components labeled clearly
+- [ ] Relationships shown with appropriate arrows
+- [ ] Color coding explained (if used)
+- [ ] Renders correctly in GitHub markdown preview
+- [ ] Index updated with new diagram location
@@ -0,0 +1,145 @@
+specification {
+  element actor {
+    style {
+      shape person
+    }
+  }
+  element system
+  element external {
+    style {
+      color muted
+    }
+  }
+  element container
+  element component
+}
+
+model {
+  actor developer = 'WPF Developer' {
+    description 'Builds WPF apps using WPF UI'
+  }
+  actor enduser = 'End User' {
+    description 'Uses WPF desktop applications'
+  }
+
+  system wpfui = 'WPF UI Library' {
+    description 'Fluent Design System for WPF. 77+ controls, theming, Win32 interop.'
+
+    container core = 'Wpf.Ui' {
+      description 'Core library - controls, theming, services, interop'
+
+      component controls = 'Controls' {
+        description '77+ Fluent Design controls including NavigationView, TitleBar, FluentWindow, ContentDialog, NumberBox, ToggleSwitch'
+      }
+      component appearance = 'Appearance' {
+        description 'Theme and accent color management via ApplicationThemeManager and ApplicationAccentColorManager'
+      }
+      component services = 'Services' {
+        description 'NavigationService, ContentDialogService, SnackbarService, TaskBarService'
+      }
+      component interop = 'Win32 Interop' {
+        description 'DWM, User32, Shell32 wrappers via CsWin32 P/Invoke'
+      }
+      component resources = 'Resources' {
+        description 'ThemesDictionary, ControlsDictionary, embedded Fluent System Icons fonts'
+      }
+      component converters = 'Converters' {
+        description 'XAML value converters for theme-aware data binding'
+      }
+      component automationPeers = 'AutomationPeers' {
+        description 'UI Automation and accessibility support for custom controls'
+      }
+    }
+
+    container abstractions = 'Wpf.Ui.Abstractions' {
+      description 'Contract interfaces for services and navigation. Multi-targets netstandard2.0/2.1.'
+    }
+    container di = 'Wpf.Ui.DependencyInjection' {
+      description 'Microsoft.Extensions.DependencyInjection integration for services and navigation'
+    }
+    container tray = 'Wpf.Ui.Tray' {
+      description 'System tray icon and context menu support'
+    }
+    container syntaxHighlight = 'Wpf.Ui.SyntaxHighlight' {
+      description 'Code syntax highlighting display control'
+    }
+    container gallery = 'Wpf.Ui.Gallery' {
+      description 'Demo application showcasing all controls and patterns'
+    }
+    container flaui = 'Wpf.Ui.FlaUI' {
+      description 'FlaUI-based test automation helpers for integration testing'
+    }
+    container fontMapper = 'Wpf.Ui.FontMapper' {
+      description 'Build-time tool generating icon enum from Fluent System Icons font'
+    }
+  }
+
+  external nuget = 'NuGet.org' {
+    description 'Package distribution for WPF-UI and satellite packages'
+  }
+  external windows = 'Windows OS' {
+    description 'Win32 APIs, Desktop Window Manager, WinRT notifications'
+  }
+  external github = 'GitHub' {
+    description 'Source hosting, CI/CD via GitHub Actions, documentation'
+  }
+  external fluentIcons = 'Fluent System Icons' {
+    description 'Microsoft open-source icon font (Filled + Regular variants)'
+  }
+  external wpfFramework = 'WPF Framework' {
+    description '.NET WPF runtime and base controls'
+  }
+
+  // Actor relationships
+  developer -> wpfui.core 'Uses controls, theming, and services via NuGet'
+  developer -> wpfui.di 'Registers services in DI container'
+  developer -> nuget 'Installs WPF-UI packages'
+  enduser -> wpfui.gallery 'Explores demo application'
+
+  // Internal container relationships
+  wpfui.core -> abstractions 'Implements service interfaces'
+  wpfui.di -> abstractions 'References contract interfaces'
+  wpfui.di -> wpfui.core 'Registers concrete service implementations'
+  wpfui.tray -> wpfui.core 'Extends with system tray functionality'
+  wpfui.syntaxHighlight -> wpfui.core 'Extends with syntax highlighting control'
+  wpfui.gallery -> wpfui.core 'Demonstrates all controls and services'
+  wpfui.gallery -> wpfui.di 'Uses DI for service registration'
+  wpfui.gallery -> wpfui.tray 'Demonstrates tray integration'
+  wpfui.gallery -> wpfui.syntaxHighlight 'Demonstrates code display'
+  wpfui.flaui -> wpfui.core 'Provides automation wrappers for controls'
+
+  // Internal component relationships
+  wpfui.core.controls -> wpfui.core.appearance 'Reacts to theme changes'
+  wpfui.core.controls -> wpfui.core.resources 'Consumes styles and templates'
+  wpfui.core.controls -> wpfui.core.interop 'Uses Win32 for TitleBar, snap layouts'
+  wpfui.core.controls -> wpfui.core.converters 'Uses value converters in templates'
+  wpfui.core.controls -> wpfui.core.automationPeers 'Exposes automation support'
+  wpfui.core.services -> wpfui.core.controls 'Manages NavigationView, ContentDialog, Snackbar'
+  wpfui.core.appearance -> wpfui.core.interop 'Detects system theme via Win32'
+  wpfui.core.appearance -> wpfui.core.resources 'Switches theme dictionaries at runtime'
+
+  // External relationships
+  wpfui.core.interop -> windows 'P/Invoke calls to DWM, User32, Shell32'
+  wpfui.core -> wpfFramework 'Extends WPF base classes (Control, Window, etc.)'
+  wpfui.core.resources -> fluentIcons 'Bundles icon font files'
+  wpfui.core -> nuget 'Published as WPF-UI package'
+  wpfui.core -> github 'Source hosted, CI/CD pipeline'
+  wpfui.fontMapper -> fluentIcons 'Parses icon font to generate enums'
+}
+
+views {
+  view context of wpfui {
+    title 'WPF UI - System Context (C4 Level 1)'
+    include *, developer, enduser, nuget, windows, github, fluentIcons, wpfFramework
+  }
+
+  view containers of wpfui {
+    title 'WPF UI - Container View (C4 Level 2)'
+    include wpfui, wpfui.*, developer, windows, nuget, wpfFramework
+  }
+
+  view components of wpfui.core {
+    title 'Wpf.Ui Core - Component View (C4 Level 3)'
+    include wpfui.core, wpfui.core.*, windows, wpfFramework, fluentIcons
+  }
+}