Bagikan melalui

Memperluas dokumen Word dan buku kerja Excel di add-in VSTO pada waktu proses

  • Artikel

Anda bisa menggunakan Add-in VSTO untuk mengkustomisasi dokumen Word dan buku kerja Excel dengan cara berikut:

  • Tambahkan kontrol terkelola ke dokumen atau lembar kerja yang terbuka.

  • Mengonversi objek daftar yang sudah ada pada lembar kerja Excel menjadi yang diperluas ListObject yang mengekspos peristiwa dan bisa terikat ke data dengan menggunakan model pengikatan data Formulir Windows.

  • Mengakses peristiwa tingkat aplikasi yang diekspos oleh Word dan Excel untuk dokumen, buku kerja, dan lembar kerja tertentu.

    Untuk menggunakan fungsionalitas ini, Anda membuat objek pada waktu proses yang memperluas dokumen atau buku kerja.

    Berlaku untuk: Informasi dalam artikel ini berlaku untuk proyek Add-in VSTO untuk aplikasi berikut: Excel dan Word. Untuk informasi selengkapnya, lihat Fitur yang tersedia berdasarkan aplikasi Office likasi dan jenis proyek.

Membuat objek yang diperluas di Add-in VSTO

Objek yang diperluas adalah contoh jenis yang disediakan oleh runtime Visual Studio Tools for Office yang menambahkan fungsionalitas ke objek yang ada secara asli dalam model objek Word atau Excel (disebut objek Office asli). Untuk menghasilkan objek yang diperluas untuk objek Word atau Excel, gunakan metode .GetVstoObject Pertama kali Anda memanggil GetVstoObject metode untuk objek Word atau Excel tertentu, ini mengembalikan objek baru yang memperluas objek yang ditentukan. Setiap kali Anda memanggil metode dan menentukan objek Word atau Excel yang sama, objek tersebut mengembalikan objek yang diperluas yang sama.

Jenis objek yang diperluas memiliki nama yang sama dengan jenis objek Office asli, tetapi jenisnya ditentukan di Microsoft.Office.Tools.Excel namespace layanan atau Microsoft.Office.Tools.Word . Misalnya, jika Anda memanggil GetVstoObject metode untuk memperluas Document objek, metode mengembalikan Document objek.

Metode ini GetVstoObject dimaksudkan untuk digunakan terutama dalam proyek Add-in VSTO. Anda juga dapat menggunakan metode ini dalam proyek tingkat dokumen, tetapi berulah secara berbeda, dan memiliki lebih sedikit penggunaan.

Untuk menentukan apakah objek yang diperluas telah dibuat untuk objek Office asli tertentu, gunakan metode .HasVstoObject Untuk informasi selengkapnya, lihat Menentukan apakah objek Office telah diperluas.

Hasilkan item host

Saat Anda menggunakan GetVstoObject untuk memperluas objek tingkat dokumen (yaitu, Workbook, , Worksheetatau Document), objek yang dikembalikan disebut item host. Item host adalah jenis yang dapat berisi objek lain, termasuk objek dan kontrol lain yang diperluas. Ini menyerupai tipe yang sesuai dalam rakitan interop utama Word atau Excel, tetapi memiliki fitur tambahan. Untuk informasi selengkapnya tentang item host, lihat Gambaran umum item host dan kontrol host.

Setelah membuat item host, Anda bisa menggunakannya untuk menambahkan kontrol terkelola ke dokumen, buku kerja, atau lembar kerja. Untuk informasi selengkapnya, lihat Menambahkan kontrol terkelola ke dokumen dan lembar kerja.

Untuk menghasilkan item host untuk dokumen Word

  • Contoh kode berikut menunjukkan cara membuat item host untuk dokumen aktif.

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

Untuk menghasilkan item host untuk buku kerja Excel

  • Contoh kode berikut menunjukkan cara membuat item host untuk buku kerja aktif.

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

Untuk menghasilkan item host untuk lembar kerja Excel

  • Contoh kode berikut menunjukkan cara membuat item host untuk lembar kerja aktif dalam proyek.

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

Membuat kontrol host ListObject

Ketika Anda menggunakan GetVstoObject metode untuk memperluas ListObject, metode mengembalikan ListObject. ListObject memiliki semua fitur asli .ListObject Ini juga memiliki fungsionalitas tambahan dan dapat terikat ke data dengan menggunakan model pengikatan data Formulir Windows. Untuk informasi selengkapnya, lihat Kontrol ListObject.

Untuk menghasilkan kontrol host untuk ListObject

  • Contoh kode berikut menunjukkan cara membuat untuk yang ListObject pertama ListObject dalam lembar kerja aktif dalam proyek.

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

Menambahkan kontrol terkelola ke dokumen dan lembar kerja

Setelah Anda membuat Document atau Worksheet, Anda bisa menambahkan kontrol ke dokumen atau lembar kerja yang diwakili objek yang diperluas ini. Untuk menambahkan kontrol, gunakan Controls properti dari Document atau Worksheet. Untuk informasi selengkapnya, lihat Menambahkan kontrol ke dokumen Office pada waktu proses.

