Panduan: Menambahkan kontrol ke dokumen pada waktu proses di Add-in VSTO

Anda bisa menambahkan kontrol ke dokumen Microsoft Office Word yang terbuka dengan menggunakan Add-in VSTO. Panduan ini menunjukkan cara menggunakan pita untuk memungkinkan pengguna menambahkan Button atau RichTextContentControl ke dokumen.

Berlaku untuk: Informasi dalam topik ini berlaku untuk proyek Add-in VSTO untuk Word 2010. Untuk informasi selengkapnya, lihat Fitur yang Tersedia oleh Aplikasi Office dan Jenis Proyek.

Panduan ini mengilustrasikan tugas-tugas berikut:

• Membuat proyek Add-in Word VSTO baru.

• Menyediakan antarmuka pengguna (UI) untuk menambahkan kontrol ke dokumen.

• Menambahkan kontrol ke dokumen pada waktu proses.

• Menghapus kontrol dari dokumen.

  Catatan

  Komputer Anda mungkin memperlihatkan nama atau lokasi yang berbeda untuk beberapa elemen antarmuka pengguna Visual Studio dalam petunjuk berikut. Edisi Visual Studio yang Anda miliki dan setelan yang Anda gunakan menentukan elemen-elemen ini. Untuk informasi selengkapnya, lihat Mempersonalisasi IDE.

Prasyarat

Anda memerlukan komponen berikut untuk menyelesaikan panduan ini:

• Edisi Visual Studio yang menyertakan alat pengembang Microsoft Office. Untuk informasi selengkapnya, lihat Mengonfigurasi komputer untuk mengembangkan solusi Office.

• Word 2013 atau Word 2010 .

Membuat proyek Add-in Word baru

Mulailah dengan membuat proyek Add-in Word VSTO.

Untuk membuat proyek Add-in Word VSTO baru

1. Buat proyek Add-in VSTO untuk Word dengan nama WordDynamicControls. Untuk informasi selengkapnya, lihat Cara: Membuat proyek Office di Visual Studio.

2. Tambahkan referensi ke rakitan Microsoft.Office.Tools.Word.v4.0.Utilities.dll . Referensi ini diperlukan untuk menambahkan kontrol Formulir Windows secara terprogram ke dokumen nanti dalam panduan ini.

Menyediakan UI untuk menambahkan kontrol ke dokumen

Tambahkan tab kustom ke Pita di Word. Pengguna dapat memilih kotak centang pada tab untuk menambahkan kontrol ke dokumen.

Untuk menyediakan UI untuk menambahkan kontrol ke dokumen

1. Pada menu Proyek, klik Tambahkan Item Baru.

2. Dalam kotak dialog Tambahkan Item Baru, pilih Pita (Visual Designer).

3. Ubah nama Pita baru menjadi MyRibbon, dan klik Tambahkan.

   File MyRibbon.cs atau MyRibbon.vb terbuka di Perancang Pita dan menampilkan tab dan grup default.

4. Di Perancang Pita, klik grup grup1 .

5. Di jendela Properti , ubah properti Label untuk grup1 menjadi Tambahkan Kontrol.

6. Dari tab Kontrol Pita Office dari Kotak Alat, seret kontrol Kotak Centang ke grup1.

7. Klik Centang Kotak1 untuk memilihnya.

8. Di jendela Properti , ubah properti berikut ini.

   Properti	Nilai
   Nama	tambahkanButtonCheckBox
   Label	Tombol Tambahkan

9. Tambahkan kotak centang kedua ke grup1, lalu ubah properti berikut.

   Properti	Nilai
   Nama	addRichTextCheckBox
   Label	Tambahkan Kontrol Teks Kaya

10. Di Perancang Pita, klik ganda Tombol Tambahkan.

    Penanganan Click aktivitas kotak centang Tambahkan Tombol terbuka di Editor Kode.

