Omówienie modelu obiektów wstążki

Środowisko uruchomieniowe Visual Studio Tools dla pakietu Office uwidacznia silnie typizowany model obiektów, którego można użyć do pobierania i ustawiania właściwości kontrolek wstążki w czasie wykonywania. Można na przykład dynamicznie wypełniać kontrolki menu lub pokazywać i ukrywać kontrolki kontekstowo. Możesz również dodawać karty, grupy i kontrolki do wstążki, ale tylko przed załadowaniem wstążki przez aplikacja pakietu Office licację. Aby uzyskać informacje, zobacz Ustawianie właściwości, które stają się tylko do odczytu.

Dotyczy: informacje w tym temacie dotyczą projektów na poziomie dokumentu i projektów dodatków VSTO dla następujących aplikacji: Excel; InfoPath 2013 i InfoPath 2010; Programu outlook; Powerpoint; Projektu; Visio; Word. Aby uzyskać więcej informacji, zobacz Funkcje dostępne przez aplikacja pakietu Office lication i typ projektu.

Ten model obiektów wstążki składa się głównie z klas wstążki, zdarzeń wstążki i klas kontrolek wstążki.

Wstążka, klasa

Po dodaniu nowego elementu wstążki (Visual Projektant) do projektu program Visual Studio dodaje klasę wstążki do projektu. Klasa wstążki dziedziczy z RibbonBase klasy .

Ta klasa jest wyświetlana jako klasa częściowa, która jest podzielona między plik kodu wstążki a wstążką Projektant pliku kodu.

Zdarzenia wstążki

Klasa Wstążki zawiera następujące trzy zdarzenia:

Wydarzenie	opis
Load	Podniesione, gdy aplikacja pakietu Office lication ładuje dostosowanie wstążki. Procedura Load obsługi zdarzeń jest automatycznie dodawana do pliku kodu wstążki. Użyj tej procedury obsługi zdarzeń, aby uruchomić kod niestandardowy podczas ładowania wstążki.
LoadImage	Umożliwia buforowanie obrazów w dostosowywaniu wstążki podczas ładowania wstążki. Jeśli napiszesz kod buforowania obrazów wstążki w tej procedurze obsługi zdarzeń, możesz uzyskać niewielki wzrost wydajności. W celu uzyskania więcej informacji, zobacz następujący temat: LoadImage.
Close	Wywoływane po zamknięciu wystąpienia wstążki.

Kontrolki wstążki

Microsoft.Office.Tools.Ribbon Przestrzeń nazw zawiera typ każdej kontrolki widocznej w grupie Kontrolki wstążki pakietu Office przybornika.

W poniższej tabeli przedstawiono typ każdej Ribbon kontrolki. Aby uzyskać opis każdej kontrolki, zobacz Omówienie wstążki.

Nazwa formantu	Nazwa klasy
Box	RibbonBox
Przycisk	RibbonButton
Grupa przycisków	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Galeria	RibbonGallery
Grupa	RibbonGroup
Etykieta	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
Splitbutton	RibbonSplitButton
Zakładka	RibbonTab
Togglebutton	RibbonToggleButton

Microsoft.Office.Tools.Ribbon Przestrzeń nazw używa prefiksu "Wstążka" dla tych typów, aby uniknąć kolizji nazw z nazwami klas kontrolek w System.Windows.Forms przestrzeni nazw.

Po dodaniu kontrolki do Projektant wstążki wstążka Projektant deklaruje klasę dla tej kontrolki jako pole w pliku kodu Projektant wstążki.

Typowe zadania korzystające z właściwości kontrolek wstążki

Każda kontrolka Ribbon zawiera właściwości, których można użyć do wykonywania różnych zadań, takich jak przypisywanie etykiety do kontrolki lub ukrywanie i wyświetlanie kontrolek.

W niektórych przypadkach właściwości stają się tylko do odczytu po załadowaniu wstążki lub po dodaniu kontrolki do menu dynamicznego. Aby uzyskać więcej informacji, zobacz Ustawianie właściwości, które stają się tylko do odczytu.

W poniższej tabeli opisano niektóre zadania, które można wykonać przy użyciu Ribbon właściwości kontrolek.

