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

Статья
02/20/2013

Visual Studio Tools for Office (cреда выполнения) предоставляет строго типизированного объекта модели, которую можно использовать для получения и задания свойств элементов управления ленты во время выполнения.Например, можно динамически наполнять элементы управления меню, а также скрывать или показывать элементы управления в зависимости от контекста.Можно также добавить вкладки, группы и элементов управления на ленте, но только до лентой загружает приложением office.Дополнительные сведения см. в разделе Установка свойств, становящихся свойствами только для чтения.

Применение. Сведения этого раздела применяются к проектам уровня документа и уровня приложения для следующих приложений: Excel 2013 и Excel 2010; InfoPath 2013 и InfoPath 2010; Outlook 2013 и Outlook 2010; PowerPoint 2013 и PowerPoint 2010; Project 2013 и Project 2010; Visio 2013 и Visio 2010; Word 2013 и Word 2010. Дополнительные сведения см. в разделе Доступность функций по типам приложений Office и проектов.

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

Класс ленты

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для данной задачи:	Действия:
Скрытие или отображение элемента управления.	Используйте свойство 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;
в конструкторе класса Ribbon.
В методе CreateRibbonExtensibilityObject класса ThisAddin, ThisWorkbook или ThisDocument проекта.

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

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

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

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

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

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

<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

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);
    }
}

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

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

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

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

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

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

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

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 });
    }
}

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

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

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

Свойство	Класс элемента управления ленты
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Динамический	RibbonMenu
Global	OfficeRibbon
Groups	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 использует для загрузки ленты.

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

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

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

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

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

Событие	Описание
Click	Происходит при щелчке на элементе управления.
TextChanged	Происходит при изменении текста в текстовом поле или поле со списком.
ItemsLoading	Происходит при запросе коллекции Items элемента управления приложением Office.Office кэширует коллекцию Items до тех пор, пока код не изменит свойства элемента управления, или не будет вызван метод IRibbonUI.InvalidateControl.
ButtonClick	Происходит при нажатии кнопки в RibbonGallery или RibbonDropDown.
SelectionChanged	Происходит при изменении выделения в RibbonDropDown или RibbonGallery.
DialogLauncherClick	Происходит при щелчке по значку вызова диалогового окна в правом нижнем углу группы.

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

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

sender

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

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

См. также

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