11. Kembali ke Perancang Pita, dan klik ganda Tambahkan Kontrol Teks Kaya.

    Penanganan Click aktivitas kotak centang Tambahkan Kontrol Teks Kaya terbuka di Editor Kode.

    Nantinya dalam panduan ini, Anda akan menambahkan kode ke penanganan aktivitas ini untuk menambahkan dan menghapus kontrol pada dokumen aktif.

Menambahkan dan menghapus kontrol pada dokumen aktif

Dalam kode Add-in VSTO, Anda harus mengonversi dokumen aktif menjadi Documentitem host sebelum dapat menambahkan kontrol. Di solusi Office, kontrol terkelola hanya dapat ditambahkan ke item host, yang bertindak sebagai kontainer untuk kontrol. Dalam proyek Add-in VSTO, item host dapat dibuat pada waktu proses dengan menggunakan GetVstoObject metode .

Tambahkan metode ke ThisAddIn kelas yang dapat dipanggil untuk menambahkan atau menghapus Button atau RichTextContentControl pada dokumen aktif. Nanti dalam panduan ini, Anda akan memanggil metode ini dari Click penanganan aktivitas kotak centang pada Pita.

Untuk menambahkan dan menghapus kontrol pada dokumen aktif

1. Di Penjelajah Solusi, klik ganda ThisAddIn.cs atau ThisAddIn.vb untuk membuka file di Editor Kode.

2. Tambahkan kode berikut ke kelas ThisAddIn. Kode ini mendeklarasikan Button dan RichTextContentControl objek yang mewakili kontrol yang akan ditambahkan ke dokumen.

   C#

   private Microsoft.Office.Tools.Word.Controls.Button button = null;
   private RichTextContentControl richTextControl = null;
   

   VB

   Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
   Private richTextControl As RichTextContentControl = Nothing
   

