Menambahkan kontrol ke dokumen Office pada waktu proses
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
, ,Sheet2
danSheet3
. 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.
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 . MetodeAddControl
mengembalikan objek yang menentukan bagaimana kontrol berinteraksi dengan lembar kerja atau dokumen. Metode mengembalikanAddControl
ControlSite (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 namarange1
. Untuk menggunakan contoh ini, jalankan dariSheet
kelas n dalam proyek.
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
, atauOLEControl
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
ControlSite
objek , ,OLEObject
atauOLEControl
.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
ControlSite
objek , ,OLEObject
atauOLEControl
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.
Konten terkait
- Kontrol pada dokumen Office
- Mempertahankan kontrol dinamis di dokumen Office
- Cara: Menambahkan kontrol ListObject ke lembar kerja
- Cara: Menambahkan kontrol NamedRange ke lembar kerja
- Cara: Menambahkan kontrol Bagan ke lembar kerja
- Cara: Menambahkan kontrol konten ke dokumen Word
- Cara: Menambahkan kontrol Bookmark ke dokumen Word
- Formulir Windows pada gambaran umum dokumen Office
- Cara: Menambahkan kontrol Formulir Windows ke dokumen Office