Bagikan melalui

Gambaran umum model objek pita

  • Artikel

Runtime Visual Studio Tools for Office mengekspos model objek yang sangat diketik yang bisa Anda gunakan untuk mendapatkan dan mengatur properti kontrol Pita pada waktu proses. Misalnya, Anda dapat mengisi kontrol menu secara dinamis, atau menampilkan dan menyembunyikan kontrol secara kontekstual. Anda juga bisa menambahkan tab, grup, dan kontrol ke pita, tetapi hanya sebelum pita dimuat oleh aplikasi Office likasi. Untuk informasi, lihat Mengatur properti yang menjadi baca-saja.

Berlaku untuk: Informasi dalam topik ini berlaku untuk proyek tingkat dokumen dan proyek Add-in VSTO untuk aplikasi berikut: Excel; InfoPath 2013 dan InfoPath 2010; Outlook; Powerpoint; Proyek; Visio; Kata. Untuk informasi selengkapnya, lihat Fitur yang tersedia berdasarkan aplikasi Office likasi dan jenis proyek.

Model objek Pita ini terutama terdiri dari kelas Pita, Peristiwa pita, dan kelas kontrol Pita.

Kelas pita

Saat Anda menambahkan item Pita (Visual Designer) baru ke proyek, Visual Studio menambahkan kelas Pita ke proyek Anda. Kelas Pita mewarisi dari RibbonBase kelas .

Kelas ini muncul sebagai kelas parsial yang dibagi antara file kode Pita dan file kode Perancang Pita.

Peristiwa pita

Kelas Pita berisi tiga peristiwa berikut ini:

Aktivitas Deskripsi
Load Dimunculkan saat aplikasi Office likasi memuat kustomisasi Pita. Penanganan Load aktivitas secara otomatis ditambahkan ke file kode Pita. Gunakan penanganan aktivitas ini untuk menjalankan kode kustom saat pita dimuat.
LoadImage Memungkinkan Anda menyimpan gambar dalam kustomisasi Pita saat pita dimuat. Anda bisa mendapatkan sedikit perolehan performa jika Anda menulis kode untuk menyimpan gambar Pita di penanganan aktivitas ini. Untuk informasi selengkapnya, lihat LoadImage .
Close Dimunculkan saat instans Pita ditutup.

Kontrol pita

Namespace Microsoft.Office.Tools.Ribbon berisi tipe untuk setiap kontrol yang Anda lihat di grup Kontrol Pita Office kotak Alat.

Tabel berikut ini memperlihatkan jenis untuk setiap Ribbon kontrol. Untuk deskripsi setiap kontrol, lihat Gambaran umum pita.

Nama kontrol Nama Kelas
Kotak RibbonBox
Tombol RibbonButton
Grup Tombol RibbonButtonGroup
KotakCentang RibbonCheckBox
ComboBox RibbonComboBox
Dropdown RibbonDropDown
EditBox RibbonEditBox
Galeri RibbonGallery
Grup RibbonGroup
Label RibbonLabel
Menu RibbonMenu
Pemisah RibbonSeparator
SplitButton RibbonSplitButton
Tab RibbonTab
ToggleButton RibbonToggleButton

Namespace Microsoft.Office.Tools.Ribbon menggunakan awalan "Pita" untuk tipe ini untuk menghindari tabrakan nama dengan nama kelas kontrol di System.Windows.Forms namespace layanan.

Saat Anda menambahkan kontrol ke Perancang Pita, Perancang Pita mendeklarasikan kelas untuk kontrol tersebut sebagai bidang dalam file kode Desainer Pita.

Tugas umum menggunakan properti kontrol Pita

Setiap Ribbon kontrol berisi properti yang bisa Anda gunakan untuk melakukan berbagai tugas, seperti menetapkan label ke kontrol, atau menyembunyikan dan memperlihatkan kontrol.

Dalam beberapa kasus, properti menjadi baca-saja setelah Pita dimuat atau setelah kontrol ditambahkan ke menu dinamis. Untuk informasi selengkapnya, lihat Mengatur properti yang menjadi baca-saja.

