Расширение документов Word и книг Excel в надстройках уровня приложения во время выполнения

Обновлен: Июль 2008

Применение
Сведения, приведенные в данном разделе, относятся только к указанным проектам Visual Studio Tools for Office и версиям Microsoft Office. Тип проекта Проекты уровня приложения Версия Microsoft Office Excel 2007 Word 2007 Дополнительные сведения см. в разделе Доступность функций по типам приложений и проектов.

Начиная с Visual Studio 2008 с пакетом обновления 1 (SP1), можно использовать надстройку уровня приложения для выполнения следующих настроек документов и книг:

• Добавление управляемых элементов управления в любой открытый документ или лист.

• Создание смарт-тегов, распознающих термины в указанном документе или книге.

• Преобразование существующего объекта списка на листе Excel в объект списка Visual Studio Tools for Office, который предоставляет события и позволяет выполнить привязку данных с помощью модели привязки данных Windows Forms.

• Получение доступа к событиям на уровне приложения, которые предоставляются Word и Excel для определенных документов, книг и листов.

Для использования данных функциональных возможностей необходимо во время выполнения создать объект Visual Studio Tools for Office, который расширяет документ или книгу.

Создание расширенных объектов в надстройках

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

• Класс Microsoft.Office.Interop.Excel.ListObject.

• Класс Microsoft.Office.Interop.Excel.Workbook.

• Класс Microsoft.Office.Interop.Excel.Worksheet.

• Класс Microsoft.Office.Interop.Word.Document.

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

Тип расширенного объекта имеет такое же имя, как тип собственного объекта Office, но этот тип определен в пространстве имен Microsoft.Office.Tools.Excel или Microsoft.Office.Tools.Word. Например, метод GetVstoObject объекта Microsoft.Office.Interop.Word.Document возвращает объект Microsoft.Office.Tools.Word.Document.

Чтобы определить создан ли уже объект Visual Studio Tools for Office для отдельного собственного объекта Office, воспользуйтесь методом HasVstoObject объекта Office. Дополнительные сведения см. в разделе Определение наличия расширенного объекта Office.

Методы GetVstoObject предназначены для использования преимущественно в проектах уровня приложения. Кроме того, можно использовать эти методы в проектах уровня документа, но тогда поведение объектов несколько отличается и имеет меньшее число применений. Дополнительные сведения см. в разделе Получение вложенных объектов из собственных объектов Office в настройках уровня документа.

Примечание.
Для использования методов GetVstoObject и HasVstoObject в файле кода, отличном от файлов ThisAddIn.cs или ThisAddIn.vb, или в проекте, который был создан до установки пакета обновления 1 (SP1), потребуется изменить проект. Дополнительные сведения см. в разделе Настройка проекта для использования методов GetVstoObject и HasVstoObject.

Создание ведущих элементов

Когда метод GetVstoObject используется для объекта уровня документа, т.е. Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet или Microsoft.Office.Interop.Word.Document, возвращаемый объект называется ведущим элементом. Ведущий элемент — это тип, который может содержать другие объекты, включающие в свою очередь другие расширенные объекты и элементы управления. Ведущий элемент похож на соответствующий тип в основной сборке взаимодействия Word или Excel, но обладает дополнительными функциональными возможностями. Дополнительные сведения о ведущих элементах см. в разделе Общие сведения о ведущих элементах и элементах управления ведущего приложения.

После того, как ведущий элемент создан, его можно использовать для добавления смарт-тегов или управляемых элементов управления в документ, книгу или лист. Дополнительные сведения см. в разделах Добавления смарт-тегов в документы и книги и Добавление управляемых элементов управления в документы и листы.

Создание ведущего элемента для документа Word

• Используйте метод GetVstoObject объекта Microsoft.Office.Interop.Word.Document. В следующем примере кода показано создание ведущего элемента для активного документа.

  If Globals.ThisAddIn.Application.Documents.Count > 0 Then
      Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
          Globals.ThisAddIn.Application.ActiveDocument
      Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
          NativeDocument.GetVstoObject()
  End If
  

  if (Globals.ThisAddIn.Application.Documents.Count > 0)
  {
      Microsoft.Office.Interop.Word.Document nativeDocument =
          Globals.ThisAddIn.Application.ActiveDocument;
      Microsoft.Office.Tools.Word.Document vstoDocument =
          nativeDocument.GetVstoObject();
  }
  

Создание ведущего элемента для книги Excel

• Используйте метод GetVstoObject объекта Microsoft.Office.Interop.Excel.Workbook. В следующем примере кода показано создание ведущего элемента для активной книги.

  Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
      Globals.ThisAddIn.Application.ActiveWorkbook
  
  If NativeWorkbook IsNot Nothing Then
      Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
          NativeWorkbook.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
      Globals.ThisAddIn.Application.ActiveWorkbook;
  
  if (nativeWorkbook != null)
  {
      Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
          nativeWorkbook.GetVstoObject();
  }
  

Создание ведущего элемента для листа Excel