Anda dapat menambahkan kontrol Formulir Windows atau kontrol host. Kontrol host adalah kontrol yang disediakan oleh runtime Visual Studio Tools for Office yang membungkus kontrol terkait di rakitan interop utama Word atau Excel. Kontrol host mengekspos semua perilaku objek Office asli yang mendasar. Ini juga meningkatkan peristiwa dan dapat terikat ke data dengan menggunakan model pengikatan data Formulir Windows. Untuk informasi selengkapnya, lihat Gambaran umum item host dan kontrol host.

Catatan

Anda tidak dapat menambahkan XmlMappedRange kontrol ke lembar kerja, atau XMLNode atau XMLNodes kontrol ke dokumen, dengan menggunakan Add-in VSTO. Kontrol host ini tidak dapat ditambahkan secara terprogram. Untuk informasi selengkapnya, lihat Batasan terprogram item host dan kontrol host.

Mempertahankan dan menghapus kontrol

Saat Anda menambahkan kontrol terkelola ke dokumen atau lembar kerja, kontrol tidak dipertahankan saat dokumen disimpan lalu ditutup. Semua kontrol host dihapus sehingga hanya objek Office asli yang mendasar yang tertinggal. Misalnya, menjadi ListObject ListObject. Semua kontrol Formulir Windows juga dihapus, tetapi pembungkus ActiveX untuk kontrol tertinggal dalam dokumen. Anda harus menyertakan kode dalam Add-in VSTO untuk membersihkan kontrol, atau untuk membuat ulang kontrol saat dokumen dibuka lagi. Untuk informasi selengkapnya, lihat Mempertahankan kontrol dinamis di dokumen Office.

Mengakses peristiwa tingkat aplikasi pada dokumen dan buku kerja

Beberapa peristiwa dokumen, buku kerja, dan lembar kerja dalam model objek Word dan Excel asli hanya dimunculkan di tingkat aplikasi. Misalnya, DocumentBeforeSave peristiwa dimunculkan ketika dokumen dibuka di Word, tetapi kejadian ini ditentukan di Application kelas, bukan Document kelas .

Saat Anda hanya menggunakan objek Office asli di Add-in VSTO, Anda harus menangani peristiwa tingkat aplikasi ini lalu menulis kode tambahan untuk menentukan apakah dokumen yang memunculkan peristiwa adalah yang telah Anda kustomisasi. Item host menyediakan peristiwa ini di tingkat dokumen, sehingga lebih mudah untuk menangani peristiwa untuk dokumen tertentu. Anda dapat membuat item host lalu menangani peristiwa untuk item host tersebut.

Contoh yang menggunakan objek Word asli

Contoh kode berikut menunjukkan cara menangani peristiwa tingkat aplikasi untuk dokumen Word. Metode ini CreateDocument membuat dokumen baru, lalu menentukan penanganan DocumentBeforeSave aktivitas yang mencegah dokumen ini disimpan. Kejadian ini adalah peristiwa tingkat aplikasi yang dinaikkan untuk Application objek, dan penanganan aktivitas harus membandingkan Doc parameter dengan document1 objek untuk menentukan apakah document1 mewakili dokumen yang disimpan.

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

Contoh yang menggunakan item host

Contoh kode berikut menyederhanakan proses ini dengan menangani BeforeSave peristiwa Document item host. Metode CreateDocument2 dalam contoh ini menghasilkan Document yang memperluas document2 objek, lalu mendefinisikan penanganan BeforeSave aktivitas yang mencegah dokumen disimpan. Penanganan aktivitas hanya dipanggil saat document2 disimpan, dan dapat membatalkan tindakan simpan tanpa melakukan pekerjaan tambahan untuk memverifikasi dokumen mana yang disimpan.

Contoh kode berikut menunjukkan tugas ini.

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

Menentukan apakah objek Office telah diperluas

Untuk menentukan apakah objek yang diperluas telah dibuat untuk objek Office asli tertentu, gunakan metode .HasVstoObject Metode ini mengembalikan true jika objek yang diperluas telah dibuat.

Gunakan metode Globals.Factory.HasVstoObject. Berikan objek Word atau Excel asli, seperti Document atau Worksheet, yang ingin Anda uji untuk objek yang diperluas.

Metode HasVstoObject ini berguna saat Anda ingin menjalankan kode hanya ketika objek Office tertentu memiliki objek yang diperluas. Misalnya, jika Anda memiliki Add-in Word VSTO yang menangani DocumentBeforeSave kejadian untuk menghapus kontrol terkelola dari dokumen sebelum disimpan, gunakan HasVstoObject metode untuk menentukan apakah dokumen telah diperluas. Jika dokumen belum diperluas, dokumen tidak dapat memiliki kontrol terkelola, dan penanganan aktivitas dapat kembali tanpa mencoba membersihkan kontrol pada dokumen.

Konten terkait