Udostępnij za pośrednictwem

Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania

  • Artykuł

Kontrolki można dodawać do dokumentu programu Microsoft Office Word i skoroszytu programu Microsoft Office Excel w czasie wykonywania. Można je również usunąć w czasie wykonywania. Kontrolki dodawane lub usuwane w czasie wykonywania są nazywane kontrolkami dynamicznymi.

Dotyczy: informacje w tym temacie dotyczą projektów na poziomie dokumentu i projektów dodatków VSTO dla programów Excel i Word. Aby uzyskać więcej informacji, zobacz Funkcje dostępne przez aplikacja pakietu Office lication i typ projektu.

W tym temacie opisano następujące kwestie:

Zarządzanie kontrolkami w czasie wykonywania przy użyciu kolekcji kontrolek

Aby dodać, pobrać lub usunąć kontrolki w czasie wykonywania, użyj metod ControlCollection pomocnika obiektów i ControlCollection .

Sposób uzyskiwania dostępu do tych obiektów zależy od typu opracowywanego projektu:

  • W projekcie na poziomie dokumentu dla programu Excel użyj Controls właściwości Sheet1klasy , Sheet2i Sheet3 . Aby uzyskać więcej informacji na temat tych klas, zobacz Element hosta arkusza.

  • W projekcie na poziomie dokumentu dla programu Word użyj Controls właściwości ThisDocument klasy . Aby uzyskać więcej informacji na temat tej klasy, zobacz dokument elementu hosta.

  • W projekcie dodatku VSTO dla programu Excel lub Word użyj Controls właściwości elementu Worksheet lub Document wygenerowanego w czasie wykonywania. Aby uzyskać więcej informacji na temat generowania tych obiektów w czasie wykonywania, zobacz Rozszerzanie dokumentów programu Word i skoroszytów programu Excel w dodatku VSTO w czasie wykonywania.

Dodaj kontrolki

Typy ControlCollection i ControlCollection obejmują metody pomocnicze, których można użyć do dodawania kontrolek hosta i typowych kontrolek formularzy systemu Windows do dokumentów i arkuszy. Każda nazwa metody ma klasę formantu formatuAdd, gdzie klasa kontrolki jest nazwą klasy, którą chcesz dodać. Aby na przykład dodać kontrolkę NamedRange do dokumentu, użyj AddNamedRange metody .

Poniższy przykładowy kod dodaje element NamedRange do Sheet1 elementu w projekcie na poziomie dokumentu dla programu Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Kontrolki dostępu i usuwania

Możesz użyć Controls właściwości obiektu Worksheet lub Document do iterowania wszystkich kontrolek w dokumencie, w tym kontrolek dodanych w czasie projektowania. Kontrolki dodawane w czasie projektowania są również nazywane kontrolkami statycznych.

Kontrolki dynamiczne można usunąć, wywołując Delete metodę kontrolki lub wywołując Remove metodę każdej kolekcji Formanty. W poniższym przykładzie kodu użyto Remove metody , aby usunąć element NamedRange z Sheet1 projektu na poziomie dokumentu dla programu Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Nie można usunąć statycznych kontrolek w czasie wykonywania. Jeśli spróbujesz użyć Delete metody or Remove w celu usunięcia kontrolki statycznej, CannotRemoveControlException zostanie zgłoszony element .

Uwaga

Nie usuwaj programowo kontrolek w procedurze Shutdown obsługi zdarzeń dokumentu. Elementy interfejsu użytkownika dokumentu nie są już dostępne po wystąpieniu Shutdown zdarzenia. Jeśli chcesz usunąć kontrolki przed zamknięciem dokumentu, dodaj kod do programu obsługi zdarzeń dla innego zdarzenia, takiego jak BeforeClose word lub BeforeSaveBeforeClose, lub BeforeSave dla programu Excel.

Dodawanie kontrolek hosta do dokumentów

Podczas programowego dodawania kontrolek hosta do dokumentów należy podać nazwę, która jednoznacznie identyfikuje kontrolkę, i należy określić, gdzie dodać kontrolkę do dokumentu. Aby uzyskać szczegółowe instrukcje, zobacz następujące tematy:

Aby uzyskać więcej informacji na temat kontrolek hostów, zobacz Host items and host controls overview (Omówienie elementów hosta i kontrolek hostów).

Gdy dokument zostanie zapisany, a następnie zamknięty, wszystkie dynamicznie utworzone kontrolki hosta zostaną odłączone od ich zdarzeń i utracą funkcjonalność powiązania danych. Możesz dodać kod do rozwiązania, aby ponownie utworzyć kontrolki hosta po ponownym otwarciu dokumentu. Aby uzyskać więcej informacji, zobacz Utrwalanie kontrolek dynamicznych w dokumentach pakietu Office.

