Пошаговое руководство. Добавление элементов управления в документ во время выполнения в надстройке уровня приложения

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

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

Начиная с пакета обновления 1 (SP1) для Visual Studio 2008, можно добавлять элементы управления в любой открытый документ Microsoft Office Word 2007, используя надстройку уровня приложения. В данном пошаговом руководстве демонстрируется, как с помощью ленты предоставить пользователям возможность добавлять в документ элементы управления Button или RichTextContentControl.

В данном пошаговом руководстве описываются следующие задачи.

• Создание проекта новой надстройки Word.

• Предоставление пользовательского интерфейса для добавления элементов управления в документ.

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

• Удаление элементов управления из документа.

Примечание.
На вашем компьютере названия некоторых элементов интерфейса пользователя Visual Studio или их расположение могут отличаться от указанных в нижеследующих инструкциях. Это зависит от имеющегося выпуска Visual Studio и используемых параметров. Дополнительные сведения см. в разделе Параметры Visual Studio.

Обязательные компоненты

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

• Visual Studio Tools for Office (необязательный компонент Visual Studio 2008 Professional и Visual Studio Team System);

• Пакет SP1 для Visual Studio 2008

• Microsoft Office Word 2007.

Создание проекта новой надстройки Word.

Начните с создания проекта надстройки Word 2007.

Создание проекта новой надстройки Word

• Создайте проект надстройки уровня приложения для Word 2007 с именем WordDynamicControls. Дополнительные сведения см. в разделе Практическое руководство. Создание проектов Visual Studio Tools for Office.

Предоставление пользовательского интерфейса для добавления элементов управления в документ

Добавьте настраиваемую вкладку на ленту в Word. Для добавления элементов управления в документ пользователи смогут устанавливать флажки на этой вкладке.

Предоставление пользовательского интерфейса для добавления элементов управления в документ

1. В меню Проект выберите команду Добавить новый элемент.

2. В диалоговом окне Добавление нового элемента выберите элемент Лента (визуальный конструктор).

3. Измените имя новой ленты на MyRibbon и нажмите кнопку Добавить.

   В конструкторе лент откроется файл MyRibbon.cs или MyRibbon.vb; отобразятся вкладка и группа, используемые по умолчанию.

4. В конструкторе лент щелкните группу group1.

5. В окне Свойства измените свойство Метка для group1 на Добавить элементы управления.

6. Перетащите элемент управления Флажок с вкладки Элементы управления ленты Office элемента управления Панель элементов в группу group1.

7. Щелкните CheckBox1, чтобы выбрать его.

8. В окне Свойства измените следующие свойства:

   Свойство	Значение
   Имя	addButtonComboBox
   Метка	Добавить кнопку

9. Добавьте второй флажок в group1 и измените следующие свойства.

   Свойство	Значение
   Имя	addRichTextCheckBox
   Метка	Добавить элемент управления текстом в формате RTF

10. В конструкторе ленты дважды щелкните Добавить кнопку.

    В редакторе кода откроется обработчик событий Click флажка Добавить кнопку.

11. Вернитесь в конструктор ленты и дважды щелкните Добавить элемент управления текстом в формате RTF.

    В редакторе кода откроется обработчик событий Click флажка Добавить элемент управления текстом в формате RTF.

В последующих шагах этого руководства в эти обработчики событий будет добавлен код для добавления и удаления элементов управления в активном документе.

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

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

Добавьте в класс ThisAddIn методы, которые могут быть вызваны для выполнения операций добавления или удаления элементов управления Button или RichTextContentControl в активном документе. Позднее в этом пошаговом руководстве эти методы будут вызваны из обработчиков событий Click флажков на ленте.

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

1. В обозревателе решений дважды щелкните ThisAddIn.cs или ThisAddIn.vb, чтобы открыть файл в редакторе кода.

2. Добавьте следующий код в класс ThisAddIn. Этот код объявляет объекты Button и RichTextContentControl, представляющие элементы управления, которые будут добавлены в документ.

   Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
   Private richTextControl As RichTextContentControl = Nothing
   

   private Microsoft.Office.Tools.Word.Controls.Button button = null;
   private RichTextContentControl richTextControl = null;
   

