Rozšíření wordových dokumentů a excelových sešitů v doplňcích VSTO za běhu

Doplněk VSTO můžete použít k přizpůsobení wordových dokumentů a excelových sešitů následujícími způsoby:

• Přidejte spravované ovládací prvky do libovolného otevřeného dokumentu nebo listu.

• Převeďte existující objekt seznamu na excelovém listu na rozšířený ListObject objekt, který zveřejňuje události a může být svázán s daty pomocí modelu datové vazby model Windows Forms.

• Přístup k událostem na úrovni aplikace, které jsou vystaveny aplikací Word a Excel pro konkrétní dokumenty, sešity a listy.

  Pokud chcete tuto funkci použít, vygenerujete objekt za běhu, který rozšiřuje dokument nebo sešit.

  Platí pro: Informace v tomto článku se vztahují na projekty doplňků VSTO pro následující aplikace: Excel a Word. Další informace naleznete v tématu Funkce dostupné aplikace Office lication a typu projektu.

Generování rozšířených objektů v doplňcích VSTO

Rozšířené objekty jsou instance typů poskytovaných modulem Runtime sady Visual Studio Tools for Office, které přidávají funkce k objektům, které existují nativně v objektových modelech Wordu nebo Excelu (označované jako nativní objekty Office). K vygenerování rozšířeného objektu pro objekt Wordu nebo Excelu použijte tuto metodu GetVstoObject . Při prvním volání GetVstoObject metody pro zadaný objekt aplikace Word nebo Excel vrátí nový objekt, který rozšiřuje zadaný objekt. Pokaždé, když zavoláte metodu a zadáte stejný objekt aplikace Word nebo Excel, vrátí stejný rozšířený objekt.

Typ rozšířeného objektu má stejný název jako typ nativního objektu Office, ale typ je definován v oboru Microsoft.Office.Tools.Excel názvů nebo Microsoft.Office.Tools.Word oboru názvů. Pokud například zavoláte metodu GetVstoObject pro rozšíření objektu Document , vrátí Document metoda objekt.

Metody GetVstoObject jsou určeny k použití primárně v projektech doplňků VSTO. Tyto metody můžete také použít v projektech na úrovni dokumentu, ale chovají se jinak a mají méně použití.

Chcete-li zjistit, zda rozšířený objekt již byl generován pro konkrétní nativní objekt Office, použijte metodu HasVstoObject . Další informace naleznete v tématu Určení, zda byl objekt Office rozšířen.

Generování položek hostitele

Pokud použijete GetVstoObject k rozšíření objektu na úrovni dokumentu (tj Workbook. , Worksheetnebo Document), vrácený objekt se nazývá hostitelská položka. Položka hostitele je typ, který může obsahovat další objekty, včetně dalších rozšířených objektů a ovládacích prvků. Podobá se odpovídajícímu typu v primárním sestavení vzájemné komunikace aplikace Word nebo Excel, ale má další funkce. Další informace o položkách hostitele najdete v tématu Přehled položek hostitele a ovládacích prvků hostitele.

Po vygenerování položky hostitele ji můžete použít k přidání spravovaných ovládacích prvků do dokumentu, sešitu nebo listu. Další informace naleznete v tématu Přidání spravovaných ovládacích prvků do dokumentů a listů.

Generování položky hostitele pro wordový dokument

• Následující příklad kódu ukazuje, jak vygenerovat položku hostitele pro aktivní dokument.

  C#

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

  VB

  If Globals.ThisAddIn.Application.Documents.Count > 0 Then
      Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
          Globals.ThisAddIn.Application.ActiveDocument
      Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
          Globals.Factory.GetVstoObject(NativeDocument)
  End If
  

Generování položky hostitele pro excelový sešit

• Následující příklad kódu ukazuje, jak vygenerovat položku hostitele pro aktivní sešit.

  C#

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

  VB

  Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
      Globals.ThisAddIn.Application.ActiveWorkbook
  If NativeWorkbook IsNot Nothing Then
      Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
          Globals.Factory.GetVstoObject(NativeWorkbook)
  End If
  

Vygenerování položky hostitele pro list aplikace Excel

• Následující příklad kódu ukazuje, jak vygenerovat položku hostitele pro aktivní list v projektu.

  C#

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

  VB

  Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
      Globals.ThisAddIn.Application.ActiveSheet
  If NativeWorksheet IsNot Nothing Then
      Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
          Globals.Factory.GetVstoObject(NativeWorksheet)
  End If
  

Generování hostitelských ovládacích prvků ListObject

Pokud použijete metodu GetVstoObject k rozšíření ListObject, vrátí metoda ListObjecthodnotu . Má ListObject všechny funkce původního ListObject. Má také další funkce a může být svázán s daty pomocí modelu datové vazby model Windows Forms. Další informace naleznete v tématu ListObject ovládací prvek.

Generování hostitelského ovládacího prvku pro Objekt ListObject

• Následující příklad kódu ukazuje, jak vygenerovat ListObject pro první ListObject v aktivním listu v projektu.

  C#

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

  VB

  Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
      Globals.ThisAddIn.Application.ActiveSheet
  If sheet.ListObjects.Count > 0 Then
      Dim listObject As Excel.ListObject = sheet.ListObjects(1)
      Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
          Globals.Factory.GetVstoObject(listObject)
  End If
  

Přidání spravovaných ovládacích prvků do dokumentů a listů

