功能区对象模型概述

Visual Studio Tools for Office Runtime 显示可用于获取和设置功能区控件属性在运行时的一个强类型对象模型。例如，可以动态填充菜单控件，或者按照上下文显示和隐藏控件。还可以添加选项卡、组和控件添加到功能区，但是，在功能区之前的 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 选件类包含以下三个操作：

Event	描述
RibbonBase.Load	引发，在 Office 应用程序加载功能区自定义项。Load 事件处理程序会自动添加到功能区代码文件。并在功能区加载时，使用此事件处理程序运行自定义代码。
RibbonBase.LoadImage	并在功能区加载时，允许您对功能区自定义项中缓存图像。可以使性能稍有，如果您编写代码来缓存此事件处理程序的功能区图像。有关更多信息，请参见LoadImage。
RibbonBase.Close	引发，后者在功能区实例关闭。

功能区控件

对于**“工具箱”的“Office 功能区控件”**组中显示的每个控件，Microsoft.Office.Tools.Ribbon 命名空间都包含一个对应的类型。

下表显示了每个 Ribbon 控件的类型。有关每个控件的说明，请参见功能区概述。

控件名称	类名
方框	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
组	RibbonGroup
Label	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	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 选件类的构造函数。

• 在项目的 ThisAddin、ThisWorkbook 或 ThisDocument 类的 CreateRibbonExtensibilityObject 方法中。

但对于动态菜单，情况则有不同。您可以创建新控件，设置其属性，然后将它们添加到动态菜单在运行时，在包含该菜单后的功能区加载。

可以随时设置添加到动态菜单的控件的属性。

有关更多信息，请参见变成只读属性的属性。

在功能区的构造函数中设置属性

可以设置一个 Ribbon 控件的属性。Ribbon 选件类的构造函数。该代码必须放在对 InitializeComponent 方法的调用之后。下面的示例在当前时间为太平洋时间 (UTC-8) 17:00 或更晚时向组中添加一个新按钮。

添加下列代码。

<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# 项目 (从 Visual Studio 升级了 2008 中，构造函数显示在功能区代码文件。

在 Visual Basic 项目中，或在 visual C# 项目。在 Visual Studio 2012创建的，构造函数显示在功能区设计器代码文件。此文件名为您的功能区项目.Designer.cs 或您的功能区项目.Designer.vb。若要查看 Visual Basic 项目中的此文件，必须先在解决方案资源管理器中单击**“显示所有文件”**按钮。

在 CreateRibbonExtensibilityObject 方法中设置属性

当您重写在 ThisAddin、ThisWorkbook或项目中时，ThisDocument 选件类的 CreateRibbonExtensibilityObject 方法可以设置 Ribbon 控件的属性。有关 CreateRibbonExtensibilityObject 方法的更多信息，请参见 功能区概述。

下面的示例将在 Excel 工作簿项目的 ThisWorkbook 选件类的 CreateRibbonExtensibilityObject 方法的功能区属性。

添加下列代码。

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
Dynamic	RibbonMenu
Global	OfficeRibbon
Groups	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
名称	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
制表符	OfficeRibbon
标题	RibbonSeparator

设置 Outlook 检查器中显示的功能区的属性

功能区的新实例后，每当用户打开功能区上的检查器。但是，因此，只有在功能区的第一个实例之前，可以设置上表中列出的属性。在创建第一个实例之后，这些属性成为只读的，因为第一个实例定义 Outlook 用来加载功能区上的 XML 文件。

如果您具有设置这些属性中的任何一个为不同的值的条件逻辑，在功能区的其他实例后，此代码将不起作用。

说明
确保 名称 特性已添加到 Outlook 功能区中的每个控件设置。如果将控件添加到 Outlook 功能区在运行时，您必须在代码中设置此属性。如果将控件添加到 Outlook 功能区在设计时，Name 自动设置属性。

功能区控件事件

每个控件类都包含一个或多个事件。下表描述了这些事件。

Event	描述
Click	在单击控件时发生。
TextChanged	在编辑框或组合框中的文本更改时发生。
ItemsLoading	在 Office 请求控件的 Items 集合时发生。Office 会缓存 Items 集合，直到代码更改控件的属性，或者调用 IRibbonUI.InvalidateControl 方法。
ButtonClick	在单击 RibbonGallery 或 RibbonDropDown 中的按钮时发生。
SelectionChanged	在 RibbonDropDown 或 RibbonGallery 中的所选内容更改时发生。
DialogLauncherClick	在单击组右下角的对话框启动器图标时发生。

这些事件的事件处理程序具有以下两个参数：

Parameter	描述
sender	一个 Object，表示引发事件的控件。
e	一个包含 Microsoft.Office.Core.IRibbonControl 的 RibbonControlEventArgs。使用此控件可访问在 Visual Studio Tools for Office Runtime 提供的功能区对象模型中不可用的任何属性。

请参见

任务

如何：开始自定义功能区

演练：使用功能区设计器创建自定义选项卡

演练：在运行时更新功能区上的控件

如何：自定义内置选项卡

如何：向 Backstage 视图添加控件

如何：将功能区从功能区设计器导出为功能区 XML

如何：显示外接程序用户界面错误

参考

Microsoft.Office.Tools.Ribbon

概念

在运行时访问功能区

功能区设计器

自定义 Outlook 功能区

其他资源

功能区概述