Bagikan melalui

Menambahkan kontrol ke dokumen Office pada waktu proses

  • Artikel

Anda bisa menambahkan kontrol ke dokumen Microsoft Office Word dan buku kerja Microsoft Office Excel pada waktu proses. Anda juga dapat menghapusnya pada waktu proses. Kontrol yang Anda tambahkan atau hapus pada waktu proses disebut kontrol dinamis.

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

Topik ini menjelaskan hal berikut:

Mengelola kontrol pada waktu proses dengan menggunakan koleksi kontrol

Untuk menambahkan, mendapatkan, atau menghapus kontrol pada waktu proses, gunakan metode pembantu ControlCollection dan ControlCollection objek.

Cara Anda mengakses objek ini tergantung pada jenis proyek yang Anda kembangkan:

  • Dalam proyek tingkat dokumen untuk Excel, gunakan Controls properti kelas Sheet1, , Sheet2dan Sheet3 . Untuk informasi selengkapnya tentang kelas ini, lihat Item host lembar kerja.

  • Dalam proyek tingkat dokumen untuk Word, gunakan Controls properti ThisDocument kelas . Untuk informasi selengkapnya tentang kelas ini, lihat Item host dokumen.

  • Dalam proyek Add-in VSTO untuk Excel atau Word, gunakan Controls properti dari Worksheet atau Document yang Anda hasilkan pada waktu proses. Untuk informasi selengkapnya tentang membuat objek ini pada waktu proses, lihat Memperluas dokumen Word dan buku kerja Excel di Add-in VSTO pada waktu proses.

Menambahkan kontrol

Jenis ControlCollection dan ControlCollection menyertakan metode pembantu yang bisa Anda gunakan untuk menambahkan kontrol host dan kontrol Formulir Windows umum ke dokumen dan lembar kerja. Setiap nama metode memiliki kelas kontrol formatAdd, di mana kelas kontrol adalah nama kelas kontrol yang ingin Anda tambahkan. Misalnya, untuk menambahkan NamedRange kontrol ke dokumen Anda, gunakan metode .AddNamedRange

Contoh kode berikut menambahkan NamedRange ke Sheet1 dalam proyek tingkat dokumen untuk Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Mengakses dan menghapus kontrol

Anda dapat menggunakan Controls properti atau WorksheetDocument untuk melakukan iterasi melalui semua kontrol dalam dokumen Anda, termasuk kontrol yang Anda tambahkan pada waktu desain. Kontrol yang Anda tambahkan pada waktu desain juga disebut kontrol statis.

Anda dapat menghapus kontrol dinamis dengan memanggil Delete metode kontrol, atau dengan memanggil Remove metode setiap koleksi Kontrol. Contoh kode berikut menggunakan Remove metode untuk menghapus NamedRange dari Sheet1 dalam proyek tingkat dokumen untuk Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Anda tidak dapat menghapus kontrol statis pada waktu proses. Jika Anda mencoba menggunakan Delete metode atau Remove untuk menghapus kontrol statis, akan CannotRemoveControlException dilemparkan.

Catatan

Jangan hapus kontrol secara terprogram dalam Shutdown penanganan aktivitas dokumen. Elemen UI dokumen tidak lagi tersedia saat Shutdown peristiwa dinaikkan. Jika Anda ingin menghapus kontrol sebelum dokumen ditutup, tambahkan kode Anda ke penanganan aktivitas untuk kejadian lain, seperti BeforeClose atau BeforeSave untuk Word, atau BeforeClose, atau BeforeSave untuk Excel.

Menambahkan kontrol host ke dokumen

Ketika Anda secara terprogram menambahkan kontrol host ke dokumen, Anda harus memberikan nama yang secara unik mengidentifikasi kontrol, dan Anda harus menentukan tempat untuk menambahkan kontrol pada dokumen. Untuk instruksi tertentu, lihat topik berikut:

Untuk informasi selengkapnya tentang kontrol host, lihat Gambaran umum item host dan kontrol host.

Saat dokumen disimpan lalu ditutup, semua kontrol host yang dibuat secara dinamis terputus dari peristiwa mereka dan kehilangan fungsi pengikatan data mereka. Anda dapat menambahkan kode ke solusi Anda untuk membuat ulang kontrol host saat dokumen dibuka kembali. Untuk informasi selengkapnya, lihat Mempertahankan kontrol dinamis di dokumen Office.