• Используйте метод GetVstoObject объекта Microsoft.Office.Interop.Excel.Worksheet. В следующем примере кода показано создание ведущего элемента для активного листа.

  Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
      TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
      Microsoft.Office.Interop.Excel.Worksheet)
  
  If NativeSheet IsNot Nothing Then
      Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
          NativeSheet.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
      Globals.ThisAddIn.Application.ActiveSheet as
      Microsoft.Office.Interop.Excel.Worksheet;
  
  if (nativeSheet != null)
  {
      Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
          nativeSheet.GetVstoObject();
  }
  

Создание элементов управления ведущего приложения ListObject

При использовании метода GetVstoObject объекта Microsoft.Office.Interop.Excel.ListObject метод возвращает объект Microsoft.Office.Tools.Excel.ListObject. Созданный объект Microsoft.Office.Tools.Excel.ListObject обладает всеми функциональными возможностями исходного объекта Microsoft.Office.Interop.Excel.ListObject, но он также имеет дополнительные функциональные возможности, например, связывания с данными с помощью модели привязки данных Windows Forms. Дополнительные сведения см. в разделе Элемент управления ListObject.

Создание элемента управления ведущего приложения для ListObject

• Используйте метод GetVstoObject объекта Microsoft.Office.Interop.Excel.ListObject. В следующем примере кода показано создание объекта Microsoft.Office.Tools.Excel.ListObject для первого объекта Microsoft.Office.Interop.Excel.ListObject в активном листе.

  Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet
  
  If sheet.ListObjects.Count > 0 Then
      Dim listObject As Excel.ListObject = sheet.ListObjects(1)
      Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
          listObject.GetVstoObject()
  End If
  

  Microsoft.Office.Interop.Excel.Worksheet sheet =
      Globals.ThisAddIn.Application.ActiveSheet as
      Microsoft.Office.Interop.Excel.Worksheet;
  
  if (sheet.ListObjects.Count > 0)
  {
      Excel.ListObject listObject = sheet.ListObjects[1];
      Microsoft.Office.Tools.Excel.ListObject vstoListObject =
          listObject.GetVstoObject();
  }
  

Добавление смарт-тегов в документы и книги

После создания объекта Microsoft.Office.Tools.Word.Document или Microsoft.Office.Tools.Excel.Workbook можно создать смарт-тег, который распознает в контексте документа или книги что представляют эти объекты. Для этого необходимо использовать свойство VstoSmartTags объекта Microsoft.Office.Tools.Word.Document или Microsoft.Office.Tools.Excel.Workbook. Дополнительные сведения см. в следующих разделах:

• Практическое руководство. Добавление смарт-тегов в документы Word

• Практическое руководство. Добавление смарт-тегов в книги Excel

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

После создания объекта Microsoft.Office.Tools.Word.Document или Microsoft.Office.Tools.Excel.Worksheet в документ или на листы можно добавить элементы управления, которые расширяют объекты. Для этого необходимо использовать свойство Controls объекта Microsoft.Office.Tools.Word.Document или Microsoft.Office.Tools.Excel.Worksheet. Дополнительные сведения см. в разделе Добавление элементов управления в документы Office во время выполнения.

Можно добавить элементы управления Windows Forms или элементы управления ведущего приложения. Элемент управления ведущего приложения — это элемент управления Visual Studio Tools for Office, который упаковывает соответствующий элемент управления в основной сборке взаимодействия Word или Excel. Элемент управления ведущего приложения предоставляет все возможности, лежащие в основе собственного объекта Office, но он также вызывает события и может быть связан с данными с помощью модели привязки данных Windows Forms. Дополнительные сведения см. в разделе Общие сведения о ведущих элементах и элементах управления ведущего приложения.

Примечание.
Невозможно добавить элемент управления XmlMappedRange на лист или элемент управления XMLNode или XMLNodes в документ с помощью надстройки. Данные элементы управления ведущего приложения невозможно добавить программными средствами. Дополнительные сведения см. в разделе Программные ограничения ведущих элементов и элементов управления ведущего приложения.

Сохранение и удаление элементов управления

При добавлении управляемых элементов управления в документ или на лист, элементы управления не сохраняются при сохранении и последующем закрытии документа. Все элементы управления удаляются, поэтому в документе остаются только лежащие в основе собственные объекты Office (например, Microsoft.Office.Tools.Excel.ListObject становится Microsoft.Office.Interop.Excel.ListObject). Все элементы управления Windows Forms также удаляются, но оболочки ActiveX для элементов управления остаются в документе. Для очистки элементов управления или повторного создания элементов управления при последующем открытии документа необходимо включить в надстройку код. Дополнительные сведения см. в разделе Сохранение динамических элементов управления в документах Office.

Получение доступа к событиям уровня приложения в документах и книгах

Некоторые события документа, рабочей книги и листа в собственных объектных моделях Word и Excel вызываются только на уровне приложения. Например, событие DocumentBeforeSave вызывается при открытии документа в Word, но данное событие определено в классе Microsoft.Office.Interop.Word.Application, а не в классе Microsoft.Office.Interop.Word.Document.

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

