功能区对象模型概述

Visual Studio Tools for Office Runtime 公开一个强类型对象模型，使用该模型可在运行时获取和设置功能区控件的属性。 例如，可以动态填充菜单控件，或者按照上下文显示和隐藏控件。 还可以在功能区中添加选项卡、组和控件，但只能在 Office 应用程序加载功能区之前添加。 有关信息，请参见设置变成只读属性的属性。

**适用于：**本主题中的信息适用于以下应用程序的文档级项目和应用程序级项目：Excel 2007 和 Excel 2010；InfoPath 2010；Outlook 2007 和 Outlook 2010；PowerPoint 2007 和 PowerPoint 2010；Project 2010；Visio 2010；Word 2007 和 Word 2010。有关更多信息，请参见按 Office 应用程序和项目类型提供的功能。

此功能区对象模型主要由功能区类、功能区事件和功能区控件类组成。

功能区类

在向项目添加新的**“功能区(可视化设计器)”**项时，Visual Studio 会自动将功能区类添加到项目中。 如果项目面向 .NET Framework 4，则功能区类继承自 RibbonBase 类。 如果您的项目以 .NET Framework 3.5 为目标，则功能区类继承自 OfficeRibbon 类。

此类作为在功能区代码文件和功能区设计器代码文件之间拆分的分部类出现。

功能区事件

功能区类包含下面的三个事件：

以 .NET Framework 4 为目标的项目	以 .NET Framework 3.5 为目标的项目	说明
RibbonBase.Load	OfficeRibbon.Load	在 Office 应用程序加载功能区自定义项时引发。 Load 事件处理程序会自动添加到功能区代码文件中。 可使用此事件处理程序在功能区加载时运行自定义代码。
RibbonBase.LoadImage	OfficeRibbon.LoadImage	使您可以在功能区加载时缓存功能区自定义项中的图像。 在此事件处理程序中编写代码来缓存功能区图像可以使性能稍有提高。 有关更多信息，请参见 LoadImage。
RibbonBase.Close	OfficeRibbon.Close	功能区实例关闭时引发。

功能区控件

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

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

控件名称	类名
方框	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
组	RibbonGroup
标签	RibbonLabel
菜单	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 属性。 若要在功能区加载到 Office 应用程序中之后向 RibbonMenu 中添加控件，必须在功能区加载到 Office 应用程序中之前将 Dynamic 属性设置为 true。 有关信息，请参见设置变成只读属性的属性。
获取下列控件的选定项：RibbonComboBox、 RibbonDropDown 或 RibbonGallery。	使用 SelectedItem 属性。 对于 RibbonComboBox，使用 Text 属性。
获取 RibbonTab 上的组。	使用 Groups 属性。
指定在 RibbonGallery 中显示的行数和列数。	使用 RowCount 和 ColumnCount 属性。

设置变成只读属性的属性

有些属性只能在功能区加载之前进行设置。 有三个位置可以设置这些属性：

• 在 Visual Studio**“属性”**窗口中。

• 在功能区类的构造函数中。

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

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

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

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

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

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

对于以 .NET Framework 4 为目标的项目，请添加以下代码：

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

对于以 .NET Framework 3.5 为目标的项目，请添加以下代码：

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

}

在从 Visual Studio 2008 升级的 Visual C# 项目中，构造函数显示在功能区代码文件中。

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

在 CreateRibbonExtensibilityObject 方法中设置属性

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

下面的示例在 Excel 工作簿项目的 ThisWorkbook 类的 CreateRibbonExtensibilityObject 方法中设置功能区属性。

对于以 .NET Framework 4 为目标的项目，请添加以下代码：

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

对于以 .NET Framework 3.5 为目标的项目，请添加以下代码：

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

变成只读属性的属性

下表显示了只能在功能区加载之前设置的属性。

提示

可以随时设置动态菜单上控件的属性。 该表不适用于这种情况。

Property	功能区控件类
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
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
制表符	OfficeRibbon
标题	RibbonSeparator

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

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

如果在创建功能区的其他实例时存在将任何这些属性设置为不同值的条件逻辑，此代码将不起作用。

提示

确保为添加到 Outlook 功能区中的每个控件设置“Name”属性。 如果在运行时将控件添加到 Outlook 功能区中，则必须在代码中设置此属性。 如果在设计时将控件添加到 Outlook 功能区中，则会自动设置 Name 属性。

功能区控件事件

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

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

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

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

请参见

任务

如何：开始自定义功能区

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

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

如何：自定义内置选项卡

如何：自定义 Microsoft Office 菜单

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

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

参考

Microsoft.Office.Tools.Ribbon

概念

在运行时访问功能区

功能区设计器

自定义 Outlook 功能区

其他资源

功能区概述