更新您要移轉至 .NET Framework 4 之 Office 專案中的功能區自訂

發行項
08/12/2011

如果您的專案包含使用 [功能區 (視覺化設計工具)] 專案項目建立的功能區自訂，則必須在目標 Framework 變更為 .NET Framework 4 時，對專案程式碼進行下列變更：

修改產生的功能區程式碼。
修改在執行階段執行個體化功能區控制項、處理功能區事件，或是以程式設計方式設定功能區元件位置的任何程式碼。

更新產生的功能區程式碼

如果您專案的目標 Framework 變更為 .NET Framework 4，則必須執行下列步驟，變更功能區項目產生的程式碼。您需要更新的程式碼檔，是根據程式語言和您建立專案的方式而定：

在 Visual Basic 專案或是您在 Visual Studio 2010 中建立的 Visual C# 專案中，於功能區程式碼後置檔 (YourRibbonItem.Designer.cs 或 YourRibbonItem.Designer.vb) 中執行所有步驟。若要在 Visual Basic 專案中查看程式碼後置檔案，請按一下 [方案總管] 中的 [顯示所有檔案] 按鈕。
接著將您在 Visual Studio 2008 中建立的 Visual C# 專案升級為 Visual Studio 2010，在功能區程式碼檔 (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 物件的其中一個 Helper 方法。

注意事項

在 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();
```
如需功能區控制項之 Helper 方法的完整清單，請參閱執行個體化功能區控制項。
在 Visual C# 專案中，將 InitializeComponent 方法中任何使用 EventHandler<TEventArgs> 委派的程式碼行，修改為使用特定功能區委派。

例如，假設您的檔案包含下列處理目標為 .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。

注意事項
在 Visual C# 專案中，您必須展開名為 Component Designer generated code 的區域查看 InitializeComponent 方法。

執行個體化功能區控制項

您必須修改動態執行個體化功能區控制項的任何程式碼。在目標為 .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 之專案中的功能區事件，以及與這些事件相關聯的委派。

事件	.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

功能區設計工具

共用方式為