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

Общие сведения об объектной модели ленты

  • Статья

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

Применение

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

Тип проекта

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

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

Версия Microsoft Office

  • Excel 2007

  • Word 2007

  • Outlook 2007

  • PowerPoint 2007

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

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

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

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

Класс ленты

При добавлении в проект нового элемента Лента (визуальный конструктор) Visual Studio Tools for Office автоматически добавляет в проект экземпляр класса, унаследованного от класса OfficeRibbon.

Этот класс отображается как разделяемый класс, который делится между файлом кода ленты и файлом кода конструктора лент.

События ленты

Класс OfficeRibbon содержит три события:

Событие Load вызывается при загрузке настройки ленты приложением Office. В файл кода ленты автоматически добавляется обработчик событий Load. Этот обработчик событий используется для выполнения пользовательского кода при загрузке ленты.

Событие LoadImage позволяет кэшировать изображения в настройке ленты при ее загрузке. Если код будет настроен на кэширование изображений ленты в этом обработчике событий, это позволит добиться некоторого улучшения производительности. Дополнительные сведения см. в разделе LoadImage.

Событие Close возникает при закрытии экземпляра ленты.

Классы элементов управления ленты

Пространство имен Microsoft.Office.Tools.Ribbon содержит классы ленты для каждого элемента управления, отображаемого в группе Элементы управления ленты Office в Панели элементов.

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

Имя элемента управления

Имя класса

Box

RibbonBox

Button

RibbonButton

ButtonGroup

RibbonButtonGroup

CheckBox

RibbonCheckBox

ComboBox

RibbonComboBox

DropDown

RibbonDropDown

EditBox

RibbonEditBox

Gallery

RibbonGallery

Group

RibbonGroup

Label

RibbonLabel

Menu

RibbonMenu

Separator

RibbonSeparator

SplitButton

RibbonSplitButton

Tab

RibbonTab

ToggleButton

RibbonToggleButton

Пространство имен Microsoft.Office.Tools.Ribbon использует префикс "Ribbon" для этих классов, чтобы избежать совпадения с именами классов элементов управления в пространстве имен System.Windows.Forms.

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

Типичные задачи использования свойств классов элементов управления ленты

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

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

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

Для данной задачи:

Следует выполнить следующие действия:

Скрытие или отображение элемента управления.

Используйте свойство Visible.

Включение и отключение элемента управления.

Используйте свойство Enabled.

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

Используйте свойство ControlSize.

Получение изображения, отображаемого на элементе управления.

Используйте свойство Image.

Изменение метки элемента управления.

Используйте свойство Label.

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

Используйте свойство Tag.

Получение элементов в элементах управления RibbonBox, RibbonDropDown, RibbonGallery или

RibbonSplitButton.

Используйте свойство Items.

Добавление элементов в элементы управления RibbonComboBox, RibbonDropDown или RibbonGallery.

Используйте свойство Items.

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

Используйте свойство Items.

Чтобы добавить элементы управления в элемент управления RibbonMenu после загрузки ленты в приложение Office, необходимо присвоить свойству Dynamic значение true до загрузки ленты в приложение Office. Дополнительные сведения см. в разделе Установка свойств, становящихся свойствами только для чтения.

Получение выбранного элемента RibbonComboBox,

RibbonDropDown или RibbonGallery.

Используйте свойство SelectedItem. Для элемента управления RibbonComboBox следует использовать свойство Text.

Получение групп в RibbonTab.

Используйте свойство Groups.

Указание числа строк и столбцов, отображаемых в RibbonGallery.

Используйте свойства RowCount и ColumnCount.

Установка свойств, становящихся свойствами только для чтения

Некоторые свойства можно установить только до загрузки ленты. Существует три места для установки этих свойств:

  • в окне Свойства Visual Studio;

  • в конструкторе класса ленты;

  • в методе CreateRibbonExtensibilityObject класса проекта ThisAddin.

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

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

Дополнительные сведения см. в разделе Свойства, становящиеся свойствами только для чтения.

Задание свойств в конструкторе ленты

Свойства элемента управления ленты можно установить в конструкторе класса ленты. После вызова метода InitializeComponent должен появиться этот код. Следующий пример добавляет в группу новую кнопку, если текущее время равно 17:00 по тихоокеанскому времени (UTC-8) или позже.

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New()

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

