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

Статья
04/28/2010

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

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

Сведения, приведенные в данном разделе, относятся только к указанным проектам Visual Studio Tools for Office и версиям Microsoft Office.

Проекты уровня документа

Excel 2003
Excel 2007
Word 2003
Word 2007

Проекты уровня приложения

Excel 2007
Word 2007

Дополнительные сведения см. в разделе Доступность функций по типам приложений и проектов.

Элементы управления можно добавлять в документы Microsoft Office Word и книги Microsoft Office Excel, а также удалять из них как во время разработки, так и во время выполнения. Элементы управления, добавляемые в документ во время выполнения, называются динамическими элементами управления. Начиная с пакета обновления 1 для Visual Studio 2008, можно добавлять динамические элементы управления в документы и на листы с помощью надстроек уровня приложения.

В данном разделе содержатся следующие сведения:

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

Управление элементами управления во время выполнения с помощью коллекций

Для добавления, получения и удаления элементов управления во время выполнения используются вспомогательные методы классов Microsoft.Office.Tools.Excel.ControlCollection и Microsoft.Office.Tools.Word.ControlCollection.

Способ обращения к коллекциям элементов управления зависит от типа разрабатываемого проекта.

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

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

Классы Microsoft.Office.Tools.Excel.ControlCollection и Microsoft.Office.Tools.Word.ControlCollection содержат вспомогательные методы, которые можно использовать для добавления элементов управления ведущего приложения и общих элементов управления Windows Forms в документы и на листы. В каждом методе используется формат Add<класс элемента управления>, где класс элемента управления — это имя класса добавляемого элемента управления. Например, чтобы добавить в документ элемент управления NamedRange, используйте метод AddNamedRange. Полный список вспомогательных методов см. в разделах Вспомогательные методы для элементов управления ведущего приложения и Вспомогательные методы для элементов управления Windows Forms.

В следующем примере кода показывается добавление NamedRange в Sheet1 в проекте уровня документа для Excel.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

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

С помощью свойства Controls класса Microsoft.Office.Tools.Excel.Worksheet или класса Microsoft.Office.Tools.Word.Document обеспечивается итерация по всем элементам управления в документе, включая добавленные во время разработки. Элементы управления, добавляемые в документ во время разработки, также называются статическими элементами управления.

Удалить динамические элементы управления можно путем вызова метода Delete элемента управления или путем вызова метода Remove каждой коллекции Controls. В следующем примере кода показывается использование метода Remove для удаления элемента управления NamedRange из листа Sheet1 в проекте уровня документа для Excel.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

Во время выполнения удаление статических элементов управления невозможно. При попытке удаления статического элемента управления с помощью метода Delete или Remove будет возникать исключение CannotRemoveControlException.

Примечание.
Не удаляйте элементы управления программными средствами в обработчике событий Shutdown документа. При возникновении события Shutdown элементы пользовательского интерфейса документа становятся недоступными. Если требуется удалить элементы управления до закрытия документа, следует добавить код в обработчик для другого события, например события Document.BeforeClose или Document.BeforeSave для Word или события Workbook.BeforeClose или Workbook.BeforeSave для Excel.

Не удаляйте элементы управления программными средствами в обработчике событий Shutdown документа. При возникновении события Shutdown элементы пользовательского интерфейса документа становятся недоступными. Если требуется удалить элементы управления до закрытия документа, следует добавить код в обработчик для другого события, например события Document.BeforeClose или Document.BeforeSave для Word или события Workbook.BeforeClose или Workbook.BeforeSave для Excel.

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

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

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

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

Примечание.
Следующие элементы управления не могут добавляться в документы программными средствами и, следовательно, не поддерживают вспомогательные методы: XmlMappedRange, XMLNode и XMLNodes.

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

В случае программного добавления элементов управления Windows Forms в документ для каждого элемента необходимо указать расположение и уникальное имя. В Visual Studio Tools for Office представлены вспомогательные методы для каждого элемента управления. Используются перегрузки этих методов, в которые передаются диапазон или конкретные координаты расположения элемента управления. Дополнительные инструкции см. в разделе Практическое руководство. Добавление элементов управления Windows Forms в документы Office.

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

Примечание.
Программное добавление элементов управления Windows Forms в защищенные документы не поддерживается. Если для добавления элемента управления защита документа Word или книги Excel снимается программными средствами, необходимо добавить дополнительный код для удаления оболочки ActiveX элемента управления при закрытии документа. Автоматическое удаление оболочки ActiveX элемента управления из защищенных документов не поддерживается.

Программное добавление элементов управления Windows Forms в защищенные документы не поддерживается. Если для добавления элемента управления защита документа Word или книги Excel снимается программными средствами, необходимо добавить дополнительный код для удаления оболочки ActiveX элемента управления при закрытии документа. Автоматическое удаление оболочки ActiveX элемента управления из защищенных документов не поддерживается.

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

Чтобы добавить элемент управления System.Windows.Forms.Control, который не поддерживается доступными вспомогательными методами (например пользовательский элемент управления), следует использовать следующие методы:

В Excel следует использовать один из методов AddControl() класса Microsoft.Office.Tools.Excel.ControlCollection.
В Word следует использовать один из методов AddControl() класса Microsoft.Office.Tools.Word.ControlCollection.

Чтобы добавить элемент управления, передайте методу AddControl элемент управления System.Windows.Forms.Control, его расположение и уникальное имя. В Excel этот метод возвращает OLEObject. В Word этот метод возвращает OLEControl. Эти объекты определяют порядок взаимодействия элемента управления с листом или документом.

В следующем примере кода показан порядок использования метода AddControl(Control, Range, String) для динамического добавления пользовательского элемента управления на лист. В этом примере пользовательский элемент управления называется UserControl1, и элемент управления Range называется range1. В этом примере предполагается, что код выполняется одним из классов Sheetn в проекте уровня документа для Excel.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.OLEObject = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.OLEObject dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

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

После добавления элемента управления на лист или в документ с помощью методов AddControl появляется два разных объекта элементов управления:

объект System.Windows.Forms.Control, представляющий пользовательский элемент управления;
объект OLEObject или OLEControl, представляющий элемент управления после его добавления на лист или в документ.

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

Для обращения к свойствам и методам, присущим только пользовательскому элементу управления, используйте System.Windows.Forms.Control.
Для обращения к общим методам и свойствам элементов управления используйте объекты OLEObject или OLEControl.

При обращении к общим методам или свойствам System.Windows.Forms.Control может возникнуть сбой без предупреждения или уведомления, либо может быть создан недопустимый результат. Если необходимый метод или свойство недоступны, следует всегда использовать методы и свойства OLEObject или OLEControl; только тогда можно будет ссылаться на System.Windows.Forms.Control.

Например оба класса OLEObject и System.Windows.Forms.Control имеют свойство Top. Чтобы получить или установить расстояние между верхом элемента управления и верхом документа, следует использовать свойство Top объекта OLEObject, а не свойство Top объекта System.Windows.Forms.Control.

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

См. также

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

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

Поделиться через

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

Управление элементами управления во время выполнения с помощью коллекций

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

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

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

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

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

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

См. также

Задачи

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

Ссылки

Другие ресурсы

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

Дополнительные ресурсы