Praca z dokumentami

Aspose.Words FOSS for .NET reprezentuje każdy plik Word jako model obiektowy w pamięci, którego korzeniem jest klasa Document, a DocumentBuilder zapewnia wysokopoziomowy, oparty na kursorze API do tworzenia treści. Ten przewodnik obejmuje tworzenie i ładowanie dokumentów, autorski proces z DocumentBuilder, strukturę sekcji/ciała, przemierzanie drzewa węzłów, łączenie dokumentów oraz ich ochronę.

Tworzenie i ładowanie dokumentów

Utwórz pusty dokument przy użyciu new Document() lub otwórz istniejący plik, przekazując ścieżkę lub Stream do konstruktora Document(fileName) lub Document(stream). Przeciążenia akceptujące argument LoadOptions pozwalają kontrolować zachowanie ładowania, na przykład podając hasło do zaszyfrowanego pliku.

Przed załadowaniem pliku z nieznanego lub niepewnego źródła, FileFormatUtil.DetectFileFormat(fileName) (lub przeciążenie Stream) zwraca FileFormatInfo opisujący wykryty LoadFormat oraz informację, czy plik jest IsEncrypted, HasDigitalSignature czy HasMacros.

Tworzenie treści przy użyciu DocumentBuilder

DocumentBuilder otacza Document i udostępnia kursor, który przesuwasz po dokumencie podczas wstawiania treści. Write(text) i Writeln(text) wstawiają tekst w miejscu kursora; InsertParagraph() rozpoczyna nowy akapit. Właściwości formatowania w konstruktorze — Font, ParagraphFormat, ListFormat, PageSetup — mają zastosowanie do wszystkiego, co zostanie napisane dalej.

Przesuń kursor przy użyciu MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) lub MoveToParagraph(paragraphIndex, characterIndex). Właściwości CurrentNode, CurrentParagraph i CurrentSection buildera raportują jego bieżącą pozycję w drzewie.

Struktura dokumentu: sekcje i treść

Document zawiera SectionCollection (Document.Sections, plus FirstSection / LastSection); każdy Section ma jeden Body, opcjonalną kolekcję nagłówków/stopki oraz własny PageSetup. Section.AppendContent(sourceSection) i PrependContent(sourceSection) kopiują zawartość między sekcjami, a ClearContent() resetuje sekcję bez usuwania jej z dokumentu.

Wewnątrz Body zawartość jest udostępniana przez Body.Paragraphs (jako ParagraphCollection) i Body.Tables. Range — dostępny z Document, Section, Paragraph i innych węzłów — reprezentuje spójny obszar drzewa; Range.Text odczytuje jego czysty tekst, a Range.Replace(pattern, replacement) wykonuje operację znajdź-i-zamień wyłącznie w tym obszarze.

Poruszanie się po drzewie węzłów przy użyciu DocumentVisitor

Każda część dokumentu — sekcje, akapity, fragmenty, tabele, pola, kształty, komentarze, przypisy dolne — jest Node w drzewie kompozytowym, którego korzeniem jest Document. Aby przetworzyć każdy węzeł danego typu bez ręcznego rekurencyjnego wywoływania, utwórz podklasę abstrakcyjnego DocumentVisitor i nadpisz potrzebne wywołania zwrotne Visit*Start/Visit*End, takie jak VisitParagraphStart(paragraph) lub VisitRun(run), a następnie wywołaj document.Accept(visitor). Każde wywołanie zwrotne może zwrócić VisitorAction (Continue, SkipThisNode lub Stop), aby kontrolować przebieg przeglądania.

Klonowanie, importowanie i dołączanie treści

Document.Clone() tworzy głęboką kopię całego dokumentu. Aby przenieść zawartość pomiędzy dwoma różnymi instancjami Document, wywołaj ImportNode(srcNode, isImportChildren) na dokumencie docelowym, aby wprowadzić węzeł z obcego drzewa, lub wywołaj Document.AppendDocument(srcDoc, importFormatMode), aby dołączyć sekcje jednego dokumentu do drugiego przy użyciu wybranego ImportFormatMode — KeepSourceFormatting, UseDestinationStyles lub KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) wstawia zawartość dokumentu źródłowego w miejscu kursora buildera zamiast na końcu dokumentu docelowego.

Ochrona dokumentów

Document.Protect(type, password) ogranicza edycję zgodnie z wartością ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields lub NoProtection, aby usunąć ochronę. Unprotect() (z hasłem lub bez) odwraca to. Jest to ograniczenie edycji narzucone przez Word, oddzielne od szyfrowania hasłem OOXML, które OoxmlSaveOptions.Password stosuje przy zapisywaniu pliku.

Wskazówki i najlepsze praktyki

