Gambaran umum item host dan kontrol host
Item host dan kontrol host adalah jenis yang membantu menyediakan model pemrograman untuk solusi Office yang dibuat dengan menggunakan alat pengembangan Office di Visual Studio. Item host dan kontrol host membuat interaksi dengan model objek Microsoft Office Word dan Microsoft Office Excel, yang didasarkan pada COM, lebih seperti berinteraksi dengan objek terkelola seperti kontrol Formulir Windows.
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.
Item host
Item host adalah jenis yang berada di bagian atas hierarki model objek di proyek Office. Runtime Visual Studio Tools for Office menentukan item host berikut untuk solusi Word dan Excel:
-
Masing-masing jenis ini memperluas objek yang ada secara asli dalam model objek Word atau Excel, yang disebut objek Office asli. Misalnya, Document item host memperluas Document objek, yang didefinisikan dalam perakitan interop utama untuk Word.
Item host umumnya memiliki fungsionalitas dasar yang sama dengan objek Office terkait, tetapi ditingkatkan dengan fitur berikut:
Kemampuan untuk menghosting kontrol terkelola, termasuk kontrol host dan kontrol Formulir Windows.
Model peristiwa yang lebih kaya. Beberapa peristiwa dokumen, buku kerja, dan lembar kerja dalam model objek Word dan Excel asli hanya dimunculkan di tingkat aplikasi. Item host menyediakan peristiwa ini di tingkat dokumen, sehingga lebih mudah untuk menangani peristiwa untuk dokumen tertentu.
Memahami item host dalam proyek tingkat dokumen
Dalam proyek tingkat dokumen, item host menyediakan titik masuk untuk kode Anda, dan mereka memiliki perancang yang membantu Anda mengembangkan solusi Anda.
Item Document host dan Worksheet memiliki perancang terkait yang merupakan representasi visual dokumen atau lembar kerja, seperti perancang Formulir Windows. Anda bisa menggunakan perancang ini untuk mengubah konten dokumen atau lembar kerja secara langsung di Word atau Excel, dan untuk menyeret kontrol ke permukaan desain. Untuk informasi selengkapnya, lihat Item host dokumen dan Item host lembar kerja.
Item Workbook host tidak bertindak sebagai kontainer untuk kontrol yang memiliki antarmuka pengguna. Sebaliknya, perancang untuk item host ini berfungsi sebagai baki komponen, yang memungkinkan Anda untuk menyeret komponen, seperti DataSet, ke permukaan desainnya. Untuk informasi selengkapnya, lihat Item host buku kerja.
Item host tidak dapat dibuat secara terprogram dalam proyek tingkat dokumen. Sebagai gantinya ThisDocument, gunakan kelas , ThisWorkbook, atau Sheetn yang dihasilkan Visual Studio secara otomatis dalam proyek Anda pada waktu desain. Kelas yang dihasilkan ini berasal dari item host, dan menyediakan titik masuk untuk kode Anda. Untuk informasi selengkapnya, lihat Batasan terprogram item host dan kontrol host.
Memahami item host di proyek Add-in VSTO
Saat membuat Add-in VSTO, Anda tidak memiliki akses ke item host apa pun secara default. Namun, Anda dapat membuat Documentitem host , Workbook, dan Worksheet di Add-in Word dan Excel VSTO pada waktu proses.
Setelah membuat item host, Anda dapat melakukan tugas seperti menambahkan kontrol ke dokumen. Untuk informasi selengkapnya, lihat Memperluas dokumen Word dan buku kerja Excel di Add-in VSTO pada waktu proses.
Kontrol host
Kontrol host memperluas berbagai objek antarmuka pengguna (UI) dalam model objek Word dan Excel, seperti Microsoft.Office.Interop.Word.ContentControl objek dan Range .
Kontrol host berikut ini tersedia untuk proyek Excel:
-
Kontrol host berikut ini tersedia untuk proyek Word:
-
Kontrol host yang ditambahkan ke dokumen Office berperilaku seperti objek Office asli; namun, kontrol host memiliki fungsionalitas tambahan, termasuk peristiwa dan kemampuan pengikatan data. Misalnya, saat Anda ingin mengambil peristiwa objek asli Range di Excel, Anda harus terlebih dahulu menangani peristiwa perubahan lembar kerja. Kemudian Anda harus menentukan apakah perubahan terjadi dalam Range. Sebaliknya, NamedRange kontrol host memiliki Change peristiwa yang dapat Anda tangani secara langsung.
Hubungan antara item host dan kontrol host mirip dengan hubungan antara Formulir Windows dan kontrol Formulir Windows. Sama seperti Anda akan menempatkan kontrol kotak teks pada Formulir Windows, Anda menempatkan NamedRange kontrol pada Worksheet item host. Ilustrasi berikut menunjukkan hubungan antara item host dan kontrol host.
Anda juga bisa menggunakan kontrol Formulir Windows di solusi Office Anda dengan menambahkannya langsung ke permukaan dokumen Word dan Excel. Untuk informasi selengkapnya, lihat Formulir Windows kontrol pada gambaran umum dokumen Office.
Catatan
Menambahkan kontrol host atau kontrol Formulir Windows ke subdokumen Word tidak didukung.
Menambahkan kontrol host ke dokumen Anda
Dalam proyek tingkat dokumen, Anda bisa menambahkan kontrol host ke dokumen Word atau lembar kerja Excel Anda pada waktu desain dengan cara berikut:
Tambahkan kontrol host ke dokumen Anda pada waktu desain dengan cara yang sama seperti Anda akan menambahkan objek asli.
Seret kontrol host dari Kotak Alat ke dokumen dan lembar kerja Anda. Kontrol host Excel tersedia di tab Kontrol Excel di proyek Excel, dan kontrol host Word tersedia di tab Kontrol Word di proyek Word.
Seret kontrol host dari jendela Sumber Data ke dokumen dan lembar kerja Anda. Ini memungkinkan Anda menambahkan kontrol yang sudah terikat ke data. Untuk informasi selengkapnya, lihat Mengikat data ke kontrol di solusi Office.
Dalam proyek add-in tingkat dokumen dan VSTO, Anda juga dapat menambahkan beberapa kontrol host ke dokumen pada waktu proses. Untuk informasi selengkapnya, lihat Menambahkan kontrol ke dokumen Office pada waktu proses.
Untuk informasi selengkapnya tentang cara menambahkan kontrol host ke dokumen, lihat topik berikut ini:
Kontrol host nama
Saat Anda menyeret kontrol host dari Kotak Alat ke dokumen Anda, kontrol secara otomatis diberi nama menggunakan jenis kontrol dengan nomor tambahan di akhir. Misalnya, bookmark diberi nama bookmark1, bookmark2, dan sebagainya. Jika Anda menggunakan fungsionalitas asli Word atau Excel untuk menambahkan kontrol, Anda bisa memberinya nama tertentu pada saat Anda membuatnya. Anda juga dapat mengganti nama kontrol Anda dengan mengubah nilai properti Nama di jendela Properti .
Catatan
Anda tidak dapat menggunakan kata yang dipesan untuk memberi nama kontrol host. Misalnya, jika Anda menambahkan NamedRange kontrol ke lembar kerja dan mengubah nama menjadi Sistem, kesalahan terjadi saat Anda membangun proyek.
Menghapus kontrol host
Dalam proyek tingkat dokumen, Anda bisa menghapus kontrol host pada waktu desain dengan memilih kontrol pada lembar kerja Excel atau dokumen Word dan menekan tombol Hapus . Namun, Anda harus menggunakan kotak dialog Tentukan Nama di Excel untuk menghapus NamedRange kontrol.
Jika Anda menambahkan kontrol host ke dokumen pada waktu desain, Anda tidak boleh menghapusnya secara terprogram pada waktu proses karena lain kali Anda mencoba menggunakan kontrol dalam kode, pengecualian akan dilemparkan. Metode Delete kontrol host hanya menghapus kontrol host yang ditambahkan ke dokumen pada waktu proses. Jika Anda memanggil Delete metode kontrol host yang dibuat pada waktu desain, pengecualian akan dilemparkan.
Misalnya, Delete metode hanya NamedRange berhasil menghapus NamedRange jika ditambahkan secara terprogram ke lembar kerja, yang dikenal sebagai membuat kontrol host secara dinamis. Kontrol host yang dibuat secara dinamis juga dapat dihapus dengan meneruskan nama kontrol ke Remove metode Controls properti atau Controls . Untuk informasi selengkapnya, lihat Menambahkan kontrol ke dokumen Office pada waktu proses.
Jika pengguna akhir menghapus kontrol host dari dokumen pada waktu proses, solusi mungkin gagal dengan cara yang tidak terduga. Anda bisa menggunakan fitur perlindungan dokumen di Word dan Excel untuk melindungi kontrol host agar tidak dihapus. Untuk informasi selengkapnya, lihat Sampel dan panduan pengembangan Office.
Catatan
Jangan hapus kontrol secara terprogram selama Shutdown penanganan aktivitas dokumen atau lembar kerja. Elemen UI tidak lagi tersedia saat Shutdown peristiwa terjadi. Jika Anda ingin menghapus kontrol sebelum aplikasi ditutup, tambahkan kode Anda ke penanganan aktivitas lain seperti BeforeClose atau BeforeSave.
Program terhadap peristiwa kontrol host
Salah satu cara host mengontrol perluasan objek Office adalah dengan menambahkan peristiwa. Misalnya, Range objek di Excel dan Bookmark objek di Word tidak memiliki peristiwa, tetapi runtime Visual Studio Tools for Office memperluas objek ini dengan menambahkan peristiwa yang dapat diprogram. Anda dapat mengakses dan membuat kode terhadap peristiwa ini dengan cara yang sama seperti Anda mengakses peristiwa kontrol di Formulir Windows: melalui daftar drop-down peristiwa di Visual Basic dan halaman properti peristiwa di C#. Untuk informasi selengkapnya, lihat Panduan: Program terhadap peristiwa kontrol NamedRange.
Catatan
Anda tidak boleh mengatur EnableEvents properti Application objek di Excel ke false. Mengatur properti ini ke false mencegah Excel menaikkan kejadian apa pun, termasuk kejadian kontrol host.