Обзор объектной модели ленты

Среда выполнения набор средств Visual Studio для Office предоставляет строго типизированную объектную модель, которую можно использовать для получения и задания свойств элементов управления лентой во время выполнения. Например, можно динамически заполнять элементы управления меню или отображать и скрывать элементы управления контекстно. Вы также можете добавлять вкладки, группы и элементы управления на ленту, но только перед загрузкой ленты Приложение Office lication. Дополнительные сведения см. в разделе "Задание свойств, которые становятся доступны только для чтения".

Область применения: сведения в этом разделе относятся к проектам на уровне документа и проектам надстроек VSTO для следующих приложений: Excel; InfoPath 2013 и InfoPath 2010; Outlook; Powerpoint; Проекта; Visio; Слово. Дополнительные сведения см. в разделе "Функции", доступные по Приложение Office ликации и типу проекта.

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

Класс ленты

При добавлении нового элемента ленты (visual Designer) в проект Visual Studio добавляется класс ленты в проект. Класс ленты наследует от RibbonBase класса.

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

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

Класс ленты содержит следующие три события:

Мероприятие	Description
Load	Вызывается при загрузке Приложение Office ликации настройки ленты. Обработчик Load событий автоматически добавляется в файл кода ленты. Используйте этот обработчик событий для запуска пользовательского кода при загрузке ленты.
LoadImage	Позволяет кэшировать изображения в настройке ленты при загрузке ленты. При написании кода для кэширования образов ленты в этом обработчике событий можно получить небольшое повышение производительности. Дополнительные сведения см. в разделе LoadImage.
Close	Вызывается при закрытии экземпляра ленты.

Элементы управления на ленте

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

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

Имя элемента управления	Имя класса
Box	RibbonBox
Кнопка	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Галерея	RibbonGallery
Групповое	RibbonGroup
Подпись	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Вкладка	RibbonTab
ToggleButton	RibbonToggleButton

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

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

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

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

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

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

Для выполнения этой задачи	Процедура
Скрытие или отображение элемента управления.	Используйте свойство Visible.
Включение или отключение элемента управления.	Используйте свойство Enabled.
Задайте размер элемента управления.	Используйте свойство ControlSize.
Получите изображение, отображаемое в элементе управления.	Используйте свойство Image.
Измените метку элемента управления.	Используйте свойство Label.
Добавьте пользовательские данные в элемент управления.	Используйте свойство Tag.
Получение элементов в объекте RibbonBox, RibbonDropDownRibbonGalleryили RibbonSplitButton Управления.	Используйте свойство Items.
Добавьте элементы в RibbonComboBoxRibbonDropDownэлемент управления или RibbonGallery элемент управления.	Используйте свойство Items.
Добавление элементов управления в RibbonMenuобъект .	Используйте свойство Items. Чтобы добавить элементы управления RibbonMenu в Приложение Office lication после загрузки ленты, необходимо задать Dynamic для свойства значение true, прежде чем лента загружается в Приложение Office ликацию. Дополнительные сведения см. в разделе "Задание свойств, которые становятся доступны только для чтения".
Получение выбранного элемента объекта RibbonComboBox, RibbonDropDown или RibbonGallery.	Используйте свойство SelectedItem. Для свойства RibbonComboBoxиспользуйте Text свойство.
Получение групп в объекте RibbonTab.	Используйте свойство Groups.
Укажите количество строк и столбцов, отображаемых в объекте RibbonGallery.	Используйте свойства RowCount и ColumnCount.

Задание свойств, которые становятся доступны только для чтения

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

• В окне свойств Visual Studio.

• В конструкторе класса ленты .

• В методе CreateRibbonExtensibilityObjectThisAddinThisWorkbookThisDocument или классе проекта.

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

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

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

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

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

Добавьте следующий код.

C#

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

VB

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

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

В проектах Visual C#, обновленных с Visual Studio 2008, конструктор появится в файле кода ленты.

В проектах Visual Basic или в проектах Visual C#, созданных в Visual Studio 2013, конструктор появится в файле кода конструктора ленты. Этот файл называется YourRibbonItem. Designer.cs или YourRibbonItem. Designer.vb. Чтобы просмотреть этот файл в проектах Visual Basic, сначала нажмите кнопку "Показать все файлы" в Обозреватель решений.

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

При переопределении CreateRibbonExtensibilityObject метода в ThisWorkbookThisAddinпроекте можно ThisDocument задать свойства Ribbon элемента управления. Дополнительные сведения о методе см. в CreateRibbonExtensibilityObject разделе " Обзор ленты".

В следующем примере задаются свойства ленты в CreateRibbonExtensibilityObject методе ThisWorkbook класса проекта книги Excel.

Добавьте следующий код.

C#

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

VB

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 Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

Свойства, которые становятся доступны только для чтения

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

Примечание.

В любое время можно задать свойства элементов управления в динамических меню. Эта таблица не применяется в этом случае.

Свойство	Класс элемента управления "Лента"
BoxStyle	RibbonBox
Buttontype	RibbonSplitButton
ColumnCount	RibbonGallery
Controlid	RibbonTab
DialogLauncher	RibbonGroup
динамически;	RibbonMenu
Global	OfficeRibbon
Группы	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Имя	RibbonComponent
Занимаемая должность	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
Вкладки	OfficeRibbon
Заголовок	RibbonSeparator

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

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

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

Примечание.

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

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

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

Мероприятие	Description
Щелчок	Происходит при щелчке элемента управления.
Textchanged	Происходит при изменении текста поля редактирования или поля со списком.
ItemsLoading	Происходит, когда коллекция элементов элемента управления запрашивается Office. Office кэширует коллекцию items, пока код не изменяет свойства элемента управления или вызывает InvalidateControl метод.
ButtonClick	Происходит при нажатии кнопки или RibbonGalleryRibbonDropDown нажатия кнопки.
SelectionChanged	Происходит при выборе в объекте RibbonDropDown или RibbonGallery изменении.
DialogLauncherClick	Происходит при щелчке значка средства запуска диалогов в правом нижнем углу группы.

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

Параметр	Описание
Отправителя	Объект, Object представляющий элемент управления, вызвавшее событие.
e	Объект, RibbonControlEventArgs содержащий объект IRibbonControl. Используйте этот элемент управления для доступа к любому свойству, недоступному в объектной модели ленты, предоставляемой средой выполнения набор средств Visual Studio для Office.

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

• Доступ к ленте во время выполнения
• Обзор ленты
• Практическое руководство. Начало настройки ленты
• Конструктор лент
• Пошаговое руководство. Создание настраиваемой вкладки с помощью конструктора лент
• Пошаговое руководство. Обновление элементов управления на ленте во время выполнения
• Настройка ленты для Outlook
• Практическое руководство. Настройка встроенной вкладки
• Практическое руководство. Добавление элементов управления в представление Backstage
• Практическое руководство. Экспорт ленты из конструктора лент в XML-файл ленты
• Практическое руководство. Отображение ошибок пользовательского интерфейса надстройки