Introduktion
Den här guiden tittar på hur Aspose.Words FOSS för .NET representerar ett Word-dokument i minnet, och på de API:er som används för att bygga, navigera och ändra den representationen: DocumentBuilder för sekventiell författning, nodträdet (Node, CompositeNode, NodeCollection) för direkt strukturell åtkomst, DocumentVisitor för att bearbeta varje nodtyp i ett pass, sök-och-ersätt via Range och FindReplaceOptions, samt metoderna för att kombinera och klona dokument. Där annonsinlägget introducerar biblioteket som helhet, så fokuserar den här på dokumentobjektmodellen (DOM) — det största området på API-ytan — och hur dess delar passar ihop.
Aspose.Words FOSS för .NET släpps under MIT-licensen utan inhemska beroenden; den riktar sig mot .NET Standard 2.0, så DOM-en som beskrivs här är tillgänglig på .NET Framework 4.6.2+ och .NET 6, 8 och 10, på Windows, Linux och macOS. Installera den via NuGet, eller bygg den från källkod — se Snabbstart nedan.
Varje uppgift som beskrivs nedan — skriva en rapport från början, omstrukturera en befintlig .docx-fil, gå igenom dess innehåll för analys, eller samla flera dokument till ett — börjar med samma fåtal grundtyper: Document, DocumentBuilder och Node-hierarkin under dem.
Den Document Object Model
Bygga dokument med DocumentBuilder
DocumentBuilder är en markörbaserad skribent som sitter ovanpå ett Document och infogar innehåll sekventiellt. Write(text) och Writeln(text) lägger till text på den aktuella positionen; InsertParagraph() och InsertBreak(breakType) lägger till stycke- och sida/kolumn/sektion-brytningar. Formatering är tillståndsbaserad: byggarens Font, ParagraphFormat, ListFormat och PageSetup-egenskaper gäller för allt som skrivs efteråt, och PushFont() / PopFont() sparar och återställer det aktuella teckensnittstillståndet så att en tillfällig stiländring inte behöver ångras manuellt. Navigeringsmetoder flyttar markören var som helst i ett befintligt dokument — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex), och den generella MoveTo(node) — och DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph och DocumentBuilder.CurrentSection rapporterar var byggaren för närvarande befinner sig. För endast läsning av text där ett fullständigt DOM inte behövs, erbjuder PlainTextDocument en lättare väg: new PlainTextDocument(fileName) exponerar bara egenskapen PlainTextDocument.Text samt dokumentets inbyggda och anpassade egenskaper.
Nodträdet: Sektioner, Stycken, Runs och Tabeller
Ett Document är ett träd av Node-objekt med roten i själva dokumentet: Section → Body → Paragraph → Run för brödtext, med Table → Row → Cell som grenar där en tabell förekommer. CompositeNode, basklassen för varje behållarnod, exponerar CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling och Node.PreviousSibling för direkt traversering, GetChildNodes(nodeType, isDeep) för att samla alla noder av en given NodeType (Paragraph, Run, Table och så vidare) på vilken djupnivå som helst, samt GetChild(nodeType, index, isDeep) för indexerade uppslag. AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) och RemoveChild(oldChild) muterar trädet direkt. CompositeNode.SelectNodes(xpath) och SelectSingleNode(xpath) väljer noder med ett XPath-likt uttryck istället för att gå igenom trädet för hand, och för mycket stora dokument kan Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) gå igenom varje nod en i taget utan rekursion.
DocumentVisitor: Bearbetning av varje nodtyp i ett pass
Att subklassa DocumentVisitor är sättet att bearbeta ett dokument utan att hårdkoda dess struktur. Den definierar parade Visit-Start / Visit-End-metoder för varje kompositnodtyp, inklusive DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart och DocumentVisitor.VisitBookmarkStart — var och en med en motsvarande End-callback — samt DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd och DocumentVisitor.VisitRun för enskilda textkörningar. Anropa Accept(visitor) på ett Document, Section eller någon annan nod för att köra besökaren över den noden och allt som ligger under den; AcceptStart(visitor) och AcceptEnd(visitor) anropar endast ingångs- och utgångscallbacks för en enskild kompositnod. Varje Visit-metod returnerar ett VisitorAction-värde som styr hur traverseringen fortsätter — Continue för att gå in i underträdet, SkipThisNode för att hoppa över det, eller Stop för att avbryta helt.
Hitta och Ersätta Text
Range.Replace(pattern, replacement) utför en sök-och-ersätt på det Range som äger den — ett helt Document, en Section eller någon nods egna Range-egenskap — med sökmönstret som kan vara antingen en bokstavlig sträng eller ett reguljärt uttryck. Överlagringen Range.Replace(pattern, replacement, options) tar en FindReplaceOptions-instans för att styra FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, sökriktning FindReplaceOptions.Direction (ett FindReplaceDirection-värde av Forward eller Backward), formatering som appliceras på ersättningstexten (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat) och vilket omgivande innehåll som ska lämnas orört (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes och relaterade Ignore*-flaggor). För logik per matchning som går utöver en enkel substitution, implementera Replacing(args)-metoden i IReplacingCallback och tilldela implementationen till FindReplaceOptions.ReplacingCallback; varje matchning anropar tillbaka med ett ReplacingArgs som beskriver matchen, och returvärdet från callback-metoden — ett ReplaceAction-värde av Replace, Skip eller Stop — bestämmer vad som händer med den.
Kombinera och Klona Dokument
Document.AppendDocument(srcDoc, importFormatMode) lägger till hela innehållet i ett Document i slutet på ett annat. Dess importFormatMode-argument — ett ImportFormatMode-värde av UseDestinationStyles, KeepSourceFormatting eller KeepDifferentStyles — bestämmer hur stilkonflikter mellan källan och destinationen löses, och överlagringen Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) ger finare kontroll via ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists och liknande flaggor). För att infoga ett annat dokuments innehåll på en specifik position istället för i slutet, gör DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) motsvarande från builderns aktuella markörposition, och DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) infogar samma innehåll utan att lägga till ett stycke- eller sektionsbrytning vid infogningspunkten. Document.ImportNode(srcNode, isImportChildren) kopierar en nod — eventuellt med dess barn — från ett annat dokument så att den kan läggas till i det aktuella, och metoden Node.Clone(isCloneChildren) som finns på alla noder duplicerar strukturen inom samma dokument, t.ex. att återanvända en Section som mall för återkommande innehåll.
Bokmärken och dokumentvariabler
Egenskapen Range.Bookmarks exponerar en BookmarkCollection av namngivna ankare inom det intervallet. DocumentBuilder.StartBookmark(bookmarkName) och EndBookmark(bookmarkName) markerar ett bokmärkess omfattning under byggandet; BookmarkCollection-indexeraren, bookmarks[name], hämtar en senare för DocumentBuilder.MoveToBookmark(bookmarkName)-navigering eller för att läsa Bookmark.Text. Separat lagrar Document.Variables — en VariableCollection — godtyckliga namn/värde-strängpar direkt på själva dokumentet, vilket är användbart för att föra små mängder tillstånd genom en dokumentgenereringspipeline utan att lägga till synligt innehåll.
Snabbstart
Aspose.Words FOSS för .NET är tillgänglig via NuGet:
dotnet add package Aspose.Words.FOSSFör att bygga från källkod istället:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Med en projektreferens till Aspose.Words.csproj på plats följer den kortaste vägen till ett dokument samma mönster som används genom hela detta inlägg: konstruera ett Document, omsluta det i en DocumentBuilder, anropa Write() eller Writeln() för att lägga till text — formatering som sätts på builderns Font- och ParagraphFormat-egenskaper överförs till varje efterföljande skrivning — och anropa Document.Save(fileName) för att skriva ut det som .docx, .docm, .dotx, .dotm, Flat OPC, Markdown eller vanlig text. För att redigera en befintlig fil istället för att börja från början, ladda den direkt med new Document(fileName), flytta buildern till en specifik plats med MoveToBookmark(), MoveToParagraph() eller MoveTo(node), och fortsätt skriva därifrån.
Stödda format
| Format | Filändelse | Läs | Skriv |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alla varianter) | (olika) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Det nodträd som beskrivits ovan är tillgängligt på samma sätt oavsett vilket av dessa format ett dokument lästes in från eller kommer att sparas till — DOM är formatoberoende internt. Vad som inte ingår i denna utgåva är allt som beror på sidlayout: ingen PDF, XPS eller bildexport, och ingen utskrift, så layoutberoende fältvärden såsom sidnummer utvärderas till platshållare istället för att beräknas. De ytterligare formatkonverterarna (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 och WordML) läses inte in eller skrivs, och sammanslagning av post, LINQ Reporting och dokumentjämförelse ingår inte. Utvecklare som behöver dessa funktioner kan gå över till den kommersiella Aspose.Words för .NET utan att skriva om DOM-koden som visas här, eftersom båda utgåvorna delar samma underliggande API.
Öppen källkod & licensiering
Aspose.Words FOSS för .NET släpps under MIT-licensen, fri för kommersiell och personlig användning utan royalties eller restriktioner för vidaredistribution. Källkoden, inklusive den Document, DocumentBuilder, och nodträdimplementeringen som beskrivits ovan, finns tillgänglig i den Aspose.Words FOSS för .NET repository på GitHub.
