Веб-расширения

Это руководство показывает, как читать и изменять метаданные панелей задач Office Add-in, встроенные в файл .docx, с помощью Aspose.Words FOSS для .NET. Aspose.Words FOSS для .NET может читать и изменять веб-расширения (Office Add-in) панели задач, встроенные в файл .docx — метаданные, которые связывают документ с Office Add-in и привязывают его к данным документа — через Document.WebExtensionTaskPanes и объектную модель TaskPane/WebExtension.

Панели задач

Document.WebExtensionTaskPanes возвращает TaskPaneCollection из TaskPane объектов. Каждый TaskPane описывает, где и как панель надстройки закреплена: DockState (это TaskPaneDockState из Right или Left), Row, Width, IsLocked и IsVisible, а также свойство WebExtension, связывающее с самой надстройкой.

Идентификация веб-расширения и ссылки

WebExtension идентифицирует надстройку через Id и IsFrozen, а её свойство Reference (это WebExtensionReference) раскрывает Id, Version, Store и StoreType (это WebExtensionStoreType, такой как SPCatalog, Exchange или FileSystem), описывающие, откуда надстройка распространяется. AlternateReferences содержит WebExtensionReferenceCollection резервных ссылок.

Привязки и пользовательские свойства

WebExtension.Bindings является WebExtensionBindingCollection из WebExtensionBinding объектов, каждый из которых построен как new WebExtensionBinding(id, bindingType, appRef) и связывает часть данных документа с надстройкой через WebExtensionBindingType (Matrix, Table или Text). WebExtension.Properties представляет собой WebExtensionPropertyCollection простых пар имя/значение WebExtensionProperty, построенных как new WebExtensionProperty(name, value), используемых для специфических для надстройки пользовательских настроек, не требующих полного связывания.

Членство в коллекции

TaskPaneCollection, WebExtensionBindingCollection, WebExtensionPropertyCollection и WebExtensionReferenceCollection имеют одинаковое базовое поведение коллекции: Add(item), Clear(), Remove(index), GetEnumerator() и Count.

Советы и лучшие практики

Проверьте TaskPane.IsVisible, прежде чем предполагать, что панель надстройки в данный момент отображается пользователю — панель задач может быть зарегистрирована, но скрыта.
WebExtensionReference.StoreType указывает, откуда была получена надстройка (каталог, Exchange, файловая система, реестр); используйте его, чтобы различать надстройки первого уровня и загруженные сторонними способами.
Связи связывают конкретный WebExtensionBindingType (матрицу, таблицу или простой текст) с данными документа — проверьте тип связи, прежде чем предполагать, какой формат данных ожидает надстройка.
Используйте WebExtension.Properties для простых конфигурационных пар имя/значение надстройки, вместо попытки хранить их в другом месте документа.

Общие проблемы

Проблема	Причина	Исправление
`Document.WebExtensionTaskPanes` пустой	В документе не зарегистрировано Office Add-ins	Убедитесь, что источник `.docx` действительно встраивает панель задач, прежде чем предполагать, что API сломан
Невозможно определить, из какого магазина пришел add-in	`StoreType` не проверено	Прочитайте `WebExtensionReference.StoreType` вместе с `Store`, чтобы получить полную картину
Данные привязки не соответствуют ожиданиям	Несоответствие типа привязки	Проверьте `WebExtensionBinding.BindingType` (`Matrix`, `Table`, `Text`) перед использованием привязанных данных

FAQ

Как найти все Office Add-ins, зарегистрированные в документе?

Перечислите Document.WebExtensionTaskPanes (a TaskPaneCollection); каждый TaskPane.WebExtension предоставляет вам идентификацию надстройки и её конфигурацию.

Могу ли я добавить новую привязку веб-расширения или свойство с помощью этого API?

Да — коллекции (WebExtensionBindingCollection, WebExtensionPropertyCollection и др.) поддерживают Add(), поэтому вы можете создавать и добавлять новые объекты WebExtensionBinding/WebExtensionProperty в существующий WebExtension.

Что именно привязывает WebExtensionBinding?

Он связывает часть данных документа с надстройкой, используя WebExtensionBindingType (Matrix, Table или Text) для описания структуры этих данных.

Как мне прочитать пользовательские настройки надстройки, сохранённые в документе?

Перебрать WebExtension.Properties (a WebExtensionPropertyCollection); каждый WebExtensionProperty раскрывает пару Name/Value.

API Reference Сводка

Класс / Метод	Описание:
`Document.WebExtensionTaskPanes`	`TaskPaneCollection` панелей задач, зарегистрированных в документе
`TaskPane`	Одна панель надстройки: `DockState`, `Row`, `Width`, `IsVisible`, `IsLocked`, `WebExtension`
`WebExtension`	Идентификатор надстройки: `Id`, `IsFrozen`, `Reference`, `Bindings`, `Properties`
`WebExtensionReference`	Источник надстройки: `Id`, `Version`, `Store`, `StoreType`
`WebExtensionBinding`	Связывает данные документа с надстройкой через `WebExtensionBindingType`
`WebExtensionProperty`	Пользовательская настройка надстройки в виде пары `Name`/`Value`

См. также:

Aspose.Words for .NET — Enterprise Documentation