簡(jiǎn)介面向希望基于 WPF 構(gòu)建類 Word 文本編輯環(huán)境的 .NET 開(kāi)發(fā)者這套開(kāi)源富文本編輯器示例提供可直接運(yùn)行的解決方案與可復(fù)用核心組件覆蓋基礎(chǔ)文本編輯、查找替換、HTML 源碼查看、打印、純文本導(dǎo)出、插入圖片和表格等常見(jiàn)能力。壓縮包共 289 個(gè)文件約 753KB以 cs 源碼、xaml/baml 界面資源、gif/png 圖片素材和 dll 程序集為主并包含 sln、csproj 等工程配置便于梳理項(xiàng)目結(jié)構(gòu)與依賴關(guān)系。已有 2875 人學(xué)習(xí)或下載。讀者可借助 HtmlEditor.Demo 了解編輯器界面與交互邏輯通過(guò) HtmlEditor 組件研究富文本處理、圖像與表格數(shù)據(jù)的組織方式并在此基礎(chǔ)上擴(kuò)展格式化選項(xiàng)、文件格式支持或第三方庫(kù)集成適合作為 WPF 桌面端文檔編輯功能的學(xué)習(xí)與二次開(kāi)發(fā)起點(diǎn)。1. 從「原生控件能不能撐住」說(shuō)起接到「仿 Word 的 WPF 富文本編輯器」需求時(shí)多數(shù)人第一反應(yīng)是找商業(yè)控件覺(jué)得原生RichTextBox太玩具。我一開(kāi)始也這么判斷直到用原生控件把一份帶編號(hào)列表、插圖、行距設(shè)置的文檔完整跑通才發(fā)現(xiàn)瓶頸從來(lái)不在控件本身而在于有沒(méi)有把FlowDocument這套文檔模型吃透。這份開(kāi)源 demo 做的事情很樸素用 WPF 原生控件搭出一個(gè)能加粗、能調(diào)字號(hào)、能插圖片、能存 RTF 的編輯區(qū)工具欄和編輯區(qū)之間靠路由命令解耦沒(méi)有任何第三方依賴。它適合兩類人一類是想給桌面端產(chǎn)品加個(gè)簡(jiǎn)易排版能力、又不想背商業(yè)授權(quán)包袱的開(kāi)發(fā)者另一類是剛上手 WPF、想找一個(gè)完整例子把依賴屬性、命令綁定、文檔序列化串起來(lái)的新手。它不打算替代 Word它想做到的是把「編輯器」這件事拆到你能自己動(dòng)手改的程度。2. 技術(shù)選型與工程結(jié)構(gòu)原生控件撐起仿 Word 的殼2.1 RichTextBox 與第三方控件的取舍WPF 里做富文本可選路線其實(shí)只有三條原生RichTextBox加FlowDocument、嵌WebView2跑一段前端編輯器、買商業(yè)控件。三條路的差別不在功能多少而在你后續(xù)要付出什么代價(jià)。原生路線的能力邊界很清晰。FlowDocument是一棵可序列化的文檔樹(shù)段落、行內(nèi)元素、列表、表格都是強(qiáng)類型對(duì)象你能直接用 LINQ 遍歷、直接改屬性、直接掛事件。TextRange提供了對(duì)任意選區(qū)做屬性讀寫(xiě)的能力EditingCommands自帶加粗、斜體、下劃線、項(xiàng)目符號(hào)、編號(hào)、縮進(jìn)、對(duì)齊這一整套命令連撤銷棧都是控件內(nèi)置的。對(duì)一個(gè)「仿 Word 的 demo」來(lái)說(shuō)這套東西的完成度已經(jīng)超出預(yù)期。它的短板同樣明顯。表格編輯能力弱合并單元格、跨頁(yè)表格基本要自己寫(xiě)圖片只能靠InlineUIContainer塞進(jìn)去排版控制粒度粗沒(méi)有分頁(yè)視圖長(zhǎng)文檔滾動(dòng)時(shí)是一次性布局幾萬(wàn)字以上會(huì)明顯卡RTF 導(dǎo)出對(duì)圖片和復(fù)雜樣式的保真度有限。這些是原生控件的天花板選它之前得認(rèn)。第三方控件的優(yōu)勢(shì)是這些坑別人已經(jīng)踩完了表格、分頁(yè)、頁(yè)眉頁(yè)腳、PDF 導(dǎo)出都是現(xiàn)成的。代價(jià)是授權(quán)費(fèi)用、包體積以及最要命的一點(diǎn)——出問(wèn)題時(shí)你只能提工單看不到源碼排查起來(lái)像個(gè)黑匣子。WebView2那條路則是把編輯能力交給前端生態(tài)功能上限最高但 WPF 側(cè)和 JS 側(cè)要維護(hù)一套消息協(xié)議文檔模型存在兩份序列化、撤銷、光標(biāo)狀態(tài)同步都是長(zhǎng)期成本。我一般的判斷標(biāo)準(zhǔn)是如果產(chǎn)品只需要「帶格式的文本 少量圖片 導(dǎo)出」原生控件完全夠用改起來(lái)也最自由如果文檔里表格占比超過(guò)三成或者需要嚴(yán)格的打印分頁(yè)趁早換路線別硬扛。這份 demo 走的是第一條路它的價(jià)值不在于功能齊全而在于每一個(gè)功能都攤開(kāi)在你眼前沒(méi)有黑盒。2.2 目錄結(jié)構(gòu)與三層分層工程結(jié)構(gòu)上這類項(xiàng)目最常見(jiàn)的做法是按職責(zé)切成四塊應(yīng)用層放窗口和啟動(dòng)邏輯控件層放編輯區(qū)和工具欄這兩個(gè)UserControl核心層放命令定義、文檔讀寫(xiě)、剪貼板清洗這些純邏輯樣式層單獨(dú)出一個(gè)資源字典項(xiàng)目方便換膚。這么切的好處是核心層不引用任何Window將來(lái)搬到別的宿主里比如嵌進(jìn)插件不用改代碼。WpfRichEditor/ ├── WpfRichEditor.sln ├── src/ │ ├── WpfRichEditor.App/ # 啟動(dòng)與主窗口 │ │ ├── App.xaml │ │ ├── MainWindow.xaml │ │ └── MainWindow.xaml.cs │ ├── WpfRichEditor.Controls/ # 可復(fù)用控件 │ │ ├── RichEditor.xaml # 編輯區(qū) UserControl │ │ ├── RichEditor.xaml.cs │ │ ├── EditorToolbar.xaml # 頂部工具欄 │ │ └── EditorToolbar.xaml.cs │ ├── WpfRichEditor.Core/ # 無(wú) UI 依賴的邏輯 │ │ ├── Commands/EditorCommands.cs # 自定義 RoutedCommand │ │ ├── Documents/DocumentIO.cs # RTF / XAML 存取 │ │ └── Services/ClipboardSanitizer.cs │ └── WpfRichEditor.Themes/ # 資源字典 │ └── EditorStyles.xaml └── tests/ └── WpfRichEditor.Tests/RichEditor這個(gè)UserControl內(nèi)部只放一個(gè)RichTextBox對(duì)外暴露Document依賴屬性和幾個(gè)方法應(yīng)用樣式、加載、保存工具欄不直接持有RichTextBox引用而是通過(guò)CommandTarget找目標(biāo)。這條約束很關(guān)鍵它決定了后面加第二個(gè)編輯區(qū)時(shí)你要不要重寫(xiě)工具欄。2.3 環(huán)境準(zhǔn)備與第一次運(yùn)行項(xiàng)目是標(biāo)準(zhǔn)的 WPF 工程目標(biāo)框架寫(xiě)net8.0-windows老一點(diǎn)的項(xiàng)目可能是net6.0-windows或net48關(guān)鍵是UseWPF必須為true否則 XAML 編譯器不會(huì)介入InitializeComponent直接找不到。!-- WpfRichEditor.Controls.csproj -- Project SdkMicrosoft.NET.Sdk PropertyGroup !-- WPF 必須鎖 windows 目標(biāo)框架跨平臺(tái) SDK 風(fēng)格項(xiàng)目里這是硬性條件 -- TargetFrameworknet8.0-windows/TargetFramework UseWPFtrue/UseWPF Nullableenable/Nullable LangVersionlatest/LangVersion /PropertyGroup /Project命令行驗(yàn)證比開(kāi) Visual Studio 快先確認(rèn) SDK 裝沒(méi)裝對(duì)再編譯運(yùn)行# 確認(rèn)本機(jī)有 8.0 或 6.0 的 SDK dotnet --list-sdks # 還原 編譯整個(gè)解決方案 dotnet build WpfRichEditor.sln -c Debug # 直接跑主程序不用開(kāi) IDE dotnet run --project src/WpfRichEditor.App/WpfRichEditor.App.csproj三個(gè)命令里最容易出問(wèn)題的是第一條。如果dotnet --list-sdks只列出 6.0 而項(xiàng)目寫(xiě)的是net8.0-windows編譯會(huì)報(bào)NETSDK1045提示當(dāng)前 SDK 不支持目標(biāo)框架反過(guò)來(lái)項(xiàng)目是net48的話就必須用 Visual Studio 的 MSBuilddotnet build會(huì)因?yàn)檎也坏組icrosoft.NETFramework.ReferenceAssemblies失敗。這兩種報(bào)錯(cuò)信息都很直白照著改目標(biāo)框架或者補(bǔ)裝 SDK 即可不算坑。跑起來(lái)之后你會(huì)看到一個(gè)典型的工具欄加編輯區(qū)布局。工具欄從上到下依次是字體、字號(hào)、加粗斜體下劃線、字體顏色、對(duì)齊方式、列表、插入圖片、保存和打開(kāi)。每一項(xiàng)都能點(diǎn)點(diǎn)到?jīng)]選區(qū)的狀態(tài)時(shí)按鈕會(huì)變灰——這個(gè)灰不是寫(xiě)死的是命令的CanExecute在起作用第 4 章會(huì)講清楚它是怎么聯(lián)動(dòng)起來(lái)的。3. 文檔模型拆解FlowDocument 樹(shù)、TextRange 與樣式落盤(pán)3.1 Block 與 Inline 樹(shù)的結(jié)構(gòu)想改這個(gè)編輯器第一件事是把FlowDocument的樹(shù)結(jié)構(gòu)在腦子里建起來(lái)。它只有兩層節(jié)點(diǎn)類型Block是塊級(jí)元素獨(dú)占一行Inline是行內(nèi)元素可以并排。FlowDocument.Blocks是整篇文檔的根集合里面裝Paragraph段落、Section分組、List列表、Table表格、BlockUIContainer塞任意控件。Paragraph.Inlines里裝Run一段同格式文本、Span可嵌套的容器、Bold/Italic/Underline語(yǔ)義化行內(nèi)元素、Hyperlink、InlineUIContainer塞圖片或任意 UI 元素、LineBreak。理解這層結(jié)構(gòu)之后很多「為什么改不動(dòng)」的問(wèn)題就自解了。比如用戶選中一段文字點(diǎn)加粗實(shí)際發(fā)生的是TextRange把選區(qū)拆成若干Run把FontWeight屬性ApplyPropertyValue到每個(gè)Run上Bold元素只是FontWeightBold的語(yǔ)法糖。再比如你想給整篇文檔統(tǒng)一行距操作對(duì)象是Paragraph而不是Run因?yàn)樾芯嗍菈K級(jí)屬性。遍歷這棵樹(shù)最常用的寫(xiě)法是遞歸比如統(tǒng)計(jì)段落數(shù)、批量改對(duì)齊、導(dǎo)出純文本都會(huì)用到// 遞歸展開(kāi)所有塊級(jí)容器只挑出 Paragraph private static IEnumerableParagraph WalkParagraphs(BlockCollection blocks) { foreach (var block in blocks) { switch (block) { case Paragraph p: yield return p; break; case Section section: // Section 是一層分組容器里面還能再套 Block foreach (var child in WalkParagraphs(section.Blocks)) yield return child; break; case List list: // 列表項(xiàng)的正文在 ListItem.Blocks 里注意別漏 foreach (var item in list.ListItems) foreach (var child in WalkParagraphs(item.Blocks)) yield return child; break; case Table table: foreach (var row in table.RowGroups.SelectMany(g g.Rows)) foreach (var cell in row.Cells) foreach (var child in WalkParagraphs(cell.Blocks)) yield return child; break; } } }這段代碼的關(guān)鍵在于「容器要展開(kāi)葉子要產(chǎn)出」。Section、List、Table都是容器自身不承載文本必須繼續(xù)往下走Paragraph是葉子產(chǎn)出后不再遞歸。實(shí)際項(xiàng)目里我見(jiàn)過(guò)有人只遍歷Document.Blocks一層結(jié)果列表和表格里的段落全部漏掉導(dǎo)出純文本時(shí)內(nèi)容缺一半排查半天才發(fā)現(xiàn)是遍歷深度的問(wèn)題。這個(gè)方法后續(xù)會(huì)被文檔大綱、查找替換、全文統(tǒng)計(jì)反復(fù)復(fù)用值得單獨(dú)抽成一個(gè)靜態(tài)工具類。3.2 選中文本改樣式ApplyPropertyValue 的完整鏈路工具欄上每個(gè)格式按鈕最終都落到同一個(gè)方法上TextRange.ApplyPropertyValue。它接收一個(gè)依賴屬性和一個(gè)值把屬性寫(xiě)進(jìn)選區(qū)覆蓋的所有TextElement。字體、字號(hào)、前景色、背景色、加粗、斜體、下劃線全走這條鏈路區(qū)別只是屬性名不同。// 統(tǒng)一的樣式應(yīng)用入口工具欄所有格式按鈕都調(diào)它 private void ApplyToSelection(DependencyProperty property, object value) { var selection _editor.Selection; // 空選區(qū)時(shí)沒(méi)有可寫(xiě)的 TextElement直接寫(xiě)會(huì)靜默失敗 // 這里的處理是把值暫存等用戶真正輸入時(shí)再補(bǔ)避免「點(diǎn)了沒(méi)反應(yīng)」的錯(cuò)覺(jué) if (selection.IsEmpty) { _pendingStyle (property, value); return; } // 整段操作包在 BeginChange/EndChange 里撤銷棧只留一個(gè)記錄點(diǎn) _editor.BeginChange(); try { selection.ApplyPropertyValue(property, value); } finally { _editor.EndChange(); } // 焦點(diǎn)必須還給編輯區(qū)否則用戶按方向鍵發(fā)現(xiàn)光標(biāo)不在文檔里 _editor.Focus(); } // 三個(gè)高頻調(diào)用的封裝 public void ToggleBold() ApplyToSelection(TextElement.FontWeightProperty, _editor.Selection.GetPropertyValue(TextElement.FontWeightProperty) is FontWeight w w FontWeights.Bold ? FontWeights.Normal : FontWeights.Bold); public void SetFontSize(double size) ApplyToSelection(TextElement.FontSizeProperty, size); public void SetForeground(Brush brush) ApplyToSelection(TextElement.ForegroundProperty, brush);逐段說(shuō)清楚。_editor.Selection返回的是TextSelection它繼承自TextRange所以ApplyPropertyValue和GetPropertyValue都能直接用。加粗的切換邏輯先用GetPropertyValue讀回當(dāng)前值再取反這是「按鈕狀態(tài)跟隨光標(biāo)」的基礎(chǔ)——注意讀回的值可能是DependencyProperty.UnsetValue表示選區(qū)里格式不統(tǒng)一這時(shí)候按「未加粗」處理比較符合直覺(jué)。BeginChange/EndChange這一對(duì)很容易被忽略但它直接決定用戶體驗(yàn)。不加的話一次「給整段設(shè)置字號(hào)」會(huì)在撤銷棧里留下幾十條記錄用戶按一次 CtrlZ 只回退一點(diǎn)點(diǎn)得連按十幾下才能回到原樣這屬于典型的「后悔藥不夠吃」。包起來(lái)之后整批操作合并成一個(gè)撤銷單元一次 CtrlZ 全部回退。最后那句_editor.Focus()是血淚經(jīng)驗(yàn)。工具欄是獨(dú)立控件點(diǎn)按鈕時(shí)焦點(diǎn)會(huì)跑到按鈕上選區(qū)在視覺(jué)上還在但TextSelection的錨點(diǎn)可能已經(jīng)失效用戶接著敲字會(huì)插到奇怪的位置。所有修改文檔的命令執(zhí)行完都要把焦點(diǎn)還給編輯區(qū)。3.3 段落級(jí)排版對(duì)齊、行距、縮進(jìn)與列表行內(nèi)屬性管字符段落屬性管整塊。對(duì)齊、行距、首行縮進(jìn)、段前段后距這些屬性的宿主是Paragraph不是Run。所以設(shè)置方式有兩種選區(qū)跨段落時(shí)用ApplyPropertyValue屬性寫(xiě)Paragraph.TextAlignmentProperty只處理光標(biāo)所在段落時(shí)直接拿CaretPosition.Paragraph改。// 段落對(duì)齊選區(qū)覆蓋多個(gè)段落時(shí)每個(gè) Paragraph 都會(huì)被寫(xiě)一遍 public void SetAlignment(TextAlignment alignment) ApplyToSelection(Paragraph.TextAlignmentProperty, alignment); // 行距必須成對(duì)設(shè)置只改 LineHeight 不生效 public void SetLineHeight(double height) { var paragraph _editor.CaretPosition.Paragraph; if (paragraph is null) return; paragraph.LineHeight height; // 單位是 DIP24 約等于 18pt paragraph.LineStackingStrategy LineStackingStrategy.BlockLineHeight; // 按固定值堆疊 } // 首行縮進(jìn)負(fù)值表示懸掛縮進(jìn) public void SetFirstLineIndent(double indent) ApplyToSelection(Paragraph.TextIndentProperty, indent);LineHeight的單位是設(shè)備無(wú)關(guān)像素DIP1 DIP 等于 1/96 英寸所以 24 大約是 18 磅中文正文常用 24 到 30 之間。真正需要注意的是LineStackingStrategy默認(rèn)值是MaxHeight意思是行高取該行內(nèi)所有元素的最大高度此時(shí)LineHeight基本不起作用必須改成BlockLineHeight才會(huì)按你設(shè)的固定值算。這個(gè)屬性組合是個(gè)經(jīng)典陷阱不少人改完行距發(fā)現(xiàn)沒(méi)反應(yīng)懷疑控件有 bug其實(shí)就差這一行。列表用的是內(nèi)置命令不用自己拼List對(duì)象// 項(xiàng)目符號(hào)和編號(hào)都由 EditingCommands 提供內(nèi)部會(huì)處理 List 容器的創(chuàng)建與拆分 public void ToggleBullets() EditingCommands.ToggleBullets.Execute(null, _editor); public void ToggleNumbering() EditingCommands.ToggleNumbering.Execute(null, _editor); // 增加/減少縮進(jìn)同理 public void IncreaseIndent() EditingCommands.IncreaseIndentation.Execute(null, _editor);這幾個(gè)命令的第二個(gè)參數(shù)必須是RichTextBox本身傳null或者傳Window都會(huì)拋InvalidOperationException因?yàn)槊顑?nèi)部要靠它拿Document和Selection。這是新手最常撞的一堵墻報(bào)錯(cuò)信息只說(shuō)「命令目標(biāo)無(wú)效」不會(huì)告訴你要傳誰(shuí)。3.4 RTF 與 XAML兩條存取路線的差別保存和打開(kāi)是這類 demo 的必備功能WPF 提供了一條極簡(jiǎn)的路徑TextRange.Save和TextRange.Load靠DataFormats決定序列化格式。整個(gè)實(shí)現(xiàn)不超過(guò)二十行。public static class DocumentIO { // 保存為 RTF兼容 Word / WPS但圖片和復(fù)雜樣式會(huì)丟 public static void SaveRtf(FlowDocument document, string path) { var range new TextRange(document.ContentStart, document.ContentEnd); using var stream File.Create(path); range.Save(stream, DataFormats.Rtf); } // 保存為 XAML 包圖片以資源形式打進(jìn) zip保真度最高 public static void SaveXamlPackage(FlowDocument document, string path) { var range new TextRange(document.ContentStart, document.ContentEnd); using var stream File.Create(path); range.Save(stream, DataFormats.XamlPackage); } // 加載時(shí)復(fù)用已有文檔實(shí)例不要 new 一個(gè) FlowDocument 再賦值 public static void Load(FlowDocument document, string path) { var range new TextRange(document.ContentStart, document.ContentEnd); using var stream File.OpenRead(path); var format Path.GetExtension(path).ToLowerInvariant() switch { .rtf DataFormats.Rtf, .xaml DataFormats.XamlPackage, _ DataFormats.Text }; range.Load(stream, format); } }四種格式的取舍用一張表說(shuō)清楚更省事格式常量是否帶圖片能否被 Word 打開(kāi)體積適用場(chǎng)景RTFDataFormats.Rtf部分支持保真度低是中交付給外部、需要跨軟件打開(kāi)XAMLDataFormats.Xaml否圖片直接丟否小內(nèi)部調(diào)試、看文檔結(jié)構(gòu)XAML 包DataFormats.XamlPackage是圖片打進(jìn) zip否大本地存檔、二次加載純文本DataFormats.Text否是最小導(dǎo)出、復(fù)制到別處Save的第一個(gè)參數(shù)是Stream而不是路徑這個(gè)設(shè)計(jì)是有意的它內(nèi)部按字節(jié)寫(xiě)不經(jīng)過(guò)字符串編碼轉(zhuǎn)換所以不會(huì)出現(xiàn)中文亂碼。反過(guò)來(lái)說(shuō)如果你圖省事用StreamWriter包一層再傳進(jìn)去中文必然亂碼因?yàn)?RTF 里的中文是\uNNNN轉(zhuǎn)義序列被編碼轉(zhuǎn)換一次就廢了。這一點(diǎn)在第 5 章還會(huì)展開(kāi)。Load那段代碼里有一句注釋值得再?gòu)?qiáng)調(diào)一遍復(fù)用已有的FlowDocument實(shí)例。很多人寫(xiě)_editor.Document new FlowDocument()再往里灌內(nèi)容看起來(lái)也能跑但撤銷棧會(huì)被整個(gè)重置用戶打開(kāi)文件后按 CtrlZ 什么都不會(huì)發(fā)生。原因在第 5 章細(xì)說(shuō)。4. 工具欄與命令層按鈕怎么真正驅(qū)動(dòng)編輯區(qū)4.1 EditingCommands 直接綁定WPF 的命令系統(tǒng)是這套編輯器的骨架。加粗、斜體、下劃線、左對(duì)齊、居中、右對(duì)齊、兩端對(duì)齊、項(xiàng)目符號(hào)、編號(hào)、增加縮進(jìn)、減少縮進(jìn)、剪切、復(fù)制、粘貼、撤銷、重做——這些全都在EditingCommands和ApplicationCommands里預(yù)置好了工具欄按鈕只需要一行 XAML 就能接上。ToolBarTray DockPanel.DockTop ToolBar !-- CommandTarget 必須指向 RichTextBox否則命令找不到執(zhí)行目標(biāo)按鈕全程灰 -- Button CommandEditingCommands.ToggleBold CommandTarget{Binding ElementNameEditor} ToolTip加粗 (CtrlB) TextBlock TextB FontWeightBold/ /Button Button CommandEditingCommands.ToggleItalic CommandTarget{Binding ElementNameEditor} TextBlock TextI FontStyleItalic/ /Button Button CommandEditingCommands.ToggleUnderline CommandTarget{Binding ElementNameEditor} TextBlock TextU TextDecorationsUnderline/ /Button Separator/ Button CommandEditingCommands.AlignLeft CommandTarget{Binding ElementNameEditor} Content左對(duì)齊/ Button CommandEditingCommands.AlignCenter CommandTarget{Binding ElementNameEditor} Content居中/ Button CommandEditingCommands.AlignJustify CommandTarget{Binding ElementNameEditor} Content兩端/ /ToolBar /ToolBarTrayCommandTarget是這段 XAML 的靈魂。WPF 的路由命令會(huì)從焦點(diǎn)元素開(kāi)始往上冒泡找CommandBinding如果工具欄按鈕和編輯區(qū)不在同一條視覺(jué)樹(shù)路徑上或者焦點(diǎn)根本不在編輯區(qū)命令就找不到目標(biāo)CanExecute返回false按鈕變灰。顯式寫(xiě)CommandTarget等于告訴命令「去這個(gè)控件上執(zhí)行」繞開(kāi)了焦點(diǎn)依賴。這套寫(xiě)法的好處是零代碼。加粗、斜體、對(duì)齊、縮進(jìn)、剪切粘貼、撤銷重做一行 XAML 頂幾十行事件處理。而且CanExecute是自動(dòng)的光標(biāo)在普通段落里ToggleBullets可用光標(biāo)已經(jīng)在列表項(xiàng)里DecreaseIndentation才可用選區(qū)為空時(shí)Cut自動(dòng)變灰。這些狀態(tài)全由控件內(nèi)部維護(hù)你不需要寫(xiě)一行判斷邏輯。4.2 自定義 RoutedCommand 支撐字號(hào)、字體、顏色內(nèi)置命令覆蓋不到的地方就得自己定義。字號(hào)下拉框、字體下拉框、字體顏色選擇器這三個(gè)是剛需EditingCommands里沒(méi)有對(duì)應(yīng)的命令得走自定義RoutedUICommand加CommandBinding的路子。// 自定義命令集中放一個(gè)靜態(tài)類方便 XAML 里用 x:Static 引用 public static class EditorCommands { public static readonly RoutedUICommand ApplyFontSize new RoutedUICommand(應(yīng)用字號(hào), nameof(ApplyFontSize), typeof(EditorCommands)); public static readonly RoutedUICommand ApplyFontFamily new RoutedUICommand(應(yīng)用字體, nameof(ApplyFontFamily), typeof(EditorCommands)); public static readonly RoutedUICommand ApplyForeground new RoutedUICommand(應(yīng)用字體顏色, nameof(ApplyForeground), typeof(EditorCommands)); public static readonly RoutedUICommand InsertImage new RoutedUICommand(插入圖片, nameof(InsertImage), typeof(EditorCommands), new InputGestureCollection { new KeyGesture(Key.I, ModifierKeys.Control | ModifierKeys.Shift) }); }命令定義好之后要在編輯區(qū)上掛CommandBindingExecuted負(fù)責(zé)干活CanExecute負(fù)責(zé)灰不灰RichTextBox x:NameEditor ... RichTextBox.CommandBindings CommandBinding Command{x:Static core:EditorCommands.ApplyFontSize} ExecutedOnApplyFontSize/ CommandBinding Command{x:Static core:EditorCommands.InsertImage} ExecutedOnInsertImage/ /RichTextBox.CommandBindings /RichTextBoxprivate void OnApplyFontSize(object sender, ExecutedRoutedEventArgs e) { // 參數(shù)從工具欄傳進(jìn)來(lái)命令本身不關(guān)心 UI 長(zhǎng)什么樣 if (e.Parameter is not double size || size 0) return; ApplyToSelection(TextElement.FontSizeProperty, size); } private void OnInsertImage(object sender, ExecutedRoutedEventArgs e) { var dialog new OpenFileDialog { Filter 圖片文件|*.png;*.jpg;*.jpeg;*.bmp, Multiselect false }; if (dialog.ShowDialog() ! true) return; var bitmap new BitmapImage(new Uri(dialog.FileName)); // 圖片必須包在 InlineUIContainer 里才能進(jìn)入 FlowDocument 的行內(nèi)流 var image new Image { Source bitmap, Stretch Stretch.Uniform }; var container new InlineUIContainer(image, _editor.CaretPosition); container.BaselineAlignment BaselineAlignment.Center; _editor.CaretPosition container.ElementEnd; _editor.Focus(); }ExecutedRoutedEventArgs.Parameter這個(gè)口子很實(shí)用它讓同一個(gè)命令能接不同來(lái)源的參數(shù)字號(hào)下拉框傳double字體下拉框傳FontFamily顏色選擇器傳Brush。工具欄側(cè)只需要CommandParameter{Binding SelectedItem, ElementNameFontSizeBox}就接上了命令實(shí)現(xiàn)里做一次類型判斷即可。InlineUIContainer那段有個(gè)細(xì)節(jié)構(gòu)造時(shí)傳CaretPosition會(huì)直接把圖片插到光標(biāo)處不需要先操作Inlines.Add再調(diào)整位置。插入完把光標(biāo)挪到container.ElementEnd用戶接著敲字就會(huì)在圖片后面而不是跑到圖片前面去。這是插入圖片最容易翻車的地方光標(biāo)位置不對(duì)用戶體感就是「圖片插進(jìn)去了但打字跑到奇怪的地方」。4.3 撤銷重做與命令可用狀態(tài)聯(lián)動(dòng)RichTextBox自帶撤銷棧IsUndoEnabled默認(rèn)是trueUndoLimit默認(rèn)值是-1不限制實(shí)際項(xiàng)目里建議改成一個(gè)有限值比如 100否則長(zhǎng)時(shí)間編輯超大文檔內(nèi)存會(huì)一路漲。撤銷棧的粒度由BeginChange/EndChange控制這對(duì)方法在第 3 章已經(jīng)用過(guò)這里補(bǔ)充幾個(gè)容易踩的點(diǎn)。// 撤銷重做直接轉(zhuǎn)發(fā)給控件不要自己維護(hù)棧 private void OnUndo(object sender, ExecutedRoutedEventArgs e) _editor.Undo(); private void OnRedo(object sender, ExecutedRoutedEventArgs e) _editor.Redo(); // 工具欄按鈕的可用狀態(tài)跟著控件的 CanUndo / CanRedo 走 private void RefreshUndoState() { BtnUndo.IsEnabled _editor.CanUndo; BtnRedo.IsEnabled _editor.CanRedo; }第一不要在BeginChange和EndChange之間再嵌套一對(duì)。WPF 支持嵌套但嵌套層數(shù)越多撤銷粒度越粗最后可能出現(xiàn)「改十個(gè)段落只留一個(gè)撤銷點(diǎn)」的情況用戶想單獨(dú)回退某一處就做不到了。批量操作包一層就夠。第二任何繞過(guò)TextRange直接改文檔對(duì)象的操作撤銷棧都記不住。比如遍歷所有Paragraph直接改TextAlignment控件不知道你改了CtrlZ 無(wú)法回退。要讓它可撤銷得把這段修改包在_editor.BeginChange()里要讓它不可撤銷比如加載文檔時(shí)批量規(guī)整格式就在加載前把IsUndoEnabled設(shè)為false加載完再打開(kāi)順手_editor.Document保持不變。第三命令的可用狀態(tài)是自動(dòng)的但工具欄如果是自繪按鈕而不是Button加Command綁定就要手動(dòng)在SelectionChanged、TextChanged、CaretPosition變化時(shí)刷新?；煊脙煞N方式是最容易出 bug 的寫(xiě)法一半按鈕自動(dòng)灰一半按鈕永遠(yuǎn)可點(diǎn)測(cè)試提的 bug 單上就寫(xiě)「格式按鈕狀態(tài)混亂」。我一般統(tǒng)一走Command綁定實(shí)在需要自繪的地方才手動(dòng)同步盡量減少狀態(tài)源。5. 避坑與排查五條踩出來(lái)的記錄5.1 從 Word 粘貼后整篇樣式崩掉現(xiàn)象用戶從 Word 復(fù)制一段帶樣式的文字粘進(jìn)來(lái)編輯區(qū)里原本設(shè)置好的字號(hào)、字體、行距全部被覆蓋有時(shí)候還會(huì)冒出奇怪的頁(yè)邊距撤銷也回不到粘貼前的狀態(tài)。原因剪貼板里同時(shí)存在DataFormats.Rtf、DataFormats.Xaml、DataFormats.UnicodeText等多種格式RichTextBox默認(rèn)會(huì)優(yōu)先挑格式最豐富的那種把外來(lái) RTF 里的一堆樣式表和文檔級(jí)屬性一并吞進(jìn)來(lái)。Word 導(dǎo)出的 RTF 帶著它自己的樣式定義進(jìn)來(lái)之后和當(dāng)前文檔的屬性打架誰(shuí)后寫(xiě)誰(shuí)贏。解決攔截DataObject.Pasting事件在粘貼真正發(fā)生前把數(shù)據(jù)對(duì)象換掉只保留純文本或者只保留最基礎(chǔ)的格式。// 在編輯區(qū)的構(gòu)造函數(shù)里掛一次 _editor.AddHandler(DataObject.PastingEvent, new DataObjectPastingEventHandler(OnPasting)); private void OnPasting(object sender, DataObjectPastingEventArgs e) { // 只接受純文本把外來(lái)的 RTF / XAML 全部丟掉 if (e.SourceDataObject.GetDataPresent(DataFormats.UnicodeText, true)) { var text (string)e.SourceDataObject.GetData(DataFormats.UnicodeText); e.DataObject new DataObject(DataFormats.UnicodeText, text); return; } // 連純文本都沒(méi)有直接取消這次粘貼 e.CancelCommand(); }如果想保留一部分格式就不要整體替換數(shù)據(jù)對(duì)象而是把 RTF 取出來(lái)做一次清洗去掉\paperw、\stylesheet這類文檔級(jí)控制字再用TextRange.Load手動(dòng)插到光標(biāo)處。這條路更細(xì)但代碼量翻好幾倍demo 階段用純文本方案完全夠。5.2 長(zhǎng)文檔輸入明顯卡頓現(xiàn)象文檔寫(xiě)到一兩萬(wàn)字、段落數(shù)上千之后每次敲鍵都有幾百毫秒延遲滾動(dòng)也發(fā)澀任務(wù)管理器里進(jìn)程內(nèi)存一路漲。原因FlowDocument是流式布局沒(méi)有虛擬化任何一次內(nèi)容變更都會(huì)觸發(fā)受影響范圍內(nèi)重新測(cè)量和排版。如果RichTextBox被放在ScrollViewer里外層滾動(dòng)容器給它的可用高度是無(wú)限大它會(huì)嘗試一次性布局整篇文檔性能直接崩。另一種常見(jiàn)情況是PageWidth沒(méi)設(shè)文檔寬度跟著宿主走窗口一拉寬所有段落重新折行。解決把RichTextBox從外層ScrollViewer里拿出來(lái)用自身的VerticalScrollBarVisibilityAuto給FlowDocument設(shè)一個(gè)固定的PageWidth和PagePadding讓折行結(jié)果穩(wěn)定段落數(shù)特別多時(shí)按章節(jié)拆文檔或者加一個(gè)「只渲染當(dāng)前可見(jiàn)頁(yè)」的分頁(yè)視圖。這三條里第一條見(jiàn)效最快也最容易被忽略。!-- 錯(cuò)誤寫(xiě)法外層套 ScrollViewer編輯區(qū)高度無(wú)限布局全量跑 -- ScrollViewer RichTextBox x:NameEditor/ /ScrollViewer !-- 正確寫(xiě)法讓編輯區(qū)自己管滾動(dòng)文檔寬度固定 -- RichTextBox x:NameEditor VerticalScrollBarVisibilityAuto HorizontalScrollBarVisibilityDisabled FlowDocument PageWidth794 PagePadding72,56,72,56 Paragraph/ /FlowDocument /RichTextBoxPageWidth794對(duì)應(yīng) A4 紙?jiān)?96 DPI 下的寬度左右邊距 72 DIP 約等于 0.75 英寸這套數(shù)值和 Word 的默認(rèn)版心基本對(duì)齊視覺(jué)上比較自然。5.3 打開(kāi)文檔后撤銷鍵失效現(xiàn)象程序啟動(dòng)后編輯幾下CtrlZ 正常點(diǎn)「打開(kāi)」加載一個(gè)文件之后再編輯CtrlZ 就不動(dòng)了撤銷按鈕也一直是灰的。原因加載時(shí)寫(xiě)了_editor.Document new FlowDocument()把整個(gè)文檔對(duì)象換掉了。撤銷棧是掛在RichTextBox上、跟著Document實(shí)例走的文檔一換棧直接清空并重置舊內(nèi)容的歷史記錄全部丟失。解決復(fù)用同一個(gè)FlowDocument實(shí)例用TextRange覆蓋它的內(nèi)容如果確實(shí)需要重置撤銷棧比如加載后不希望用戶撤銷回上一個(gè)文件顯式在加載前后切IsUndoEnabled讓行為可控。private void OpenDocument(string path) { // 加載期間關(guān)掉撤銷避免「加載」本身變成一條可撤銷記錄 _editor.IsUndoEnabled false; try { DocumentIO.Load(_editor.Document, path); // 復(fù)用實(shí)例不清空棧引用 } finally { _editor.IsUndoEnabled true; _editor.CaretPosition _editor.Document.ContentStart; _editor.Focus(); } }5.4 中文輸入法期間選區(qū)丟失、字符順序錯(cuò)亂現(xiàn)象用拼音輸入法打字時(shí)如果中途點(diǎn)了工具欄的加粗或者字號(hào)候選框會(huì)消失已經(jīng)輸入的拼音被打斷有時(shí)候字符還會(huì)插到光標(biāo)前面去。原因輸入法組合字符串composition string還沒(méi)上屏?xí)rTextSelection處于一種中間狀態(tài)此時(shí)調(diào)用ApplyPropertyValue或讓編輯區(qū)失焦會(huì)強(qiáng)行結(jié)束組合導(dǎo)致輸入法緩沖區(qū)的內(nèi)容丟失或錯(cuò)位。工具欄按鈕點(diǎn)擊本身也會(huì)讓RichTextBox失焦而 IME 對(duì)失焦非常敏感。解決在工具欄按鈕的命令執(zhí)行前判斷輸入法狀態(tài)組合期間直接拒絕執(zhí)行或者不判斷但保證命令執(zhí)行完立刻把焦點(diǎn)還回來(lái)讓 IME 有機(jī)會(huì)恢復(fù)。private void OnApplyFontSize(object sender, ExecutedRoutedEventArgs e) { // 輸入法正在組合時(shí)不要?jiǎng)游臋n否則拼音會(huì)被打斷 if (InputMethod.Current.ImeState InputMethodState.On InputMethod.Current.ImeConversionMode.HasFlag(ImeConversionModeValues.Native)) { // 這里選擇直接返回也可以給個(gè)提示讓用戶先上屏 return; } if (e.Parameter is not double size) return; ApplyToSelection(TextElement.FontSizeProperty, size); }更穩(wěn)妥的做法是在工具欄的PreviewMouseDown里做判斷并e.Handled true從源頭阻止焦點(diǎn)轉(zhuǎn)移。這類問(wèn)題在測(cè)試階段很容易漏因?yàn)闇y(cè)試同學(xué)多用英文輸入上線后中文用戶一多就集中爆發(fā)。5.5 導(dǎo)出 RTF 后中文亂碼、圖片消失現(xiàn)象存成.rtf用 Word 打開(kāi)中文全變成問(wèn)號(hào)或者方塊帶圖片的文檔打開(kāi)后圖片位置是空白有時(shí)文件能打開(kāi)但格式全亂。原因中文亂碼十有八九是中間經(jīng)過(guò)了一次字符編碼轉(zhuǎn)換。TextRange.Save應(yīng)該直接接收FileStream如果為了「保險(xiǎn)」先Save到MemoryStream再用StreamReader讀成字符串寫(xiě)文件RTF 里的\uNNNN轉(zhuǎn)義就被破壞掉了。圖片消失則是 RTF 格式本身的限制WPF 的 RTF 序列化對(duì)InlineUIContainer里的圖片支持很弱很多情況下直接跳過(guò)。解決中文問(wèn)題保證Save的Stream是從文件直接打開(kāi)的中間不做任何字符串轉(zhuǎn)換圖片問(wèn)題改存DataFormats.XamlPackage它是 zip 包圖片作為資源打進(jìn)去加載時(shí)能完整還原。必須交付 RTF 的話就把圖片單獨(dú)導(dǎo)出成文件正文里留占位符接收方自己插圖——聽(tīng)起來(lái)笨但比導(dǎo)出一個(gè)「圖片全丟」的 RTF 更可靠。// 正確流直接來(lái)自文件不經(jīng)過(guò)任何編碼轉(zhuǎn)換 using (var stream File.Create(path)) { range.Save(stream, DataFormats.Rtf); } // 錯(cuò)誤示范中間轉(zhuǎn)了一次字符串中文必亂 using var memory new MemoryStream(); range.Save(memory, DataFormats.Rtf); var content Encoding.UTF8.GetString(memory.ToArray()); // 這里就毀了 File.WriteAllText(path, content);6. 二次開(kāi)發(fā)把 demo 改成能用的編輯器拿到這份代碼之后最值得先做的一件事是把編輯區(qū)徹底組件化。demo 里RichEditor已經(jīng)把RichTextBox包了一層但對(duì)外暴露的還是控件本身宿主窗口可以直接摸到Editor.Document。我一般會(huì)再收一層對(duì)外只留Document依賴屬性、LoadAsync、SaveAsync和幾個(gè)格式操作方法內(nèi)部RichTextBox標(biāo)成internal。這樣將來(lái)加第二個(gè)編輯區(qū)比如批注面板、對(duì)比視圖時(shí)工具欄的CommandTarget只要換綁定源邏輯一行不用改。第二個(gè)改造點(diǎn)是樣式預(yù)設(shè)?，F(xiàn)在工具欄是「點(diǎn)一下改一下」的即時(shí)模式用戶想統(tǒng)一全文格式得全選再點(diǎn)。加一套R(shí)esourceDictionary里的段落樣式標(biāo)題一、標(biāo)題二、正文、引用用Style加BasedOn定義字號(hào)、行距、段前段后距工具欄改成下拉選擇選中后對(duì)光標(biāo)所在段落paragraph.Style ...。FlowDocument對(duì)Style的支持是完整的這套改造成本很低但對(duì)「像 Word」這件事的提升立竿見(jiàn)影。第三個(gè)是查找替換。FlowDocument沒(méi)有內(nèi)置查找得自己遍歷Run用TextRange定位再高亮。核心思路是從Document.ContentStart開(kāi)始用GetTextInRun逐個(gè)取文本塊命中后new TextRange(start, end).ApplyPropertyValue(TextElement.BackgroundProperty, highlightBrush)。要注意跨Run的匹配比如「富文本」三個(gè)字被加粗拆成兩段穩(wěn)妥的做法是先拼全文再算偏移然后用GetPositionAtOffset反查這條路徑慢但準(zhǔn)幾千字的文檔完全夠用。最容易被低估的改造點(diǎn)是文檔大綱。FlowDocument沒(méi)有「標(biāo)題」概念得靠Paragraph.Style或者自定義附加屬性標(biāo)記段落級(jí)別然后遍歷一遍生成樹(shù)。這一步做完左側(cè)掛一個(gè)TreeView點(diǎn)擊節(jié)點(diǎn)滾到對(duì)應(yīng)段落paragraph.BringIntoView()整個(gè)編輯器的體感就從「能打字的框」變成了「能寫(xiě)文章的軟件」。驗(yàn)證這塊我給個(gè)實(shí)用建議編輯器這類控件不要只靠手點(diǎn)?？梢栽跍y(cè)試項(xiàng)目里起一個(gè) STA 線程創(chuàng)建RichTextBox加載一段構(gòu)造好的 RTF跑一遍格式應(yīng)用再斷言GetPropertyValue的返回值。WPF 控件必須在 STA 線程上創(chuàng)建測(cè)試框架默認(rèn)是 MTA忘了加[STAThread]或者線程 ApartmentState 設(shè)置測(cè)試會(huì)直接拋InvalidOperationException報(bào)錯(cuò)信息還不明顯。// 測(cè)試?yán)飫?chuàng)建 WPF 控件的標(biāo)準(zhǔn)姿勢(shì) [Fact] public void ApplyBold_ShouldChangeFontWeight() { Exception? captured null; var thread new Thread(() { try { var editor new RichTextBox(); editor.Document.Blocks.Add(new Paragraph(new Run(測(cè)試文本))); // 全選后應(yīng)用加粗再讀回驗(yàn)證 editor.Selection.Select(editor.Document.ContentStart, editor.Document.ContentEnd); editor.Selection.ApplyPropertyValue(TextElement.FontWeightProperty, FontWeights.Bold); var weight editor.Selection.GetPropertyValue(TextElement.FontWeightProperty); Assert.Equal(FontWeights.Bold, weight); } catch (Exception ex) { captured ex; } }); thread.SetApartmentState(ApartmentState.STA); thread.Start(); thread.Join(); if (captured is not null) throw captured; }最后說(shuō)個(gè)心態(tài)上的事。這個(gè) demo 最容易讓人上頭的地方是它讓你覺(jué)得「再補(bǔ)幾個(gè)功能就能上線」——表格、分頁(yè)、頁(yè)眉頁(yè)腳、PDF 導(dǎo)出每一項(xiàng)看起來(lái)都不難。我從那以后每次接編輯器需求都先把「文檔模型」和「視圖」的邊界畫(huà)一遍再動(dòng)手哪些數(shù)據(jù)必須進(jìn)FlowDocument哪些只存在于宿主序列化時(shí)怎么保證兩邊對(duì)得上。邊界畫(huà)不清楚功能補(bǔ)得越多后面重構(gòu)越疼。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取