Làm việc với Tài liệu

Aspose.Words FOSS cho .NET đại diện cho mỗi tệp Word như một mô hình đối tượng trong bộ nhớ có gốc tại lớp Document, với DocumentBuilder cung cấp một API cấp cao, dựa trên con trỏ để tạo nội dung. Hướng dẫn này bao gồm việc tạo và tải tài liệu, tạo nội dung với DocumentBuilder, cấu trúc phần/thân, duyệt cây nút, kết hợp tài liệu và bảo vệ chúng.

Tạo và Tải Tài liệu

Tạo một tài liệu trống bằng new Document(), hoặc mở một tệp hiện có bằng cách truyền một đường dẫn hoặc Stream cho hàm khởi tạo Document(fileName) hoặc Document(stream). Các phiên bản quá tải chấp nhận đối số LoadOptions cho phép bạn kiểm soát hành vi tải, chẳng hạn như cung cấp mật khẩu cho tệp được mã hóa.

Trước khi tải một tệp từ nguồn không xác định hoặc không tin cậy, FileFormatUtil.DetectFileFormat(fileName) (hoặc phiên bản quá tải Stream) trả về một FileFormatInfo mô tả LoadFormat đã phát hiện, và liệu tệp IsEncrypted, HasDigitalSignature, hoặc HasMacros.

Tạo nội dung với DocumentBuilder

DocumentBuilder bao bọc một Document và cung cấp một con trỏ mà bạn di chuyển qua tài liệu trong khi chèn nội dung. Write(text) và Writeln(text) chèn văn bản tại con trỏ; InsertParagraph() bắt đầu một đoạn mới. Các thuộc tính định dạng trên builder — Font, ParagraphFormat, ListFormat, PageSetup — áp dụng cho bất kỳ nội dung nào được viết tiếp theo.

Di chuyển con trỏ bằng MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), hoặc MoveToParagraph(paragraphIndex, characterIndex). Các thuộc tính CurrentNode, CurrentParagraph và CurrentSection của builder báo cáo vị trí hiện tại của nó trong cây.

Cấu trúc tài liệu: Các phần và Thân.

Một Document chứa một SectionCollection (Document.Sections, cộng với FirstSection / LastSection); mỗi Section có một Body, một bộ sưu tập tiêu đề/chân trang tùy chọn, và PageSetup riêng của nó. Section.AppendContent(sourceSection) và PrependContent(sourceSection) sao chép nội dung giữa các phần, và ClearContent() đặt lại một phần mà không xóa nó khỏi tài liệu.

Trong một Body, nội dung được hiển thị qua Body.Paragraphs (một ParagraphCollection) và Body.Tables. Một Range — có sẵn từ Document, Section, Paragraph, và các nút khác — đại diện cho một khu vực liên tục của cây; Range.Text đọc văn bản thuần của nó và Range.Replace(pattern, replacement) thực hiện tìm và thay thế chỉ trong khu vực đó.

Duyệt cây nút với DocumentVisitor.

Mỗi phần của một tài liệu — các phần, đoạn văn, run, bảng, trường, hình dạng, bình luận, chú thích chân trang — là một Node trong một cây hợp chất có gốc tại Document. Để xử lý mọi nút của một kiểu nhất định mà không cần đệ quy thủ công, kế thừa lớp trừu tượng DocumentVisitor và ghi đè các callback Visit*Start/Visit*End mà bạn cần, chẳng hạn VisitParagraphStart(paragraph) hoặc VisitRun(run), sau đó gọi document.Accept(visitor). Mỗi callback có thể trả về một VisitorAction (Continue, SkipThisNode, hoặc Stop) để kiểm soát cách duyệt tiếp tục.

Sao chép, Nhập và Gắn nội dung.

Document.Clone() tạo ra một bản sao sâu của toàn bộ tài liệu. Để di chuyển nội dung giữa hai thực thể Document khác nhau, gọi ImportNode(srcNode, isImportChildren) trên tài liệu đích để đưa vào một nút từ cây bên ngoài, hoặc gọi Document.AppendDocument(srcDoc, importFormatMode) để nối các phần của một tài liệu vào tài liệu khác bằng một ImportFormatMode đã chọn — KeepSourceFormatting, UseDestinationStyles, hoặc KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) chèn nội dung của tài liệu nguồn vào vị trí con trỏ của builder thay vì ở cuối tài liệu đích.

Bảo vệ Tài liệu

Document.Protect(type, password) hạn chế việc chỉnh sửa dựa trên giá trị ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields, hoặc NoProtection để gỡ bỏ bảo vệ. Unprotect() (có hoặc không có mật khẩu) sẽ đảo ngược nó. Đây là một hạn chế chỉnh sửa do Word thực thi, tách biệt khỏi việc mã hóa mật khẩu OOXML mà OoxmlSaveOptions.Password áp dụng khi lưu tệp.

Mẹo và Thực hành Tốt nhất

