Bagikan melalui

Kontrol konten

  • Artikel

Kontrol konten menyediakan cara bagi Anda untuk merancang dokumen dan templat yang memiliki fitur ini:

Tentang kontrol konten

Kontrol konten menyediakan UI yang dioptimalkan untuk input dan cetak pengguna. Saat Anda menambahkan kontrol konten ke dokumen, kontrol diidentifikasi oleh batas, judul, dan teks sementara yang dapat memberikan instruksi kepada pengguna. Batas dan judul kontrol tidak muncul dalam versi dokumen yang dicetak.

Misalnya, jika Anda ingin pengguna memasukkan tanggal di bagian dokumen, Anda bisa menambahkan kontrol konten pemilih tanggal ke dokumen. Saat pengguna mengklik kontrol, UI pemilih tanggal standar akan muncul. Anda juga bisa mengatur properti kontrol untuk mengatur kalender regional yang ditampilkan dan untuk menentukan format tanggal. Setelah pengguna memilih tanggal, UI kontrol disembunyikan, dan hanya tanggal yang muncul jika pengguna mencetak dokumen.

Kontrol konten juga membantu Anda melakukan hal berikut:

  • Mencegah pengguna mengedit atau menghapus bagian dokumen. Ini berguna jika Anda memiliki informasi dalam dokumen atau templat yang harus dapat dibaca pengguna tetapi tidak dapat mengedit, atau jika Anda ingin pengguna dapat mengedit kontrol konten tetapi tidak menghapusnya.

  • Mengikat bagian dokumen atau templat ke data. Anda dapat mengikat kontrol konten ke bidang database, objek terkelola di elemen .NET Framework, XML yang disimpan dalam dokumen, dan sumber data lainnya.

    Dalam proyek tingkat dokumen, Anda dapat menambahkan kontrol konten ke dokumen Anda pada waktu desain atau pada waktu proses. Di proyek Add-in VSTO, Anda dapat menambahkan kontrol konten ke dokumen apa pun yang terbuka pada waktu proses. Untuk informasi selengkapnya, lihat Cara: Menambahkan kontrol konten ke dokumen Word.

Catatan

Anda hanya bisa menggunakan kontrol konten dalam dokumen yang disimpan dalam format Open XML. Anda tidak dapat menggunakan kontrol konten dalam dokumen yang disimpan dalam format dokumen Word 97-2003 (.doc).

Tipe kontrol konten

Ada sembilan tipe kontrol konten berbeda yang bisa Anda tambahkan ke dokumen. Sebagian besar kontrol konten memiliki jenis yang sesuai di Microsoft.Office.Tools.Word namespace layanan. Anda juga dapat menggunakan generik ContentControl, yang dapat mewakili salah satu kontrol konten yang tersedia. Untuk panduan yang menunjukkan cara menggunakan setiap kontrol konten yang tersedia, lihat Panduan: Membuat templat dengan menggunakan kontrol konten.

Galeri blok penyusun memungkinkan pengguna memilih dari daftar blok penyusun dokumen untuk disisipkan ke dalam dokumen. Blok penyusun dokumen adalah bagian dari konten yang telah dibuat untuk digunakan beberapa kali, seperti halaman sampul umum, tabel yang diformat, atau header. Untuk informasi selengkapnya, lihat jenisnya BuildingBlockGalleryContentControl . Untuk informasi selengkapnya tentang blok penyusun, lihat Apa yang baru bagi pengembang di Word 2007.

Kotak centang

Kotak centang menyediakan UI yang mewakili status biner: dipilih atau dikosongkan.

Tidak seperti tipe kontrol konten lainnya, runtime Visual Studio Tools for Office tidak menyediakan tipe tertentu yang mewakili kontrol konten kotak centang. Dengan kata lain, tidak CheckBoxContentControl ada jenis. Namun, Anda masih dapat membuat kontrol konten kotak centang dengan menambahkan generik ContentControl ke dokumen secara terprogram. Untuk informasi selengkapnya, lihat Kontrol konten kotak centang di proyek Word.

Kotak kombo

Kotak kombo menampilkan daftar item yang bisa dipilih pengguna. Tidak seperti daftar drop-down, kotak kombo memungkinkan pengguna untuk menambahkan item mereka sendiri. Untuk informasi selengkapnya, lihat jenisnya ComboBoxContentControl .

Pemilih tanggal

Pemilih tanggal menyediakan UI kalender untuk memilih tanggal. Kalender muncul saat pengguna akhir mengklik panah drop-down di kontrol. Anda bisa menggunakan kalender regional dan format tanggal yang berbeda. Untuk informasi selengkapnya, lihat jenisnya DatePickerContentControl .

