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

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

  • Статья

Среда выполнения набор средств 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.

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

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

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

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

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

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

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

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

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#, обновленных с 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.

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

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
Группы 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 Происходит при нажатии кнопки или RibbonGallery RibbonDropDown нажатия кнопки.
SelectionChanged Происходит при выборе в объекте RibbonDropDown или RibbonGallery изменении.
DialogLauncherClick Происходит при щелчке значка средства запуска диалогов в правом нижнем углу группы.

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

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

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