簡介面向 WPF 桌面應(yīng)用開發(fā)者的一套現(xiàn)代化界面框架源碼與示例適合希望擺脫默認控件外觀、快速搭建統(tǒng)一視覺風格的中級開發(fā)者參考也可作為團隊 UI 規(guī)范與主題定制的基礎(chǔ)。壓縮包約 1.84MB共 336 個文件以 143 個 C# 源碼與 115 個 XAML 界面文件為主體另含 15 個 csproj 工程文件、圖標與圖片素材、Visual Studio 項目模板及少量說明文檔覆蓋控件實現(xiàn)、窗口外殼、主題資源到可復用模板的完整鏈路。目前已有 6464 人學習下載。內(nèi)容圍繞現(xiàn)代化窗口、菜單、對話框與過渡動畫控件展開涉及主題外觀管理與系統(tǒng)版本適配等模塊可據(jù)此理解樣式模板、資源字典與 MVVM 在真實項目中的組織方式并直接改造為自己的應(yīng)用外殼。1. 一個漂亮的 WPF 界面框架漂亮之外到底解決什么問題上個月幫一個內(nèi)部工具做收尾功能全跑通了評審時被一句話打回來這套 WPF 界面看著像十年前的。真正動手改才發(fā)現(xiàn)難點不在畫得好看而在主色散落在二十多個 XAML 里、按鈕存在三套模板、每個窗口的標題欄各寫各的。這份 WPF 界面框架源碼包就是把這堆散件整理成三層主題 Token、控件模板、窗口外殼再配一套 MVVM 骨架和若干示例頁。它主要解決兩件具體的事改一處顏色不用翻遍工程新頁面照著示例拼就能交付。適合正在用 WPF 做桌面端、要把界面從「能跑」推到「能驗收」的人不適合想找拖拽式設(shè)計器、指望完全不寫 XAML 的人。2. 拆目錄結(jié)構(gòu)主題 Token、控件模板、窗口外殼這三層怎么分拿到一個界面框架先別急著運行 Demo也別急著往自己的工程里復制。先看Themes目錄的層次因為它決定了后面所有覆蓋、換膚、定制動作能不能生效。這套框架的劃分是比較典型的做法Tokens放純值顏色、字號、圓角、間距、控件高度Controls放控件樣式與ControlTemplateSkins放皮膚覆蓋Shell放窗口外殼與標題欄。分層的意義在于職責邊界清晰Token 里不該出現(xiàn)任何ControlTemplate控件模板里不該出現(xiàn)任何寫死的#2F6FED。我見過太多項目的資源字典是一個幾千行的Styles.xaml顏色、模板、動畫、轉(zhuǎn)換器全塞在一起。這種文件在項目第三個月就會變成黑匣子誰都不敢刪任何一行因為不知道刪了會影響哪個頁面。分層不是潔癖是為了讓你敢改。2.1 先看資源字典的合并順序它決定后面所有覆蓋能不能生效WPF 在MergedDictionaries里查找同一個 Key 時后加入的字典優(yōu)先級更高。這條規(guī)則很短但它是整套換膚機制的基石。很多人的皮膚切換做不出來原因就一個把皮膚字典加在了 Token 字典前面于是 Token 里的舊值一直勝出換膚看起來「沒反應(yīng)」。正確的合并順序是先 Token再 Controls最后 Skin。!-- App.xamlxmlns 省略實際工程里按模板生成的寫 -- Application.Resources ResourceDictionary ResourceDictionary.MergedDictionaries !-- 第 1 層純值沒有任何模板。換膚就是換這一層的值 -- ResourceDictionary SourceThemes/Tokens/Colors.Default.xaml/ ResourceDictionary SourceThemes/Tokens/Typography.xaml/ ResourceDictionary SourceThemes/Tokens/Metrics.xaml/ !-- 第 2 層控件模板只允許引用第 1 層的 Key -- ResourceDictionary SourceThemes/Controls/Button.xaml/ ResourceDictionary SourceThemes/Controls/TextBox.xaml/ ResourceDictionary SourceThemes/Controls/Card.xaml/ !-- 第 3 層皮膚覆蓋第 1 層同名 Key必須放最后 -- ResourceDictionary SourceThemes/Skins/Light.xaml/ /ResourceDictionary.MergedDictionaries /ResourceDictionary /Application.Resources這段順序背后有兩條必須記住的規(guī)則。第一條是查找方向MergedDictionaries的檢索是從后往前所以最后加載的皮膚能蓋住前面所有同名 Key。第二條是作用域Application.Resources是全局的窗口和控件會逐級向上查找一旦某一層出現(xiàn)了同名 Key上層的就永遠取不到——調(diào)試時「樣式在別的頁面正常、就這個頁面不對」八成是這個頁面的Window.Resources里藏了一個同名項。跨程序集引用時路徑要改成 pack URI比如pack://application:,,,/YourApp;component/Themes/Tokens/Colors.Default.xaml程序集名寫錯的話運行時會拋IOException而不是編譯錯誤這也是常見的第一道問題。2.2 顏色、字號、圓角三組 Token為什么主色要用 DynamicResourceToken 層只做一件事把「設(shè)計決定」變成「命名常量」。這套框架里大致是三類鍵名前綴即語義分類示例 Key典型值說明顏色Color.Accent.Base#2F6FED主色另配 Hover、Pressed 兩檔顏色Color.Surface.Card#FFFFFF卡片、面板底色字號Font.Size.Body13正文另有 Caption 12、Title 18圓角Radius.Control6按鈕、輸入框統(tǒng)一圓角間距Space.Unit8所有間距取它的整數(shù)倍尺寸Metric.Control.Height32單行控件標準高度主色不要只給一個值Hover 和 Pressed 要手調(diào)出來別用Opacity疊。原因是透明疊加的結(jié)果依賴背景色同一個按鈕放在白色卡片和深色側(cè)欄上淺色疊加出來的效果完全不同深色背景上會發(fā)灰。這是很常見的視覺問題單看沒問題一放到深色區(qū)域就顯得臟。!-- Tokens/Colors.Default.xaml -- ResourceDictionary xmlns... xmlns:x... !-- 主色三檔Hover/Pressed 手工調(diào)深保證在深色和淺色背景上都成立 -- Color x:KeyColor.Accent.Base#2F6FED/Color Color x:KeyColor.Accent.Hover#245BD0/Color Color x:KeyColor.Accent.Pressed#1C48A8/Color !-- Brush 單獨一層控件模板里用 Brush換膚時只換 Brush 即可 -- SolidColorBrush x:KeyBrush.Accent.Base Color{StaticResource Color.Accent.Base}/ SolidColorBrush x:KeyBrush.Accent.Hover Color{StaticResource Color.Accent.Hover}/ SolidColorBrush x:KeyBrush.Text.OnAccent Color#FFFFFF/ SolidColorBrush x:KeyBrush.Surface.Card Color#FFFFFF/ !-- 字號與度量數(shù)值型 Token 用 sys:Double必須帶命名空間 -- sys:Double x:KeyFont.Size.Body13/sys:Double sys:Double x:KeyFont.Size.Title18/sys:Double CornerRadius x:KeyRadius.Control6/CornerRadius sys:Double x:KeyMetric.Control.Height32/sys:Double /ResourceDictionary關(guān)鍵在于「顏色」和「畫筆」分成兩層。Color是不可變結(jié)構(gòu)體SolidColorBrush才是控件屬性真正吃的東西模板里引用的必須是 Brush。數(shù)值型 Token 要注意類型x:Double需要引入sys命名空間clr-namespace:System;assemblySystem.Runtime不同目標框架程序集名略有差異CornerRadius直接寫元素即可不用額外命名空間?，F(xiàn)在說DynamicResource和StaticResource怎么選這是最常被問的一個問題。結(jié)論是會隨皮膚變化的 Key 用DynamicResource永不變的 Key 用StaticResource。StaticResource在 XAML 解析時就把值取出來定死換膚后不會重新求值所以把主色用StaticResource引到模板里切皮膚必然失敗DynamicResource每次取值走一次資源查找會帶來額外開銷在DataGrid單元格模板、ItemsControl項模板這種會實例化成千上萬次的地方能靜態(tài)就靜態(tài)。我的習慣是Token 里跟顏色相關(guān)的全用DynamicResource字號、圓角、間距這類換膚不動的用StaticResource。這個劃分一句話能記住后面維護的人也不會亂改。2.3 拆一個按鈕從 Token 到 ControlTemplate 的完整鏈路理解了層次再拆一個具體控件看看這套框架里一個主按鈕是怎么拼起來的。這段值得逐行讀因為它是后面所有控件的模板。!-- Controls/Button.xaml只引用 Token不出現(xiàn)任何字面色值 -- Style x:KeyButton.Primary TargetTypeButton Setter PropertyHeight Value{StaticResource Metric.Control.Height}/ Setter PropertyMinWidth Value72/ Setter PropertyPadding Value16,0/ Setter PropertyFontSize Value{StaticResource Font.Size.Body}/ Setter PropertyForeground Value{DynamicResource Brush.Text.OnAccent}/ Setter PropertyBackground Value{DynamicResource Brush.Accent.Base}/ Setter PropertyBorderThickness Value0/ Setter PropertyCursor ValueHand/ Setter PropertyTemplate Setter.Value ControlTemplate TargetTypeButton Border x:NameBd Background{TemplateBinding Background} CornerRadius{StaticResource Radius.Control} SnapsToDevicePixelsTrue ContentPresenter HorizontalAlignmentCenter VerticalAlignmentCenter Margin{TemplateBinding Padding} RecognizesAccessKeyTrue/ /Border ControlTemplate.Triggers !-- 順序有講究后定義的觸發(fā)器優(yōu)先級更高 -- Trigger PropertyIsMouseOver ValueTrue Setter TargetNameBd PropertyBackground Value{DynamicResource Brush.Accent.Hover}/ /Trigger Trigger PropertyIsPressed ValueTrue Setter TargetNameBd PropertyBackground Value{DynamicResource Brush.Accent.Pressed}/ /Trigger Trigger PropertyIsEnabled ValueFalse Setter TargetNameBd PropertyOpacity Value0.45/ Setter PropertyCursor ValueArrow/ /Trigger /ControlTemplate.Triggers /ControlTemplate /Setter.Value /Setter /Style這里有幾個容易被忽略的細節(jié)每一個都可能變成后期幾分鐘甚至幾小時地去排查的問題。第一TemplateBinding是單向的、不支持轉(zhuǎn)換器且只能綁到模板化父級的屬性上。所以Padding能綁Background能綁但如果你想把Background轉(zhuǎn)成漸變就必須換成{Binding Background, RelativeSource{RelativeSource TemplatedParent}}再掛 Converter。混用這兩者時不要抱有僥幸心理模板里一旦出現(xiàn)轉(zhuǎn)換需求就整體換成Binding。第二觸發(fā)器順序決定最終效果。IsMouseOver和IsPressed同時為真時后定義的IsPressed生效所以按下色必須寫在懸停色后面。反過來寫按下時看到的還是懸停色看起來就像「按下沒反饋」。第三IsEnabledFalse時如果只改OpacityCursorHand依然生效鼠標移上去還是手型用戶會以為可以點。所以禁用態(tài)要順手把Cursor也改回來這類細節(jié)在驗收時最容易被挑出來。最后控件模板里不要出現(xiàn)字面色值這是硬性約束。只要模板里出現(xiàn)一個#2F6FED換膚那一刻它就會變成色塊不一致的元兇而且很難靠肉眼定位到具體是哪個模板?？蚣芾镞@類違規(guī)用一次文本搜索就能找出來接入前先搜一遍#順手清理掉。3. 接入現(xiàn)有工程從復制目錄到跑出第一個頁面3.1 目錄落位與 csproj 里的資源聲明把整個工程復制進來是最快的驗證方式但真正接入現(xiàn)有項目時建議只復制Themes和Infrastructure兩個目錄示例頁按需挑選著拿。目錄放在項目根下即可不要塞進Properties或者obj旁邊obj目錄在清理時容易誤刪。csproj這塊有個高頻問題SDK 風格工程的默認 glob 已經(jīng)把**/*.xaml編譯成Page你再手寫一遍Page IncludeThemes\**\*.xaml /就會報重復項NETSDK1022。所以大部分情況下什么都不用寫只在需要排除或者改變構(gòu)建方式時才動它。ItemGroup !-- 默認 glob 已包含 **/*.xaml這里只做排除草稿目錄不參與編譯 -- Page RemoveThemes\_draft\**\*.xaml / !-- 字體、圖標這類二進制資源用 Resource隨程序集嵌入pack URI 才取得到 -- Resource IncludeAssets\Fonts\*.ttf / Resource IncludeAssets\Icons\*.png / !-- 示例數(shù)據(jù)用 Content 復制到輸出目錄別用 Resource 塞進程序集 -- Content IncludeSampleData\*.json CopyToOutputDirectoryPreserveNewest / /ItemGroup構(gòu)建項的選擇直接決定資源能不能取到這張表建議存下來構(gòu)建項編譯結(jié)果適用場景取用方式Page編譯為 BAML所有 XAML包括資源字典Source相對路徑Resource嵌入程序集字體、圖標、小圖片pack://application:,,,/程序集;component/路徑Content原樣復制到輸出目錄示例數(shù)據(jù)、可替換配置相對輸出目錄的路徑None不處理文檔、說明無字體用Resource嵌入之后在 XAML 里通過FontFamily/Assets/Fonts/#字體內(nèi)部名引用注意斜杠后面那個#后面跟的是字體家族名不是文件名。寫錯了不會報錯只會靜默回退到系統(tǒng)默認字體——這類靜默失敗最耗時間。3.2 App.xaml 合并字典與運行時換膚皮膚切換不要用「先清空再添加」的寫法。清空MergedDictionaries會在瞬間讓所有DynamicResource失效控件重繪時可能拋出找不到資源的異常而「只添加不移除」會讓字典越積越多切換五十次之后內(nèi)存和查找開銷都會肉眼可見地上漲。正確做法是把皮膚字典固定在MergedDictionaries的最后一位換膚就是替換這一項。public static class ThemeManager { // 皮膚字典固定放在 MergedDictionaries 的末位替換這一項即為換膚 private static readonly Uri LightSkin new(pack://application:,,,/YourApp;component/Themes/Skins/Light.xaml); private static readonly Uri DarkSkin new(pack://application:,,,/YourApp;component/Themes/Skins/Dark.xaml); public static void Apply(bool dark) { var merged Application.Current.Resources.MergedDictionaries; if (merged.Count 0) return; var skin new ResourceDictionary { Source dark ? DarkSkin : LightSkin }; // 關(guān)鍵替換而不是 Add避免字典無限增長 merged[merged.Count - 1] skin; } }替換完成后不需要手動刷新任何控件DynamicResource會自動重新求值。這里有個前提所有隨皮膚變化的引用必須是DynamicResource只要模板里漏了一個StaticResource換膚后那個控件就會保持舊色在一片新配色里顯得很突兀。還要注意換膚的時機。啟動時在App構(gòu)造函數(shù)里調(diào)用是最穩(wěn)的如果放在窗口Loaded之后用戶會看到一次明顯的閃爍。真想做到無閃爍就得在窗口顯示前把皮膚定好也就是把配置讀取提前到App初始化階段。3.3 無邊框窗口外殼與自定義標題欄這套框架的外殼用的是WindowChrome而不是WindowStyleNone加AllowsTransparencyTrue。后者雖然也能做出無邊框效果但會讓窗口失去硬件加速路徑拖動和縮放時明顯發(fā)澀圓角邊緣還會有鋸齒。WindowChrome保留系統(tǒng)窗口的非客戶區(qū)行為只把繪制權(quán)交給你。!-- Shell/AppWindow.xaml無邊框外殼保留系統(tǒng)縮放與拖拽行為 -- Window x:ClassYourApp.Shell.AppWindow WindowStyleNone ResizeModeCanResize AllowsTransparencyFalse Background{DynamicResource Brush.Surface.Card} !-- CaptionHeight頂部可拖拽區(qū)高度等于標題欄高度 -- !-- ResizeBorderThickness邊緣拖拽熱區(qū)觸屏場景建議放大到 8 -- WindowChrome.WindowChrome WindowChrome CaptionHeight40 ResizeBorderThickness6 GlassFrameThickness0 CornerRadius0 UseAeroCaptionButtonsFalse/ /WindowChrome.WindowChrome Grid Grid.RowDefinitions RowDefinition Height40/ RowDefinition Height*/ /Grid.RowDefinitions !-- 標題欄區(qū)域內(nèi)的按鈕必須聲明 IsHitTestVisibleInChrome否則點不到 -- StackPanel Grid.Row0 OrientationHorizontal HorizontalAlignmentRight WindowChrome.IsHitTestVisibleInChromeTrue Button Content— Style{StaticResource Button.Caption}/ Button Content□ Style{StaticResource Button.Caption}/ Button Content× Style{StaticResource Button.Caption}/ /StackPanel ContentPresenter Grid.Row1 Content{Binding Body}/ /Grid /Window三個參數(shù)決定了使用手感。CaptionHeight要和標題欄那一行的高度嚴格對齊寫 40 就是 40寫小了頂部會剩一條既不能拖也不能點的死區(qū)ResizeBorderThickness在鼠標場景 6 夠了觸屏設(shè)備建議 8 到 10否則邊緣拖不動GlassFrameThickness0去掉系統(tǒng)玻璃層避免深色皮膚下邊緣發(fā)亮。標題欄里的按鈕必須加WindowChrome.IsHitTestVisibleInChromeTrue這一條不加按鈕會變成「看得見點不著」鼠標事件被拖拽區(qū)吃掉了。這是無邊框窗口最常見的一個問題排查時容易往命令綁定上想繞一圈才發(fā)現(xiàn)是命中測試。另一個是最大化蓋住任務(wù)欄。無邊框窗口最大化時系統(tǒng)給的尺寸包含非工作區(qū)直接鋪滿會頂?shù)羧蝿?wù)欄。簡單的做法是在窗口構(gòu)造里設(shè)MaxHeight SystemParameters.MaximizedPrimaryScreenHeight多顯示器場景下這個值只在主屏正確需要監(jiān)聽WM_GETMINMAXINFO自己算工作區(qū)框架的Shell目錄里有對應(yīng)的輔助類接入時按屏幕數(shù)量確認一下。3.4 驗收入口DPI、縮放、多屏的檢查清單界面框架接進去功能點兩下都正常不代表能交付。下面這張表是我每次接入必過的一遍成本不到十分鐘能提前擋掉大部分返工。檢查項操作不通過的表現(xiàn)單屏 100%系統(tǒng)縮放調(diào)到 100%逐頁翻一遍1px 邊框消失或變粗單屏 150%縮放到 150%看文字與圖標文字發(fā)虛、圖標模糊多屏不同縮放兩屏分別設(shè) 100% 和 150%拖窗口來回拖到另一屏后整體變糊高對比度切換系統(tǒng)高對比度主題文字與背景同色看不見觸摸觸屏設(shè)備上點邊緣縮放邊緣拖不動最小尺寸拖到最小寬高標題欄按鈕被擠出可視區(qū)DPI 那一欄解釋一下WPF 是邏輯像素體系縮放變化時如果圖片資源只準備了一份系統(tǒng)會拉伸結(jié)果就是模糊。圖標盡量用矢量路徑位圖則按 100%、150%、200% 各備一份靠Image的尺寸選擇邏輯去匹配。這條不做用戶在 150% 縮放的筆記本上第一眼就會覺得「這軟件有點舊」。4. MVVM 骨架命令、通知、導航與對話框怎么切界面層的活干完接著看骨架。這套框架的Infrastructure目錄里放的是一套很薄的基礎(chǔ)設(shè)施ViewModelBase、RelayCommand、AsyncCommand、導航服務(wù)、對話框服務(wù)。判斷一套 MVVM 骨架好不好標準只有一條ViewModel 里能不能完全不出現(xiàn)Window、MessageBox、Application.Current。出現(xiàn)了單測就廢了復用也別想了。4.1 ViewModelBase屬性通知與 SetProperty 的寫法public abstract class ViewModelBase : INotifyPropertyChanged { public event PropertyChangedEventHandler? PropertyChanged; // 返回 bool方便 setter 里鏈式通知派生屬性 protected bool SetPropertyT(ref T field, T value, [CallerMemberName] string? name null) { // 用 EqualityComparer 而不是 object.Equals避免值類型裝箱 if (EqualityComparerT.Default.Equals(field, value)) return false; field value; OnPropertyChanged(name); return true; } protected void OnPropertyChanged([CallerMemberName] string? name null) PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name)); }CallerMemberName省掉了手寫屬性名字符串改屬性名時不會漏改通知。相等判斷用EqualityComparerT.Default而不是因為泛型里對值類型是裝箱比較屬性高頻更新時這點開銷會積少成多。返回bool是個很實用的小設(shè)計if (SetProperty(ref _name, value)) OnPropertyChanged(nameof(DisplayName));這樣派生屬性只在真正變化時通知避免無謂的綁定刷新。老項目里常見的寫法是 setter 里連續(xù)調(diào)三次OnPropertyChanged每次輸入都觸發(fā)一輪完整重算。集合屬性是另一個問題點。ObservableCollectionT不要每次賦值都new那等于讓ItemsControl重建整個視圖樹滾動位置會跳回頂部。正確做法是初始化一次之后用Clear()加Add()更新。4.2 RelayCommand 與 AsyncCommandCanExecute 刷新時機的坑public sealed class RelayCommand : ICommand { private readonly Actionobject? _execute; private readonly Funcobject?, bool? _canExecute; public RelayCommand(Actionobject? execute, Funcobject?, bool? canExecute null) { _execute execute ?? throw new ArgumentNullException(nameof(execute)); _canExecute canExecute; } public bool CanExecute(object? parameter) _canExecute?.Invoke(parameter) ?? true; public void Execute(object? parameter) _execute(parameter); public event EventHandler? CanExecuteChanged { add CommandManager.RequerySuggested value; remove CommandManager.RequerySuggested - value; } // 手動觸發(fā)異步命令結(jié)束、集合變化后必須調(diào) public void RaiseCanExecuteChanged() CommandManager.InvalidateRequerySuggested(); }CommandManager.RequerySuggested是隱式刷新只在鍵盤、鼠標等輸入事件之后觸發(fā)。這意味著如果你在后臺線程里改了某個標志位按鈕的可用狀態(tài)可能要等到用戶點一下別的地方才更新。血淚經(jīng)驗是異步命令執(zhí)行完畢、批量數(shù)據(jù)加載完成這類時刻必須顯式調(diào)一次RaiseCanExecuteChanged()否則用戶會看到「按鈕還是灰的但功能其實已經(jīng)好了」。異步命令額外要處理兩件事。一是防重入執(zhí)行中把CanExecute置為false避免用戶連點三次發(fā)出三個請求。二是異常兜底async void里拋出的異常會直接打到未處理異常上進程就掛了?？蚣芾锏腁syncCommand用try/catch包住執(zhí)行體把異常交給注入的錯誤處理器再由它彈提示。public sealed class AsyncCommand : ICommand { private readonly Funcobject?, Task _execute; private readonly Funcobject?, bool? _canExecute; private bool _isRunning; // 防重入標志 public AsyncCommand(Funcobject?, Task execute, Funcobject?, bool? canExecute null) { _execute execute; _canExecute canExecute; } public bool CanExecute(object? parameter) !_isRunning (_canExecute?.Invoke(parameter) ?? true); public async void Execute(object? parameter) { if (_isRunning) return; _isRunning true; RaiseCanExecuteChanged(); try { await _execute(parameter); } catch (Exception ex) { // 必須兜住async void 里的異常無處可去 ErrorHandler?.Invoke(ex); } finally { _isRunning false; RaiseCanExecuteChanged(); } } public event ActionException? ErrorHandler; public event EventHandler? CanExecuteChanged; public void RaiseCanExecuteChanged() CanExecuteChanged?.Invoke(this, EventArgs.Empty); }AsyncCommand我沒有復用CommandManager而是自己維護CanExecuteChanged。原因是異步場景下按鈕狀態(tài)變化跟輸入事件沒有必然關(guān)系走隱式刷新容易失準自己控制雖然要多調(diào)幾次RaiseCanExecuteChanged但行為可預期。4.3 導航與對話框接口怎么切才不綁死 UI接口切分的目標是讓 ViewModel 只描述「要什么」不描述「怎么顯示」。這張表是框架里的切法接口職責不該做的事INavigationService按 ViewModel 類型切換主區(qū)域內(nèi)容不引用具體Page、Window類型IDialogService確認框、輸入框、等待提示不直接調(diào)MessageBoxINotificationService頂欄消息、Toast不持有具體控件的引用IThemeService讀取與切換皮膚不碰Application.Resources的索引public interface IDialogService { // 返回 Task調(diào)用方 await 之后拿結(jié)果避免回調(diào)地獄 Taskbool ConfirmAsync(string title, string message); Taskstring? PromptAsync(string title, string message, string? defaultValue null); }實現(xiàn)側(cè)常見的做法是用一個覆蓋全窗口的ContentControl加半透明遮罩把對話框內(nèi)容當作普通控件渲染返回值靠TaskCompletionSourcebool在用戶點擊時SetResult。這樣對話框也吃同一套 Token深色皮膚下不會出現(xiàn)一個白底黑字的系統(tǒng)彈窗視覺上跳出來。這里要提醒一點TaskCompletionSource必須用TaskCreationOptions.RunContinuationsAsynchronously否則SetResult會在 UI 線程上同步跑完整個await后續(xù)邏輯遇到重活就卡界面。這個問題非常隱蔽表現(xiàn)為「點確認之后界面頓一下」把選項加上就好。5. 避坑記錄樣式不生效、內(nèi)存上漲、DPI 模糊的排查順序這一章是這份框架里最值得先讀的部分。下面四條都是我在真實接入里遇到過的每一條按現(xiàn)象、原因、解決的順序?qū)懹龅酵悊栴}時可以照著順序查。5.1 現(xiàn)象改了 Token控件紋絲不動現(xiàn)象把Color.Accent.Base從藍改成橙重新生成主按鈕還是藍的。清緩存、重啟 IDE 都試過仍然是藍。原因控件模板里引用的是{StaticResource Brush.Accent.Base}。StaticResource在 BAML 解析階段就把值取出來寫死了后續(xù)字典變化對它沒有任何影響。另一種可能是這個頁面的Window.Resources里定義了一個同名的Brush.Accent.Base局部作用域優(yōu)先全局的改動被它遮住。解決在解決方案里搜StaticResource Brush.凡是顏色類的引用全部換成DynamicResource再逐頁檢查Window.Resources和UserControl.Resources里有沒有同名 Key。這兩步做完改動立即生效。我的習慣是把這條寫進代碼評審清單模板里出現(xiàn)StaticResource后面跟Brush.前綴的一律打回。5.2 現(xiàn)象切幾次皮膚內(nèi)存一路往上走現(xiàn)象在設(shè)置頁反復切換淺色和深色任務(wù)管理器里的內(nèi)存從 180MB 漲到 400MB 不回落切得越多漲得越多。原因換膚實現(xiàn)寫成了merged.Add(skin)每次切換都往MergedDictionaries里追加一個字典舊字典既沒被移除也沒被回收資源查找還得從后往前遍歷一長串。另一個隱性原因是畫筆沒凍結(jié)SolidColorBrush每次創(chuàng)建都是新的可凍結(jié)對象沒調(diào)Freeze()就參與變更通知無法被共享。解決換膚改成替換末位元素見 3.2 的寫法Token 里所有SolidColorBrush在創(chuàng)建后調(diào)一次Freeze()凍結(jié)后的畫筆可以被多個控件共享內(nèi)存占用會明顯下降。改完再測反復切換五十次內(nèi)存曲線基本走平。提示Freeze()只能用于可凍結(jié)對象而且凍結(jié)后不能再改屬性。如果某個畫筆需要在運行時調(diào)色就別凍結(jié)它。5.3 現(xiàn)象4K 屏上字體發(fā)虛、1px 邊框消失現(xiàn)象開發(fā)機 100% 縮放一切正常換到 150% 縮放的筆記本上正文明顯發(fā)糊卡片之間的 1px 分隔線時有時無圓角處還有毛邊。原因三個疊加問題。位圖圖標只準備了一份系統(tǒng)拉伸導致模糊Border的BorderThickness用了1但沒開UseLayoutRounding和SnapsToDevicePixels在非整數(shù)縮放比下 1px 被攤到兩個物理像素上顏色被稀釋到看不見再就是窗口設(shè)了AllowsTransparencyTrue透明窗口在部分縮放下失去硬件渲染路徑。解決圖標改用矢量路徑在外殼根元素上開UseLayoutRoundingTrue需要像素對齊的Border和Image加SnapsToDevicePixelsTrue無邊框窗口換回WindowChrome方案。三條一起改150% 下再對比截圖邊緣和文字都恢復銳利。5.4 現(xiàn)象設(shè)計器里正常運行時拋 XamlParseException現(xiàn)象XAML 在設(shè)計器里預覽得好好的一運行就拋XamlParseException提示找不到某個資源堆棧指向一個看起來沒問題的Setter。原因StaticResource的解析是編譯期決定的它只能向前查找——引用必須出現(xiàn)在定義之后或者定義在更早就合并的字典里。設(shè)計器有時會更寬松地加載于是出現(xiàn)「設(shè)計器能看、跑起來就崩」。另一種原因是跨程序集引用時 pack URI 里的程序集名寫錯編譯期不校驗運行時才爆。解決先在App.xaml里把 Token 字典排在最前面確保所有模板在后面再檢查所有跨程序集的Source程序集名、大小寫、component關(guān)鍵字都要對上。定位技巧是把App.xaml里的合并字典臨時注釋掉一半二分法很快能鎖定是哪個文件。5.5 常見問題速查表癥狀第一嫌疑快速驗證換膚后個別控件不變色模板里用了StaticResource全工程搜StaticResource Brush.按鈕點不動標題欄命中測試被吃檢查IsHitTestVisibleInChrome最大化蓋住任務(wù)欄無邊框窗口的尺寸計算看MaxHeight是否按工作區(qū)算列表刷新后滾動條跳頂集合被整體new檢查ObservableCollection賦值處命令按鈕一直灰隱式刷新未觸發(fā)手動調(diào)一次RaiseCanExecuteChanged字體不是預期那個FontFamily的家族名寫錯核對#后面是家族名而非文件名6. 進階把換膚做成可以回歸驗證的流程界面類的改動最難驗證因為它「看起來沒問題」和「確實沒問題」之間差得很遠。這套框架里我最常用的一個技巧是把換膚做成可以對比的回歸流程。第一步把 Token 抽出來做一份中間格式。框架的Tokens目錄本身就是鍵值對用幾十行代碼掃一遍 XAML把Color.*、Font.Size.*、Radius.*導出成 JSON交給設(shè)計側(cè)對齊。之后設(shè)計師改配色改的是這份 JSON工程師用腳本回寫 XAML比在群里發(fā)色值截圖靠譜得多?；貙懩_本要注意保留原有的x:Key順序和縮進否則每次生成都是幾百行 diff評審時沒人看得下去。第二步準備一個「Token 全覽頁」。把所有 Token 渲染成色塊、字號樣例、圓角樣例配上鍵名放在調(diào)試菜單里。換膚以后直接翻這一頁哪個鍵沒被覆蓋一眼就能看出來。這個頁面我一般不到半小時就能拼完但省下來的排查時間遠超投入。第三步截圖比對。把關(guān)鍵頁面在淺色和深色下各截一張存在版本庫里改了樣式之后重新截用逐像素差值定位變化區(qū)域。閾值不要設(shè)在零字體渲染有亞像素抖動允許千分之三以內(nèi)的差異超過就是真改了。這套流程跑順之后改一個 Token 影響哪些頁面提交前就能知道。還有一個小習慣值得說一下每次接入新的界面框架我都會先在空工程里跑一遍它的 Demo把所有頁面點一遍重點看深色皮膚下的對比度和禁用態(tài)。原因很簡單這些地方最容易藏問題而在自身工程里樣式問題會被業(yè)務(wù)邏輯掩蓋很難判斷到底是框架的問題還是你寫錯了。從那以后我每次往項目里引 UI 框架都強制先走一遍這套空工程驗證再動業(yè)務(wù)代碼。希望幫到你。本文還有配套的精品資源點擊獲取