共用方式為


功能區物件模型概觀

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 屬性。
取得、、 RibbonDropDownRibbonGallery或中的RibbonBox專案

RibbonSplitButton 控制。
使用 Items 屬性。
將專案新增至 RibbonComboBoxRibbonDropDownRibbonGallery 控制件。 使用 Items 屬性。
將控制項新增至 RibbonMenu 使用 Items 屬性。

若要將控件新增至RibbonMenu功能區載入 Office 應用程式 lication 之後,您必須先將 屬性設定Dynamic為 true,才能將功能區載入至 Office 應用程式 lication。 如需詳細資訊,請參閱 設定變成唯讀的屬性。
取得的選取專案 RibbonComboBox

RibbonDropDownRibbonGallery
使用 SelectedItem 屬性。 RibbonComboBox針對 ,請使用 Text 屬性。
取得上的 RibbonTab群組。 請使用 Groups 屬性。
指定出現在中的數據 RibbonGallery列和數據行數目。 RowCount使用和 ColumnCount 屬性。

設定變成唯讀的屬性

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

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

  • 在 Ribbon 類別的建構函式中

  • CreateRibbonExtensibilityObject專案的、 ThisWorkbookThisDocument 類別的方法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);
    }
}

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

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

在 CreateRibbonExtensibilityObject 方法中設定屬性

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

下列範例會在 Excel 活頁簿項目的 類別方法ThisWorkbookCreateRibbonExtensibilityObject設定 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 });
    }
}

變成唯讀的屬性

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

注意

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

屬性 功能區控件類別
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 運行時間 所提供的功能區物件模型中無法使用的任何屬性。