Uwaga

Metody pomocnika nie są udostępniane dla następujących kontrolek hosta, ponieważ tych kontrolek nie można dodawać programowo do dokumentów: XmlMappedRange, XMLNodei XMLNodes.

Dodawanie kontrolek Windows Forms do dokumentów

Po programowym dodaniu kontrolki Windows Forms do dokumentu należy podać lokalizację kontrolki i nazwę, która jednoznacznie identyfikuje kontrolkę. Środowisko uruchomieniowe Visual Studio Tools dla pakietu Office udostępnia metody pomocnicze dla każdej kontrolki. Te metody są przeciążone, dzięki czemu można przekazać zakres lub określone współrzędne dla lokalizacji kontrolki.

Gdy dokument zostanie zapisany, a następnie zamknięty, wszystkie dynamicznie utworzone kontrolki formularzy systemu Windows zostaną usunięte z dokumentu. Możesz dodać kod do rozwiązania, aby ponownie utworzyć kontrolki po ponownym otwarciu dokumentu. Jeśli tworzysz dynamiczne kontrolki Windows Forms przy użyciu dodatku VSTO, otoki ActiveX dla kontrolek pozostają w dokumencie. Aby uzyskać więcej informacji, zobacz Utrwalanie kontrolek dynamicznych w dokumentach pakietu Office.

Uwaga

Nie można programowo dodać kontrolek formularzy systemu Windows do chronionych dokumentów. Jeśli programowo wyłączysz ochronę dokumentu programu Word lub arkusza programu Excel w celu dodania kontrolki, musisz napisać dodatkowy kod, aby usunąć otokę ActiveX kontrolki po zamknięciu dokumentu. Otoka ActiveX kontrolki nie jest automatycznie usuwana z chronionych dokumentów.

Dodaj formanty niestandardowe

Jeśli chcesz dodać element Control , który nie jest obsługiwany przez dostępne metody pomocnicze, takie jak niestandardowa kontrolka użytkownika, użyj następujących metod:

  • W przypadku programu Excel użyj jednej z AddControl metod ControlCollection obiektu.

  • W przypadku programu Word użyj jednej z AddControl metod ControlCollection obiektu.

    Aby dodać kontrolkę, przekaż Controlelement , lokalizację dla kontrolki i nazwę, która jednoznacznie identyfikuje kontrolkę do AddControl metody . Metoda AddControl zwraca obiekt, który definiuje sposób interakcji kontrolki z arkuszem lub dokumentem. Metoda AddControl zwraca ControlSite obiekt (dla programu Excel) lub ControlSite obiekt (dla programu Word).

    W poniższym przykładzie kodu pokazano, jak za pomocą AddControl metody dynamicznie dodać niestandardową kontrolkę użytkownika do arkusza w projekcie programu Excel na poziomie dokumentu. W tym przykładzie kontrolka użytkownika nosi nazwę UserControl1, a nazwa Range to range1. Aby użyć tego przykładu, uruchom go z Sheetklasy n w projekcie.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Używanie elementów członkowskich kontrolek niestandardowych

Po użyciu jednej z AddControl metod dodawania kontrolki do arkusza lub dokumentu masz teraz dwa różne obiekty sterujące:

  • Kontrolka Control reprezentująca kontrolkę niestandardową.

  • Obiekt ControlSite, OLEObjectlub OLEControl reprezentujący kontrolkę po dodaniu jej do arkusza lub dokumentu.

    Wiele właściwości i metod jest współużytkowanych między tymi kontrolkami. Ważne jest, aby uzyskać dostęp do tych członków za pomocą odpowiedniej kontroli:

  • Aby uzyskać dostęp do elementów członkowskich należących tylko do kontrolki niestandardowej, użyj elementu Control.

  • Aby uzyskać dostęp do elementów członkowskich, które są współużytkowane przez kontrolki, użyj ControlSiteobiektu , OLEObjectlub OLEControl .

    Jeśli uzyskujesz dostęp do udostępnionego Controlelementu członkowskiego z usługi , może to zakończyć się niepowodzeniem bez ostrzeżenia lub powiadomienia lub może spowodować nieprawidłowe wyniki. Zawsze używaj metod lub właściwości ControlSiteobiektu , OLEObjectlub OLEControl , chyba że wymagana metoda lub właściwość nie jest dostępna; tylko wtedy należy odwołać się do Controlobiektu .

    Na przykład zarówno ControlSite klasa, jak i Control klasa mają Top właściwość . Aby uzyskać lub ustawić odległość między górną częścią kontrolki a górną częścią dokumentu, użyj Top właściwości ControlSite, a nie Top właściwości Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Powiązana zawartość