Rozszerzanie dokumentów programu Word i skoroszytów programu Excel w dodatku VSTO w czasie wykonywania

  • Artykuł

Dodatek VSTO umożliwia dostosowywanie dokumentów programu Word i skoroszytów programu Excel w następujący sposób:

  • Dodaj kontrolki zarządzane do dowolnego otwartego dokumentu lub arkusza.

  • Przekonwertuj istniejący obiekt listy w arkuszu programu Excel na rozszerzenie ListObject , które uwidacznia zdarzenia i może być powiązane z danymi przy użyciu modelu powiązania danych formularzy systemu Windows.

  • Uzyskaj dostęp do zdarzeń na poziomie aplikacji, które są udostępniane przez programy Word i Excel dla określonych dokumentów, skoroszytów i arkuszy.

    Aby użyć tej funkcji, należy wygenerować obiekt w czasie wykonywania, który rozszerza dokument lub skoroszyt.

    Dotyczy: informacje zawarte w tym artykule dotyczą projektów dodatków VSTO dla następujących aplikacji: Excel i Word. Aby uzyskać więcej informacji, zobacz Funkcje dostępne przez aplikacja pakietu Office lication i typ projektu.

Generowanie obiektów rozszerzonych w dodatku VSTO

Obiekty rozszerzone to wystąpienia typów udostępnianych przez środowisko uruchomieniowe Visual Studio Tools dla pakietu Office, które dodają funkcje do obiektów, które istnieją natywnie w modelach obiektów programu Word lub Excel (nazywanych natywnymi obiektami pakietu Office). Aby wygenerować obiekt rozszerzony dla obiektu programu Word lub Excel, użyj GetVstoObject metody . Przy pierwszym wywołaniu GetVstoObject metody dla określonego obiektu programu Word lub Excel zwraca on nowy obiekt, który rozszerza określony obiekt. Za każdym razem, gdy wywołasz metodę i określisz ten sam obiekt programu Word lub Excel, zwraca on ten sam obiekt rozszerzony.

Typ obiektu rozszerzonego ma taką samą nazwę jak typ natywnego obiektu pakietu Office, ale typ jest zdefiniowany w Microsoft.Office.Tools.Excel przestrzeni nazw lub Microsoft.Office.Tools.Word . Jeśli na przykład wywołasz metodę GetVstoObjectDocument w celu rozszerzenia obiektu, metoda zwróci Document obiekt.

Metody GetVstoObject mają być używane głównie w projektach dodatków VSTO. Można również używać tych metod w projektach na poziomie dokumentu, ale zachowują się inaczej i mają mniej zastosowań.

Aby określić, czy obiekt rozszerzony został już wygenerowany dla określonego natywnego obiektu pakietu Office, użyj HasVstoObject metody . Aby uzyskać więcej informacji, zobacz Określanie, czy obiekt pakietu Office został rozszerzony.

Generowanie elementów hosta

W przypadku rozszerzenia GetVstoObject obiektu na poziomie dokumentu (czyli Workbook, , Worksheetlub Document) zwracany obiekt jest nazywany elementem hosta. Element hosta jest typem, który może zawierać inne obiekty, w tym inne obiekty rozszerzone i kontrolki. Przypomina odpowiedni typ w podstawowym zestawie międzyoperacyjności programu Word lub Excel, ale ma dodatkowe funkcje. Aby uzyskać więcej informacji na temat elementów hosta, zobacz Omówienie elementów hosta i kontrolek hosta.

Po wygenerowaniu elementu hosta można go użyć do dodawania kontrolek zarządzanych do dokumentu, skoroszytu lub arkusza. Aby uzyskać więcej informacji, zobacz Dodawanie kontrolek zarządzanych do dokumentów i arkuszy.

Aby wygenerować element hosta dla dokumentu programu Word

  • W poniższym przykładzie kodu pokazano, jak wygenerować element hosta dla aktywnego dokumentu.

    if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

Aby wygenerować element hosta dla skoroszytu programu Excel

  • W poniższym przykładzie kodu pokazano, jak wygenerować element hosta dla aktywnego skoroszytu.

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Aby wygenerować element hosta dla arkusza programu Excel

  • W poniższym przykładzie kodu pokazano, jak wygenerować element hosta dla aktywnego arkusza w projekcie.

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Generowanie kontrolek hosta ListObject

W przypadku użycia GetVstoObject metody w celu rozszerzenia ListObjectmetody metoda zwraca ListObjectwartość . Element ListObject ma wszystkie funkcje oryginalnego ListObjectobiektu . Ma ona również dodatkowe funkcje i może być powiązana z danymi przy użyciu modelu powiązania danych formularzy systemu Windows. Aby uzyskać więcej informacji, zobacz Kontrolka ListObject.

Aby wygenerować kontrolkę hosta dla obiektu ListObject

  • W poniższym przykładzie kodu pokazano, jak wygenerować element ListObject dla pierwszego ListObject w aktywnym arkuszu w projekcie.

    Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

Dodawanie kontrolek zarządzanych do dokumentów i arkuszy

Po wygenerowaniu elementu Document lub Worksheetmożna dodać kontrolki do dokumentu lub arkusza, które reprezentują te obiekty rozszerzone. Aby dodać kontrolki, użyj Controls właściwości Document lub Worksheet. Aby uzyskać więcej informacji, zobacz Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania.