Preferuj DocumentBuilder przy tworzeniu nowej treści; przejdź do bezpośredniej manipulacji węzłami (AppendChild, InsertAfter, Clone), gdy potrzebujesz precyzyjnej kontroli nad istniejącym drzewem.
Wywołaj FileFormatUtil.DetectFileFormat przed wczytaniem pliku z niepewnego lub dostarczonego przez użytkownika źródła, aby móc sprawdzić LoadFormat i wcześnie odrzucić nieobsługiwane lub zaszyfrowane dane wejściowe.
Podczas łączenia dokumentów przy użyciu AppendDocument lub InsertDocument, wybierz ImportFormatMode świadomie — KeepSourceFormatting zachowuje wygląd źródła, UseDestinationStyles dopasowuje zestaw stylów dokumentu docelowego.
Użyj podklasy DocumentVisitor zamiast ręcznego rekurencyjnego przechodzenia drzewa, gdy potrzebujesz konsekwentnie przetwarzać każdą instancję określonego typu węzła.
Document.Protect jest ograniczeniem edycji, a nie szyfrowaniem — połącz je z OoxmlSaveOptions.Password, jeśli sam zapisany plik ma wymagać hasła przy otwieraniu.

Typowe problemy

Problem	Przyczyna	Poprawka
`Document(fileName)` zgłasza błąd dla pliku, który otwiera się poprawnie w Wordzie	Format pliku nie jest obsługiwany przez tę edycję przy wczytywaniu	Najpierw wywołaj `FileFormatUtil.DetectFileFormat` i sprawdź zwrócony `LoadFormat` przed wczytaniem
Dołączona zawartość przyjmuje nieprawidłowe czcionki lub style	`ImportFormatMode` niezgodność między zestawami stylów źródła i przeznaczenia	Przekaż `KeepSourceFormatting` lub `UseDestinationStyles` jawnie zamiast polegać na wartości domyślnej
Przeglądanie `DocumentVisitor` kończy się przedwcześnie lub pomija zawartość	Nadpisanie `VisitStart` / `VisitEnd` zwraca `SkipThisNode` lub `Stop` niezamierzenie	Zwróć `VisitorAction.Continue` w każdym nadpisaniu, chyba że konkretnie zamierzasz pominąć lub zatrzymać
`Unprotect()` nie ma żadnego efektu	Dokument nie był zabezpieczony hasłem, lub podano niewłaściwe hasło	Wywołaj `Unprotect()` bez argumentów, jeśli `Protect` zostało wywołane bez hasła, w przeciwnym razie przekaż odpowiednie hasło

FAQ

Jaka jest różnica między `Document.Clone()` a `ImportNode`?

Clone() kopiuje cały dokument do nowej instancji Document. ImportNode(srcNode, isImportChildren) przenosi pojedynczy węzeł (i opcjonalnie jego potomków) z drzewa jednego dokumentu do drugiego, co jest używane, gdy łączy się określoną zawartość zamiast całych dokumentów.

Jakie formaty plików może `Document(fileName)` ładować?

Document(fileName) ładuje DOCX, DOCM, DOTX, DOTM, Flat OPC (wraz z wariantami z makrami i szablonami), Markdown oraz zwykły tekst. Starsze formaty edytorów tekstu i formaty internetowe są wykluczone z loaderów tej edycji.

Jak mogę znaleźć, gdzie aktualnie znajduje się `DocumentBuilder`?

Przeczytaj CurrentNode, CurrentParagraph lub CurrentSection w instancji buildera.

Czy `Document.Protect` szyfruje zapisany plik?

Nie — jest to ograniczenie edycji narzucone przez Word podczas otwierania pliku. Aby wymagać hasła tylko przy otwieraniu pliku, ustaw OoxmlSaveOptions.Password podczas zapisywania.

Jak odczytać tylko akapity w treści dokumentu?

Użyj kolekcji Body.Paragraphs, lub Body.GetChildNodes(nodeType, isDeep) dla innych typów węzłów.

API Reference Podsumowanie

Klasa/Metoda	Opis
`Document`	Korzeń modelu obiektowego dokumentu; konstruktory ładują z pliku lub strumienia albo tworzą pusty dokument.
`Document.Save`	Zapisuje dokument do pliku, strumienia lub odpowiedzi HTTP w wybranym formacie.
`Document.Clone()`	Tworzy głęboką kopię całego dokumentu.
`Document.Protect(type, password)` / `Unprotect()`	Zastosowuje lub usuwa ograniczenie edycji.
`Document.AppendDocument(srcDoc, importFormatMode)`	Dołącza sekcje innego dokumentu do tego.
`DocumentBuilder`	Oparte na kursorskim API do pisania tekstu i wstawiania treści do dokumentu.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Wstawia zawartość dokumentu źródłowego w miejscu kursora.
`Section` / `SectionCollection`	Pojedyncza sekcja dokumentu oraz zbiór wszystkich sekcji.
`Body`	Kontener dla głównego tekstu (akapitów i tabel) sekcji.
`Range`	Spójny obszar drzewa dokumentu; obsługuje `Text` i `Replace`.
`DocumentVisitor`	Abstrakcyjna klasa bazowa do przemierzania każdego węzła w drzewie dokumentu.
`ProtectionType`	Enum ograniczeń edycji na poziomie dokumentu.
`FileFormatUtil.DetectFileFormat`	Wykrywa format pliku lub strumienia przed jego wczytaniem.

Zobacz także

Aspose.Words for .NET — Enterprise Documentation

Praca z dokumentami