Пример, в котором используются собственные объекты Word

В следующем примере кода показана обработка событий уровня приложения для документов Word. В данном примере метод CreateDocument1 создает новый документ и затем определяет обработчик событий DocumentBeforeSave, который предотвращает сохранение документа. Поскольку данное событие уровня приложения вызывается для объекта Microsoft.Office.Interop.Word.Application, то обработчик событий должен сравнить параметр с Doc объектом document1 для установления, представляет ли объект document1 сохраненный документ.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Пример, в котором используется ведущий элемент

В следующем примере кода упрощен процесс обработки события BeforeSave ведущего элемента Microsoft.Office.Tools.Word.Document. В данном примере метод CreateDocument2 создает объект Microsoft.Office.Tools.Word.Document, который расширяет объект document2 и затем определяет обработчик событий BeforeSave, который предотвращает сохранение документа. Поскольку обработчик событий вызывается только при сохранении объекта document2, обработчик событий может отменить действие сохранения без выполнения дополнительных действий для проверки какой был сохранен документ.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Определение, является ли объект Office расширенным

Чтобы определить создан ли уже объект Visual Studio Tools for Office для отдельного собственного объекта Office, воспользуйтесь методом HasVstoObject объекта Office. Этот метод возвращает значение true, если расширенный объект Office уже создан, а в противном случае — значение false.

Это удобно в ситуации, когда необходимо запустить код только при условии, что заданный объект Office имеет расширенный объект. Например, если есть надстройка Word, которая обрабатывает событие DocumentBeforeSave удаления управляемых элементов управления из документа до сохранения, то можно использовать метод HasVstoObject для определения расширен ли документ. Если документ не был расширен, он не может содержать управляемые элементы управления и следовательно обработчик событий может не осуществлять попытку очистки элементов управления из документа.

Настройка проекта на использование методов GetVstoObject и HasVstoObject

При создании проекта уровня приложения после установки Visual Studio 2008 с пакетом обновления 1 (SP1), проект автоматически настроен для использования методов GetVstoObject и HasVstoObject в файлах кода ThisAddIn.cs или ThisAddIn.vb.

Для использования этих методов в файле кода, отличном от ThisAddIn.cs или ThisAddIn.vb, необходимо выполнить в файле кода следующие изменения.

Изменение файла кода в проекте Excel для создания расширенных объектов

• Добавьте инструкцию using (для C#) или Imports (для Visual Basic) в начале файла кода, в котором необходимо использовать методы GetVstoObject и HasVstoObject.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

Изменение файла кода в проекте Word для создания расширенных объектов

• Добавьте инструкцию using (для C#) или Imports (для Visual Basic) в начале файла кода, в котором необходимо использовать методы GetVstoObject и HasVstoObject.

  Imports Microsoft.Office.Tools.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

Для использования этих методов в проекте уровня приложения, который создается до установки пакета обновления 1 (SP1), необходимо выполнить следующие изменения в проекте.

Изменение существующей надстройки Excel для создания расширенных объектов

1. Добавьте ссылку на сборку Microsoft.Office.Tools.Excel.v9.0.dll.

2. Добавьте инструкцию using (для C#) или Imports (для Visual Basic) в начале файла кода, в котором необходимо использовать методы GetVstoObject и HasVstoObject.

   Imports Microsoft.Office.Tools.Excel.Extensions
   

   using Microsoft.Office.Tools.Excel.Extensions;
   

Изменение существующей надстройки Word для создания расширенных объектов

1. Добавьте ссылку на сборку Microsoft.Office.Tools.Word.v9.0.dll.

2. Добавьте инструкцию using (для C#) или Imports (для Visual Basic) в начале файла кода, в котором необходимо использовать методы GetVstoObject и HasVstoObject.

   Imports Microsoft.Office.Tools.Word.Extensions
   

   using Microsoft.Office.Tools.Word.Extensions;
   

Эти изменения необходимы, поскольку методы GetVstoObject и HasVstoObject, реализованы как методы расширения. Хотя методы GetVstoObject и HasVstoObject используются так, как если бы они были определены в типах основной сборки взаимодействия Excel или Word, они действительно заданы в типах пространств имен Microsoft.Office.Tools.Excel.Extensions и Microsoft.Office.Tools.Word.Extensions Visual Studio Tools for Office среды выполнения. Дополнительные сведения о методах расширения см. в разделах Методы расширения (руководство по программированию в C#) и Методы расширения (Visual Basic).

См. также

Задачи

Пример динамических элементов управления надстройками Excel

Пример динамических элементов управления в надстройках Word

Основные понятия

Программирование надстроек уровня приложения

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

Общие сведения о ведущих элементах и элементах управления ведущего приложения

Общие сведения о смарт-тегах

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

Журнал изменений

Дата	Изменения	Причина
Июль 2008	Добавленный раздел.	Изменение функции SP1.