更新迁移到 .NET Framework 4 的 Office 项目中的功能区自定义项

项目
08/12/2011

如果项目包含通过使用**“功能区(可视化设计器)”**项目项创建的功能区自定义项，则当目标框架更改为 .NET Framework 4 时，必须对项目代码进行以下更改：

修改生成的功能区代码。
修改在运行时实例化功能区控件、处理功能区事件或以编程方式设置功能区组件位置的任何代码。

更新生成的功能区代码

如果项目的目标框架已更改为 .NET Framework 4，则必须通过执行以下步骤来更改功能区项的生成代码。需要更新的代码文件取决于编程语言和项目创建方式：

在 Visual Basic 项目中，或在 Visual Studio 2010 中创建的 Visual C# 项目中，执行功能区代码隐藏文件（YourRibbonItem.Designer.cs 或 YourRibbonItem.Designer.vb）中的所有步骤。若要查看 Visual Basic 项目中的代码隐藏文件，请单击**“解决方案资源管理器”中的“显示所有文件”**按钮。
在 Visual Studio 2008 中创建、然后升级至 Visual Studio 2010 的 Visual C# 项目中，执行功能区代码文件（YourRibbonItem.cs 或 YourRibbonItem.vb）中的前两个步骤，然后执行功能区代码隐藏文件中的其余步骤。

更改生成的功能区代码

修改功能区类的声明，以便它从 Microsoft.Office.Tools.Ribbon.RibbonBase 而非 Microsoft.Office.Tools.Ribbon.OfficeRibbon 中派生。
修改功能区类的构造函数，如下所示。如果已将任何自己的代码添加到构造函数，则不要更改代码。在 Visual Basic 项目中，仅修改无参数构造函数。忽略其他构造函数。

下面的代码示例演示面向 .NET Framework 3.5 的项目中功能区类的默认构造函数。
```
Public Sub New()
    MyBase.New()
    InitializeComponent()
End Sub
```
```
public Ribbon1()
{
    InitializeComponent();
}
```
下面的代码示例演示面向 .NET Framework 4 的项目中功能区类的默认构造函数。
```
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())
    InitializeComponent()
End Sub
```
```
public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
}
```
在 InitializeComponent 方法中，修改任何用于构造功能区控件的代码，以便该代码改用 RibbonFactory 对象的帮助器方法之一。

提示

在 Visual C# 项目中，必须展开名为“Component Designer generated code”的区域才能查看 InitializeComponent 方法。

例如，假设文件包含下面一行用来实例化面向 .NET Framework 3.5 的项目中一个名为 button1 的 RibbonButton 的代码。
```
Me.button1 = New Microsoft.Office.Tools.Ribbon.RibbonButton()
```
```
this.button1 = new Microsoft.Office.Tools.Ribbon.RibbonButton();
```
在面向 .NET Framework 4 的项目中，必须改用以下代码。
```
Me.button1 = Me.Factory.CreateRibbonButton()
```
```
this.button1 = this.Factory.CreateRibbonButton();
```
有关功能区控件的帮助器方法的完整列表，请参见实例化功能区控件。
在 Visual C# 项目中，修改使用 EventHandler<TEventArgs> 委托的 InitializeComponent 方法中的任何代码行，以改用特定的功能区委托。

例如，假设文件包含下面一行在面向 .NET Framework 3.5 的项目中处理 RibbonButton.Click 事件的代码。
```
this.button1.Click += new System.EventHandler<Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>(
    this.button1_Click);
```
在面向 .NET Framework 4 的项目中，必须改用以下代码。
```
this.button1.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(
    this.button1_Click);
```
有关完整的功能区委托列表，请参见处理功能区事件。
在 Visual Basic 项目中，找到文件末尾的 ThisRibbonCollection 类。修改此类的声明，以便它不再从 Microsoft.Office.Tools.Ribbon.RibbonReadOnlyCollection 继承。

实例化功能区控件

您必须修改任何用来动态实例化功能区控件的代码。在面向 .NET Framework 3.5 的项目中，功能区控件是在某些情况下可以直接进行实例化的类。在面向 .NET Framework 4 的项目中，这些控件是不能直接实例化的接口。您必须通过使用由 RibbonFactory 对象提供的方法来创建控件。

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

使用功能区类的 Factory 属性。请通过功能区类中的代码使用此方法。
使用 Globals.Factory.GetRibbonFactory 方法。请通过功能区类之外的代码使用此方法。有关 Globals 类的更多信息，请参见对 Office 项目中对象的全局访问。

下面的代码示例演示如何在面向 .NET Framework 4 的项目中的功能区类中创建 RibbonButton。

