Çalışma zamanında VSTO eklentilerinde Word belgelerini ve Excel çalışma kitaplarını genişletme

Makale
09/27/2022

Şunlar için geçerlidir:Visual Studio Mac için Visual Studio Visual Studio Code

Word belgelerini özelleştirmek ve çalışma kitaplarını Excel için VSTO Eklentisi'ni aşağıdaki yollarla kullanabilirsiniz:

Açık herhangi bir belgeye veya çalışma sayfasına yönetilen denetimler ekleyin.
Excel çalışma sayfasındaki mevcut bir liste nesnesini olayları kullanıma sunan ve Windows Forms veri bağlama modeli kullanılarak verilere bağlanabilen genişletilmiş ListObject bir nesneye dönüştürün.
Word tarafından kullanıma sunulan uygulama düzeyinde olaylara erişin ve belirli belgeler, çalışma kitapları ve çalışma sayfaları için Excel.

Bu işlevselliği kullanmak için, çalışma zamanında belgeyi veya çalışma kitabını genişleten bir nesne oluşturursunuz.

Şunlar için geçerlidir: Bu makaledeki bilgiler, aşağıdaki uygulamalar için VSTO Eklenti projeleri için geçerlidir: Excel ve Word. Daha fazla bilgi için bkz. Office uygulama ve proje türüne göre kullanılabilen özellikler.

VSTO Eklentilerinde genişletilmiş nesneler oluşturma

Genişletilmiş nesneler, word veya Excel nesne modellerinde yerel olarak bulunan nesnelere (yerel Office nesneler olarak adlandırılır) işlevsellik ekleyen Office için Visual Studio Araçları çalışma zamanı tarafından sağlanan tür örnekleridir. Word veya Excel nesnesi için genişletilmiş nesne oluşturmak için yöntemini kullanınGetVstoObject. Belirtilen bir Word veya Excel nesnesi için yöntemini ilk kez çağırdığınızdaGetVstoObject, belirtilen nesneyi genişleten yeni bir nesne döndürür. yöntemini her çağırdığınızda ve aynı Word veya Excel nesnesini belirttiğinizde, aynı genişletilmiş nesneyi döndürür.

Genişletilmiş nesnenin türü, yerel Office nesnesinin türüyle aynı ada sahiptir, ancak tür veya Microsoft.Office.Tools.Word ad alanında Microsoft.Office.Tools.Excel tanımlanır. Örneğin, bir Document nesneyi genişletmek için yöntemini çağırırsanızGetVstoObject, yöntemi bir Document nesnesi döndürür.

Yöntemlerin GetVstoObject öncelikle VSTO Eklenti projelerinde kullanılması amaçlanmıştır. Bu yöntemleri belge düzeyi projelerde de kullanabilirsiniz, ancak farklı davranırlar ve daha az kullanımları olur.

Belirli bir yerel Office nesnesi için genişletilmiş bir nesnenin önceden oluşturulup oluşturulmadığını belirlemek için yöntemini kullanınHasVstoObject. Daha fazla bilgi için bkz. Office nesnesinin genişletilip genişletilmemiş olduğunu belirleme.

Konak öğeleri oluşturma

bir belge düzeyi nesnesini (, bir Workbook, Worksheetveya Document) genişletmek için kullandığınızdaGetVstoObject, döndürülen nesneye konak öğesi adı verilir. Konak öğesi, diğer genişletilmiş nesneler ve denetimler de dahil olmak üzere diğer nesneleri içerebilen bir türdür. Word veya Excel birincil birlikte çalışma derlemesindeki ilgili türe benzer, ancak ek özellikleri vardır. Konak öğeleri hakkında daha fazla bilgi için bkz . Konak öğelerine ve konak denetimlerine genel bakış.

Bir konak öğesi oluşturduktan sonra, belge, çalışma kitabı veya çalışma sayfasına yönetilen denetimler eklemek için bu öğeyi kullanabilirsiniz. Daha fazla bilgi için bkz. Belgelere ve çalışma sayfalarına yönetilen denetimler ekleme.

Word belgesi için konak öğesi oluşturmak için

Aşağıdaki kod örneğinde, etkin belge için bir konak öğesinin nasıl oluşturulacağı gösterilmektedir.

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

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

Excel çalışma kitabı için konak öğesi oluşturmak için

Aşağıdaki kod örneğinde, etkin çalışma kitabı için konak öğesinin nasıl oluşturulacağı gösterilmektedir.

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

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

Excel çalışma sayfasına konak öğesi oluşturmak için

Aşağıdaki kod örneği, projedeki etkin çalışma sayfası için bir konak öğesinin nasıl oluşturulacağı gösterilmektedir.

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

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

ListObject konak denetimleri oluşturma

bir genişletmek ListObjectiçin yöntemini kullandığınızdaGetVstoObject, yöntemi bir ListObjectdöndürür. ListObject, özgün ListObjectöğesinin tüm özelliklerine sahiptir. Ayrıca ek işlevlere sahiptir ve Windows Forms veri bağlama modeli kullanılarak verilere bağlanabilir. Daha fazla bilgi için bkz . ListObject denetimi.

ListObject için konak denetimi oluşturmak için

Aşağıdaki kod örneğinde, projedeki etkin çalışma sayfasında ilk ListObject çalışma sayfası için nasıl oluşturulacağı ListObject gösterilmektedir.

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

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

Belgelere ve çalışma sayfalarına yönetilen denetimler ekleme

