Werken met Documenten

Werken met documenten

Aspose.Words FOSS voor .NET stelt elk Word-bestand voor als een in-memory objectmodel dat is verankerd in de Document-klasse, waarbij DocumentBuilder een high-level, cursor-based API biedt voor het maken van inhoud. Deze gids behandelt het maken en laden van documenten, authoring met DocumentBuilder, de sectie/body-structuur, het doorlopen van de knoopboom, het combineren van documenten en het beveiligen ervan.

Documenten maken en laden

Maak een leeg document met new Document(), of open een bestaand bestand door een pad of Stream door te geven aan de Document(fileName)- of Document(stream)-constructor. Overloads die een LoadOptions-argument accepteren stellen je in staat het laadgedrag te beheersen, bijvoorbeeld door een wachtwoord voor een versleuteld bestand te verstrekken.

Voordat je een bestand van een onbekende of onbetrouwbare bron laadt, geeft FileFormatUtil.DetectFileFormat(fileName) (of de Stream-overload) een FileFormatInfo terug die de gedetecteerde LoadFormat beschrijft, en aangeeft of het bestand IsEncrypted, HasDigitalSignature of HasMacros is.

Authoring met DocumentBuilder

DocumentBuilder wikkelt een Document in en stelt een cursor beschikbaar die je door het document beweegt tijdens het invoegen van inhoud. Write(text) en Writeln(text) voegen tekst in op de cursor; InsertParagraph() start een nieuwe alinea. Opmaak-eigenschappen op de builder — Font, ParagraphFormat, ListFormat, PageSetup — worden toegepast op alles wat daarna wordt geschreven.

Verplaats de cursor met MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) of MoveToParagraph(paragraphIndex, characterIndex). De CurrentNode, CurrentParagraph en CurrentSection eigenschappen van de builder geven de huidige positie in de boom weer.

Documentstructuur: Secties en Inhoud

Een Document bevat een SectionCollection (Document.Sections, plus FirstSection / LastSection); elke Section heeft één Body, een optionele collectie kopteksten/voetteksten, en zijn eigen PageSetup. Section.AppendContent(sourceSection) en PrependContent(sourceSection) kopiëren inhoud tussen secties, en ClearContent() reset een sectie zonder deze uit het document te verwijderen.

Binnen een Body wordt inhoud blootgesteld via Body.Paragraphs (een ParagraphCollection) en Body.Tables. Een Range — beschikbaar vanaf Document, Section, Paragraph en andere knooppunten — vertegenwoordigt een aaneengesloten gebied van de boom; Range.Text leest de platte tekst en Range.Replace(pattern, replacement) voert een zoeken-en-vervangen uit uitsluitend over dat gebied.

De knooppuntboom doorlopen met DocumentVisitor

Elk onderdeel van een document — secties, alinea’s, runs, tabellen, velden, vormen, opmerkingen, voetnoten — is een Node in een samengestelde boom met wortel Document. Om elk knooppunt van een bepaald type te verwerken zonder handmatig te recursief te gaan, maak een subklasse van de abstracte DocumentVisitor en overschrijf de Visit*Start / Visit*End callbacks die je nodig hebt, zoals VisitParagraphStart(paragraph) of VisitRun(run), roep vervolgens document.Accept(visitor) aan. Elke callback kan een VisitorAction (Continue, SkipThisNode of Stop) retourneren om te bepalen hoe de traversie verloopt.

Klonen, importeren en inhoud toevoegen

Document.Clone() produceert een diepe kopie van een geheel document. Om inhoud te verplaatsen tussen twee verschillende Document instanties, roep ImportNode(srcNode, isImportChildren) aan op het bestemmingsdocument om een knooppunt uit een vreemde boom binnen te halen, of roep Document.AppendDocument(srcDoc, importFormatMode) aan om de secties van het ene document aan het andere toe te voegen met een gekozen ImportFormatMode — KeepSourceFormatting, UseDestinationStyles of KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) plaatst de inhoud van een brondocument bij de cursor van de builder in plaats van aan het einde van de bestemming.

Documenten beveiligen

Document.Protect(type, password) beperkt bewerken volgens een ProtectionType waarde — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields of NoProtection om de bescherming te verwijderen. Unprotect() (met of zonder wachtwoord) keert dit om. Dit is een bewerkingsbeperking die door Word wordt afgedwongen, los van de OOXML-wachtwoordversleuteling die OoxmlSaveOptions.Password toepast bij het opslaan van een bestand.

Tips en beste praktijken

