通过

功能区对象模型概述

  • 项目

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

适用于： 本主题中的信息适用于以下应用程序的文档级项目和 VSTO 外接程序项目： Excel;InfoPath 2013 和 InfoPath 2010;前景;幻灯片;项目;Visio;词。 有关详细信息，请参阅办公室应用程序和项目类型提供的功能。

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

功能区类

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

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

功能区事件

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

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

功能区控件

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

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

控件名称 类名
Box RibbonBox
按钮 RibbonButton
ButtonGroup RibbonButtonGroup
CheckBox RibbonCheckBox
ComboBox RibbonComboBox
DropDown RibbonDropDown
EditBox RibbonEditBox
库 RibbonGallery
组 RibbonGroup
标签 RibbonLabel
菜单 RibbonMenu
分隔符 RibbonSeparator
SplitButton RibbonSplitButton
Tab RibbonTab
ToggleButton RibbonToggleButton

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

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

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

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

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

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

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

RibbonSplitButton 控制。		 使用 Items 属性。
向控件RibbonComboBoxRibbonDropDownRibbonGallery或控件添加项。 使用 Items 属性。
将控件添加到 .RibbonMenu 使用 Items 属性。

要将控件RibbonMenu添加到功能区加载到办公室应用程序中之后，必须先将Dynamic属性设置为 true，然后才能将功能区加载到办公室应用程序中。 有关信息，请参阅 “设置变为只读”的属性。
获取所选项的 RibbonComboBox、

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

设置变为只读的属性

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

  • 在 Visual Studio 属性 窗口中。

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

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

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

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

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

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

可以在功能区类的构造函数中设置控件的属性Ribbon。 此代码必须出现在对方法的调用 InitializeComponent 之后。 以下示例在当前时间为 17：00 太平洋时间（UTC-8）或更高版本时向组添加新按钮。

添加以下代码。

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或类时CreateRibbonExtensibilityObject，可以设置控件的属性Ribbon。ThisDocumentThisWorkbook 有关该方法的详细信息 CreateRibbonExtensibilityObject ，请参阅 功能区概述。

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

添加以下代码。

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

变为只读的属性

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

注意

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

properties 功能区控件类
BoxStyle RibbonBox
ButtonType RibbonSplitButton
ColumnCount RibbonGallery
ControlId RibbonTab
DialogLauncher RibbonGroup
动态 RibbonMenu
全局 OfficeRibbon
组 RibbonTab
ImageName RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton
ItemSize RibbonMenu

RibbonSplitButton
MaxLength RibbonComboBox

RibbonEditBox
Name 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 属性。

功能区控件事件

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

事件 说明
单击 单击控件时发生。
TextChanged 更改编辑框或组合框的文本时发生。
ItemsLoading 当办公室请求控件的 Items 集合时发生。 办公室缓存 Items 集合，直到代码更改控件的属性或调用InvalidateControl该方法。
ButtonClick 在单击或RibbonDropDown单击某个按钮RibbonGallery时发生。
SelectionChanged 在所选内容RibbonDropDownRibbonGallery或更改时发生。
DialogLauncherClick 单击组右下角的对话框启动器图标时发生。

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

参数 说明
sender 一个 Object 表示引发事件的控件。
e RibbonControlEventArgs一个IRibbonControl包含 . 使用此控件访问 Visual Studio Tools for 办公室 运行时提供的功能区对象模型中不可用的任何属性。

相关内容