Будівельні блоки

Цей посібник показує, як читати та змінювати повторно використовувані блоки вмісту, що зберігаються у глосарному документі документа за допомогою Aspose.Words FOSS для .NET. Бібліотека надає AutoText записи, обкладинки, заголовки, нижні колонтитули та подібний заздалегідь визначений вміст через Document.GlossaryDocument та модель об’єктів BuildingBlock/BuildingBlockCollection.

Глосарний документ

Кожен Document містить GlossaryDocument — доступний через Document.GlossaryDocument — який сам є підкласом DocumentBase, що містить будівельні блоки. Його властивість BuildingBlocks повертає BuildingBlockCollection, при цьому FirstBuildingBlock/LastBuildingBlock забезпечують швидкий доступ до кінців списку. Шукайте конкретний будівельний блок за допомогою GetBuildingBlock(gallery, category, name), співставляючи його BuildingBlockGallery, рядок категорії та назву разом.

Структура будівельного блоку

BuildingBlock є CompositeNode, тому він містить власне дерево вмісту — Sections (SectionCollection), FirstSection та LastSection — так само, як Document містить розділи. Його метадані-властивості ідентифікують та класифікують його: Name, Guid, Description, Category, Gallery (BuildingBlockGallery — AutoText, CoverPage, Headers, Footers, Tables, Watermarks, і десятки інших заздалегідь визначених галерей), Type (BuildingBlockType), та Behavior (BuildingBlockBehavior of Content, Paragraph або Page), що контролює, як його вміст об’єднується в документі під час вставки.

Керування колекцією будівельних блоків

BuildingBlockCollection підтримує повне редагування колекції: Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node) та IndexOf(node), разом із ToArray() і GetEnumerator() для читання. Оскільки це NodeCollection, блоки будуються, клонуються та переміщуються за допомогою тих самих API вузлів, що й будь-яка інша частина дерева документа.

Будівельні блоки заповнювального тексту

Теги структурованих документів можуть посилатися на будівельний блок як їх вміст-заповнювач: StructuredDocumentTag.Placeholder і StructuredDocumentTagRangeStart.Placeholder обидва повертають BuildingBlock, який показується, коли тег порожній, через спільну властивість IStructuredDocumentTag.Placeholder.

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

Уважно підбирайте три аргументи GetBuildingBlock(gallery, category, name) — однакова назва може існувати у різних галереях або категоріях.
Використовуйте BuildingBlockGallery для фільтрації типу повторно використовуваного вмісту, який ви шукаєте (AutoText, CoverPage, Tables, Watermarks тощо), замість того, щоб переглядати кожен будівельний блок лише за назвою.
BuildingBlockBehavior визначає, як вставлений вміст об’єднується з оточуючим документом (Content, Paragraph або Page) — перевірте це, перш ніж припускати, що будівельний блок вставиться так, як ви очікуєте.
Оскільки BuildingBlock є CompositeNode, ставтеся до нього як до будь-якого іншого піддерева вузлів під час створення або редагування його вмісту — AppendChild, InsertAfter та подібні методи вузлів застосовуються.

Типові проблеми

Проблема	Причина	Виправлення
`GetBuildingBlock()` не повертає нічого	Галерея, категорія або назва не точно відповідає існуючому будівельному блоку	Перелічити `GlossaryDocument.BuildingBlocks`, щоб знайти точну комбінацію `Gallery`/`Category`/`Name`
Вставлений вміст будівельного блоку об’єднується неочікувано	`Behavior` (`Content`/`Paragraph`/`Page`) не враховано	Перевірте `BuildingBlock.Behavior` перед вставкою, щоб зрозуміти, як він буде об’єднуватися
Заповнювач тегу структурованого документа не показує очікуваний вміст	`Placeholder` вказує на інший `BuildingBlock`, ніж передбачалося	Прочитайте `StructuredDocumentTag.Placeholder`, щоб підтвердити, який будівельний блок фактично використовується

FAQ

Де зберігаються будівельні блоки в документі?

У GlossaryDocument документа, доступному через Document.GlossaryDocument, властивість BuildingBlocks якого є BuildingBlockCollection.

Як знайти конкретний будівельний блок, наприклад запис AutoText?

Викличте GlossaryDocument.GetBuildingBlock(gallery, category, name) з відповідним BuildingBlockGallery, категорією та іменем.

Чи можу я додавати нові будівельні блоки програмно?

Так — BuildingBlockCollection підтримує Add(node) і Insert(index, node), оскільки це NodeCollection.

Що контролює BuildingBlockBehavior?

Як вміст будівельного блоку поєднується з документом під час вставки — як Content, цілий Paragraph або цілий Page.

Як будівельний блок пов’язаний із текстом заповнювача структурованого тегу документа?

StructuredDocumentTag.Placeholder (і StructuredDocumentTagRangeStart.Placeholder) повертають BuildingBlock, який забезпечує вміст заповнювача SDT, коли він порожній.

API Reference Підсумок

Клас / Метод	Опис
`Document.GlossaryDocument`	`GlossaryDocument` документа, що містить усі будівельні блоки
`GlossaryDocument.BuildingBlocks`	`BuildingBlockCollection` кожного будівельного блоку
`GlossaryDocument.GetBuildingBlock()`	Шукає будівельний блок за галереєю, категорією та назвою
`BuildingBlock`	`CompositeNode` з `Name`, `Gallery`, `Category`, `Behavior`, `Type`, `Sections`
`BuildingBlockCollection`	`Add()`, `Insert()`, `Remove()`, `Clear()`, `Contains()`, `IndexOf()`
`BuildingBlockGallery` / `BuildingBlockType` / `BuildingBlockBehavior`	Перелічення, що класифікують будівельний блок
`StructuredDocumentTag.Placeholder`	`BuildingBlock`, який використовується як заповнювальний вміст SDT

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

Aspose.Words for .NET — Enterprise Documentation