通过

功能区对象模型概述

Visual Studio Tools for Office 运行时公开了一个严格类型化的对象模型，可用于在运行时获取和设置功能区控件的属性。 例如，可以动态填充菜单控件，或根据上下文显示和隐藏控件。 还可以将选项卡、组和控件添加到功能区，但仅在 Office 应用程序加载功能区之前。 信息请参考 设置成为只读的属性。

适用于： 本主题中的信息适用于以下应用程序的文档级项目和 VSTO 外接程序项目：Excel、InfoPath 2013 和 InfoPath 2010、Outlook、PowerPoint、Project、Visio、Word。 有关详细信息，请参阅 Office 应用程序和项目类型提供的功能。

此功能区对象模型主要包括 功能区类、 功能区事件和 功能区控件类。

功能区类

向项目添加新的功能区（Visual Designer）项时，Visual Studio 会将功能区类添加到项目中。 Ribbon类继承自RibbonBase类。

此类是一个在功能区代码文件和功能区设计器代码文件之间拆分的分部类。

功能区事件

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

事件 / 活动 Description
Load 当 Office 应用程序加载功能区自定义设置时引发。 Load事件处理程序会自动添加到功能区代码文件中。 使用此事件处理程序在功能区加载时运行自定义代码。
LoadImage 使你可以在功能区加载时缓存功能区自定义中的映像。 如果编写代码来缓存此事件处理程序中的功能区映像，则可以获得轻微的性能提升。 有关详细信息，请参阅 LoadImage。
Close 当 Ribbon 实例关闭时触发。

功能区控件

命名空间Microsoft.Office.Tools.Ribbon包含工具箱的 Office 功能区控件组中看到的每个控件的类型。

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

控件名称 类名
箱 RibbonBox
按钮 RibbonButton
ButtonGroup RibbonButtonGroup
CheckBox RibbonCheckBox
ComboBox RibbonComboBox
DropDown RibbonDropDown
EditBox RibbonEditBox
库 RibbonGallery
分组 RibbonGroup
标签 RibbonLabel
菜单 RibbonMenu
分隔符 RibbonSeparator
SplitButton （拆分按钮） RibbonSplitButton
选项卡 RibbonTab
ToggleButton （切换按钮） RibbonToggleButton

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

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

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

每个 Ribbon 控件都包含可用于执行各种任务的属性，例如向控件分配标签或隐藏和显示控件。

在某些情况下，当功能区加载后或在控件添加到动态菜单后，属性变为只读。 有关详细信息，请参阅设定为只读的属性。

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

对于此任务： 请执行以下操作：
隐藏或显示控件。 使用 Visible 属性。
启用或禁用控件。 使用 Enabled 属性。
设置控件的大小。 使用 ControlSize 属性。
获取显示在控件上的图像。 使用 Image 属性。
更改控件的标签。 使用 Label 属性。
将用户定义的数据添加到控件。 使用 Tag 属性。
获取RibbonBox、RibbonDropDown或RibbonGallery中的项目

RibbonSplitButton 控制。		 使用 Items 属性。
向RibbonComboBox、RibbonDropDown或RibbonGallery控件添加项。 使用 Items 属性。
将控件添加到RibbonMenu。 使用 Items 属性。

在功能区加载到 Office 应用程序后要添加控件，必须在功能区加载到 Office 应用程序之前将Dynamic属性设置为true。 信息请参考 设置成为只读的属性。
获取所选项的 RibbonComboBox

RibbonDropDown 或 RibbonGallery 中的一项。		 使用 SelectedItem 属性。 对于RibbonComboBox，使用Text属性。
在RibbonTab上获取组。 使用属性 Groups 。
指定在一个 RibbonGallery中出现的行数和列数。 使用RowCount和ColumnCount属性。

将属性设置为只读

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

  • 在 Visual Studio 属性 窗口中。

  • 在 Ribbon 类的构造函数中。

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

    动态菜单提供一些例外。 可以创建新控件、设置其属性，然后在运行时将其添加到动态菜单，即使在加载包含菜单的功能区之后也是如此。

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

    有关详细信息，请参阅 变为只读的属性。

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

可以在Ribbon类的构造函数中设置Ribbon的属性。 此代码必须出现在对方法的调用 InitializeComponent 之后。 以下示例在当前时间为太平洋时间（UTC-8）下午5点或更晚时，向组添加新按钮。

添加以下代码。

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

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

在 CreateRibbonExtensibilityObject 方法中设置属性

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

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

添加以下代码。

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
全球 OfficeRibbon
组 RibbonTab
ImageName RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton
项目大小 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 检查器中显示的功能区的属性

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

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

注释

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

功能区控件事件

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

事件 / 活动 Description
Click 单击控件时发生。
TextChanged（文本更改） 当编辑框或组合框的文本发生更改时触发。
项目加载 当 Office 请求控件的 Items 集合时发生。 Office 会缓存 Items 集合，直到代码更改控件的属性，或调用 InvalidateControl 方法。
ButtonClick 在RibbonGallery或RibbonDropDown中单击某个按钮时发生。
选择更改 在RibbonDropDown或RibbonGallery中选择更改时发生。
DialogLauncherClick 当单击群组右下角的对话框启动器图标时，事件发生。

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

参数 Description
寄件人 一个 Object 表示引发事件的控件。
e 包含IRibbonControl的RibbonControlEventArgs。 使用此控件访问在 Visual Studio Tools for Office 运行时提供的功能区对象模型中无法获得的任何属性。

相关内容