Настройки программирования уровня документа

Статья
02/20/2013

Расширив Microsoft Office Word или Microsoft Office Excel при помощи настройки уровня документа, можно выполнить следующие задачи:

Автоматизация приложения с помощью его объектной модели.
Добавить элементы управления в область документа.
Вызвать код VBA в документ из сборки настройки.
Вызвать код в сборке настройки из VBA.
Управлять определенными аспектами документа, если он размещен на сервере, на котором не установлена система Microsoft Office.
Настроить пользовательский интерфейс приложения.

Применение. Сведения этого раздела применяются к проектам уровня документа для следующих приложений: Excel 2013 и Excel 2010; Word 2013 и Word 2010. Дополнительные сведения см. в разделе Доступность функций по типам приложений Office и проектов.

Написание кода в проектах уровня документа в некоторых аспектах отличается от написания кода в других проектах Visual Studio.Многие из этих отличий связаны с тем, каким образом объектные модели Microsoft Office представлены управляемому коду.Дополнительные сведения см. в разделе Написание кода в решениях Office.

Общие сведения о программных настройках на уровне документа и других типах решений, которые можно создать при помощи средств разработки Office в Visual Studio см. в разделе Общие сведения о разработке решений Office.

Использование созданных классах в проектах уровня документа

При создании проекта уровня документа Visual Studio автоматически генерирует класс в проекте, который можно использовать, чтобы приступить к написанию кода.Visual Studio генерирует различные классы для Word и Excel:

В проектах уровня документа для Word класс вызывается ThisDocument по умолчанию.
Проекты уровня документа для Excel генерируют несколько классов: один для самой книги и по одному для каждого листа.По умолчанию эти классы имеют следующие имена:
- ThisWorkbook
- Sheet1
- Sheet2
- Sheet3

Сгенерированные классы включают обработчики событий, которые вызываются при открытии и закрытии документа.Для выполнения кода при открытом документе добавьте код в обработчик событий Startup.Для выполнения кода непосредственно перед закрытием документа добавьте код в обработчик событий Shutdown.Дополнительные сведения см. в разделе События в проектах Office.

Общие сведения о разработке созданных классов

В проектах, целевой объект .NET Framework 4 или .NET Framework 4.5, типы ведущего элемента в Visual Studio Tools for Office (cреда выполнения) интерфейсов, поэтому созданных классах не могут наследовать свои реализации от них.Вместо этого создаваемые классы наследуют большинство своих членов от следующих базовых классов:

ThisDocument: является производным от Microsoft.Office.Tools.Word.DocumentBase.
ThisWorkbook: является производным от Microsoft.Office.Tools.Excel.WorkbookBase.
Sheetn: является производным от Microsoft.Office.Tools.Excel.WorksheetBase.

Эти базовые классы перенаправляют все вызовы своих элементов на внутренние реализации соответствующих интерфейсов ведущих элементов в Visual Studio Tools for Office (cреда выполнения).Например, при вызове метода Protect класса ThisDocument, класс Microsoft.Office.Tools.Word.DocumentBase перенаправляет этот вызов внутренней реализации интерфейса Microsoft.Office.Tools.Word.Document в Visual Studio Tools for Office (cреда выполнения).

Доступ к объектной модели ведущего приложения

Чтобы получить доступ к объектной модели ведущего приложения, используйте члены созданного класса в разрабатываемом проекте.Каждый из этих классов соответствует объекту в объектной модели Excel или Word, они содержат в основном одинаковые свойства, методы и события.Например, класс ThisDocument в проекте уровня документа для Word представляет большинство тех же членов, что и объект Microsoft.Office.Interop.Word.Document в объектной модели Word.

В следующем примере кода показано, как использовать объектную модель Word, чтобы записать документ, который является частью настройки уровня документа для Word.Этот пример предназначен для запуска из класса ThisDocument.

Me.Save()

this.Save();

Чтобы сделать все то же самое, что и вне класса ThisDocument, используйте объект Globals для получения доступа к классу ThisDocument.Например, можно добавить этот код в панель действий файла кода, если необходимо включить кнопку Записать в панель действий пользовательского интерфейса.

Globals.ThisDocument.Save()

Globals.ThisDocument.Save();

Поскольку класс ThisDocument получает большинство своих членов от ведущего элемента Microsoft.Office.Tools.Word.Document, метод Save, который вызывает этот код, в действительности является методом Save ведущего элемента Microsoft.Office.Tools.Word.Document.Этот метод соответствует методу Save объекта Microsoft.Office.Interop.Word.Document в объектной модели Word.

Дополнительные сведения об использовании объектной модели Word и Excel см. в разделах Общие сведения об объектной модели Word и Общие сведения об объектной модели Excel.

Дополнительные сведения об объекте Globals см. в разделе Глобальный доступ к объектам в проектах Office.

Добавление элементов управления в документы

Чтобы настроить пользовательский интерфейс документа, можно добавить элементы управления Windows Forms или ведущие элементы управления в область документа.Используя различные сочетания элементов управления и кода, можно связывать элементы управления с данными, собирать вводимые пользователем сведения и реагировать на действия пользователя.

