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

  • Makale

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

  • Tüm açık belgelere veya çalışma sayfaları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 ve Excel tarafından belirli belgeler, çalışma kitapları ve çalışma sayfaları için kullanıma sunulan uygulama düzeyi olaylara erişin.

    Bu işlevi 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 uygulaması ve proje türüne göre kullanılabilen özellikler.

VSTO Eklentilerinde genişletilmiş nesneler oluşturma

Genişletilmiş nesneler, Office çalışma zamanı için Visual Studio Araçları tarafından sağlanan ve Word veya Excel nesne modellerinde yerel olarak bulunan nesnelere (yerel Office nesneleri olarak adlandırılır) işlevsellik ekleyen tür örnekleridir. Word veya Excel nesnesi için genişletilmiş nesne oluşturmak için yöntemini kullanın GetVstoObject . Belirtilen bir Word veya Excel nesnesi için yöntemini ilk kez çağırdığınızda GetVstoObject , 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 öncelikli olarak 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.

Genişletilmiş bir nesnenin belirli bir yerel Office nesnesi için önceden oluşturulup oluşturulmadığını belirlemek için yöntemini kullanın HasVstoObject . 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 , veya ) genişletmek için öğesini kullandığınızdaGetVstoObject, Workbookdöndürülen nesneye konak öğesi adı verilir.DocumentWorksheet 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);
}

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

  • Aşağıdaki kod örneğinde, etkin çalışma kitabı için bir 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);
}

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

  • Aşağıdaki kod örneğinde, projedeki etkin çalışma sayfası için 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);
}

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

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 yaptığı denetimler ekleyebilirsiniz. Denetim eklemek için veya Worksheetözelliğini Document kullanınControls. Daha fazla bilgi için bkz . Çalışma zamanında Office belgelerine denetim ekleme.

Windows Forms denetimleri veya konak denetimleri ekleyebilirsiniz. Konak denetimi, Office çalışma zamanı için Visual Studio Araçları tarafından sağlanan ve Word veya Excel birincil birlikte çalışma derlemesinde karşılık gelen bir denetimi sarmalayan bir denetimdir. Konak denetimi, temel alınan yerel Office nesnesinin tüm davranışlarını kullanıma sunar. 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 XMLNode belgeye denetim ekleyemezsiniz.XmlMappedRange XMLNodes 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 kaydedildiğinde ve kapatıldığında denetimler kalıcı olmaz. Yalnızca temel alınan yerel Office nesnelerinin geride kalması 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çılışında denetimleri yeniden oluşturmak için VSTO Eklentinize kod eklemeniz gerekir. Daha fazla bilgi için bkz . Office belgelerinde 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 word'de bir belge 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ı tetikleyen 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ğlar, böylece belirli bir belgenin olaylarını işlemek daha kolay olur. 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şleneceğini gösterir. CreateDocument yöntemi yeni bir belge oluşturur ve sonra bu belgenin kaydedilmesini engelleyen bir DocumentBeforeSave olay işleyicisi tanımlar. Olay, nesne için tetiklenen uygulama düzeyinde bir olaydır ve olay işleyicisinin kaydedilen belgeyi temsil edip etmediğini document1 belirlemek için Application parametresini nesnesiyle document1 karşılaştırması Doc 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;
    }
}

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öntemi, 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ği bu görevi gösterir.

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

Office nesnesinin genişletilip genişletilmemiş olduğunu belirleme

Genişletilmiş bir nesnenin belirli bir yerel Office nesnesi için önceden oluşturulup oluşturulmadığını belirlemek için yöntemini kullanın HasVstoObject . Genişletilmiş bir nesne zaten oluşturulmuşsa bu yöntem true döndürür.

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

HasVstoObject yöntemi, kodu yalnızca belirtilen bir Office nesnesinin genişletilmiş nesnesi olduğunda çalıştırmak istediğinizde kullanışlı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.

İlgili içerik