Tabel berikut ini menjelaskan beberapa tugas yang bisa Anda lakukan dengan menggunakan Ribbon properti kontrol.

Untuk tugas ini: Lakukan ini:
Sembunyikan atau perlihatkan kontrol. Gunakan properti Terlihat.
Mengaktifkan atau menonaktifkan kontrol. Gunakan properti Diaktifkan.
Atur ukuran kontrol. Gunakan properti ControlSize.
Dapatkan gambar yang muncul pada kontrol. Gunakan properti Gambar.
Mengubah label kontrol. Gunakan properti Label.
Tambahkan data yang ditentukan pengguna ke kontrol. Gunakan properti Tag.
Mendapatkan item dalam RibbonBox, , RibbonDropDownRibbonGallery, atau

RibbonSplitButton Kontrol.		 Gunakan properti Item.
Tambahkan item ke RibbonComboBoxkontrol , RibbonDropDown, atau RibbonGallery . Gunakan properti Item.
Tambahkan kontrol ke RibbonMenu. Gunakan properti Item.

Untuk menambahkan kontrol ke RibbonMenu setelah Pita dimuat ke dalam aplikasi Office likasi, Anda harus mengatur Dynamic properti ke true sebelum Pita dimuat ke dalam aplikasi Office likasi. Untuk informasi, lihat Mengatur properti yang menjadi baca-saja.
Mendapatkan item yang dipilih dari RibbonComboBox,

RibbonDropDown, atau RibbonGallery.		 Gunakan properti SelectedItem. RibbonComboBoxUntuk , gunakan Text properti .
Dapatkan grup di RibbonTab. Gunakan properti Groups.
Tentukan jumlah baris dan kolom yang muncul di RibbonGallery. RowCount Gunakan properti dan ColumnCount .

Mengatur properti yang menjadi baca-saja

Beberapa properti hanya dapat diatur sebelum pita dimuat. Ada tiga tempat untuk mengatur properti ini:

  • Di jendela Properti Visual Studio.

  • Di konstruktor kelas Pita .

  • CreateRibbonExtensibilityObject Dalam metode ThisAddin, , ThisWorkbookatau ThisDocument kelas proyek Anda.

    Menu dinamis memberikan beberapa pengecualian. Anda dapat membuat kontrol baru, mengatur propertinya, lalu menambahkannya ke menu dinamis pada waktu proses, bahkan setelah pita yang berisi menu dimuat.

    Properti kontrol yang Anda tambahkan ke menu dinamis dapat diatur kapan saja.

    Untuk informasi selengkapnya, lihat Properti yang menjadi baca-saja.

Mengatur properti di konstruktor pita

Anda bisa mengatur properti Ribbon kontrol di konstruktor kelas Pita . Kode ini harus muncul setelah panggilan ke InitializeComponent metode . Contoh berikut menambahkan tombol baru ke grup jika waktu saat ini adalah 17:00 Waktu Pasifik (UTC-8) atau yang lebih baru.

Tambahkan kode berikut.

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

Di proyek Visual C# yang Anda tingkatkan dari Visual Studio 2008, konstruktor muncul di file kode Pita.

Di proyek Visual Basic, atau di proyek Visual C# yang Anda buat di Visual Studio 2013, konstruktor muncul di file kode Desainer Pita. File ini bernama YourRibbonItem. Designer.cs atau YourRibbonItem. Designer.vb. Untuk melihat file ini di proyek Visual Basic, Anda harus terlebih dahulu mengklik tombol Perlihatkan Semua File di Penjelajah Solusi.

Mengatur properti dalam metode CreateRibbonExtensibilityObject

Anda dapat mengatur properti Ribbon kontrol saat mengambil alih CreateRibbonExtensibilityObject metode di ThisAddin, , ThisWorkbookatau ThisDocument kelas proyek Anda. Untuk informasi selengkapnya tentang metode ini CreateRibbonExtensibilityObject , lihat Gambaran Umum Pita.