Элементы управления являются классами, которые расширяют некоторые из объектов в объектной модели Word и Excel.Например, ведущий элемент управления Microsoft.Office.Tools.Excel.ListObject предоставляет всю функциональность Microsoft.Office.Interop.Excel.ListObject в Excel.Однако ведущий управляющий элемент Microsoft.Office.Tools.Excel.ListObject также имеет дополнительные возможности событий и привязки к данным.

Дополнительные сведения см. в разделах Общие сведения о ведущих элементах и элементах управления ведущего приложения и Общие сведения об использовании элементов управления Windows Forms в документах Office.

Объединение настроек VBA и настроек на уровне документа

Можно использовать код VBA в документе, который является частью настройки уровня документа.Код VBA можно вызывать из сборки настройки в документе, также можно настроить проект таким образом, чтобы разрешить использование в документе кода VBA для вызова кода из сборки настройки.

Дополнительные сведения см. в разделе Объединение настроек VBA и настроек на уровне документа.

Управление документами на сервере

Можно управлять некоторыми аспектами настроек уровня документа, если он размещен на сервере, на котором не установлены Office Word или Microsoft Office Excel.Например, можно получить доступ к данным и изменить данные в кэше данных документа.Можно управлять сборкой настройки, связанной с документом.Например, можно программно удалить сборку из документа, чтобы документ больше не выполнял код, или можно программно прикрепить сборку к документу.

Дополнительные сведения см. в разделе Управление документами на сервере с помощью класса ServerDocument.

Настройка пользовательского интерфейса приложений Microsoft Office

Можно настроить пользовательский интерфейс Word и Excel путем использования настройки уровня документа, как показано ниже.

Добавление элементов управления ведущего приложения или элементов управления Windows Forms в область документа.

Дополнительные сведения см. в разделах Автоматизация Word с помощью расширенных объектов, Автоматизация Excel с помощью расширенных объектов и Общие сведения об использовании элементов управления Windows Forms в документах Office.
Добавление панели действий к документу.

Дополнительные сведения см. в разделе Общие сведения о панели действий.
Добавление пользовательских вкладок на ленте.

Дополнительные сведения см. в разделе Обзор ленты.
Добавление настраиваемых команды во встроенном вкладке на ленте.

Дополнительные сведения см. в разделе Практическое руководство. Настройка встроенной вкладки.

Дополнительные сведения о настройке пользовательского интерфейса Microsoft Office см. в разделе Настройка пользовательского интерфейса Office.

Получение расширенных объектов из собственных объектов office в настройках уровня документа

Многие обработчики событий для событий Office получают собственные объекты Office, представляющие рабочую книгу, лист или документ, инициирующий событие.В некоторых случаях может возникнуть необходимость в выполнении определенного кода только в том случае, если рабочая книга или документ в настройке уровня документа инициирует событие.Например, в настройке уровня документа для Excel может возникнуть необходимость в выполнении определенного кода, когда пользователь активирует один из листов в настраиваемой книге, но не тогда, когда пользователь активирует рабочий лист в какой-либо книге, которая в это же время оказывается открытой.

При наличии собственного объекта Office можно проверить, был ли объект расширен до ведущего элемента или ведущего элемента управления в настройке уровня документа.Ведущие элементы и элементы управления ведущего приложения являются типами, предоставляемыми средой Visual Studio Tools for Office (cреда выполнения) и добавляющими функциональные возможности объектам, существующим внутри объектных моделей Word или Excel (называемых собственными объектами Office).Собирательно ведущие элементы и элементы управления ведущего приложения также называются расширенными объектами. Дополнительные сведения о ведущих элементах и элементах см. в разделе Общие сведения о ведущих элементах и элементах управления ведущего приложения.

Основные сведения о методах GetVstoObject и HasVstoObject

Чтобы проверить собственный объект Office, необходимо использовать методы HasVstoObject и GetVstoObject в проекте.

Если необходимо определить, имеет ли собственный объект Office расширенный объект в текущей настройке, используйте метод HasVstoObject.Этот метод возвращает true, если собственный объект Office имеет расширенный объект, и false, если нет.
Если нужно получить расширенный объект для собственного объекта Office, используйте метод GetVstoObject.Этот метод возвращает объект Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet или Microsoft.Office.Tools.Word.Document, если таковой имеется в заданном собственном объекте Office.В противном случае GetVstoObject возвращает null.Например, метод GetVstoObject возвращает объект Microsoft.Office.Tools.Word.Document, если заданный объект Microsoft.Office.Interop.Word.Document, является основным объектом для документа в текущем проекте документа Word.

В проектах уровня документа нельзя использовать метод GetVstoObject для создания нового ведущего элемента Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet или Microsoft.Office.Tools.Word.Document во время выполнения.Этот метод можно использовать только для доступа к существующим ведущим элементам, созданным в текущем проекте во время выполнения.Если требуется создать во время выполнения новые ведущие элементы, необходимо построить проект уровня приложения.Дополнительные сведения см. в разделах Программные ограничения ведущих элементов и элементов управления ведущего приложения и Расширение документов Word и книг Excel в надстройках уровня приложения во время выполнения.

Использование методов GetVstoObject и HasVstoObject

Для вызова метода HasVstoObject и GetVstoObject, следует использовать метод Globals.Factory.GetVstoObject или Globals.Factory.HasVstoObject и передачи собственное ключевое слово или Excel объект (например, Microsoft.Office.Interop.Word.Document или Microsoft.Office.Interop.Excel.Worksheet), которое требуется выполнить.