Dim button As Microsoft.Office.Tools.Ribbon.RibbonButton =
    Me.Factory.CreateRibbonButton()

Microsoft.Office.Tools.Ribbon.RibbonButton button =
    this.Factory.CreateRibbonButton();

下表列出了在面向 .NET Framework 4 的项目中可以通过编程方式创建的控件和用于创建控件的方法。

控件	要在 .NET Framework 4 项目中使用的 RibbonFactory 方法
RibbonButton	CreateRibbonButton
RibbonButtonGroup	CreateRibbonButtonGroup
RibbonCheckBox	CreateRibbonCheckBox
RibbonComboBox	CreateRibbonComboBox
RibbonDialogLauncher	CreateRibbonDialogLauncher
RibbonDropDown:	CreateRibbonDropDown
RibbonDropDownItem	CreateRibbonDropDownItem
RibbonEditBox	CreateRibbonEditBox
RibbonGallery	CreateRibbonGallery
RibbonGroup	CreateRibbonGroup
RibbonLabel	CreateRibbonLabel
RibbonManager	CreateRibbonManager
RibbonMenu	CreateRibbonMenu
RibbonSeparator	CreateRibbonSeparator
RibbonSplitButton	CreateRibbonSplitButton
RibbonTab	CreateRibbonTab
RibbonToggleButton	CreateRibbonToggleButton

处理功能区事件

必须修改所有处理功能区控件事件的代码。在面向 .NET Framework 3.5 的项目中，这些事件由泛型 EventHandler<TEventArgs> 委托处理。在面向 .NET Framework 4 的项目中，这些事件现在由其他委托处理。

下表列出了面向 .NET Framework 4 的项目中的功能区事件以及与这些事件关联的委托。

Event	要在 .NET Framework 4 项目中使用的委托
生成的功能区类中的 LoadImage 事件	RibbonLoadImageEventHandler
Load	RibbonUIEventHandler
RibbonButton.Click RibbonCheckBox.Click RibbonComboBox.ItemsLoading RibbonComboBox.TextChanged RibbonDropDown.ButtonClick RibbonDropDown.ItemsLoading RibbonDropDown.SelectionChanged RibbonEditBox.TextChanged RibbonGallery.ButtonClick RibbonGallery.Click RibbonGallery.ItemsLoading RibbonGroup.DialogLauncherClick RibbonMenu.ItemsLoading RibbonSplitButton.Click RibbonToggleButton.Click	RibbonControlEventHandler

生成的功能区类中的 LoadImage 事件

RibbonLoadImageEventHandler

RibbonComboBox.ItemsLoading

RibbonComboBox.TextChanged

RibbonDropDown.ButtonClick

RibbonDropDown.ItemsLoading

RibbonDropDown.SelectionChanged

RibbonEditBox.TextChanged

RibbonGallery.ButtonClick

RibbonGallery.Click

RibbonGallery.ItemsLoading

RibbonGroup.DialogLauncherClick

RibbonMenu.ItemsLoading

RibbonSplitButton.Click

RibbonToggleButton.Click

RibbonControlEventHandler

以编程方式设置功能区组件的位置

您必须修改所有设置功能区组、选项卡或控件的位置的代码。在面向 .NET Framework 3.5 的项目中，可以使用静态 Microsoft.Office.Tools.Ribbon.RibbonPosition 类的 AfterOfficeId 和 BeforeOfficeId 方法来分配组、选项卡或控件的 Position 属性。在面向 .NET Framework 4 的项目中，必须通过使用由 RibbonFactory 对象提供的 RibbonPosition 属性访问这些方法。

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

使用功能区类的 Factory 属性。请通过功能区类中的代码使用此方法。
使用 Globals.Factory.GetRibbonFactory 方法。请通过功能区类之外的代码使用此方法。有关 Globals 类的更多信息，请参见对 Office 项目中对象的全局访问。

下面的代码示例演示如何在面向 .NET Framework 3.5 的项目中设置功能区类中的选项卡的 Position 属性。

Me.tab1.Position = RibbonPosition.AfterOfficeId("TabHome")

this.tab1.Position = RibbonPosition.AfterOfficeId("TabHome");

下面的代码示例演示面向 .NET Framework 4 的项目中的相同任务。

Me.tab1.Position = Me.Factory.RibbonPosition.AfterOfficeId("TabHome")

this.tab1.Position = this.Factory.RibbonPosition.AfterOfficeId("TabHome");

请参见

概念

将 Office 解决方案迁移到 .NET Framework 4

功能区设计器

通过