功能區物件模型概觀

更新： 2008 年 7 月

適用於
本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。 專案類型 文件層級專案 應用程式層級專案 Microsoft Office 版本 Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

Visual Studio Tools for Office 會公開 (Expose) 強型別 (Strongly Typed) 物件模型，而您可在執行階段使用這種物件模型，取得和設定功能區控制項的屬性。例如，您可以動態填入 (Populate) 功能表控制項，或是依內容顯示與隱藏控制項。

您也可以將索引標籤、群組和控制項加入至功能區，但是這些動作必須在 Office 應用程式載入功能區之前完成。如需詳細資訊，請參閱設定變成唯讀的屬性。

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

功能區類別

當您將新的 [功能區 (視覺化設計工具)] 項目加入至專案時，Visual Studio Tools for Office 會在您的專案中加入一個繼承自 OfficeRibbon 類別的類別。

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

功能區事件

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

• Load

• LoadImage

• Close

Load 事件會在 Office 應用程式載入功能區自訂時引發。Load 事件處理常式會自動加入至功能區程式碼檔案。您可以使用這個事件處理常式，在功能區載入時執行自訂程式碼。

LoadImage 事件可讓您在功能區載入時快取功能區自訂中的影像。如果您撰寫程式碼來快取這個事件處理常式中的功能區影像，可以稍微提升一些效能。如需詳細資訊，請參閱 LoadImage。

Close 事件會在功能區執行個體關閉時引發。

功能區控制項類別

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

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

控制項名稱	類別名稱
Box	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
Group	RibbonGroup
Label	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

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

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

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

每個功能區控制項類別都包含一些屬性，讓您用來執行各種不同工作，例如將標籤指派給控制項，或是隱藏與顯示控制項。

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

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

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

設定變成唯讀的屬性

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

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

• 在功能區類別的建構函式 (Constructor) 中。

• 在專案的 ThisAddin 類別的 CreateRibbonExtensibilityObject 方法中。

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

從 Visual Studio 2008 Service Pack 1 (SP1) 開始，您加入至動態功能表之控制項的屬性都可隨時加以設定。不過，如果您尚未安裝 SP1，其中一些屬性就會在控制項加入至功能表後變成唯讀。

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

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

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

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

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

設定 CreateRibbonExtensibilityObject 方法中的屬性

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

下列範例會在 Excel 2007 活頁簿專案 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 New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

變成唯讀的屬性

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

注意事項：
如果安裝了 SP1，您就可以隨時對動態功能表上控制項的屬性進行設定。下表不適用於這種情況。

屬性	功能區控制項類別
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
Groups	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Name	RibbonComponent
Position	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
Tabs	OfficeRibbon
Title	RibbonSeparator

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

每當使用者開啟會出現功能區的偵測器時，就會建立新的功能區執行個體。但是，您只能在建立新的功能區執行個體之前，設定上述表格中所列的屬性。一旦第一個執行個體建立之後，這些屬性就會變成唯讀，因為第一個執行個體會定義 Outlook 用來載入功能區的 XML 檔案。

如果您擁有可在建立其他功能區執行個體時將這些屬性設為其他值的條件式邏輯，此程式碼將無任何作用。

注意事項：
請針對加入至 Outlook 功能區的每個控制項，確定已設定了 [Name] 屬性。如果您在執行階段將控制項加入至 Outlook 功能區，則您必須在程式碼中設定此屬性。如果您在設計階段將控制項加入至 Outlook 功能區，則 Name 屬性會自動進行設定。

功能區控制項事件

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

事件	說明
Click	會在按一下控制項時發生。
TextChanged	會在編輯方塊或下拉式方塊中的文字變更時發生。
ItemsLoading	會在 Office 要求控制項的 Items 集合時發生。Office 會將 Items 保留在快取區中，直到您的程式碼變更控制項的屬性，或您呼叫 Microsoft.Office.Core.IRibbonUI.InvalidateControl 方法為止。
ButtonClick	會在按一下 RibbonGallery 或 RibbonDropDown 中的按鈕時發生。
SelectionChanged	會在 RibbonDropDown 或 RibbonGallery 中的選取範圍變更時發生。
DialogLauncherClick	會在按一下群組右下角的對話方塊啟動程式圖示時發生。

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

參數	說明
sender	Object，表示引發事件的控制項。
e	包含 Microsoft.Office.Core.IRibbonControl 的 RibbonControlEventArgs。您可以使用此控制項，存取 Visual Studio Tools for Office 功能區物件模型內無法提供的任何屬性。

請參閱

工作

HOW TO：開始自訂功能區

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

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

HOW TO：自訂內建索引標籤

HOW TO：自訂 Microsoft Office 功能表

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

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

概念

在執行階段存取功能區

功能區概觀

功能區設計工具

自訂 Outlook 的功能區

參考

Microsoft.Office.Tools.Ribbon

變更記錄

日期	記錄	原因
2008 年 7 月	修訂有關在安裝 SP1 後設定動態功能表上控制項屬性的資訊。	SP1 功能變更。