Catatan

Metode pembantu tidak disediakan untuk kontrol host berikut, karena kontrol ini tidak dapat ditambahkan secara terprogram ke dokumen: XmlMappedRange, , XMLNodedan XMLNodes.

Menambahkan kontrol Formulir Windows ke dokumen

Saat Anda menambahkan kontrol Formulir Windows secara terprogram ke dokumen, Anda harus menyediakan lokasi kontrol dan nama yang secara unik mengidentifikasi kontrol. Runtime Visual Studio Tools for Office menyediakan metode pembantu untuk setiap kontrol. Metode ini kelebihan beban sehingga Anda dapat melewati rentang atau koordinat tertentu untuk lokasi kontrol.

Saat dokumen disimpan lalu ditutup, semua kontrol Formulir Windows yang dibuat secara dinamis akan dihapus dari dokumen. Anda dapat menambahkan kode ke solusi Anda untuk membuat ulang kontrol saat dokumen dibuka kembali. Jika Anda membuat kontrol Formulir Windows dinamis dengan menggunakan Add-in VSTO, pembungkus ActiveX untuk kontrol dibiarkan dalam dokumen. Untuk informasi selengkapnya, lihat Mempertahankan kontrol dinamis di dokumen Office.

Catatan

Formulir Windows kontrol tidak dapat ditambahkan secara terprogram ke dokumen yang dilindungi. Jika Anda secara terprogram membuka proteksi dokumen Word atau lembar kerja Excel untuk menambahkan kontrol, Anda harus menulis kode tambahan untuk menghapus pembungkus ActiveX kontrol saat dokumen ditutup. Pembungkus ActiveX kontrol tidak dihapus secara otomatis dari dokumen yang dilindungi.

Menambahkan kontrol kustom

Jika Anda ingin menambahkan Control yang tidak didukung oleh metode pembantu yang tersedia, seperti kontrol pengguna kustom, gunakan metode berikut:

  • Untuk Excel, gunakan salah AddControl satu metode ControlCollection objek.

  • Untuk Word, gunakan salah AddControl satu metode ControlCollection objek.

    Untuk menambahkan kontrol, berikan Control, lokasi untuk kontrol, dan nama yang secara unik mengidentifikasi kontrol ke AddControl metode . Metode AddControl mengembalikan objek yang menentukan bagaimana kontrol berinteraksi dengan lembar kerja atau dokumen. Metode mengembalikan AddControlControlSite (untuk Excel) atau ControlSite objek (untuk Word).

    Contoh kode berikut menunjukkan cara menggunakan AddControl metode untuk menambahkan kontrol pengguna kustom secara dinamis ke lembar kerja dalam proyek Excel tingkat dokumen. Dalam contoh ini, kontrol pengguna diberi nama UserControl1, dan Range diberi nama range1. Untuk menggunakan contoh ini, jalankan dari Sheetkelas n dalam proyek.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Menggunakan anggota kontrol kustom

Setelah menggunakan salah AddControl satu metode untuk menambahkan kontrol ke lembar kerja atau dokumen, Anda sekarang memiliki dua objek kontrol yang berbeda:

  • Control yang mewakili kontrol kustom.

  • Objek ControlSite, OLEObject, atau OLEControl yang mewakili kontrol setelah ditambahkan ke lembar kerja atau dokumen.

    Banyak properti dan metode dibagikan di antara kontrol ini. Penting bagi Anda untuk mengakses anggota ini melalui kontrol yang sesuai:

  • Untuk mengakses anggota yang hanya termasuk dalam kontrol kustom, gunakan Control.

  • Untuk mengakses anggota yang dibagikan oleh kontrol, gunakan ControlSiteobjek , , OLEObjectatau OLEControl .

    Jika Anda mengakses anggota bersama dari Control, mungkin gagal tanpa peringatan atau pemberitahuan, atau dapat menghasilkan hasil yang tidak valid. Selalu gunakan metode atau properti ControlSiteobjek , , OLEObjectatau OLEControl kecuali metode atau properti yang diperlukan tidak tersedia; hanya dengan begitu Anda harus mereferensikan Control.

    Misalnya, kelas ControlSite dan Control kelas memiliki Top properti. Untuk mendapatkan atau mengatur jarak antara bagian atas kontrol dan bagian atas dokumen, gunakan Top properti , bukan Top properti dari ControlControlSite.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Konten terkait