Contoh berikut mengatur properti Pita dalam CreateRibbonExtensibilityObject metode ThisWorkbook kelas proyek buku kerja Excel.

Tambahkan kode berikut.

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Properti yang menjadi baca-saja

Tabel berikut ini memperlihatkan properti yang hanya bisa diatur sebelum pita dimuat.

Catatan

Anda dapat mengatur properti kontrol pada menu dinamis kapan saja. Tabel ini tidak berlaku dalam kasus tersebut.

Properti Kelas kontrol pita
BoxStyle RibbonBox
Tipe Tombol RibbonSplitButton
ColumnCount RibbonGallery
ControlId RibbonTab
DialogLauncher RibbonGroup
Dinamis RibbonMenu
Global OfficeRibbon
Grup RibbonTab
ImageName RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton
Ukuran Item RibbonMenu

RibbonSplitButton
MaxLength RibbonComboBox

RibbonEditBox
Nama RibbonComponent
Posisi RibbonButton

RibbonCheckBox

RibbonGallery

RibbonGroup

RibbonMenu

RibbonSeparator

RibbonSplitButton

RibbonTab

RibbonToggleButton
Tipe Pita OfficeRibbon
RowCount RibbonGallery
ShowItemImage RibbonComboBox

RibbonDropDown

RibbonGallery
ShowItemLabel RibbonDropDown

RibbonGallery
ShowItemSelection RibbonGallery
SizeString RibbonComboBox

RibbonDropDown

RibbonEditBox
StartFromScratch OfficeRibbon
Tab OfficeRibbon
Judul RibbonSeparator

Mengatur properti untuk pita yang muncul di pemeriksa Outlook

Instans baru pita dibuat setiap kali pengguna membuka Pemeriksa tempat pita muncul. Namun, Anda bisa mengatur properti yang tercantum dalam tabel di atas hanya sebelum instans pertama pita dibuat. Setelah instans pertama dibuat, properti ini menjadi baca-saja karena instans pertama menentukan file XML yang digunakan Outlook untuk memuat pita.

Jika Anda memiliki logika bersyarat yang mengatur salah satu properti ini ke nilai yang berbeda ketika instans pita lain dibuat, kode ini tidak akan berpengaruh.

Catatan

Pastikan bahwa properti Nama diatur untuk setiap kontrol yang Anda tambahkan ke Pita Outlook. Jika Anda menambahkan kontrol ke Pita Outlook pada waktu proses, Anda harus mengatur properti ini dalam kode Anda. Jika Anda menambahkan kontrol ke Pita Outlook pada waktu desain, properti Nama diatur secara otomatis.

Peristiwa kontrol pita

Setiap kelas kontrol berisi satu atau beberapa peristiwa. Tabel berikut ini menjelaskan peristiwa ini.

Aktivitas Deskripsi
Klik Terjadi ketika kontrol diklik.
TextChanged Terjadi saat teks kotak edit atau kotak kombo diubah.
Item Memuat Terjadi ketika kumpulan Item kontrol diminta oleh Office. Office menyimpan cache kumpulan Item hingga kode Anda mengubah properti kontrol, atau Anda memanggil metode .InvalidateControl
ButtonClick Terjadi ketika tombol dalam atau RibbonDropDown diklikRibbonGallery.
SelectionChanged Terjadi ketika pilihan dalam atau RibbonDropDown RibbonGallery berubah.
DialogLauncherClick Terjadi ketika ikon peluncur dialog di sudut kanan bawah grup diklik.

Penanganan aktivitas untuk peristiwa ini memiliki dua parameter berikut.

Parameter Deskripsi
Pengirim Yang Object mewakili kontrol yang menaikkan peristiwa.
e Yang RibbonControlEventArgs berisi IRibbonControl. Gunakan kontrol ini untuk mengakses properti apa pun yang tidak tersedia dalam model objek Pita yang disediakan oleh Visual Studio Tools untuk runtime Office .

Konten terkait