Bagikan melalui

Batasan terprogram item host dan kontrol host

  • Artikel

Setiap item host dan kontrol host dirancang untuk berperilaku seperti objek Microsoft Office Word atau Microsoft Office Excel asli terkait, dengan fungsionalitas tambahan. Namun, ada beberapa perbedaan mendasar antara perilaku item host dan kontrol host dan objek Office asli pada waktu proses.

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

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.

Membuat item host secara terprogram

Saat Anda secara terprogram membuat atau membuka dokumen, buku kerja, atau lembar kerja pada waktu proses dengan menggunakan model objek Word atau Excel, item tersebut bukan item host. Sebagai gantinya, objek baru adalah objek Office asli. Misalnya, jika Anda menggunakan Add metode untuk membuat dokumen Word baru pada waktu proses, itu akan menjadi objek asli Document daripada Document item host. Demikian pula, ketika Anda membuat lembar kerja baru pada run time menggunakan metode , Add Anda mendapatkan objek asli Worksheet daripada Worksheet item host.

Dalam proyek tingkat dokumen, Anda tidak dapat membuat item host pada waktu proses. Item host hanya dapat dibuat pada waktu desain dalam proyek tingkat dokumen. Untuk informasi selengkapnya, lihat Item host dokumen, Item host buku kerja, dan Item host lembar kerja.

Di proyek Add-in VSTO, Anda dapat membuat Documentitem , , Workbookatau Worksheet host pada waktu proses. Untuk informasi selengkapnya, lihat Memperluas dokumen Word dan buku kerja Excel di Add-in VSTO pada waktu proses.

Membuat kontrol host secara terprogram

Anda dapat secara terprogram menambahkan kontrol host ke Document item atau Worksheet host pada waktu proses. Untuk informasi selengkapnya, lihat Menambahkan kontrol ke dokumen Office pada waktu proses.

Anda tidak dapat menambahkan kontrol host ke asli Document atau Worksheet.

Catatan

Kontrol host berikut tidak dapat ditambahkan secara terprogram ke lembar kerja atau dokumen: XmlMappedRange, , XMLNodedan XMLNodes.

Memahami perbedaan jenis antara item host, kontrol host, dan objek Office asli

Untuk setiap item host dan kontrol host, ada objek Microsoft Office Word atau Microsoft Office Excel asli yang mendasar. Anda dapat mengakses objek yang mendasar dengan menggunakan properti InnerObject dari item host atau kontrol host. Namun, tidak ada cara untuk melemparkan objek Office asli ke item host atau kontrol host yang sesuai. Jika Anda mencoba mentransmisikan objek Office asli ke dalam jenis item host atau kontrol host, InvalidCastException objek akan dilemparkan.

Ada beberapa skenario di mana perbedaan antara jenis item host dan kontrol host dan objek Office asli yang mendasarinya dapat memengaruhi kode Anda.

Meneruskan kontrol host ke metode dan properti

Di Word, Anda tidak dapat meneruskan kontrol host ke metode atau properti yang memerlukan objek Word asli sebagai parameter. Anda harus menggunakan properti InnerObject kontrol host untuk mengembalikan objek Word asli yang mendasar. Misalnya, Anda dapat meneruskan Bookmark objek ke metode dengan meneruskan InnerObject properti Bookmark kontrol host ke metode .

Di Excel, Anda harus menggunakan properti InnerObject kontrol host untuk meneruskan kontrol host ke metode atau properti ketika metode atau properti mengharapkan objek Excel yang mendasar.

Contoh berikut membuat NamedRange kontrol dan meneruskannya ke AutoFill metode . Kode menggunakan properti rentang bernama untuk mengembalikan Office Range yang mendasar InnerObject yang diperlukan oleh AutoFill metode .

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Mengembalikan tipe metode dan properti Office asli

Sebagian besar metode dan properti item host mengembalikan objek Office asli yang mendasar tempat item host berada. Misalnya, Parent properti NamedRange kontrol host di Excel mengembalikan Worksheet objek daripada Worksheet item host. Demikian pula, Parent properti RichTextContentControl kontrol host di Word mengembalikan Document objek daripada Document item host.

Mengakses kumpulan kontrol host

Runtime Visual Studio Tools for Office tidak menyediakan koleksi individual untuk setiap jenis kontrol host. Sebagai gantinya, gunakan properti Kontrol item host untuk melakukan iterasi melalui semua kontrol terkelola (kontrol host dan kontrol Formulir Windows) pada dokumen atau lembar kerja, lalu cari item yang cocok dengan tipe kontrol host yang Anda minati. Contoh kode berikut memeriksa setiap kontrol pada dokumen Word dan menentukan apakah kontrolnya adalah Bookmark.

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

Untuk informasi selengkapnya tentang properti Kontrol item host, lihat Menambahkan kontrol ke dokumen Office pada waktu proses.

Model objek Word dan Excel menyertakan properti yang mengekspos kumpulan kontrol asli pada dokumen dan lembar kerja. Anda tidak dapat mengakses kontrol terkelola dengan menggunakan properti ini. Misalnya, tidak dimungkinkan untuk menghitung setiap Bookmark kontrol host dalam dokumen dengan menggunakan Bookmarks properti Document atau Bookmarks properti dari Document. Properti ini hanya Bookmark mencakup kontrol dalam dokumen; tidak berisi Bookmark kontrol host dalam dokumen.

Konten terkait