Daftar drop-down menampilkan daftar item yang bisa dipilih pengguna. Tidak seperti kotak kombo, daftar drop-down tidak mengizinkan pengguna menambahkan atau mengedit item. Untuk informasi selengkapnya, lihat jenisnya DropDownListContentControl .

Grupkan

Kontrol grup menentukan wilayah dokumen yang dilindungi yang tidak dapat diedit atau dihapus pengguna. Kontrol grup dapat berisi item dokumen apa pun, seperti teks, tabel, grafik, dan kontrol konten lainnya. Untuk informasi selengkapnya, lihat jenisnya GroupContentControl .

Gambar

Kontrol gambar menampilkan gambar. Anda dapat menentukan gambar pada waktu desain atau waktu proses, atau pengguna dapat mengklik kontrol ini untuk memilih gambar yang akan disisipkan dalam dokumen. Untuk informasi selengkapnya, lihat jenisnya PictureContentControl .

Teks kaya

Kontrol teks kaya berisi teks atau item lain, seperti tabel, gambar, atau kontrol konten lainnya. Untuk informasi selengkapnya, lihat jenisnya RichTextContentControl .

Teks biasa

Kontrol teks biasa berisi teks. Kontrol teks biasa tidak boleh berisi item lain, seperti tabel, gambar, atau kontrol konten lainnya. Selain itu, semua teks dalam kontrol teks biasa memiliki pemformatan yang sama. Misalnya, jika Anda memiringkan satu kata kalimat yang berada dalam kontrol teks biasa, semua teks di dalam kontrol di miring. Untuk informasi selengkapnya, lihat jenisnya PlainTextContentControl .

Kontrol konten generik

Kontrol konten generik adalah ContentControl objek yang dapat mewakili salah satu jenis kontrol konten yang tersedia. Anda dapat mengubah ContentControl objek agar berulah seperti jenis kontrol konten yang berbeda dengan menggunakan Type properti . Misalnya, jika Anda membuat ContentControl objek yang mewakili kontrol teks biasa, Anda dapat mengubahnya pada waktu proses sehingga berperilaku seperti kotak kombo.

Anda hanya dapat membuat ContentControl objek pada waktu proses, bukan pada waktu desain. Untuk informasi selengkapnya, lihat Cara: Menambahkan kontrol konten ke dokumen Word.

Fitur umum kontrol konten

Sebagian besar kontrol konten berbagi sekumpulan anggota yang bisa Anda gunakan untuk melakukan tugas umum. Tabel berikut ini menjelaskan beberapa tugas yang bisa Anda lakukan dengan menggunakan anggota ini.

Untuk tugas ini: Lakukan ini:
Dapatkan atau atur teks yang ditampilkan dalam kontrol. Gunakan properti Teks. Catatan: Jenis PictureContentControl dan ContentControl tidak memiliki properti ini.
Dapatkan atau atur teks sementara yang ditampilkan di kontrol hingga pengguna mengedit kontrol, kontrol diisi dengan data dari sumber data, atau konten kontrol dihapus. Gunakan properti PlaceholderText. Catatan: PictureContentControl Jenis tidak memiliki properti ini.
Dapatkan atau atur judul yang ditampilkan di batas kontrol konten saat pengguna mengkliknya. Gunakan properti Judul.
Hapus kontrol dari dokumen secara otomatis setelah pengguna mengedit kontrol. (Teks dalam kontrol tetap berada di dokumen.) Gunakan properti Sementara.
Jalankan kode saat pengguna mengklik kontrol konten, atau saat kursor dipindahkan ke kontrol konten secara terprogram. Entering Tangani peristiwa kontrol.
Jalankan kode saat pengguna mengklik di luar kontrol konten, atau saat kursor dipindahkan di luar kontrol konten secara terprogram. Exiting Tangani peristiwa kontrol.
Jalankan kode setelah kontrol konten ditambahkan ke dokumen sebagai hasil dari operasi ulang atau batalkan. Added Tangani peristiwa kontrol.
Jalankan kode tepat sebelum kontrol konten dihapus dari dokumen. Deleting Tangani peristiwa kontrol.

Lindungi bagian dokumen dengan menggunakan kontrol konten

Saat Anda memproteksi bagian dari dokumen, Anda mencegah pengguna mengubah atau menghapus konten di bagian dokumen tersebut. Ada beberapa cara untuk melindungi bagian dokumen dengan menggunakan kontrol konten.

