功能區物件模型概觀

發行項
01/13/2024

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

適用於： 本主題中的資訊適用於下列應用程式的檔層級專案和 VSTO 載入宏專案：Excel;InfoPath 2013 和 InfoPath 2010;前景;幻燈片;專案;Visio;詞。如需詳細資訊，請參閱 Office 應用程式 lication 和項目類型所提供的功能。

這個功能區物件模型主要包含功能區類別、功能區事件和功能區控件類別。

功能區類別

當您將新的功能區（Visual Designer） 專案新增至專案時，Visual Studio 會將功能區類別新增至專案。 Ribbon 類別繼承自類別RibbonBase。

這個類別會顯示為在功能區程式代碼檔案與功能區設計工具程式代碼檔之間分割的部分類別。

功能區事件

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

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

功能區控制項

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

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

控制項名稱	類別名稱
Box	RibbonBox
按鈕	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
拉	RibbonDropDown
EditBox	RibbonEditBox
資源庫	RibbonGallery
群組	RibbonGroup
標籤	RibbonLabel
功能表	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
定位字元	RibbonTab
ToggleButton	RibbonToggleButton

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

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

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

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

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

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

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

設定變成唯讀的屬性

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

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

動態功能表提供一些例外狀況。您可以建立新的控件、設定其屬性，然後在運行時間將它們新增至動態功能表，即使載入包含功能區也一定。

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

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

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

您可以在功能區類別的建構函式中設定控制件的屬性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 方法中設定屬性

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

下列範例會在 Excel 活頁簿項目的類別方法ThisWorkbook中CreateRibbonExtensibilityObject設定 Ribbon 屬性。

加入下列程式碼。

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

變成唯讀的屬性

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

注意

您可以隨時在動態功能表上設定控制元件的屬性。在此情況下，此數據表不適用。

屬性	功能區控件類別
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
動態	RibbonMenu
全球	OfficeRibbon
群組	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
名稱	RibbonComponent
位置	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
RowCount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
索引標籤	OfficeRibbon
標題	RibbonSeparator

設定 Outlook 偵測器中顯示的功能區屬性

每次用戶開啟功能區出現的 Inspector 時，都會建立功能區的新實例。不過，您只能在建立功能區的第一個實例之前，設定上表中所列的屬性。建立第一個實例之後，這些屬性會變成只讀，因為第一個實例會定義 Outlook 用來載入功能區的 XML 檔案。

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

注意

請確定 您已針對您新增至 Outlook 功能區的每個控件設定 Name 屬性。如果您在運行時間將控件新增至 Outlook 功能區，則必須在程式代碼中設定此屬性。如果您在設計時間將控件新增至 Outlook 功能區，則會自動設定 Name 屬性。

功能區控件事件

每個控件類別都包含一或多個事件。下表描述這些事件。

事件	描述
按一下	發生於單擊控件時。
TextChanged	發生於編輯框或下拉式方塊的文字變更時。
ItemsLoading	發生於 Office 要求控制件的 Items 集合時。 Office 會快取 Items 集合，直到您的程式代碼變更控件的屬性，或呼叫 InvalidateControl 方法為止。
ButtonClick	發生於按兩下或 RibbonDropDown 中的RibbonGallery按鈕時。
SelectionChanged \(英文\)	發生於或 RibbonGallery 中的RibbonDropDown選取範圍變更時。
DialogLauncherClick	發生於單擊群組右下角的對話框啟動器圖示時。

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

參數	描述
發送	Object，表示引發事件的控件。
e	RibbonControlEventArgs，包含 IRibbonControl。使用此控件來存取 Visual Studio Tools for Office 運行時間所提供的功能區物件模型中無法使用的任何屬性。