Geef de voorkeur aan DocumentBuilder voor het construeren van nieuwe inhoud; schakel over naar directe knooppuntmanipulatie (AppendChild, InsertAfter, Clone) wanneer je fijne controle over een bestaande boom nodig hebt.
Roep FileFormatUtil.DetectFileFormat aan voordat je een bestand laadt van een niet-vertrouwde of door de gebruiker geleverde bron, zodat je LoadFormat kunt controleren en ongeondersteunde of versleutelde invoer vroegtijdig kunt afwijzen.
Wanneer je documenten combineert met AppendDocument of InsertDocument, kies dan de ImportFormatMode bewust — KeepSourceFormatting behoudt het uiterlijk van de bron, UseDestinationStyles past de stijlset van het doeldocument aan.
Gebruik een DocumentVisitor-subklasse in plaats van handmatig recursief door de boom lopen wanneer je elke instantie van een knooppunttype consequent moet verwerken.
Document.Protect is een bewerkingsbeperking, geen versleuteling — combineer het met OoxmlSaveOptions.Password als het opgeslagen bestand zelf een wachtwoord moet vereisen om te openen.

Veelvoorkomende problemen

Probleem	Oorzaak	Oplossing
`Document(fileName)` geeft een fout voor een bestand dat in Word prima opent	Het bestandsformaat wordt door deze editie niet ondersteund voor het laden	Roep eerst `FileFormatUtil.DetectFileFormat` aan en controleer de geretourneerde `LoadFormat` voordat je laadt
Toegevoegde inhoud neemt de verkeerde lettertypen of stijlen over	`ImportFormatMode` mismatch tussen de bron- en bestemmingsstijlsets	Geef `KeepSourceFormatting` of `UseDestinationStyles` expliciet door in plaats van te vertrouwen op een standaardwaarde
`DocumentVisitor` traversatie stopt vroeg of slaat inhoud over	Een `VisitStart` / `VisitEnd` override geeft `SkipThisNode` of `Stop` onbedoeld terug	Retourneer `VisitorAction.Continue` van elke override, tenzij je specifiek van plan bent te overslaan of te stoppen
`Unprotect()` heeft geen effect	Het document was niet met een wachtwoord beveiligd, of er werd een verkeerd wachtwoord opgegeven	Roep `Unprotect()` aan zonder argumenten als `Protect` werd aangeroepen zonder wachtwoord, anders geef je het overeenkomstige wachtwoord door

FAQ

Wat is het verschil tussen `Document.Clone()` en `ImportNode`?

Clone() kopieert een heel document naar een nieuwe Document instantie. ImportNode(srcNode, isImportChildren) brengt een enkele node (en optioneel de kinderen) van de boom van één document naar een andere, wat je gebruikt wanneer je specifieke inhoud combineert in plaats van volledige documenten.

Welke bestandsformaten kan `Document(fileName)` laden?

Document(fileName) laadt DOCX, DOCM, DOTX, DOTM, Flat OPC (plus de macro-ingeschakelde en sjabloonvarianten), Markdown en platte tekst. Oudere tekstverwerkings- en webformaten zijn uitgesloten van de laders van deze editie.

Hoe vind ik waar een `DocumentBuilder` zich momenteel bevindt?

Lees CurrentNode, CurrentParagraph of CurrentSection op de builder-instantie.

Versleutelt `Document.Protect` het opgeslagen bestand?

Nee — het is een bewerkingsbeperking die door Word wordt afgedwongen wanneer het bestand wordt geopend. Om een wachtwoord te vereisen alleen om het bestand te openen, stel OoxmlSaveOptions.Password in bij het opslaan.

Hoe lees ik alleen de alinea’s in de hoofdtekst van een document?

Gebruik de Body.Paragraphs collectie, of Body.GetChildNodes(nodeType, isDeep) voor andere knooppeltypen.

API Reference Samenvatting

Klasse/Methode	Beschrijving
`Document`	Wortel van het documentobjectmodel; constructors laden vanuit een bestand of stream, of maken een leeg document aan.
`Document.Save`	Schrijft het document naar een bestand, stream, of HTTP response in een gekozen formaat.
`Document.Clone()`	Produceert een diepe kopie van het volledige document.
`Document.Protect(type, password)` / `Unprotect()`	Past een bewerkingsbeperking toe of verwijdert deze.
`Document.AppendDocument(srcDoc, importFormatMode)`	Voegt de secties van een ander document toe aan dit document.
`DocumentBuilder`	Cursor-gebaseerde API voor het schrijven van tekst en het invoegen van inhoud in een document.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Voegt de inhoud van een brondocument in op de cursor.
`Section` / `SectionCollection`	Een enkele sectie van een document, en de verzameling van alle secties.
`Body`	Container voor de hoofdtekst (alinea’s en tabellen) van een sectie.
`Range`	Een aaneengesloten gebied van de documentboom; ondersteunt `Text` en `Replace`.
`DocumentVisitor`	Abstracte basisklasse voor het doorlopen van elke knoop in de documentboom.
`ProtectionType`	Enum van bewerkingsbeperkingen op documentniveau.
`FileFormatUtil.DetectFileFormat`	Detecteert het formaat van een bestand of stream voordat het wordt geladen.

Zie ook

Aspose.Words for .NET — Enterprise Documentation

Werken met Documenten