Задание свойств в методе CreateRibbonExtensibilityObject

Свойства элемента управления ленты можно задать путем переопределения метода CreateRibbonExtensibilityObject в классах проекта ThisAddin, ThisWorkbook или ThisDocument. Дополнительные сведения о методе CreateRibbonExtensibilityObject см. в разделе Обзор ленты.

Следующий пример задает свойства ленты в методе CreateRibbonExtensibilityObject класса ThisWorkbook проекта рабочей книги Excel 2007:

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

Свойства, становящиеся свойствами только для чтения

Следующая таблица показывает свойства, которые можно установить только до загрузки ленты:

Bb608623.alert_note(ru-ru,VS.90).gifПримечание.

При наличии установленного пакета обновления 1 (SP1) можно задавать свойства элементов управления динамического меню в любой момент времени. В этом случае сведения данной таблицы не актуальны.

Свойство

Класс элемента управления ленты

BoxStyle

RibbonBox

ButtonType

RibbonSplitButton

ColumnCount

RibbonGallery

ControlId

RibbonTab

DialogLauncher

RibbonGroup

Dynamic

RibbonMenu

Global

OfficeRibbon

Groups

RibbonTab

ImageName

RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton

ItemSize

RibbonMenu

RibbonSplitButton

MaxLength

RibbonComboBox

RibbonEditBox

Name

RibbonComponent

Position

RibbonButton

RibbonCheckBox

RibbonGallery

RibbonGroup

RibbonMenu

RibbonSeparator

RibbonSplitButton

RibbonTab

RibbonToggleButton

RibbonType

OfficeRibbon

RowCount

RibbonGallery

ShowItemImage

RibbonComboBox

RibbonDropDown

RibbonGallery

ShowItemLabel

RibbonDropDown

RibbonGallery

ShowItemSelection

RibbonGallery

SizeString

RibbonComboBox

RibbonDropDown

RibbonEditBox

StartFromScratch

OfficeRibbon

Tabs

OfficeRibbon

Title

RibbonSeparator

Установка свойств для лент, отображаемых в окнах инспекторов Outlook

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

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

Bb608623.alert_note(ru-ru,VS.90).gifПримечание.

Убедитесь, что свойство Имя установлено для каждого элемента управления, добавляемого в ленту Outlook. Если элемент управления добавляется на ленту Outlook во время выполнения, необходимо установить это свойство в коде. При добавлении элемента управления на ленту Outlook во время разработки свойство Name устанавливается автоматически.

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

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

Событие

Описание

Click

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

TextChanged

Происходит при изменении текста в текстовом поле или поле со списком.

ItemsLoading

Происходит при запросе коллекции Items элемента управления приложением Office. Office кэширует коллекцию Items до тех пор, пока код не изменит свойства элемента управления, или не будет вызван метод Microsoft.Office.Core.IRibbonUI.InvalidateControl.

ButtonClick

Происходит при нажатии кнопки в RibbonGallery или RibbonDropDown.

SelectionChanged

Происходит при изменении выделения в RibbonDropDown или RibbonGallery.

DialogLauncherClick

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

Обработчики событий для этих событий имеют два параметра:

Параметр

Описание

sender

Object, представляющий элемент управления, вызвавший событие.

e

RibbonControlEventArgs, содержащий объект Microsoft.Office.Core.IRibbonControl. Используйте этот элемент управления для доступа к любому свойству, недоступному в объектной модели ленты Visual Studio Tools for Office.

См. также

Задачи

Практическое руководство. Работа с настройкой ленты

Пошаговое руководство. Создание настраиваемой вкладки с помощью конструктора лент

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

Практическое руководство. Настройка встроенной вкладки

Практическое руководство. Настройка меню Microsoft Office

Практическое руководство. Экспорт лент из конструктора лент в XML-ленты

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

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

Доступ к ленте во время выполнения

Обзор ленты

Конструктор лент

Настройка ленты для Outlook

Ссылки

Microsoft.Office.Tools.Ribbon

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

Дата

Изменения

Причина

Июль 2008

Исправлены сведения об установке свойств элементов управления динамического меню после установки пакета обновления 1 (SP1).

Изменение функции SP1.