Jika area yang ingin Anda lindungi berada di dalam kontrol konten, Anda bisa menggunakan properti kontrol konten untuk mencegah pengguna mengedit atau menghapus kontrol:

  • Properti LockContents mencegah pengguna mengedit konten.

  • Properti LockContentControl mencegah pengguna menghapus kontrol.

    Jika area yang ingin Anda lindungi tidak berada di dalam kontrol konten, atau jika Anda ingin melindungi area yang berisi kontrol konten dan jenis konten lainnya, Anda dapat menempatkan seluruh area dalam GroupContentControl. Tidak seperti kontrol konten lainnya, GroupContentControl tidak menyediakan UI yang terlihat oleh pengguna. Satu-satunya tujuannya adalah untuk menentukan wilayah yang tidak dapat diedit pengguna.

Catatan

Jika Anda membuat GroupContentControl yang berisi kontrol konten yang disematkan, kontrol konten yang disematkan tidak dilindungi secara otomatis. Anda harus menggunakan properti LockContents dari setiap kontrol yang disematkan untuk mencegah pengguna mengedit konten mereka.

Untuk informasi selengkapnya tentang cara menggunakan kontrol konten untuk melindungi bagian dokumen, lihat Cara: Melindungi bagian dokumen dengan menggunakan kontrol konten.

Mengikat data ke kontrol konten

Anda bisa menampilkan data dalam dokumen dengan mengikat kontrol konten ke sumber data. Saat sumber data diperbarui, kontrol konten mencerminkan perubahan. Anda juga dapat menyimpan perubahan kembali ke sumber data.

Kontrol konten menyediakan opsi pengikatan data berikut:

  • Anda dapat mengikat kontrol konten ke bidang database atau objek terkelola dengan menggunakan model pengikatan data yang sama dengan Formulir Windows.

  • Anda dapat mengikat kontrol konten ke elemen dalam bagian XML (juga bernama bagian XML kustom) yang disematkan dalam dokumen.

    Untuk gambaran umum pengikatan kontrol host di solusi Office ke data, lihat Mengikat data ke kontrol di solusi Office.

Menggunakan model pengikatan data Formulir Windows

Sebagian besar kontrol konten mendukung model pengikatan data sederhana yang Formulir Windows gunakan. Pengikatan data sederhana berarti bahwa kontrol terikat ke satu elemen data, seperti nilai dalam kolom tabel data. Untuk informasi selengkapnya, lihat Pengikatan dan Formulir Windows data.

Dalam proyek tingkat dokumen, Anda dapat mengikat data ke kontrol konten dengan menggunakan jendela Sumber Data di Visual Studio. Untuk informasi selengkapnya tentang cara menambahkan kontrol konten terikat data ke dokumen, lihat Cara: Mengisi dokumen dengan data dari database dan Cara: Mengisi dokumen dengan data dari objek.

Tabel berikut ini mencantumkan kontrol konten yang bisa Anda ikat ke setiap tipe data di jendela Sumber Data.

Jenis data Kontrol konten default Kontrol konten lain yang dapat terikat ke tipe data ini
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Byte array		 PictureContentControl Tidak

Dalam proyek Add-in tingkat dokumen dan VSTO, Anda dapat mengikat kontrol konten ke sumber data secara terprogram dengan menggunakan Add metode DataBindings properti kontrol. Jika Anda melakukan ini, teruskan string Teks ke parameter propertyName metode Add . Properti Teks adalah properti pengikatan data default kontrol konten.

Kontrol konten juga mendukung pengikatan data dua arah, di mana perubahan dalam kontrol diperbarui ke sumber data. Untuk informasi selengkapnya, lihat Cara: Memperbarui sumber data dengan data dari kontrol host.

Catatan

Kontrol konten tidak mendukung pengikatan data yang kompleks. Jika Anda mengikat DropDownListContentControl atau ComboBoxContentControl ke sumber data dengan menggunakan model data Formulir Windows, pengguna hanya akan melihat satu nilai saat mereka mengklik kontrol. Jika Anda ingin mengikat kontrol ini ke sekumpulan nilai data yang dapat dipilih pengguna, Anda dapat mengikat kontrol ini ke elemen di bagian XML kustom.

Mengikat kontrol konten ke bagian XML kustom

Anda dapat mengikat beberapa kontrol konten ke elemen di bagian XML kustom yang disematkan dalam dokumen. Untuk informasi selengkapnya tentang bagian XML kustom, lihat Gambaran umum bagian XML kustom.

Untuk mengikat kontrol konten ke elemen di bagian XML kustom, gunakan properti XMLMapping kontrol. Contoh kode berikut menunjukkan cara mengikat PlainTextContentControl Price elemen di bawah Product simpul di bagian XML kustom yang telah ditambahkan ke dokumen.

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

Untuk panduan yang menunjukkan cara mengikat kontrol konten ke bagian XML kustom secara lebih rinci, lihat Panduan: Mengikat kontrol konten ke bagian XML kustom.