veya Document Worksheetoluşturduktan sonra, belgeye veya çalışma sayfasına bu genişletilmiş nesnelerin temsil ettiğini denetimler ekleyebilirsiniz. Denetim eklemek için veya Worksheetözelliğini Document kullanınControls. Daha fazla bilgi için bkz. Çalışma zamanında Office belgelere denetim ekleme.

Windows Forms denetimleri veya konak denetimleri ekleyebilirsiniz. Konak denetimi, word veya Excel birincil birlikte çalışma derlemesinde karşılık gelen bir denetimi sarmalayan Office için Visual Studio Araçları çalışma zamanı tarafından sağlanan bir denetimdir. Konak denetimi, temel alınan yerel Office nesnesinin tüm davranışını gösterir. Ayrıca olayları oluşturur ve Windows Forms veri bağlama modeli kullanılarak verilere bağlanabilir. Daha fazla bilgi için bkz . Konak öğelerine ve konak denetimlerine genel bakış.

Not

VSTO Eklentisi kullanarak bir çalışma sayfasına veya belgeye denetim veya XMLNode XMLNodes denetim ekleyemezsinizXmlMappedRange. Bu konak denetimleri program aracılığıyla eklenemez. Daha fazla bilgi için bkz. Konak öğelerinin ve konak denetimlerinin programlı sınırlamaları.

Denetimleri kalıcı hale ekleme ve kaldırma

Bir belgeye veya çalışma sayfasına yönetilen denetimler eklediğinizde, belge kaydedilip kapatıldığında denetimler kalıcı olmaz. Yalnızca temel alınan yerel Office nesnelerinin geride bırakılması için tüm konak denetimleri kaldırılır. Örneğin, bir ListObject olur ListObject. Tüm Windows Forms denetimleri de kaldırılır, ancak denetimler için ActiveX sarmalayıcılar belgede geride bırakılır. Denetimleri temizlemek veya belgenin bir sonraki açışında denetimleri yeniden oluşturmak için VSTO Eklentinize kod eklemeniz gerekir. Daha fazla bilgi için bkz. Office belgelerde dinamik denetimleri kalıcı hale getir.

Belgeler ve çalışma kitaplarında uygulama düzeyinde olaylara erişme

Yerel Word ve Excel nesne modellerindeki bazı belge, çalışma kitabı ve çalışma sayfası olayları yalnızca uygulama düzeyinde oluşturulur. Örneğin, DocumentBeforeSave bir belge Word'de açıldığında olay oluşturulur, ancak bu olay sınıfı yerine Document sınıfında tanımlanırApplication.

VSTO Eklentinizde yalnızca yerel Office nesneleri kullandığınızda, bu uygulama düzeyi olayları işlemeniz ve ardından olayı oluşturan belgenin özelleştirdiğiniz bir belge olup olmadığını belirlemek için ek kod yazmanız gerekir. Konak öğeleri bu olayları belge düzeyinde sağlayarak belirli bir belgenin olaylarını işlemenin daha kolay olmasını sağlar. Bir konak öğesi oluşturabilir ve ardından bu konak öğesi için olayı işleyebilirsiniz.

Yerel Word nesnelerini kullanan örnek

Aşağıdaki kod örneği, Word belgeleri için uygulama düzeyinde bir olayın nasıl işlendiğini gösterir. CreateDocument yöntemi yeni bir belge oluşturur ve ardından bu belgenin kaydedilmesini engelleyen bir DocumentBeforeSave olay işleyicisi tanımlar. Olay, nesne için Application tetiklenen uygulama düzeyinde bir olaydır ve olay işleyicisinin kaydedilen belgeyi Doc temsil edip etmediğini document1 belirlemek için parametresini nesnesiyle document1 karşılaştırması gerekir.

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

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

Konak öğesi kullanan örnekler

Aşağıdaki kod örnekleri, bir Document konak öğesinin BeforeSave olayını işleyerek bu işlemi basitleştirir. CreateDocument2 Bu örneklerdeki yöntem, nesnesini genişleten document2 bir Document oluşturur ve sonra belgenin kaydedilmesini engelleyen bir BeforeSave olay işleyicisi tanımlar. Olay işleyicisi yalnızca kaydedildiğinde document2 çağrılır ve hangi belgenin kaydedileceğini doğrulamak için ek bir çalışma yapmadan kaydetme eylemini iptal edebilir.

Aşağıdaki kod örneğinde bu görev gösterilmektedir.

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

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

bir Office nesnesinin genişletilip genişletildiğini belirleme

Belirli bir yerel Office nesnesi için genişletilmiş bir nesnenin önceden oluşturulup oluşturulmadığını belirlemek için yöntemini kullanınHasVstoObject. Genişletilmiş bir nesne zaten oluşturulduysa bu yöntem true değerini döndürür.

Globals.Factory.HasVstoMethod yöntemini kullanın. Genişletilmiş nesne için test etmek istediğiniz veya gibi Document yerel Word veya WorksheetExcel nesnesini geçirin.

HasVstoObject yöntemi, yalnızca belirtilen Office nesnenin genişletilmiş bir nesnesi olduğunda kod çalıştırmak istediğinizde yararlıdır. Örneğin, kaydedilmeden önce belgeden yönetilen denetimleri kaldırmak için olayı işleyen DocumentBeforeSave bir Word VSTO Eklentiniz varsa, belgenin HasVstoObject genişletilip genişletilmediğini belirlemek için yöntemini kullanın. Belge genişletilmemişse, yönetilen denetimlere sahip olamaz ve olay işleyicisi belgedeki denetimleri temizlemeye çalışmadan geri dönebilir.