Робота з документами

Робота з документами

Aspose.Words FOSS для .NET представляє кожен файл Word як об’єктну модель у пам’яті, що базується на класі Document, при цьому DocumentBuilder забезпечує високорівневий, курсорний API для створення контенту. Цей посібник охоплює створення та завантаження документів, створення контенту за допомогою DocumentBuilder, структуру розділів/тіла, обходження дерева вузлів, об’єднання документів та їх захист.

Створення та завантаження документів

Створіть порожній документ за допомогою new Document() або відкрийте існуючий файл, передавши шлях або Stream у конструктор Document(fileName) чи Document(stream). Перевантаження, які приймають аргумент LoadOptions, дозволяють контролювати поведінку завантаження, наприклад, вказати пароль для зашифрованого файлу.

Перед завантаженням файлу з невідомого або ненадійного джерела, FileFormatUtil.DetectFileFormat(fileName) (або перевантаження Stream) повертає FileFormatInfo, що описує виявлений LoadFormat, і чи файл IsEncrypted, HasDigitalSignature або HasMacros.

Створення контенту за допомогою DocumentBuilder

DocumentBuilder обгортає Document і надає курсор, яким ви переміщуєтеся по документу під час вставки контенту. Write(text) і Writeln(text) вставляють текст у курсор; InsertParagraph() починає новий абзац. Властивості форматування у будівельнику — Font, ParagraphFormat, ListFormat, PageSetup — застосовуються до всього, що буде написано далі.

Перемістіть курсор за допомогою MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) або MoveToParagraph(paragraphIndex, characterIndex). Властивості CurrentNode, CurrentParagraph і CurrentSection будівельника повідомляють про його поточну позицію в дереві.

Структура документа: розділи та тіло

Document містить SectionCollection (Document.Sections, плюс FirstSection / LastSection); кожен Section має один Body, необов’язкову колекцію верхніх/нижніх колонтитулів і свій власний PageSetup. Section.AppendContent(sourceSection) і PrependContent(sourceSection) копіюють вміст між розділами, а ClearContent() скидає розділ, не видаляючи його з документа.

У межах Body вміст доступний через Body.Paragraphs (це ParagraphCollection) та Body.Tables. Range — доступний з Document, Section, Paragraph та інших вузлів — представляє неперервну ділянку дерева; Range.Text читає його простий текст, а Range.Replace(pattern, replacement) виконує пошук-заміну лише в цій ділянці.

Обхід дерева вузлів за допомогою DocumentVisitor

Кожна частина документа — розділи, абзаци, run, таблиці, поля, форми, коментарі, виноски — є Node у складному дереві з коренем у Document. Щоб обробити кожен вузол певного типу без ручної рекурсії, успадкуйте абстрактний DocumentVisitor і перевизначте потрібні вам колбеки Visit*Start / Visit*End, такі як VisitParagraphStart(paragraph) або VisitRun(run), потім викличте document.Accept(visitor). Кожен колбек може повертати VisitorAction (Continue, SkipThisNode або Stop), щоб керувати процесом обходу.

Клонування, імпорт та додавання вмісту

Document.Clone() створює глибоку копію всього документа. Щоб перемістити вміст між двома різними екземплярами Document, викличте ImportNode(srcNode, isImportChildren) у документі-призначенні, щоб імпортувати вузол із зовнішнього дерева, або викличте Document.AppendDocument(srcDoc, importFormatMode), щоб додати розділи одного документа до іншого, використовуючи обраний ImportFormatMode — KeepSourceFormatting, UseDestinationStyles або KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) вставляє вміст вихідного документа в курсор будівельника замість в кінець призначення.

Захист документів

Document.Protect(type, password) обмежує редагування відповідно до значення ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields або NoProtection для зняття захисту. Unprotect() (з паролем або без нього) скасовує це. Це обмеження редагування, яке застосовує Word, окремо від шифрування паролем OOXML, яке OoxmlSaveOptions.Password застосовує під час збереження файлу.

Поради та найкращі практики

• Віддавайте перевагу DocumentBuilder при створенні нового вмісту; переходьте до прямого маніпулювання вузлами (AppendChild, InsertAfter, Clone), коли потрібен тонкий контроль над існуючим деревом.
• Викликайте FileFormatUtil.DetectFileFormat перед завантаженням файлу з ненадійного або користувачем наданого джерела, щоб мати можливість перевірити LoadFormat і заздалегідь відхилити непідтримуваний або зашифрований вхід.
• При об’єднанні документів за допомогою AppendDocument або InsertDocument вибирайте ImportFormatMode навмисно — KeepSourceFormatting зберігає вигляд джерела, UseDestinationStyles відповідає набору стилів цільового документа.
• Використовуйте підклас DocumentVisitor замість ручного рекурсивного обходу дерева, коли потрібно послідовно обробляти кожен екземпляр типу вузла.
• Document.Protect — це обмеження редагування, а не шифрування — поєднайте його з OoxmlSaveOptions.Password, якщо сам збережений файл має вимагати пароль для відкриття.

Поширені проблеми

FAQ

У чому різниця між Document.Clone() і ImportNode?

Clone() копіює весь документ у новий екземпляр Document. ImportNode(srcNode, isImportChildren) переносить окремий вузол (і, за потреби, його дочірні елементи) з дерева одного документа в інший, що використовується, коли потрібно об’єднати конкретний вміст, а не цілі документи.

Які формати файлів може завантажувати Document(fileName)?

Document(fileName) завантажує DOCX, DOCM, DOTX, DOTM, Flat OPC (разом з його макросумісними та шаблонними варіантами), Markdown і простий текст. Старі формати обробки тексту та веб-формати виключені з завантажувачів цієї редакції.

Як дізнатися, де зараз розташований DocumentBuilder?

Прочитайте CurrentNode, CurrentParagraph або CurrentSection у екземплярі builder.

Чи Document.Protect шифрує збережений файл?

Ні — це обмеження редагування, встановлене Word під час відкриття файлу. Щоб вимагати пароль лише для відкриття файлу, встановіть OoxmlSaveOptions.Password під час збереження.

Як прочитати лише абзаци в тілі документа?

Використовуйте колекцію Body.Paragraphs, або Body.GetChildNodes(nodeType, isDeep) для інших типів вузлів.

API Reference Підсумок

Дивіться також

• Aspose.Words for .NET — Enterprise Documentation