Einleitung
Aspose.Words FOSS für .NET enthält dasselbe Textformatierungs-Objektmodell wie die kommerzielle Aspose.Words Engine: Font für Lauf-Level-Attribute, ParagraphFormat für Absatz-Level-Attribute, ListFormat für nummerierte und Aufzählungslisten, FrameFormat für positionierte Textrahmen und Range.Replace für Suchen-und-Ersetzen. Dieser Leitfaden betrachtet speziell diese Ebene — das Formatieren und Umschreiben von bereits im Dokument vorhandenen Text — und nicht das Aufbauen der Dokumentenstruktur von Grund auf (siehe den Einführungs-Beitrag für einen Überblick über die Veröffentlichung).
Die Bibliothek ist MIT-lizenziert, hat keine nativen Abhängigkeiten und zielt auf .NET Standard 2.0 ab, sodass sie auf .NET Framework 4.6.2+ und .NET 6, 8 und 10 läuft. Installieren Sie sie über NuGet oder bauen Sie sie aus dem Quellcode (siehe unten Schnellstart). Alles, was hier beschrieben wird, funktioniert mit .docx, .docm, .dotx, .dotm und Flat-OPC-Dateien, die mit new Document(fileName) geladen wurden, oder mit im Speicher erstellten Dokumenten mittels DocumentBuilder.
Da Aspose.Words FOSS für .NET der echte Aspose.Words-Codebestand ist, der zu einem freien Kern reduziert wurde und nicht neu geschrieben ist, übernimmt das Objektmodell von Font, ParagraphFormat, ListFormat und FrameFormat direkt die kommerzielle Aspose.Words für .NET, falls ein Projekt später Seitenlayout, Rendering oder die zusätzlichen Formatkonverter benötigt, die diese Edition ausschließt.
Hauptfunktionen
Lauf-Level-Formatierung mit Schriftart
Jedes Run stellt eine Font-Eigenschaft bereit, und DocumentBuilder.Font legt die Schriftart fest, die auf den anschließend geschriebenen Text angewendet wird. Neben den offensichtlichen Bold, Italic und Underline (ein Underline-Enum mit Werten wie Single, Double, Dotted, Dash, Wavy und deren *Heavy-Varianten) deckt Font StrikeThrough, DoubleStrikeThrough, Superscript, Subscript, SmallCaps, AllCaps, Hidden, Shadow, Outline, Emboss, Engrave, Color, HighlightColor, Spacing, Position, Kerning, Scaling und EmphasisMark ab. Font.Style, Font.StyleName und Font.StyleIdentifier verknüpfen einen Lauf mit einem Zeichenstil, und Font.ClearFormatting() setzt die direkte Formatierung eines Laufs auf die Stil-Standardwerte zurück. DocumentBuilder stellt zudem Bold, Italic und Underline direkt als Kurzbefehle bereit, plus PushFont() und PopFont(), um den aktuellen Schriftzustand des Builders vor einer temporären Formatierungsänderung zu speichern und wiederherzustellen.
Absatzformatierung mit ParagraphFormat
ParagraphFormat (erreichbar über Paragraph.ParagraphFormat oder DocumentBuilder.ParagraphFormat) steuert die Ausrichtung über das ParagraphAlignment-Enum (Left, Center, Right, Justify, Distributed, plus arabische Kashida- und thailändische verteilte Varianten), die Einrückung über LeftIndent, RightIndent und FirstLineIndent (mit CharacterUnit*-Entsprechungen für ostasiatische Layouts) und den Abstand über SpaceBefore, SpaceAfter und LineSpacingRule/LineSpacing. Das Seitenumbruchverhalten wird mit KeepTogether, KeepWithNext, PageBreakBefore und WidowControl gesteuert, und Bidi kennzeichnet einen Absatz als rechts-nach-links. Benutzerdefinierte Tabulatorstopps befinden sich in ParagraphFormat.TabStops, einer TabStopCollection von TabStop-Objekten, jedes mit einem Position, einem TabAlignment (Left, Center, Right, Decimal, Bar) und einem TabLeader (None, Dots, Dashes, Line, Heavy, MiddleDot). Wie bei Font verknüpfen ParagraphFormat.Style und StyleName den Absatz mit einem benannten Style, und ClearFormatting() löscht die direkte Absatzformatierung.
Listen mit ListFormat
ListFormat (auf Paragraph.ListFormat oder DocumentBuilder.ListFormat) wendet Listformatierung auf einen Absatz an: ApplyBulletDefault() und ApplyNumberDefault() schalten ihn zu einer Standard-Aufzählungs- bzw. nummerierten Liste um, RemoveNumbers() entfernt die Listformatierung vollständig, und ListIndent()/ListOutdent() verschieben ihn zwischen Listenebenen. ListFormat.List gibt die zugrunde liegende List-Definition zurück, und ListFormat.ListLevel liefert das für diesen Absatz wirksame ListLevel, das pro Ebene Einstellungen wie NumberStyle, NumberFormat, Alignment (ein ListLevelAlignment von Left, Center oder Right), StartAt, RestartAfterLevel, ein ebenenspezifisches Font und TrailingCharacter (ein ListTrailingCharacter von Tab, Space oder Nothing) enthält, das den Abstand zwischen Listensymbol und Absatztext steuert. Neue Listendefinitionen stammen von ListCollection.Add(listTemplate) unter Verwendung einer der integrierten ListTemplate-Voreinstellungen (BulletDefault, NumberArabicDot, NumberUppercaseRomanDot und ähnlichen) oder AddSingleLevelList für eine ein-stufige Liste; die Listen eines Dokuments werden über Document.Lists aufgezählt.
Textrahmen mit FrameFormat
Paragraph.FrameFormat ist ein schreibgeschütztes Berichtobjekt: Jede Eigenschaft darauf spiegelt den eines Absatzes aktuelle Frame-Zustand, anstatt ihn direkt festzulegen. IsFrame meldet, ob der Absatz momentan ein Frame ist; Width, Height, und HeightRule meldet seine Größe; HorizontalPosition und VerticalPosition, zusammen mit RelativeHorizontalPosition und RelativeVerticalPosition, berichten Sie, wo es relativ zur Seite, zum Rand, zur Spalte oder zum Absatz verankert ist; und HorizontalDistanceFromText/VerticalDistanceFromText berichten Sie über die Lücke zwischen dem Rahmen und dem umgebenden Fließtext. HorizontalAlignment und VerticalAlignment berichten Sie, wie der Inhalt innerhalb des Rahmens ausgerichtet ist.
Suchen und Ersetzen mit Range und IReplacingCallback
Range.Replace – verfügbar auf Document.Range für einen Durchlauf über das gesamte Dokument oder auf dem Range eines beliebigen Knotens – bietet Überladungen für ein einfaches Muster/Ersetzung-Paar und für ein Muster/Ersetzung-Paar kombiniert mit einer FindReplaceOptions-Instanz, die regex-basiertes Matching unterstützt. FindReplaceOptions.MatchCase und FindWholeWordsOnly schränken ein, was als Treffer gilt; Direction (FindReplaceDirection.Forward oder Backward) legt die Scan-Reihenfolge fest; ApplyFont und ApplyParagraphFormat ermöglichen es einem Ersetzungslauf, die Formatierung auf den Ersetzungstext zu übertragen; und ein Satz von Ignore*-Flags (IgnoreDeleted, IgnoreInserted, IgnoreFields, IgnoreFieldCodes, IgnoreFootnotes, IgnoreStructuredDocumentTags, IgnoreShapes, IgnoreOfficeMath) schließt bestimmte Inhaltskategorien vom Treffer aus. Für Ersetzungslogik, die ein fester String nicht ausdrücken kann, implementieren Sie IReplacingCallback.Replacing(args) und setzen es als FindReplaceOptions.ReplacingCallback (oder übergeben es an einen der FindReplaceOptions-Konstruktoren, die einen Callback direkt akzeptieren); der args-Parameter ist ein ReplacingArgs, das Match, MatchNode, MatchOffset offenlegt und eine einstellbare Replacement-Zeichenkette enthält, sodass der Callback pro Treffer einen Wert berechnen kann. Ein verwandtes ReplaceAction-Enum (Replace, Skip, Stop) beschreibt die möglichen Ergebnisse für einen einzelnen Treffer während des Vorgangs.
Schnellstart
Aspose.Words FOSS für .NET ist über NuGet verfügbar:
dotnet add package Aspose.Words.FOSSUm stattdessen aus dem Quellcode zu bauen:
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
Fügen Sie dann eine Projektreferenz zu Aspose.Words.csproj hinzu. Um Text beim Schreiben zu formatieren, setzen Sie DocumentBuilder.Font Eigenschaften (Bold, Italic, Underline), DocumentBuilder.ParagraphFormat Eigenschaften (Alignment, Einzüge, Abstand) und DocumentBuilder.ListFormat (ApplyBulletDefault(), ApplyNumberDefault()) bevor Sie Write(), Writeln() oder InsertParagraph() aufrufen — der Builder wendet seinen aktuellen Formatierungszustand auf alles Geschriebene an, bis Sie ihn erneut ändern oder eine vorübergehende Änderung in PushFont()/PopFont() einbetten. Um bereits im Dokument vorhandenen Text neu zu formatieren oder umzuschreiben, öffnen Sie ihn mit new Document(fileName) und rufen Range.Replace() auf doc.Range auf — entweder die reine Muster/Ersetzung-Überladung oder die Überladung, die ein FindReplaceOptions mit MatchCase, FindWholeWordsOnly oder einem benutzerdefinierten IReplacingCallback übernimmt — dann Save() Sie das Ergebnis.
Unterstützte Formate
| Format | Erweiterung | Lesen | Schreiben |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle Varianten) | (verschiedene) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Die oben genannten Formatierungsklassen gelten gleichermaßen, unabhängig davon, aus welchem dieser Formate ein Dokument geladen oder in welches es gespeichert wird. Diese Edition unterstützt DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 oder WordML weder zum Lesen noch zum Schreiben und unterstützt PDF, XPS oder den Bildexport nicht, da Seitenlayout und Rendering außerhalb ihres Umfangs liegen.
Open Source & Lizenzierung
Aspose.Words FOSS für .NET wird unter der MIT-Lizenz veröffentlicht, kostenlos für kommerzielle und private Nutzung ohne Lizenzgebühren oder Weiterverbreitungsbeschränkungen. Der vollständige Quellcode, einschließlich der Font, ParagraphFormat, ListFormat, FrameFormat und Range Implementierungen, ist auf GitHub im Aspose.Words FOSS für .NET Repository verfügbar.
