Ribbon 物件模型概觀

Visual Studio Tools for Office 執行階段會公開強型別物件模型，可用來在執行階段取得和設定功能區控制項的屬性。例如，您可以動態填入功能表控制項，或根據內容顯示和隱藏控制項。您也可以將索引標籤、群組和控制項新增至功能區，但只能在 Office 應用程式載入功能區之前。如需詳細資訊，請參閱設定變成唯讀的屬性。

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

此功能區物件模型主要由功能區類別、功能區事件和功能區控制項類別組成。

Ribbon 類別

當您將新的 功能區（視覺化設計工具） 專案新增至專案時，Visual Studio 會將 功能區 類別新增至您的專案。 Ribbon 類別繼承自RibbonBase類別。

這個類別被表示為一個部分類別，在功能區程式碼檔案和功能區設計工具程式碼檔案之間分割。

功能區事件

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

Event	Description
Load	當 Office 應用程式載入功能區自訂時引發。 Load事件處理常式會自動新增至功能區程式碼檔案。使用此事件處理常式，在功能區載入時執行自訂程式碼。
LoadImage	可讓您在功能區載入時將影像緩存至功能區自訂中。如果您撰寫程式碼來快取此事件處理常式中的功能區影像，則可以獲得輕微的效能提升。如需詳細資訊，請參閱LoadImage。
Close	功能區實例關閉時觸發。

功能區控制項

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

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

控制項名稱	類別名稱
箱子	RibbonBox
按鈕	RibbonButton
按鈕群組	RibbonButtonGroup
核取方塊	RibbonCheckBox
組合盒	RibbonComboBox
下拉式選單	RibbonDropDown
編輯框	RibbonEditBox
資源庫	RibbonGallery
Group	RibbonGroup
標籤	RibbonLabel
選單	RibbonMenu
分隔符	RibbonSeparator
SplitButton （分割按鈕）	RibbonSplitButton
Tab鍵	RibbonTab
ToggleButton （切換按鈕）	RibbonToggleButton

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

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

使用功能區控制項屬性的常見工作

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

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

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

針對這項工作：	這樣做：
隱藏或顯示控制項。	使用 Visible 屬性。
啟用或停用控制項。	使用 Enabled 屬性。
設定控制項的大小。	使用 ControlSize 屬性。
取得控制項上顯示的影像。	使用 Image 屬性。
變更控制項的標籤。	使用 Label 屬性。
將使用者定義的資料新增至控制項。	使用 Tag 屬性。
取得 RibbonBox 內的項目、RibbonDropDown、RibbonGallery 或 RibbonSplitButton 控制。	使用 Items 屬性。
將項目新增至 RibbonComboBox、RibbonDropDown 或 RibbonGallery 控制項。	使用 Items 屬性。
將控制項新增至RibbonMenu。	使用 Items 屬性。若要在功能區載入到 Office 應用程式中之後，將控制項新增至 RibbonMenu，您必須在功能區載入之前先將 Dynamic 設為 true。如需詳細資訊，請參閱設定變成唯讀的屬性。
取得 RibbonComboBox 中的選定項目 RibbonDropDown 或 RibbonGallery。	使用 SelectedItem 屬性。對於 RibbonComboBox，請使用屬性 Text 。
在RibbonTab上獲取群組。	使用屬性 Groups 。
指定在RibbonGallery中出現的列和行的數目。	使用 RowCount 和 ColumnCount 屬性。

設定變成唯讀的屬性

某些性質只能在功能區載入之前設定。有三個位置可以設定這些屬性：

在 [Visual Studio 屬性] 視窗中。
在 Ribbon 類別的建構函式中。
在專案中的CreateRibbonExtensibilityObject、ThisAddin或ThisWorkbook類別的方法ThisDocument中。

動態功能表提供一些例外狀況。您可以建立新的控制項、設定其屬性，然後在執行階段將它們新增至動態功能表，即使在載入包含功能表的功能區之後也是如此。

您可以隨時設定新增至動態功能表的控制項屬性。

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

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

您可以在 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);
    }
}

<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

在您從 Visual Studio 2008 升級的 Visual C# 專案中，建構函式會出現在功能區程式碼檔案中。

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

在 CreateRibbonExtensibilityObject 方法中設定屬性

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

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

加入下列程式碼。

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

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

變成唯讀的屬性

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

備註

您可以隨時在動態功能表上設定控制項的屬性。此表不適用於此情況。

房產	功能區控制類別
盒子樣式	RibbonBox
按鈕類型	RibbonSplitButton
列數	RibbonGallery
控制標識碼	RibbonTab
對話啟動器	RibbonGroup
動態	RibbonMenu
全球	OfficeRibbon
群組	RibbonTab
影像名稱	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
項目大小	RibbonMenu RibbonSplitButton
最大長度	RibbonComboBox RibbonEditBox
名稱	RibbonComponent
職位	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
功能區類型	OfficeRibbon
資料列計數	RibbonGallery
顯示項目圖像	RibbonComboBox RibbonDropDown RibbonGallery
顯示項目標籤	RibbonDropDown RibbonGallery
顯示項目選擇	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
從頭開始	OfficeRibbon
索引標籤	OfficeRibbon
標題	RibbonSeparator

設定 Outlook 檢視器中顯示的功能區屬性

每當使用者開啟顯示功能區的「檢視器」時，會創建一個功能區的新實例。不過，您只能在建立功能區的第一個實例之前設定上表中列出的屬性。建立第一個實例之後，這些屬性會變成唯讀，因為第一個實例會定義 Outlook 用來載入功能區的 XML 檔案。

如果您有條件式邏輯，在建立功能區的其他實例時，將這些屬性中的任何一個設定為不同的值，則此程式碼將不會有任何作用。

備註

請確定已針對您新增至 Outlook 功能區的每個控制項設定 [名稱 ] 屬性。如果您在執行階段將控制項新增至 Outlook 功能區，則必須在程式碼中設定此屬性。如果您在設計階段將控制項新增至 Outlook 功能區，則會自動設定 [名稱] 屬性。

功能區控制項事件

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

Event	Description
Click	按一下控制項時發生。
文字變更	當編輯框或組合框的文字變更時發生。
項目加載中	當 Office 請求控制項的 Items 集合時發生。 Office 會快取 Items 集合，直到您的程式碼變更控制項的屬性，或您呼叫 InvalidateControl 方法為止。
按鈕點擊	當按下 RibbonGallery 或 RibbonDropDown 中的按鈕時，會發生事件。
SelectionChanged \(英文\)	當 RibbonDropDown 或 RibbonGallery 中的選取範圍變更時發生。
對話方塊啟動器點擊	按一下群組右下角的對話方塊啟動器圖示時發生。

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

參數	Description
寄件者	代表引發事件的Object控制項。
e	一個RibbonControlEventArgs包含IRibbonControl。使用此控制項來存取 Visual Studio Tools for Office 執行階段所提供的功能區物件模型中無法使用的任何屬性。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-12