3. Добавьте следующий метод в класс ThisAddIn. Когда пользователь щелкает на ленте флажок Добавить кнопку, этот метод добавляет элемент управления Button в текущее выделение в документе, если флажок устанавливается, или удаляет элемент управления Button, если флажок снимается.

   Friend Sub ToggleButtonOnDocument()
       Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
       Dim vstoDocument As Document = nativeDocument.GetVstoObject()
       Dim name As String = "MyButton"
   
       If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
           If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
               button = vstoDocument.Controls.AddButton( _
                   Globals.ThisAddIn.Application.Selection.Range, 100, 30, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

   internal void ToggleButtonOnDocument()
   {
       Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
       Document vstoDocument = nativeDocument.GetVstoObject();
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           if (Globals.ThisAddIn.Application.Selection != null)
           {
               button = vstoDocument.Controls.AddButton(
                   Globals.ThisAddIn.Application.Selection.Range, 100, 30, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

4. Добавьте следующий метод в класс ThisAddIn. Когда пользователь щелкает на ленте флажок Добавить элемент управления текстом в формате RTF, этот метод добавляет элемент управления RichTextContentControl в текущее выделение в документе, если флажок устанавливается, или удаляет элемент управления RichTextContentControl, если флажок снимается.

   Friend Sub ToggleRichTextControlOnDocument()
       Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
       Dim vstoDocument As Document = nativeDocument.GetVstoObject()
       Dim name As String = "MyRichTextBoxControl"
   
       If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
           If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
               richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                       Globals.ThisAddIn.Application.Selection.Range, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

   internal void ToggleRichTextControlOnDocument()
   {
       Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
       Document vstoDocument = nativeDocument.GetVstoObject();
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           if (Globals.ThisAddIn.Application.Selection != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   Globals.ThisAddIn.Application.Selection.Range, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

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

Элементы управления Windows Forms не сохраняются при сохранении и закрытии документа. Но для каждого элемента управления в документе сохраняется программа-оболочка ActiveX, и граница этой оболочки может быть видна конечным пользователям при повторном открытии документа. Существует несколько способов очистить динамически созданные элементы управления Windows Forms в надстройках. В этом пошаговом руководстве настраивается удаление элемента управления Button программными средствами при сохранении документа.

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

1. В файле кода ThisAddIn.cs или ThisAddIn.vb добавьте в класс следующий метод ThisAddIn следующий метод. Этот метод является обработчиком событий для события DocumentBeforeSave. Если у сохраненного документа есть связанный с ним ведущий элемент Document, обработчик событий получает этот ведущий элемент и удаляет элемент управления Button, если таковой существует.

   Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
       ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
       If Doc.HasVstoObject() Then
           Dim vstoDocument As Document = Doc.GetVstoObject()
           If vstoDocument.Controls.Contains(button) Then
               vstoDocument.Controls.Remove(button)
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
           End If
       End If
   End Sub
   

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       if (Doc.HasVstoObject())
       {
           Document vstoDocument = Doc.GetVstoObject();
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

2. В C# добавьте следующий код в обработчик событий ThisAddIn_Startup. В C# этот код требуется для подключения к обработчику событий Application_DocumentBeforeSave события DocumentBeforeSave.

   this.Application.DocumentBeforeSave += 
       new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
       Application_DocumentBeforeSave);
   

Добавление и удаление элементов управления при щелчке пользователем флажков на ленте

Наконец, измените обработчики событий Click добавленных на ленту флажков, чтобы добавлять элементы управления в документ и удалять их из документа.

Добавление и удаление элементов управления при щелчке пользователем флажков на ленте

• В файл кода MyRibbon.cs или MyRibbon.vb замените созданные обработчики событий addButtonCheckBox_Click и addRichTextCheckBox_Click следующим кодом. Данный код переопределяет эти обработчики событий для вызова методов ToggleButtonOnDocument и ToggleRichTextControlOnDocument, добавленных в класс ThisAddIn в предыдущих шагах этого руководства.

  Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
      ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
      Globals.ThisAddIn.ToggleButtonOnDocument()
  End Sub
  
  Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
      ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
      Globals.ThisAddIn.ToggleRichTextControlOnDocument()
  End Sub
  

  private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
  {
      Globals.ThisAddIn.ToggleButtonOnDocument();
  }
  
  private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
  {
      Globals.ThisAddIn.ToggleRichTextControlOnDocument();
  }
  

Проверка работы решения

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

Проверка решения.

1. Нажмите клавишу F5 для запуска проекта.

2. В активном документе нажмите клавишу ВВОД несколько раз, чтобы добавить в документ новые пустые абзацы.

3. Выделите первый абзац.

4. Выберите вкладку Надстройки.

5. В группе Добавить элементы управления щелкните Добавить кнопку.

   В первом абзаце появится кнопка.

6. Выделите последний абзац.

7. В группе Добавить элементы управления щелкните Добавить элемент управления текстом в формате RTF.

   В последний абзац будет добавлен элемент управления текстом в формате RTF.

8. Сохраните документ.

   Кнопка удаляется из документа.

Следующие действия

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

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

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

См. также

Задачи

Практическое руководство. Добавление элементов управления Windows Forms в документы Office

Практическое руководство. Добавление элементов управления содержимым в документы Word

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

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

Разработка надстроек уровня приложения для Word

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

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

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

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

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