Można dodawać kontrolki formularzy systemu Windows lub kontrolki hosta. Kontrolka hosta to kontrolka zapewniana przez środowisko uruchomieniowe Visual Studio Tools dla pakietu Office, które opakowuje odpowiednią kontrolkę w podstawowym zestawie międzyoperacyjności programu Word lub Excel. Kontrolka hosta uwidacznia wszystkie zachowania bazowego natywnego obiektu pakietu Office. Zgłasza również zdarzenia i może być powiązany z danymi przy użyciu modelu powiązania danych formularzy systemu Windows. Aby uzyskać więcej informacji, zobacz Omówienie elementów hosta i kontrolek hosta.

Uwaga

Nie można dodać XmlMappedRange kontrolki do arkusza lub kontrolki do XMLNodeXMLNodes dokumentu przy użyciu dodatku VSTO. Nie można programowo dodać tych kontrolek hosta. Aby uzyskać więcej informacji, zobacz Programowe ograniczenia elementów hosta i kontrolek hosta.

Utrwalanie i usuwanie kontrolek

Po dodaniu kontrolek zarządzanych do dokumentu lub arkusza kontrolki nie są utrwalane po zapisaniu dokumentu, a następnie zamknięciu. Wszystkie kontrolki hosta są usuwane, tak aby pozostawiono tylko podstawowe natywne obiekty pakietu Office. Na przykład element ListObject staje się wartością ListObject. Wszystkie kontrolki Windows Forms są również usuwane, ale otoki ActiveX dla kontrolek pozostają w dokumencie. Aby wyczyścić kontrolki, należy dołączyć kod do dodatku VSTO lub ponownie utworzyć kontrolki przy następnym otwarciu dokumentu. Aby uzyskać więcej informacji, zobacz Utrwalanie kontrolek dynamicznych w dokumentach pakietu Office.

Uzyskiwanie dostępu do zdarzeń na poziomie aplikacji w dokumentach i skoroszytach

Niektóre zdarzenia dokumentu, skoroszytu i arkusza w natywnych modelach obiektów programu Word i Excel są wywoływane tylko na poziomie aplikacji. Na przykład DocumentBeforeSave zdarzenie jest zgłaszane, gdy dokument jest otwierany w programie Word, ale to zdarzenie jest zdefiniowane w klasie, a nie w ApplicationDocument klasie.

Jeśli używasz tylko natywnych obiektów pakietu Office w dodatku VSTO, musisz obsługiwać te zdarzenia na poziomie aplikacji, a następnie napisać dodatkowy kod, aby określić, czy dokument, który wywołał zdarzenie, jest taki, który został dostosowany. Elementy hosta udostępniają te zdarzenia na poziomie dokumentu, aby ułatwić obsługę zdarzeń dla określonego dokumentu. Możesz wygenerować element hosta, a następnie obsłużyć zdarzenie dla tego elementu hosta.

Przykład korzystający z natywnych obiektów programu Word

W poniższym przykładzie kodu pokazano, jak obsługiwać zdarzenie na poziomie aplikacji dla dokumentów programu Word. Metoda CreateDocument tworzy nowy dokument, a następnie definiuje procedurę DocumentBeforeSave obsługi zdarzeń, która uniemożliwia zapisanie tego dokumentu. Zdarzenie jest zdarzeniem na poziomie aplikacji, które jest zgłaszane dla Application obiektu, a program obsługi zdarzeń musi porównać Doc parametr z obiektem document1 , aby określić, czy document1 reprezentuje zapisany dokument.

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Przykłady używające elementu hosta

Poniższe przykłady kodu upraszczają ten proces, obsługując BeforeSave zdarzenie Document elementu hosta. Metoda CreateDocument2 w tych przykładach generuje obiekt Document , który rozszerza document2 obiekt, a następnie definiuje procedurę obsługi zdarzeń BeforeSave , która uniemożliwia zapisanie dokumentu. Procedura obsługi zdarzeń jest wywoływana tylko wtedy, gdy document2 jest zapisywana, i może anulować akcję zapisywania bez wykonywania dodatkowej pracy w celu sprawdzenia, który dokument został zapisany.

Poniższy przykład kodu przedstawia to zadanie.

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Określanie, czy obiekt pakietu Office został rozszerzony

Aby określić, czy obiekt rozszerzony został już wygenerowany dla określonego natywnego obiektu pakietu Office, użyj HasVstoObject metody . Ta metoda zwraca wartość true , jeśli obiekt rozszerzony został już wygenerowany.

Użyj metody Globals.Factory.HasVstoObject. Przekaż natywny obiekt programu Word lub Excel, taki jak Document lub Worksheet, który chcesz przetestować dla obiektu rozszerzonego.

Metoda jest przydatna HasVstoObject , gdy chcesz uruchomić kod tylko wtedy, gdy określony obiekt pakietu Office ma obiekt rozszerzony. Jeśli na przykład masz dodatek programu Word VSTO, który obsługuje DocumentBeforeSave zdarzenie w celu usunięcia kontrolek zarządzanych z dokumentu przed zapisaniem, użyj HasVstoObject metody , aby określić, czy dokument został rozszerzony. Jeśli dokument nie został rozszerzony, nie może mieć kontrolek zarządzanych, a program obsługi zdarzeń może powrócić bez próby wyczyszczenia kontrolek w dokumencie.

Powiązana zawartość