Saat Anda mengikat kontrol konten ke bagian XML kustom, pengikatan data dua arah diaktifkan secara otomatis. Jika pengguna mengedit teks dalam kontrol, elemen XML yang sesuai akan diperbarui secara otomatis. Demikian pula, jika nilai elemen di bagian XML kustom diubah, kontrol konten yang terikat ke elemen XML akan menampilkan data baru.

Anda bisa mengikat tipe kontrol konten berikut ke bagian XML kustom:

Peristiwa pengikatan data untuk kontrol konten

Semua kontrol konten menyediakan serangkaian peristiwa yang dapat Anda tangani untuk melakukan tugas terkait data, seperti memvalidasi bahwa teks dalam kontrol memenuhi kriteria tertentu sebelum sumber data diperbarui. Tabel berikut mencantumkan peristiwa kontrol konten yang terkait dengan pengikatan data.

Task Aktivitas
Jalankan kode tepat sebelum Word secara otomatis memperbarui teks dalam kontrol konten yang terikat ke bagian XML kustom. ContentUpdating
Jalankan kode tepat sebelum Word secara otomatis memperbarui data di bagian XML kustom yang terikat ke kontrol konten (yaitu, setelah teks dalam kontrol konten berubah). StoreUpdating
Jalankan kode Anda sendiri untuk memvalidasi konten kontrol sesuai dengan kriteria kustom. Validating
Jalankan kode setelah konten kontrol berhasil divalidasi. Validated

Batasan kontrol konten

Saat Anda menggunakan kontrol konten di proyek Office Anda, ketahui batasan berikut.

Perbedaan perilaku antara waktu desain dan runtime

Banyak batasan yang diberlakukan Microsoft Office Word pada kontrol konten pada waktu proses tidak diberlakukan pada waktu desain. Saat Anda merancang antarmuka pengguna solusi tingkat dokumen di Visual Studio, pastikan untuk memodifikasi kontrol konten hanya dengan cara yang didukung pada waktu proses.

Jika Anda mengubah kontrol konten pada waktu desain dengan cara yang tidak didukung kontrol pada waktu proses, perancang Visual Studio tidak akan memberi tahu Anda tentang perubahan yang tidak didukung. Namun, saat Anda men-debug atau menjalankan proyek, atau jika Anda menyimpan lalu membuka kembali proyek, Word akan menampilkan pesan kesalahan dan meminta izin untuk memperbaiki dokumen. Saat Anda memperbaiki dokumen, Word menghapus semua konten dan pemformatan yang tidak didukung dari kontrol.

Misalnya, Word tidak mencegah Anda menambahkan tabel ke PlainTextContentControl waktu desain. Namun, karena PlainTextContentControl objek tidak boleh berisi tabel pada waktu proses, Word akan menampilkan pesan kesalahan saat dokumen dibuka.

Perhatikan juga bahwa banyak properti yang menentukan perilaku kontrol konten tidak berpengaruh pada waktu desain. Misalnya, jika Anda mengatur properti LockContents dari kontrol konten ke True pada waktu desain, Anda masih dapat mengedit teks dalam kontrol di perancang Visual Studio. Properti ini hanya mencegah pengguna mengedit kontrol pada waktu proses.

Batasan peristiwa

Kontrol konten tidak menyediakan peristiwa yang dimunculkan saat pengguna mengubah teks atau item lain dalam kontrol. Misalnya, tidak ada peristiwa yang dimunculkan saat pengguna memilih item lain dalam DropDownListContentControl atau ComboBoxContentControl.

Untuk menentukan kapan pengguna mengedit konten kontrol konten, Anda dapat mengikat kontrol ke bagian XML kustom, lalu menangani peristiwa tersebut StoreUpdating . Kejadian ini dimunculkan ketika pengguna mengubah konten kontrol yang terikat ke bagian XML kustom. Untuk panduan yang menunjukkan cara mengikat kontrol konten ke bagian XML kustom, lihat Panduan: Mengikat kontrol konten ke bagian XML kustom.

Kotak centang kontrol konten dalam proyek Word

Word 2010 memperkenalkan tipe kontrol konten baru yang mewakili kotak centang. Namun, runtime Visual Studio Tools for Office tidak menyediakan jenis CheckBoxContentControl yang sesuai untuk Anda gunakan di proyek Office. Untuk membuat kontrol konten kotak centang di proyek Word 2013 atau Word 2010, gunakan AddContentControl metode untuk membuat ContentControl objek, dan teruskan wdContentControlCheckBox nilai ke metode untuk menentukan kontrol konten kotak centang. Cuplikan kode berikut menunjukkan cara melakukannya:

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

Konten terkait