RibbonButton 接口

项目
05/20/2013

表示自定义功能区上的按钮。

命名空间： Microsoft.Office.Tools.Ribbon
程序集： Microsoft.Office.Tools.Common（在 Microsoft.Office.Tools.Common.dll 中）

语法

声明
<GuidAttribute("b57e6217-33f2-46bf-9625-c313526de60c")> _
Public Interface RibbonButton _
    Inherits RibbonControl, RibbonComponent, IComponent, IDisposable

[GuidAttribute("b57e6217-33f2-46bf-9625-c313526de60c")]
public interface RibbonButton : RibbonControl, 
    RibbonComponent, IComponent, IDisposable

RibbonButton 类型公开以下成员。

属性

	名称	说明
	ControlSize	获取或设置按钮的大小。
	Description	获取或设置当菜单的 ItemSize 属性设置为 Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge 时，出现在菜单中的此按钮上的文本。
	Enabled	获取或设置一个值，该值指示是否启用此 RibbonControl。（继承自 RibbonControl。）
	Id	获取一个字符串，Microsoft Office 使用它来标识此 RibbonControl 对象。（继承自 RibbonControl。）
	Image	获取或设置在按钮上显示的图像。
	ImageName	获取或设置用于在 LoadImage 事件处理程序中标识按钮的名称。
	KeyTip	获取或设置该按钮的键盘快捷键。
	Label	获取或设置显示在按钮上的文本。
	Name	获取或设置此 RibbonComponent 的名称。（继承自 RibbonComponent。）
	OfficeImageId	获取或设置要在按钮上显示的图像（如果要使用内置 Microsoft Office 图标）。
	Parent	获取一个表示此 RibbonComponent 的父级的 RibbonComponent。（继承自 RibbonComponent。）
	Position	获取或设置按钮的位置（如果按钮在 Microsoft Office 菜单上）。
	Ribbon	获取包含控件层次结构的顶级 Ribbon 对象。（继承自 RibbonComponent。）
	RibbonUI	基础结构。获取 Microsoft Office 应用程序提供给功能区扩展性代码的 IRibbonUI 实例。（继承自 RibbonComponent。）
	ScreenTip	获取或设置当用户将指针移到按钮上时显示的工具提示文本。
	ShowImage	获取或设置一个值，该值指示与按钮关联的图像是否可见。
	ShowLabel	获取或设置一个值，该值指示此按钮的标签是否可见。
	Site	获取或设置与 IComponent 关联的 ISite。（继承自 IComponent。）
	SuperTip	获取或设置当用户将指针移到按钮上时显示的多行提示文本。
	Tag	获取或设置与此 RibbonComponent 关联的特定于应用程序的数据。（继承自 RibbonComponent。）
	Visible	获取或设置一个值，该值指示此 RibbonControl 是否可见。（继承自 RibbonControl。）

页首

方法

	名称	说明
	Dispose	执行与释放或重置非托管资源相关的应用程序定义的任务。（继承自 IDisposable。）
	PerformDynamicLayout	如果 RibbonComponent 有一个动态父级（如动态菜单）且布局未挂起，则调用父控件的 Microsoft.Office.Core.IRibbonUI.InvalidateControl 方法。（继承自 RibbonComponent。）
	PerformLayout	如果 RibbonComponent 有父级，并且布局未挂起，则调用 Microsoft.Office.Core.IRibbonUI.InvalidateControl。（继承自 RibbonComponent。）
	ResumeLayout()	取消 SuspendLayout 方法的效果。（继承自 RibbonComponent。）
	ResumeLayout(Boolean)	取消 SuspendLayout 方法的效果。（继承自 RibbonComponent。）
	SuspendLayout	阻止 Microsoft Office 应用程序刷新功能区上的控件的状态。（继承自 RibbonComponent。）

页首

事件

	名称	说明
	Click	在用户单击按钮时发生。
	Disposed	表示处理组件的 Disposed 事件的方法。（继承自 IComponent。）

页首

备注

在将**“按钮”控件从“工具箱”的“Office 功能区控件”**选项卡拖入功能区设计器时，Visual Studio 将创建实现 RibbonButton 接口的类的实例。