Ưu tiên DocumentBuilder để tạo nội dung mới; chuyển sang thao tác trực tiếp trên nút (AppendChild, InsertAfter, Clone) khi bạn cần kiểm soát chi tiết một cây hiện có.
Gọi FileFormatUtil.DetectFileFormat trước khi tải tệp từ nguồn không đáng tin cậy hoặc do người dùng cung cấp để bạn có thể kiểm tra LoadFormat và từ chối sớm các đầu vào không được hỗ trợ hoặc đã được mã hóa.
Khi kết hợp các tài liệu bằng AppendDocument hoặc InsertDocument, hãy chọn ImportFormatMode một cách có chủ ý — KeepSourceFormatting giữ nguyên giao diện của nguồn, UseDestinationStyles phù hợp với bộ kiểu của tài liệu đích.
Sử dụng một lớp con DocumentVisitor thay vì việc duyệt cây đệ quy thủ công khi bạn cần xử lý nhất quán mọi trường hợp của một kiểu nút.
Document.Protect là một hạn chế chỉnh sửa, không phải mã hóa — kết hợp nó với OoxmlSaveOptions.Password nếu tệp đã lưu cần yêu cầu mật khẩu để mở.

Các vấn đề thường gặp

Vấn đề	Nguyên nhân	Cách khắc phục
`Document(fileName)` ném lỗi cho một tệp mở bình thường trong Word	Định dạng của tệp không phải là một trong những định dạng mà phiên bản này hỗ trợ tải	Gọi `FileFormatUtil.DetectFileFormat` trước và kiểm tra `LoadFormat` trả về trước khi tải
Nội dung được nối thêm nhận phông chữ hoặc kiểu dáng sai	`ImportFormatMode` không khớp giữa các bộ kiểu nguồn và đích	Truyền `KeepSourceFormatting` hoặc `UseDestinationStyles` một cách rõ ràng thay vì dựa vào giá trị mặc định
Việc duyệt `DocumentVisitor` dừng sớm hoặc bỏ qua nội dung	Một việc ghi đè `VisitStart` / `VisitEnd` trả về `SkipThisNode` hoặc `Stop` một cách không mong muốn	Trả về `VisitorAction.Continue` từ mọi việc ghi đè trừ khi bạn cố ý muốn bỏ qua hoặc dừng lại
`Unprotect()` không có ảnh hưởng	Tài liệu không được bảo vệ bằng mật khẩu, hoặc mật khẩu được cung cấp không đúng	Gọi `Unprotect()` mà không có đối số nếu `Protect` đã được gọi mà không có mật khẩu, nếu không hãy truyền mật khẩu phù hợp

FAQ

Sự khác biệt giữa `Document.Clone()` và `ImportNode` là gì?

Clone() sao chép toàn bộ tài liệu vào một thể hiện Document mới. ImportNode(srcNode, isImportChildren) đưa một nút duy nhất (và tùy chọn các nút con của nó) từ cây của một tài liệu sang tài liệu khác, đây là cách bạn sử dụng khi kết hợp nội dung cụ thể thay vì toàn bộ tài liệu.

Các định dạng tệp nào mà `Document(fileName)` có thể tải?

Document(fileName) tải DOCX, DOCM, DOTX, DOTM, Flat OPC (cùng các biến thể hỗ trợ macro và mẫu), Markdown và văn bản thuần. Các định dạng xử lý văn bản và web cũ hơn không được bao gồm trong các bộ tải của phiên bản này.

Làm sao tôi có thể tìm vị trí hiện tại của `DocumentBuilder`?

Đọc CurrentNode, CurrentParagraph hoặc CurrentSection trên thể hiện builder.

Liệu `Document.Protect` có mã hoá tệp đã lưu không?

Không — đó là một hạn chế chỉnh sửa do Word áp dụng khi tệp được mở. Để yêu cầu mật khẩu chỉ để mở tệp, hãy đặt OoxmlSaveOptions.Password khi lưu.

Làm sao để tôi chỉ đọc các đoạn văn trong phần thân của tài liệu?

Sử dụng bộ sưu tập Body.Paragraphs, hoặc Body.GetChildNodes(nodeType, isDeep) cho các kiểu nút khác.

API Reference Tóm tắt

Lớp/Phương thức	Mô tả
`Document`	Gốc của mô hình đối tượng tài liệu; các hàm khởi tạo tải từ tệp hoặc luồng, hoặc tạo một tài liệu trống.
`Document.Save`	Ghi tài liệu ra tệp, luồng, hoặc phản hồi HTTP ở định dạng đã chọn.
`Document.Clone()`	Tạo một bản sao sâu của toàn bộ tài liệu.
`Document.Protect(type, password)` / `Unprotect()`	Áp dụng hoặc loại bỏ một ràng buộc chỉnh sửa.
`Document.AppendDocument(srcDoc, importFormatMode)`	Thêm các phần của tài liệu khác vào tài liệu này.
`DocumentBuilder`	Công cụ API dựa trên con trỏ để viết văn bản và chèn nội dung vào tài liệu.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Chèn nội dung của tài liệu nguồn vào vị trí con trỏ.
`Section` / `SectionCollection`	Một phần riêng lẻ của tài liệu, và tập hợp của tất cả các phần.
`Body`	Bộ chứa cho văn bản chính (đoạn văn và bảng) của một phần.
`Range`	Một khu vực liên tục của cây tài liệu; hỗ trợ `Text` và `Replace`.
`DocumentVisitor`	Lớp cơ sở trừu tượng để duyệt mọi nút trong cây tài liệu.
`ProtectionType`	Kiểu liệt kê của các hạn chế chỉnh sửa ở mức tài liệu.
`FileFormatUtil.DetectFileFormat`	Phát hiện định dạng của tệp hoặc luồng trước khi tải nó.

Xem thêm

Aspose.Words for .NET — Enterprise Documentation

Làm việc với Tài liệu