Dla tego zadania:	Wykonaj następujące czynności:
Ukryj lub pokaż kontrolkę.	Użyj właściwości Visible.
Włączanie lub wyłączanie kontrolki.	Użyj właściwości Włączone.
Ustaw rozmiar kontrolki.	Użyj właściwości ControlSize.
Pobierz obraz wyświetlany w kontrolce.	Użyj właściwości Image.
Zmień etykietę kontrolki.	Użyj właściwości Label.
Dodawanie danych zdefiniowanych przez użytkownika do kontrolki.	Użyj właściwości Tag.
Pobieranie elementów w obiekcie RibbonBox, RibbonDropDown, RibbonGallerylub RibbonSplitButton Kontroli.	Użyj właściwości Items.
Dodaj elementy do kontrolki RibbonComboBox, RibbonDropDownlub RibbonGallery .	Użyj właściwości Items.
Dodaj kontrolki do elementu RibbonMenu.	Użyj właściwości Items. Aby dodać kontrolki do kontrolki RibbonMenu po załadowaniu wstążki do aplikacja pakietu Office licacji, należy ustawić Dynamic właściwość na true przed załadowaniem wstążki do aplikacja pakietu Office licacji. Aby uzyskać informacje, zobacz Ustawianie właściwości, które stają się tylko do odczytu.
Pobieranie wybranego elementu elementu elementu RibbonComboBox, RibbonDropDownlub RibbonGallery.	Użyj właściwości SelectedItem. W przypadku elementu RibbonComboBoxużyj Text właściwości .
Pobierz grupy w obiekcie RibbonTab.	Groups Użyj właściwości .
Określ liczbę wierszy i kolumn wyświetlanych w obiekcie RibbonGallery.	RowCount Użyj właściwości i ColumnCount .

Ustawianie właściwości, które stają się tylko do odczytu

Niektóre właściwości można ustawić tylko przed załadowaniem wstążki. Istnieją trzy miejsca do ustawienia tych właściwości:

• W oknie Właściwości programu Visual Studio.

• W konstruktorze klasy Wstążki.

• W metodzie CreateRibbonExtensibilityObjectThisAddinklasy , ThisWorkbooklub ThisDocument projektu.

  Menu dynamiczne udostępniają pewne wyjątki. Możesz utworzyć nowe kontrolki, ustawić ich właściwości, a następnie dodać je do menu dynamicznego w czasie wykonywania, nawet po załadowaniu wstążki zawierającej menu.

  Właściwości kontrolek dodanych do menu dynamicznego można ustawić w dowolnym momencie.

  Aby uzyskać więcej informacji, zobacz Właściwości, które stają się tylko do odczytu.

Ustawianie właściwości w konstruktorze wstążki

Właściwości kontrolki Ribbon można ustawić w konstruktorze klasy Wstążki . Ten kod musi pojawić się po wywołaniu InitializeComponent metody . Poniższy przykład dodaje nowy przycisk do grupy, jeśli bieżąca godzina to 17:00 Czas pacyficzny (UTC-8) lub nowszy.

Dodaj następujący kod źródłowy języka.

C#

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

VB

<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

W projektach Visual C# uaktualnionych z programu Visual Studio 2008 konstruktor pojawia się w pliku kodu wstążki.

W projektach Visual Basic lub w projektach Visual C# utworzonych w programie Visual Studio 2013 konstruktor pojawia się w pliku kodu wstążki Projektant. Ten plik ma nazwę YourRibbonItem.Projektant. cs lub YourRibbonItem.Projektant. Vb. Aby wyświetlić ten plik w projektach Visual Basic, należy najpierw kliknąć przycisk Pokaż wszystkie pliki w Eksplorator rozwiązań.

Ustawianie właściwości w metodzie CreateRibbonExtensibilityObject

Właściwości kontrolki Ribbon można ustawić podczas zastępowania CreateRibbonExtensibilityObject metody w klasie , ThisWorkbooklub ThisDocument w projekcieThisAddin. Aby uzyskać więcej informacji na temat CreateRibbonExtensibilityObject metody, zobacz Omówienie wstążki.

Poniższy przykład ustawia właściwości wstążki w CreateRibbonExtensibilityObject metodzie ThisWorkbook klasy projektu skoroszytu programu Excel.

Dodaj następujący kod źródłowy języka.

C#

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

VB

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

Właściwości, które stają się tylko do odczytu

