Omówienie elementów hosta i kontrolek hosta

  • Artykuł

Elementy hosta i kontrolki hosta to typy, które ułatwiają udostępnianie modelu programowania dla rozwiązań pakietu Office tworzonych przy użyciu narzędzi programistycznych pakietu Office w programie Visual Studio. Elementy hosta i kontrolki hosta umożliwiają interakcję z modelami obiektów programów Microsoft Office Word i Microsoft Office Excel, które są oparte na modelu COM, podobnie jak interakcja z obiektami zarządzanymi, takimi jak kontrolki Windows Forms.

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.

Elementy hosta

Elementy hosta to typy, które znajdują się w górnej części hierarchii modelu obiektów w projektach pakietu Office. Środowisko uruchomieniowe Visual Studio Tools dla pakietu Office definiuje następujące elementy hosta dla rozwiązań word i Excel:

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    Każdy z tych typów rozszerza obiekt, który istnieje natywnie w modelu obiektów programu Word lub Excel, nazywany natywnym obiektem pakietu Office. Na przykład Document element hosta rozszerza Document obiekt, który jest zdefiniowany w podstawowym zestawie międzyoperacyjności dla programu Word.

    Elementy hosta zazwyczaj mają tę samą podstawową funkcjonalność co odpowiadające im obiekty pakietu Office, ale są rozszerzone o następujące funkcje:

  • Możliwość hostowania kontrolek zarządzanych, w tym kontrolek hosta i kontrolek Windows Forms.

  • Bogatsze modele zdarzeń. Niektóre zdarzenia dokumentu, skoroszytu i arkusza w natywnych modelach obiektów programu Word i Excel są wywoływane tylko na poziomie aplikacji. Elementy hosta udostępniają te zdarzenia na poziomie dokumentu, aby ułatwić obsługę zdarzeń dla określonego dokumentu.

Omówienie elementów hosta w projektach na poziomie dokumentu

W projektach na poziomie dokumentu elementy hosta zapewniają punkt wejścia dla kodu i mają projektantów, którzy ułatwiają opracowywanie rozwiązania.

Document Elementy hosta i Worksheet mają skojarzonych projektantów, którzy są wizualną reprezentacją dokumentu lub arkusza, na przykład projektanta formularzy systemu Windows. Za pomocą tego projektanta można modyfikować zawartość dokumentu lub arkusza bezpośrednio w programie Word lub Excel oraz przeciągać kontrolki na powierzchnię projektową. Aby uzyskać więcej informacji, zobacz Document host item (Element hosta dokumentu) i Arkusz host item (Element hosta arkusza).

Element Workbook hosta nie działa jako kontener dla kontrolek, które mają interfejs użytkownika. Zamiast tego projektant tego elementu hosta działa jako zasobnik składnika, który umożliwia przeciąganie składnika, takiego jak , DataSetna jego powierzchni projektowej. Aby uzyskać więcej informacji, zobacz Element hosta skoroszytu.

Nie można programowo tworzyć elementów hosta w projektach na poziomie dokumentu. Zamiast tego należy użyć ThisDocumentklas , ThisWorkbooklub Sheetn , które program Visual Studio automatycznie generuje w projekcie w czasie projektowania. Te wygenerowane klasy pochodzą z elementów hosta i zapewniają punkt wejścia dla kodu. Aby uzyskać więcej informacji, zobacz Programowe ograniczenia elementów hosta i kontrolek hosta.

Omówienie elementów hosta w projektach dodatków VSTO

Podczas tworzenia dodatku VSTO nie masz domyślnie dostępu do żadnych elementów hosta. Można jednak wygenerować Documentelementy , Workbooki Worksheet hostów w dodatku Word i Excel VSTO w czasie wykonywania.

Po wygenerowaniu elementu hosta można wykonywać zadania, takie jak dodawanie kontrolek do dokumentów. Aby uzyskać więcej informacji, zobacz Rozszerzanie dokumentów programu Word i skoroszytów programu Excel w dodatku VSTO w czasie wykonywania.

Kontrolki hosta

Kontrolki hosta rozszerzają różne obiekty interfejsu użytkownika w modelach obiektów programów Word i Excel, takich jak Microsoft.Office.Interop.Word.ContentControl i Range .

Następujące kontrolki hosta są dostępne dla projektów programu Excel:

  • Kontrolka wykresu

  • Kontrolka ListObject

  • Nazwana kontrolkaRange

  • XmlMappedRange, kontrolka

    Następujące kontrolki hosta są dostępne dla projektów programu Word:

  • Kontrolka zakładki

  • Kontrolki zawartości

  • Kontrolka XMLNode

  • Kontrolka XMLNodes

    Kontrolki hosta dodawane do dokumentów pakietu Office zachowują się jak natywne obiekty pakietu Office; Jednak kontrolki hosta mają dodatkowe funkcje, w tym zdarzenia i możliwości powiązania danych. Jeśli na przykład chcesz przechwycić zdarzenia obiektu natywnego Range w programie Excel, musisz najpierw obsłużyć zdarzenie zmiany arkusza. Następnie należy określić, czy zmiana wystąpiła Rangew obiekcie . Z kolei kontrolka NamedRange hosta ma Change zdarzenie, które można obsługiwać bezpośrednio.

    Relacja między elementem hosta i kontrolkami hosta jest podobna do relacji między kontrolkami Formularz systemu Windows i Windows Forms. Podobnie jak w przypadku umieszczenia kontrolki pola tekstowego w formularzu systemu Windows, należy umieścić kontrolkę NamedRange na elemencie Worksheet hosta. Poniższa ilustracja przedstawia relację między elementami hosta i kontrolkami hosta.

    Relationship between host items and host controls

    Kontrolki formularzy systemu Windows można również używać w rozwiązaniach pakietu Office, dodając je bezpośrednio do powierzchni dokumentów programów Word i Excel. Aby uzyskać więcej informacji, zobacz Kontrolki formularzy systemu Windows w dokumentach pakietu Office — omówienie.