3. Tambahkan metode berikut ke kelas ThisAddIn. Ketika pengguna mengklik kotak centang Tambahkan Tombol pada Pita, metode ini menambahkan Button ke pilihan saat ini pada dokumen jika kotak centang dipilih, atau menghapus jika kotak centang dikosongkan Button .

   C#

   internal void ToggleButtonOnDocument()
   {
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               button = vstoDocument.Controls.AddButton(
                   selection.Range, 100, 30, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleButtonOnDocument()
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyButton"
   
       If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               button = vstoDocument.Controls.AddButton( _
                   selection.Range, 100, 30, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

4. Tambahkan metode berikut ke kelas ThisAddIn. Ketika pengguna mengklik kotak centang Tambahkan Kontrol Teks Kaya pada Pita, metode ini menambahkan RichTextContentControl ke pilihan saat ini pada dokumen jika kotak centang dipilih, atau menghapus jika kotak centang dikosongkan RichTextContentControl .

   C#

   internal void ToggleRichTextControlOnDocument()
   {
   
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   selection.Range, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleRichTextControlOnDocument()
   
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyRichTextBoxControl"
   
       If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                       selection.Range, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

Hapus kontrol Tombol saat dokumen disimpan

Formulir Windows kontrol tidak bertahan ketika dokumen disimpan lalu ditutup. Namun, pembungkus ActiveX untuk setiap kontrol tetap berada dalam dokumen, dan batas pembungkus ini dapat dilihat oleh pengguna akhir saat dokumen dibuka kembali. Ada beberapa cara untuk membersihkan kontrol Formulir Windows yang dibuat secara dinamis di Add-in VSTO. Dalam panduan ini, Anda secara terprogram menghapus Button kontrol saat dokumen disimpan.

Untuk menghapus kontrol Tombol saat dokumen disimpan

1. Dalam file kode ThisAddIn.cs atau ThisAddIn.vb, tambahkan metode berikut ke ThisAddIn kelas . Metode ini adalah penanganan aktivitas untuk peristiwa tersebut DocumentBeforeSave . Jika dokumen yang disimpan memiliki Document item host yang terkait dengannya, penanganan aktivitas mendapatkan item host dan menghapus Button kontrol, jika ada.

   C#

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
   
       if (isExtended)
       {
   
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

   VB

   Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
       ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
   
       Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
   
   
       If isExtended Then
           Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
   
   
           If vstoDocument.Controls.Contains(button) Then
               vstoDocument.Controls.Remove(button)
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
           End If
       End If
   End Sub
   

2. Di C#, tambahkan kode berikut ke penanganan ThisAddIn_Startup aktivitas. Kode ini diperlukan di C# untuk menyambungkan Application_DocumentBeforeSave penanganan aktivitas dengan DocumentBeforeSave peristiwa.

   this.Application.DocumentBeforeSave += 
       new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
       Application_DocumentBeforeSave);
   

Menambahkan dan menghapus kontrol saat pengguna mengklik kotak centang pada pita

Terakhir, ubah Click penanganan aktivitas kotak centang yang Anda tambahkan ke pita untuk menambahkan atau menghapus kontrol pada dokumen.

Untuk menambahkan atau menghapus kontrol saat pengguna mengklik kotak centang pada pita

1. Dalam file kode MyRibbon.cs atau MyRibbon.vb, ganti penanganan peristiwa dan addRichTextCheckBox_Click yang dihasilkan addButtonCheckBox_Click dengan kode berikut. Kode ini mendefinisikan ulang penanganan aktivitas ini untuk memanggil ToggleButtonOnDocument metode dan ToggleRichTextControlOnDocument yang Anda tambahkan ke ThisAddIn kelas sebelumnya dalam panduan ini.

   C#

   private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisAddIn.ToggleButtonOnDocument();
   }
   
   private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisAddIn.ToggleRichTextControlOnDocument();
   }
   

   VB

   Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
       ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
       Globals.ThisAddIn.ToggleButtonOnDocument()
   End Sub
   
   Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
       ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
       Globals.ThisAddIn.ToggleRichTextControlOnDocument()
   End Sub
   

Menguji solusi

Tambahkan kontrol ke dokumen dengan memilihnya dari tab kustom pada Pita. Saat Anda menyimpan dokumen, Button kontrol akan dihapus.

Untuk menguji solusinya.

1. Tekan F5 untuk menjalankan proyek Anda.

2. Di dokumen aktif, tekan Enter beberapa kali untuk menambahkan paragraf kosong baru ke dokumen.

3. Pilih paragraf pertama.

4. Klik tab Add-In .

5. Di grup Tambahkan Kontrol, klik Tombol Tambahkan.

   Tombol muncul di paragraf pertama.

6. Pilih paragraf terakhir.

7. Di grup Tambahkan Kontrol, klik Tambahkan Kontrol Teks Kaya.

   Kontrol konten teks kaya ditambahkan ke paragraf terakhir.

8. Simpan dokumen.

   Tombol dihapus dari dokumen.

Langkah berikutnya

Anda dapat mempelajari selengkapnya tentang kontrol di Add-in VSTO dari topik ini:

• Untuk sampel yang menunjukkan cara menambahkan banyak tipe kontrol lain ke dokumen pada waktu proses dan membuat ulang kontrol saat dokumen dibuka kembali, lihat Sampel Kontrol Dinamis Add-In Word di sampel dan panduan pengembangan Office.

• Untuk panduan yang menunjukkan cara menambahkan kontrol ke lembar kerja dengan menggunakan Add-in VSTO untuk Excel, lihat Panduan: Menambahkan kontrol ke lembar kerja pada waktu proses dalam proyek add-in VSTO.

Konten terkait

• Solusi Word
• Menambahkan kontrol ke dokumen Office pada waktu proses
• Mempertahankan kontrol dinamis di dokumen Office
• Cara: Menambahkan kontrol Formulir Windows ke dokumen Office
• Cara: Menambahkan kontrol konten ke dokumen Word
• Memperluas dokumen Word dan buku kerja Excel di Add-in VSTO pada waktu proses