W poniższej tabeli przedstawiono właściwości, które można ustawić tylko przed załadowaniem wstążki.

Uwaga

Właściwości kontrolek można ustawić w menu dynamicznym w dowolnym momencie. Ta tabela nie ma zastosowania w tym przypadku.

Właściwości	Wstążka, klasa kontrolki
Styl pola	RibbonBox
Buttontype	RibbonSplitButton
Columncount	RibbonGallery
Controlid	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Globalne	OfficeRibbon
Grupy	RibbonTab
Imagename	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
Itemsize	RibbonMenu RibbonSplitButton
Maxlength	RibbonComboBox RibbonEditBox
Nazwa/nazwisko	RibbonComponent
Pozycja	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
WstążkaTyp	OfficeRibbon
Rowcount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Karty	OfficeRibbon
Tytuł	RibbonSeparator

Ustawianie właściwości wstążek wyświetlanych w inspektorach programu Outlook

Nowe wystąpienie wstążki jest tworzone za każdym razem, gdy użytkownik otworzy inspektora, w którym pojawi się wstążka. Można jednak ustawić właściwości wymienione w powyższej tabeli dopiero przed utworzeniem pierwszego wystąpienia wstążki. Po utworzeniu pierwszego wystąpienia te właściwości stają się tylko do odczytu, ponieważ pierwsze wystąpienie definiuje plik XML używany przez program Outlook do załadowania wstążki.

Jeśli masz logikę warunkową, która ustawia dowolną z tych właściwości na inną wartość podczas tworzenia innych wystąpień wstążki, ten kod nie będzie mieć żadnego wpływu.

Uwaga

Upewnij się, że właściwość Name jest ustawiona dla każdej kontrolki dodawanej do wstążki programu Outlook. Jeśli dodasz kontrolkę do wstążki programu Outlook w czasie wykonywania, musisz ustawić tę właściwość w kodzie. Jeśli dodasz kontrolkę do wstążki programu Outlook w czasie projektowania, właściwość Name zostanie ustawiona automatycznie.

Zdarzenia kontrolki wstążki

Każda klasa kontrolki zawiera co najmniej jedno zdarzenie. W poniższej tabeli opisano te zdarzenia.

Wydarzenie	opis
Kliknij pozycję	Występuje po kliknięciu kontrolki.
Textchanged	Występuje po zmianie tekstu pola edycji lub pola kombi.
ItemsLoading (Ładowanie elementów)	Występuje, gdy kolekcja Items kontrolki jest żądana przez pakiet Office. Pakiet Office buforuje kolekcję Items, dopóki kod nie zmieni właściwości kontrolki lub wywoła metodę InvalidateControl .
PrzyciskKliknij	Występuje po kliknięciu przycisku w elemecie RibbonGallery lub RibbonDropDown .
Selectionchanged	Występuje, gdy wybór w elemecie RibbonDropDown lub RibbonGallery się zmienia.
DialogLauncherClick	Występuje po kliknięciu ikony uruchamiania okna dialogowego w prawym dolnym rogu grupy.

Programy obsługi zdarzeń dla tych zdarzeń mają następujące dwa parametry.

Parametr	Opis
Nadawcy	Element Object reprezentujący kontrolkę, która wywołała zdarzenie.
e	Obiekt RibbonControlEventArgs zawierający element IRibbonControl. Użyj tej kontrolki, aby uzyskać dostęp do dowolnej właściwości, która nie jest dostępna w modelu obiektów wstążki udostępnionym przez środowisko uruchomieniowe Visual Studio Tools dla pakietu Office .

Powiązana zawartość

• Uzyskiwanie dostępu do wstążki w czasie wykonywania
• Omówienie wstążki
• Instrukcje: rozpoczynanie dostosowywania wstążki
• Projektant wstążki
• Przewodnik: tworzenie karty niestandardowej przy użyciu Projektant wstążki
• Przewodnik: aktualizowanie kontrolek na wstążce w czasie wykonywania
• Dostosowywanie wstążki dla programu Outlook
• Instrukcje: dostosowywanie wbudowanej karty
• Instrukcje: dodawanie kontrolek do widoku Backstage
• Instrukcje: eksportowanie wstążki z Projektant wstążki do formatu XML wstążki
• Instrukcje: pokazywanie błędów interfejsu użytkownika dodatku