Uwaga

Dodawanie kontrolek hosta lub kontrolek formularzy systemu Windows do dokumentu podrzędnego programu Word nie jest obsługiwane.

Dodawanie kontrolek hosta do dokumentów

W projektach na poziomie dokumentu można dodawać kontrolki hosta do dokumentów programu Word lub arkuszy programu Excel w czasie projektowania w następujący sposób:

Kontrolki hosta nazw

Po przeciągnięciu kontrolki hosta z przybornika do dokumentu kontrolka zostanie automatycznie nazwana przy użyciu typu kontrolki z liczbą przyrostową na końcu. Na przykład zakładki mają nazwę bookmark1, bookmark2 itd. Jeśli używasz natywnej funkcjonalności programu Word lub Excel do dodawania kontrolki, możesz nadać jej określoną nazwę w momencie jego utworzenia. Możesz również zmienić nazwy kontrolek, zmieniając wartość właściwości Name w oknie Właściwości .

Uwaga

Nie można używać wyrazów zarezerwowanych do nazywania kontrolek hosta. Jeśli na przykład dodasz kontrolkę NamedRange do arkusza i zmienisz nazwę na System, podczas kompilowania projektu wystąpią błędy.

Usuwanie kontrolek hosta

W projektach na poziomie dokumentu możesz usunąć kontrolki hosta w czasie projektowania, wybierając kontrolkę w arkuszu programu Excel lub dokumencie programu Word i naciskając klawisz Usuń . Aby usunąć NamedRange kontrolki, należy jednak użyć okna dialogowego Definiowanie nazwy w programie Excel.

Jeśli dodasz kontrolkę hosta do dokumentu w czasie projektowania, nie należy go programowo usuwać w czasie wykonywania, ponieważ następnym razem, gdy spróbujesz użyć kontrolki w kodzie, zostanie zgłoszony wyjątek. Metoda Delete kontrolki hosta usuwa tylko kontrolki hosta, które są dodawane do dokumentu w czasie wykonywania. Jeśli wywołasz metodę Delete kontrolki hosta, która została utworzona w czasie projektowania, zostanie zgłoszony wyjątek.

Na przykład Delete metoda klasy tylko pomyślnie usuwa NamedRange element NamedRange , jeśli został on programowo dodany do arkusza, który jest znany jako dynamiczne tworzenie kontrolek hosta. Dynamicznie tworzone kontrolki hosta można również usunąć, przekazując nazwę kontrolki do Remove metody Controls lub Controls . Aby uzyskać więcej informacji, zobacz Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania.

Jeśli użytkownicy końcowi usuną kontrolkę hosta z dokumentu w czasie wykonywania, rozwiązanie może zakończyć się niepowodzeniem w nieoczekiwany sposób. Funkcje ochrony dokumentów w programach Word i Excel umożliwiają ochronę kontrolek hosta przed usunięciem. Aby uzyskać więcej informacji, zobacz Office development samples and walkthroughs (Przykłady i przewodniki dotyczące programowania w pakiecie Office).

Uwaga

Nie usuwaj programowo kontrolek podczas Shutdown obsługi zdarzeń dokumentu lub arkusza. Elementy interfejsu Shutdown użytkownika nie są już dostępne w przypadku wystąpienia zdarzenia. Jeśli chcesz usunąć kontrolki przed zamknięciem aplikacji, dodaj kod do innej procedury obsługi zdarzeń, takiej jak BeforeClose lub BeforeSave.

Program pod kątem zdarzeń kontroli hosta

Jednym ze sposobów rozszerzania obiektów pakietu Office przez host jest dodanie zdarzeń. Na przykład Range obiekt w programie Excel i Bookmark obiekcie w programie Word nie mają zdarzeń, ale środowisko uruchomieniowe Visual Studio Tools dla pakietu Office rozszerza te obiekty przez dodanie programowalnych zdarzeń. Dostęp do tych zdarzeń i kod można uzyskać w taki sam sposób, jak w przypadku zdarzeń kontrolek w formularzach systemu Windows: za pośrednictwem listy rozwijanej zdarzeń w języku Visual Basic i strony właściwości zdarzenia w języku C#. Aby uzyskać więcej informacji, zobacz Przewodnik: Program względem zdarzeń kontrolki NamedRange.

Uwaga

Nie należy ustawiać EnableEvents właściwości Application obiektu w programie Excel na wartość false. Ustawienie tej właściwości na wartość false uniemożliwia programowi Excel zgłaszanie wszelkich zdarzeń, w tym zdarzeń kontrolek hosta.

Powiązana zawartość