Udostępnij za pośrednictwem

Omówienie modelu obiektów wstążki

  • Artykuł

Ś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 CreateRibbonExtensibilityObject ThisAddinklasy , 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.

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

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.

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

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ść