Po vygenerování Document nebo Worksheetmůžete přidat ovládací prvky do dokumentu nebo listu, které tyto rozšířené objekty představují. Chcete-li přidat ovládací prvky, použijte Controls vlastnost Document nebo Worksheet. Další informace naleznete v tématu Přidání ovládacích prvků do dokumentů Office za běhu.

Můžete přidat model Windows Forms ovládací prvky nebo hostitelské ovládací prvky. Hostitelský ovládací prvek je ovládací prvek poskytovaný modulem Runtime sady Visual Studio Tools for Office, který zabalí odpovídající ovládací prvek do sestavení primární spolupráce aplikace Word nebo Excel. Ovládací prvek hostitele zveřejňuje veškeré chování základního nativního objektu Office. Vyvolává také události a může být svázán s daty pomocí modelu datové vazby model Windows Forms. Další informace najdete v tématu Přehled položek hostitele a ovládacích prvků hostitele.

Poznámka:

Ovládací prvek nelze přidat XmlMappedRange do listu nebo XMLNode ovládacího prvku do XMLNodes dokumentu pomocí doplňku VSTO. Tyto hostitelské ovládací prvky nelze přidat programově. Další informace naleznete v tématu Programová omezení hostitelských položek a hostitelských ovládacích prvků.

Zachování a odebrání ovládacích prvků

Když přidáte spravované ovládací prvky do dokumentu nebo listu, ovládací prvky se při uložení a zavření dokumentu neuchovají. Všechny hostitelské ovládací prvky se odeberou, aby zůstaly za sebou jenom základní nativní objekty Office. Například se změní na ListObject hodnotu ListObject. Všechny ovládací prvky model Windows Forms se také odeberou, ale technologie ActiveX obálky ovládacích prvků zůstanou v dokumentu za sebou. Do doplňku VSTO musíte zahrnout kód, který ovládací prvky vyčistí nebo znovu vytvoří ovládací prvky při příštím otevření dokumentu. Další informace naleznete v tématu Zachování dynamických ovládacích prvků v dokumentech Office.

Přístup k událostem na úrovni aplikace u dokumentů a sešitů

Některé události dokumentu, sešitu a listu v nativních objektových modelech Wordu a Excelu jsou vyvolány pouze na úrovni aplikace. Například událost DocumentBeforeSave je vyvolána při otevření dokumentu ve Wordu, ale tato událost je definována ve Application třídě, nikoli ve Document třídě.

Pokud v doplňku VSTO používáte pouze nativní objekty Office, musíte tyto události na úrovni aplikace zpracovat a pak napsat další kód, abyste zjistili, jestli je dokument, který vyvolal událost, takový, který jste přizpůsobili. Hostitelské položky poskytují tyto události na úrovni dokumentu, aby bylo snazší zpracovat události pro konkrétní dokument. Položku hostitele můžete vygenerovat a pak zpracovat událost pro danou položku hostitele.

Příklad, který používá nativní objekty Wordu

Následující příklad kódu ukazuje, jak zpracovat událost na úrovni aplikace pro wordové dokumenty. Metoda CreateDocument vytvoří nový dokument a pak definuje obslužnou rutinu DocumentBeforeSave události, která brání uložení tohoto dokumentu. Událost je událost na úrovni aplikace, která je vyvolána pro Application objekt, a obslužná rutina události musí porovnat Doc parametr s objektem document1 , aby bylo možné určit, zda document1 představuje uložený dokument.

C#

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

VB

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

Příklady, které používají položku hostitele

Následující příklady kódu zjednodušují tento proces zpracováním BeforeSave události Document položky hostitele. Metoda CreateDocument2 v těchto příkladech generuje Document objekt, který rozšiřuje document2 objekt, a pak definuje obslužnou rutinu BeforeSave události, která brání uložení dokumentu. Obslužná rutina události je volána pouze při document2 uložení a může zrušit akci uložení bez provedení jakékoli další práce k ověření, který dokument byl uložen.

Následující příklad kódu ukazuje tuto úlohu.

C#

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

VB

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

Určení, jestli byl objekt Office rozšířen

Chcete-li zjistit, zda rozšířený objekt již byl generován pro konkrétní nativní objekt Office, použijte metodu HasVstoObject . Tato metoda vrátí hodnotu true , pokud byl již vygenerován rozšířený objekt.

Použijte metodu Globals.Factory.HasVstoObject. Předejte nativní objekt Aplikace Word nebo Excel, například Document objekt nebo Worksheet, který chcete testovat pro rozšířený objekt.

Tato HasVstoObject metoda je užitečná, pokud chcete spustit kód pouze v případech, kdy má zadaný objekt Office rozšířený objekt. Pokud máte například doplněk VSTO wordu, který zpracovává DocumentBeforeSave událost, aby před uložením odebral spravované ovládací prvky z dokumentu, použijte metodu HasVstoObject k určení, jestli byl dokument rozšířen. Pokud dokument nebyl rozšířen, nemůže mít spravované ovládací prvky a obslužná rutina události se může vrátit bez pokusu o vyčištění ovládacích prvků v dokumentu.

Související obsah

• Programové doplňky VSTO
• Přidání ovládacích prvků do dokumentů Office za běhu
• Přehled hostitelských položek a ovládacích prvků hostitele
• Ukázky a názorné postupy pro vývoj pro Office