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

  • Статья

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

Область применения. Сведения в этом разделе относятся к проектам уровня документа и проектам надстроек VSTO для Excel и Word. Дополнительные сведения см. в разделе "Функции", доступные по Приложение Office ликации и типу проекта.

Этот раздел содержит сведения по следующим темам.

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

Чтобы добавить, получить или удалить элементы управления во время выполнения, используйте вспомогательные методы объектов ControlCollection и ControlCollection .

Способ доступа к этим объектам зависит от типа разрабатываемого проекта.

  • В проекте уровня документа для Excel используйте свойство Controls классов Sheet1, Sheet2и Sheet3 . Дополнительные сведения об этих классах см. в разделе "Узел листа".

  • В проекте уровня документа для Word используйте свойство Controls класса ThisDocument . Дополнительные сведения об этом классе см. в разделе "Элемент узла документа".

  • В проекте надстройки VSTO для Excel или Word используйте Controls свойство или WorksheetDocument создайте его во время выполнения. Дополнительные сведения о создании этих объектов во время выполнения см. в статье Расширение документов Word и книг Excel в надстройках VSTO во время выполнения.

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

Типы ControlCollection И ControlCollection включают вспомогательные методы, которые можно использовать для добавления элементов управления ведущего приложения и общих элементов управления Windows Forms в документы и листы. Each method name has the format Addcontrol class, where control class is the class name of the control that you want to add. Например, чтобы добавить элемент управления NamedRange в документ, используйте метод AddNamedRange .

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

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

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

Свойства Controls объекта Worksheet или Document можно использовать для перебора всех элементов управления в документе, в том числе элементов управления, добавленных во время разработки. Элементы управления, добавляемые во время разработки, также называются статическими элементами управления.

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

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

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

Примечание.

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

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

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

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

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

Примечание.

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

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

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

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

Примечание.

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

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

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

  • В Excel следует использовать один из методов AddControl объекта ControlCollection .

  • В Word следует использовать один из методов AddControl объекта ControlCollection .

    Чтобы добавить элемент управления, передайте Control, расположение элемента управления и имя, которое однозначно определяет элемент управления, в метод AddControl. Метод AddControl возвращает объект, который определяет способ взаимодействия элемента управления с листом или документом. Метод AddControl возвращает ControlSite объект (для Excel) или ControlSite объект (для Word).

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

    UserControl1 customControl = new UserControl1();

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

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

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

  • Control , представляющий пользовательский элемент управления.

  • Объект ControlSite, OLEObject или OLEControl, представляющий элемент управления после его добавления в лист или документ.

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

  • Для доступа к членам, относящимся только к пользовательскому элементу управления, используйте Control.

  • Для доступа к членам, которые являются общими для элементов управления, используйте объект ControlSite, OLEObject или OLEControl.

    При доступе к общему члену из Controlможет возникнуть сбой без предупреждения или уведомления либо может быть получен недопустимый результат. Всегда используйте методы и свойства объекта ControlSite, OLEObject или OLEControl, если требуемые метод или свойство доступны. Только случае их недоступности следует ссылаться на Control.

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

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

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

Связанный контент