功能区对象模型概述

更新： 2008 年 7 月

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

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

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

功能区类

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

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

功能区事件

OfficeRibbon 类包含下列三个事件：

• Load

• LoadImage

• Close

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

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

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

功能区控件类

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

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

Microsoft.Office.Tools.Ribbon 命名空间对这些类使用“Ribbon”前缀，以避免与 System.Windows.Forms 命名空间中的控件类名称发生名称冲突。

向功能区设计器中添加控件时，功能区设计器会将该控件的类声明为功能区设计器代码文件中的一个字段。

使用功能区控件类属性的常见任务

每个功能区控件类都包含可以用来执行各种任务的属性，例如为控件指定标签或者隐藏和显示控件。

在某些情况下，属性会在功能区加载之后或控件添加到动态菜单中之后变成只读属性。有关更多信息，请参见设置变成只读属性的属性。

下表描述了可以使用功能区控件属性执行的一些任务。

设置变成只读属性的属性

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

• 在 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，则可以随时设置动态菜单上控件的属性。该表不适用于这种情况。

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

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

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

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

功能区控件事件

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

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

请参见

任务

如何：开始自定义功能区

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

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

如何：自定义内置选项卡

如何：自定义 Microsoft Office 菜单

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

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

概念

在运行时访问功能区

功能区概述

功能区设计器

自定义 Outlook 功能区

参考

Microsoft.Office.Tools.Ribbon

修订记录