功能区对象模型概述

项目
09/10/2008

更新： 2008 年 7 月

适用于
本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。项目类型文档级项目应用程序级项目 Microsoft Office 版本 Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 有关更多信息，请参见按应用程序和项目类型提供的功能。

本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。

项目类型

文档级项目
应用程序级项目

Microsoft Office 版本

Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

有关更多信息，请参见按应用程序和项目类型提供的功能。

Visual Studio Tools for Office 公开一个强类型对象模型，使用该模型可以在运行时获取和设置功能区控件的属性。例如，可以动态填充菜单控件，或者按照上下文显示和隐藏控件。

还可以在功能区中添加选项卡、组和控件，但只能在 Office 应用程序加载功能区之前添加。有关信息，请参见设置变成只读属性的属性。

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

功能区类

在项目添加新的“功能区(可视化设计器)”项时，Visual Studio Tools for Office 会向项目添加一个从 OfficeRibbon 类继承的类。

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

功能区事件

OfficeRibbon 类包含下列三个事件：

Load 事件在 Office 应用程序加载功能区自定义项时引发。Load 事件处理程序会自动添加到功能区代码文件中。可使用此事件处理程序在功能区加载时运行自定义代码。

使用 LoadImage 事件可以在功能区加载时缓存功能区自定义项中的图像。在此事件处理程序中编写代码来缓存功能区图像可以使性能稍有提高。有关更多信息，请参见 LoadImage。

Close 事件在功能区实例关闭时引发。

功能区控件类

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

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

控件名称	类名
Box	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
Group	RibbonGroup
Label	RibbonLabel
Menu	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 类的 CreateRibbonExtensibilityObject 方法中。

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

从 Visual Studio 2008 Service Pack 1 (SP1) 开始，可随时设置添加到动态菜单的控件的属性。但若还未安装 SP1，则在控件已添加到菜单后，它的某些属性会变为只读。

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

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

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

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

}

在 CreateRibbonExtensibilityObject 方法中设置属性

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

下面的示例在 Excel 2007 工作簿项目的 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 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 });
    }
}

变成只读属性的属性

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

说明：
如果安装 SP1，则可以随时设置动态菜单上控件的属性。该表不适用于这种情况。

属性	功能区控件类
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
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
Tabs	OfficeRibbon
Title	RibbonSeparator

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

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

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

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

功能区控件事件

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

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

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

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

请参见

修订记录

日期	修订历史记录	原因
2008 年 7 月	修订了有关在安装 SP1 之后设置动态菜单上控件的属性的信息。	SP1 功能更改。

通过