您还可以在运行时创建此控件的实例并将它添加到动态菜单。如果将菜单的 Dynamic 属性设置为 true，则该菜单是动态菜单。

此控件的某些属性只能在运行时设置，并且只能在功能区加载到 Office 应用程序之前，或者该控件添加到动态菜单之前进行设置。有关如何设置这些属性的信息，请参见功能区对象模型概述。

在运行时，可以使用 RibbonFactory 对象的 CreateRibbonButton 方法创建 RibbonButton。

有两种方法可访问 RibbonFactory 对象：

使用功能区类的 Factory 属性。请通过功能区类中的代码使用此方法。
使用 Globals.Factory.GetRibbonFactory 方法。请通过功能区类之外的代码使用此方法。

常规任务

下表列出了对常规任务有用的成员。

任务	成员
在运行时，将按钮添加到其 Dynamic 属性设置为 true 的菜单。	使用 CreateRibbonButton 创建实现 RibbonButton 接口的类的实例 RibbonFactory 类的方法。有关更多信息，请参见对 Office 项目中对象的全局访问。将此实例添加到菜单的 Items 集合。
更改按钮的大小。	将 ControlSize 设置为所需的值。例如，对于大按钮，将其设置为 Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge。
在按钮上显示图像。	有三种显示图像的方式：使用 Image 属性。此属性提供了最大控制。将 OfficeImageId 设置为您要将其显示为按钮图标的内置 Microsoft Office 图像的 ID。可将 ImageName 属性与 LoadImage 事件一起使用。此属性会带来一些性能好处。
禁用或隐藏按钮。	若要禁用按钮，请将 Enabled 设置为 false。若要隐藏按钮，请将 Visible 设置为 false。
在用户单击按钮时运行代码。	将代码添加到 Click 事件处理程序。

备注

此接口由 Visual Studio Tools for Office Runtime 实现。不应在代码中实现此接口。有关更多信息，请参见 Visual Studio Tools for Office Runtime 概述。

用法

本文档介绍面向 .NET Framework 4 和 .NET Framework 4.5 的 Office 项目中所用此类型的版本。在面向 .NET Framework 3.5 的项目中，此类型可能具有不同的成员，因此本文档为此类型提供的代码示例可能并不适用。有关面向 .NET Framework 3.5 的项目中的此类型的文档，请参见 Visual Studio 2008 文档中的以下参考部分：https://go.microsoft.com/fwlink/?LinkId=160658。

示例

下面的示例创建一个新按钮，设置该按钮的各种属性，然后将该按钮添加到菜单中。若要运行此代码示例，必须先执行下列步骤：

将**“功能区(可视化设计器)”**项添加到使用 Visual Studio 中的 Office 开发工具创建的项目中。
在自定义选项卡中添加一个组。
将一个菜单添加到该组。
将该菜单的**“Dynamic”**属性设置为 true。
将该菜单的**“ItemSize”属性设置为“RibbonControlSizeLarge”**。

Private Sub AddButtonsToMenu()
    Dim tempButton = Me.Factory.CreateRibbonButton()
    tempButton.Label = "Button 1"
    tempButton.ControlSize = _
        Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge
    tempButton.Description = "My Ribbon Button"
    tempButton.ShowImage = True
    tempButton.ShowImage = True
    tempButton.Image = My.Resources.Image1
    tempButton.Image = My.Resources.Image2
    tempButton.KeyTip = "A1"
    menu1.Items.Add(tempButton)
End Sub

private void AddButtonsToMenu()
{
    RibbonButton tempButton = this.Factory.CreateRibbonButton();
    tempButton.Label = "Button 1";
    tempButton.ControlSize =
        Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge;
    tempButton.Description = "My Ribbon Button";
    tempButton.ShowImage = true;
    tempButton.ShowImage = true;
    tempButton.Image = Properties.Resources.Image1;
    tempButton.Image = Properties.Resources.Image2;
    tempButton.KeyTip = "A1";
    menu1.Items.Add(tempButton);

}