Inleiding
Deze gids kijkt naar hoe Aspose.Words FOSS voor .NET een Word-document in het geheugen weergeeft, en naar de API’s die worden gebruikt om die weergave te bouwen, te navigeren en te wijzigen: DocumentBuilder voor sequentieel schrijven, de knooppomboom (Node, CompositeNode, NodeCollection) voor directe structurele toegang, DocumentVisitor voor het verwerken van elk knooppeltype in één doorloop, zoeken-en-vervangen via Range en FindReplaceOptions, en de methoden voor het combineren en klonen van documenten. Waar de aankondigingspost introduceert de bibliotheek als geheel, deze richt zich op het document-objectmodel (DOM) — het grootste gebied van het API-oppervlak — en hoe de onderdelen in elkaar passen.
Aspose.Words FOSS voor .NET wordt uitgegeven onder de MIT-licentie zonder native afhankelijkheden; het richt zich op .NET Standard 2.0, zodat het hier beschreven DOM beschikbaar is op .NET Framework 4.6.2+ en .NET 6, 8 en 10, op Windows, Linux en macOS. Installeer het via NuGet, of bouw het vanuit de bron — zie Quick Start hieronder.
Elke taak die hieronder wordt beschreven — een rapport vanaf nul schrijven, een bestaand .docx-bestand herstructureren, de inhoud doorlopen voor analyse, of verschillende documenten tot één samenvoegen — begint met dezelfde kleine set basistypen: Document, DocumentBuilder en de Node-hiërarchie eronder.
De Document Object Model
Documenten bouwen met DocumentBuilder
DocumentBuilder is een cursor-gebaseerde schrijver die bovenop een Document zit en inhoud sequentieel invoegt. Write(text) en Writeln(text) voegen tekst toe op de huidige positie; InsertParagraph() en InsertBreak(breakType) voegen alinea- en pagina/kolom/sectie-breuken toe. Opmaak is toestand-afhankelijk: de Font, ParagraphFormat, ListFormat en PageSetup eigenschappen van de builder gelden voor alles wat daarna wordt geschreven, en PushFont() / PopFont() slaan de huidige lettertype-toestand op en herstellen deze, zodat een tijdelijke stijlwijziging niet handmatig ongedaan gemaakt hoeft te worden. Navigatiemethoden verplaatsen de cursor overal in een bestaand document — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex), en de algemene MoveTo(node) — en DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph en DocumentBuilder.CurrentSection geven aan waar de builder zich momenteel bevindt. Voor alleen-lezen tekste-extractie waarbij een volledige DOM niet nodig is, biedt PlainTextDocument een lichtere weg: new PlainTextDocument(fileName) maakt alleen de PlainTextDocument.Text eigenschap en de ingebouwde en aangepaste documenteigenschappen beschikbaar.
De Node Tree: secties, alinea’s, runs en tabellen
Een Document is een boom van Node-objecten met als wortel het document zelf: Section → Body → Paragraph → Run voor hoofdtekst, met Table → Row → Cell die aftakken waar een tabel voorkomt. CompositeNode, de basisklasse voor elk container-node, biedt CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling en Node.PreviousSibling voor directe traversatie, GetChildNodes(nodeType, isDeep) om elk node van een gegeven NodeType (Paragraph, Run, Table, enz.) op elke diepte te verzamelen, en GetChild(nodeType, index, isDeep) voor geïndexeerde opzoekingen. AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) en RemoveChild(oldChild) muteren de boom direct. CompositeNode.SelectNodes(xpath) en SelectSingleNode(xpath) selecteren nodes met een XPath-achtige expressie in plaats van de boom handmatig te doorlopen, en voor zeer grote documenten stappen Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) elke node één voor één door zonder recursie.
DocumentVisitor: elke knooptype in één doorgang verwerken
Subklassen van DocumentVisitor is de manier om een document te verwerken zonder de structuur hard-gecodeerd te hebben. Het definieert gekoppelde Visit-Start / Visit-End-methoden voor elk type composite node, inclusief DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart en DocumentVisitor.VisitBookmarkStart — elk met een bijbehorende End-callback — plus DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd en DocumentVisitor.VisitRun voor individuele tekst-runs. Roep Accept(visitor) aan op een Document, Section of een andere node om de visitor over die node en alles eronder uit te voeren; AcceptStart(visitor) en AcceptEnd(visitor) roepen alleen de entry- en exit-callbacks aan voor één enkele composite node. Elke Visit-methode retourneert een VisitorAction-waarde die bepaalt hoe de traversie doorgaat — Continue in de subboom, SkipThisNode om deze over te slaan, of Stop om volledig te stoppen.
Tekst zoeken en vervangen
Range.Replace(pattern, replacement) voert een zoeken-en-vervangen uit over de Range die het bezit — een geheel Document, een Section, of de eigen Range-eigenschap van een node — waarbij het zoekpatroon wordt geaccepteerd als een letterlijke tekenreeks of een reguliere expressie. De overload Range.Replace(pattern, replacement, options) neemt een FindReplaceOptions-instantie om FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, zoek FindReplaceOptions.Direction (een FindReplaceDirection-waarde van Forward of Backward), opmaak toegepast op vervangende tekst (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat), en welke omringende inhoud onaangeroerd blijft (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes, en verwante Ignore*-vlaggen) te beheersen. Voor logica per overeenkomst die verder gaat dan een eenvoudige substitutie, implementeer de Replacing(args)-methode van IReplacingCallback en wijs de implementatie toe aan FindReplaceOptions.ReplacingCallback; elke overeenkomst roept terug met een ReplacingArgs die de overeenkomst beschrijft, en de retourwaarde van de callback — een ReplaceAction-waarde van Replace, Skip of Stop — bepaalt wat ermee gebeurt.
Documenten combineren en klonen
Document.AppendDocument(srcDoc, importFormatMode) voegt de volledige inhoud van één Document toe aan het einde van een andere. Het argument importFormatMode — een ImportFormatMode-waarde van UseDestinationStyles, KeepSourceFormatting of KeepDifferentStyles — bepaalt hoe stijlconflicten tussen de bron en bestemming worden opgelost, en de overload Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) biedt fijnmazigere controle via ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists en soortgelijke vlaggen). Om de inhoud van een ander document op een specifieke positie in plaats van aan het einde in te voegen, voert DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) het equivalent uit vanaf de huidige cursorpositie van de builder, en DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) voegt dezelfde inhoud in zonder een alinea- of sectie-einde toe te voegen op het invoegpunt. Document.ImportNode(srcNode, isImportChildren) kopieert één knoop — optioneel met zijn kinderen — uit een ander document zodat deze kan worden toegevoegd aan het huidige document, en de methode Node.Clone(isCloneChildren) die op elke knoop beschikbaar is, dupliceert de structuur binnen hetzelfde document, bijvoorbeeld door een Section opnieuw te gebruiken als sjabloon voor herhaalde inhoud.
Bladwijzers en Documentvariabelen
De Range.Bookmarks-eigenschap maakt een BookmarkCollection van benoemde ankers binnen dat bereik beschikbaar. DocumentBuilder.StartBookmark(bookmarkName) en EndBookmark(bookmarkName) markeren de omvang van een bladwijzer tijdens het bouwen; de BookmarkCollection-indexer, bookmarks[name], haalt er later een op voor DocumentBuilder.MoveToBookmark(bookmarkName)-navigatie of voor het lezen van Bookmark.Text. Apart slaat Document.Variables — een VariableCollection — willekeurige naam/waarde-tekenreeksparen direct op het document zelf op, wat handig is om kleine stukjes status mee te nemen door een documentgeneratie-pipeline zonder zichtbare inhoud toe te voegen.
Snelstart
Aspose.Words FOSS voor .NET is beschikbaar via NuGet:
dotnet add package Aspose.Words.FOSSOm in plaats daarvan vanuit de bron te bouwen:
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
Met een projectreferentie naar Aspose.Words.csproj op zijn plaats, volgt de kortste weg naar een document hetzelfde patroon dat in dit artikel wordt gebruikt: maak een Document aan, wikkel deze in een DocumentBuilder, roep Write() of Writeln() aan om tekst toe te voegen — opmaak die is ingesteld op de builder’s Font en ParagraphFormat-eigenschappen, wordt meegenomen in elke volgende schrijfopdracht — en roep Document.Save(fileName) aan om het weg te schrijven als .docx, .docm, .dotx, .dotm, Flat OPC, Markdown of platte tekst. Om een bestaand bestand te bewerken in plaats van vanaf nul te beginnen, laad je het direct met new Document(fileName), verplaats je de builder naar een specifieke locatie met MoveToBookmark(), MoveToParagraph() of MoveTo(node), en ga je vanaf daar verder schrijven.
Ondersteunde formaten
| Formaat | Extensie | Lezen | Schrijven |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle varianten) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
De hierboven beschreven knooppuntboom is op dezelfde manier beschikbaar, ongeacht uit welk van deze formaten een document is geladen of naar welk formaat het zal worden opgeslagen — de DOM is intern formaatonafhankelijk. Wat niet is inbegrepen in deze editie is alles wat afhankelijk is van paginalay-out: geen PDF, XPS of afbeeldingsexport, en geen afdrukken, zodat lay-outafhankelijke veldwaarden zoals paginanummers worden geëvalueerd als tijdelijke aanduidingen in plaats van berekend te worden. De extra formaatconverters (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 en WordML) worden niet gelezen of geschreven, en mail-merge-executie, LINQ-Reporting en documentvergelijking zijn niet inbegrepen. Ontwikkelaars die die mogelijkheden nodig hebben, kunnen overstappen naar de commerciële Aspose.Words voor .NET zonder de hier getoonde DOM-code opnieuw te schrijven, aangezien beide edities dezelfde onderliggende API delen.
Open source & licenties
Aspose.Words FOSS voor .NET wordt uitgebracht onder de MIT-licentie, gratis voor commercieel en persoonlijk gebruik zonder royalty’s of beperkingen op herdistributie. De bron, inclusief de Document, DocumentBuilder, en de hierboven beschreven knooppuntboom-implementatie, is beschikbaar in de Aspose.Words FOSS voor .NET repository op GitHub.
