功能區物件模型概觀

Visual Studio Tools for Office Runtime 會公開許多您可用來取得和設定功能區控制項屬性在執行階段的強型別 (Strongly Typed) 物件模型。例如，您可以動態填入 (Populate) 功能表控制項，或是依內容顯示與隱藏控制項。您也可以將索引標籤、群組及控制項加入至功能區，不過，在功能區之前由 Office 應用程式只能載入。如需詳細資訊，請參閱設定變成唯讀的屬性。

**適用於：**本主題中的資訊適用於下列應用程式的文件層級專案和應用程式層級專案：Excel 2013 和 Excel 2010、InfoPath 2013 和 InfoPath 2010、Outlook 2013 和 Outlook 2010、PowerPoint 2013 和 PowerPoint 2010、Project 2013 和 Project 2010、Visio 2013 和 Visio 2010、Word 2013 和 Word 2010。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

此功能區物件模型主要包含功能區類別、功能區事件和功能區控制項類別。

功能區類別

當您將新的 [功能區 (視覺化設計工具)]項目加入至專案時， Visual Studio 會將 Ribbon 類別加入至專案。Ribbon 類別繼承自 RibbonBase 類別。

此類別看起來就像是從功能區程式碼檔案與功能區設計工具程式碼檔案之間分割出來的部分類別。

功能區事件

Ribbon 類別包含下列三個事件:

功能區控制項

Microsoft.Office.Tools.Ribbon 命名空間包含您在 [工具箱] 之 [Office 功能區控制項] 中看到的每個控制項的型別。

下表顯示每 Ribbon 控制項的型別。如需每個控制項的說明，請參閱功能區概觀。

Microsoft.Office.Tools.Ribbon 命名空間會針對這些型別使用 "Ribbon" 前置詞，避免與 System.Windows.Forms 命名空間中的控制項類別名稱產生名稱衝突。

當您將控制項加入至功能區設計工具時，功能區設計工具就會將該控制項的類別宣告為功能區設計工具程式碼檔案中的欄位。

使用功能區控制項屬性的一般工作

每 Ribbon 控制項包含可用來執行各種工作，例如將標籤指派給控制項或是隱藏與顯示控制項的屬性。

在某些情況下，，在功能區載入或在控制項之後加入至動態功能表之後，屬性會變成唯讀。如需詳細資訊，請參閱設定變成唯讀的屬性。

下表說明使用 Ribbon 控制項屬性，您可執行的工作。

設定變成唯讀的屬性

某些屬性只能在功能區載入之前只設定。這些屬性可以在下列三個位置中進行設定：

• 在 Visual Studio 的 [屬性] 視窗。

• 在 Ribbon 類別的建構函式。

• 在專案之 ThisAddin、ThisWorkbook 或 ThisDocument 類別的 CreateRibbonExtensibilityObject 方法中。

動態功能表會提供一些例外狀況 (Exception)。您可以建立新的控制項，設定其屬性，然後將它們加入至動態功能表會在執行階段，在這種情況下，包含功能表的功能區之後載入。

您隨時可以對加入至動態功能表中的控制項設定屬性。

如需詳細資訊，請參閱變成唯讀的屬性。

在功能區的建構函式中設定屬性

您可以設定 Ribbon 控制項屬性之 Ribbon 類別之建構函式的。此程式碼必須位於 InitializeComponent 方法呼叫的後面。下列範例會在目前時間為太平洋時間 17:00 (UTC-8) (含) 之後，將新按鈕加入至群組中。

加入下列程式碼。

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

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 C# 專案從 Visual Studio SP1 升級，建構函式會出現在功能區程式碼檔案。

在 Visual Basic 專案，或 Visual C# 專案中 Visual Studio 2012建立，建構函式會出現在功能區設計工具程式碼檔案。此檔案的名稱為 <您的功能區項目>.Designer.cs 或 <您的功能區項目>.Designer.vb。若要在 Visual Basic 專案中查看此檔案，您必須先按一下 [方案總管] 中的 [顯示所有檔案] 按鈕。

設定 CreateRibbonExtensibilityObject 方法中的屬性

當您覆寫 ThisAddin、 ThisWorkbook或專案時， ThisDocument 類別的 CreateRibbonExtensibilityObject 方法可以設定 Ribbon 控制項的屬性。如需 CreateRibbonExtensibilityObject 方法的詳細資訊，請參閱功能區概觀。

下列範例會在 Excel 活頁簿專案中的 ThisWorkbook 類別的 CreateRibbonExtensibilityObject 方法的功能區屬性。

加入下列程式碼。

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As 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
        Dim tempRibbon As 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})
    End If
End Function

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

變成唯讀的屬性

下表說明只能在載入功能區之前設定的屬性。

注意事項
您隨時可以設定動態功能表上之控制項的屬性。下表不適用於這種情況。

針對出現在 Outlook 偵測器中的功能區設定其屬性

功能區的新建立執行個體，每次使用者開啟功能區上出現的偵測器。不過，，只有在功能區上的第一個執行個體建立之前，您可以將上述表格中所列的屬性。在第一個執行個體建立之後，這些屬性會變成唯讀，因為第一個執行個體定義了使用 Outlook 載入功能區的 XML 檔案。

如果您有設定這些屬性中的任一對不同值的條件邏輯，當功能區的其他執行個體之後，這個程式碼不會有作用。

注意事項
確定 [Name] 屬性為您加入至 Outlook 功能區的每個控制項設定。如果您將控制項加入至 Outlook 功能區要在執行階段，您必須設定這個屬性會以您的程式碼。如果您將控制項加入至 Outlook 功能區在設計階段， Name 屬性會自動設定為。

功能區控制項事件

每個控制項類別都包含一個或多個事件。下表將說明這些事件。

這些事件的事件處理常式具有下列兩個參數。

請參閱

工作

HOW TO：開始自訂功能區

逐步解說：使用功能區設計工具建立自訂的索引標籤

逐步解說：在執行階段更新功能區中的控制項

HOW TO：自訂內建索引標籤

HOW TO：將控制項加入至 Backstage 檢視

HOW TO：將功能區設計工具的功能區匯出到功能區 XML

HOW TO：顯示增益集使用者介面錯誤

參考

Microsoft.Office.Tools.Ribbon

概念

在執行階段存取功能區

功能區設計工具

自訂 Outlook 的功能區

其他資源

功能區概觀