Cara VSPackages menambahkan elemen antarmuka pengguna

VSPackage dapat menambahkan elemen antarmuka pengguna (UI), misalnya, menu, toolbar, dan jendela alat, ke Visual Studio dengan menggunakan file .vsct .

Anda dapat menemukan panduan desain untuk elemen UI di panduan pengalaman pengguna Visual Studio.

Arsitektur tabel perintah Visual Studio

Seperti yang disebutkan, arsitektur tabel perintah mendukung prinsip arsitektur yang sudah ada di atas. Tenet di balik abstraksi, struktur data, dan alat arsitektur tabel perintah adalah sebagai berikut:

Ada tiga jenis item dasar: menu, perintah, dan grup. Menu dapat diekspos di UI sebagai menu, submenu, toolbar, atau jendela alat. Perintah adalah prosedur yang dapat dijalankan pengguna di IDE, dan mereka dapat diekspos sebagai item menu, tombol, kotak daftar, atau kontrol lainnya. Grup adalah kontainer untuk menu dan perintah.
Setiap item ditentukan oleh definisi yang menjelaskan item, prioritasnya relatif terhadap item lain, dan bendera yang mengubah perilakunya.
Setiap item memiliki posisi yang menjelaskan hierarki induk item. Item dapat memiliki beberapa induk, sehingga dapat muncul di beberapa lokasi di UI.

Setiap perintah harus memiliki grup sebagai induknya, meskipun itu adalah satu-satunya anak dalam grup tersebut. Setiap menu standar juga harus memiliki grup induk. Bilah alat dan jendela alat bertindak sebagai orang tua mereka sendiri. Grup dapat memiliki sebagai induknya bilah menu Visual Studio utama, atau menu, toolbar, atau jendela alat apa pun.

Bagaimana item ditentukan

File .vsct diformat dalam XML. Ini mendefinisikan elemen UI untuk paket dan menentukan di mana elemen tersebut muncul di IDE. Setiap menu, grup, atau perintah dalam paket pertama-tama diberi GUID dan ID di bagian .Symbols Di seluruh file .vsct lainnya, setiap menu, perintah, dan grup diidentifikasi oleh kombinasi GUID dan ID-nya. Contoh berikut menunjukkan bagian umum Symbols seperti yang dihasilkan oleh templat paket Visual Studio saat Perintah Menu dipilih dalam templat.

<Symbols>
  <!-- This is the package guid. -->
  <GuidSymbol name="guidMenuTextPkg" value="{b1253bc6-d266-402b-89e7-5e3d3b22c746}" />

  <!-- This is the guid used to group the menu commands together -->
  <GuidSymbol name="guidMenuTextCmdSet" value="{a633d4e4-6c65-4436-a138-1abeba7c9a69}">
    <IDSymbol name="MyMenuGroup" value="0x1020" />
    <IDSymbol name="cmdidMyCommand" value="0x0100" />
  </GuidSymbol>

  <GuidSymbol name="guidImages" value="{53323d9a-972d-4671-bb5b-9e418480922f}">
    <IDSymbol name="bmpPic1" value="1" />
    <IDSymbol name="bmpPic2" value="2" />
    <IDSymbol name="bmpPicSearch" value="3" />
    <IDSymbol name="bmpPicX" value="4" />
    <IDSymbol name="bmpPicArrows" value="5" />
  </GuidSymbol>
</Symbols>

Elemen tingkat atas bagian Symbols adalah elemen GuidSymbol. GuidSymbol elemen memetakan nama ke GUID yang digunakan oleh IDE untuk mengidentifikasi paket dan bagian komponennya.

Nota

GUID dihasilkan secara otomatis oleh templat paket Visual Studio. Anda juga dapat membuat GUID unik dengan mengklik Buat GUID pada menu Alat .

Elemen pertama GuidSymbol , guid<PackageName>Pkg, adalah GUID dari paket itu sendiri. Ini adalah GUID yang digunakan oleh Visual Studio untuk memuat paket. Biasanya, ia tidak memiliki elemen turunan.

Menurut konvensi, menu dan perintah dikelompokkan di bawah elemen kedua GuidSymbol , guid<PackageName>CmdSet, dan bitmap berada di bawah elemen ketiga GuidSymbol , guidImages. Anda tidak perlu mengikuti konvensi ini, tetapi setiap menu, grup, perintah, dan bitmap harus merupakan anak dari GuidSymbol elemen.

Dalam elemen kedua GuidSymbol , yang mewakili kumpulan perintah paket, adalah beberapa IDSymbol elemen. Setiap elemen IDSymbol memetakan nama ke nilai numerik, dan dapat mewakili menu, grup, atau perintah yang merupakan bagian dari set perintah. Elemen IDSymbol dalam elemen ketiga GuidSymbol mewakili bitmap yang dapat digunakan sebagai ikon untuk perintah. Karena pasangan GUID/ID harus unik dalam aplikasi, tidak ada dua anak dari elemen yang sama GuidSymbol yang mungkin memiliki nilai yang sama.

Menu, grup, dan perintah

Saat menu, grup, atau perintah memiliki GUID dan ID, itu dapat ditambahkan ke IDE. Setiap elemen UI harus memiliki hal-hal berikut:

Atribut guid yang sesuai dengan nama elemen GuidSymbol di bawah mana elemen UI didefinisikan.
Atribut id yang cocok dengan nama elemen terkait IDSymbol .

Bersama-sama, guid atribut dan id menyusun tanda tangan elemen UI.

Atribut priority yang menentukan penempatan elemen UI di menu atau grup induknya.
Elemen Induk yang memiliki guid atribut dan id yang menentukan tanda tangan menu atau grup induk.

Atribut type yang menentukan apakah menu akan muncul di IDE sebagai jenis menu atau sebagai toolbar.
Elemen Strings yang berisi elemen ButtonText, yang menjabarkan judul menu di IDE, dan elemen CommandName, yang menjabarkan nama yang digunakan di jendela Perintah untuk mengakses menu.
Tanda opsional. Elemen CommandFlag dapat muncul dalam definisi menu untuk mengubah tampilan atau perilakunya di IDE.

Setiap Menu elemen harus memiliki grup sebagai induknya, kecuali itu adalah elemen yang dapat ditambat seperti toolbar. Menu yang dapat ditampung adalah induknya sendiri. Untuk informasi selengkapnya tentang menu dan nilai untuk type atribut, lihat dokumentasi Elemen menu .

Contoh berikut menunjukkan menu yang muncul di bilah menu Visual Studio, di samping menu Alat .

<Menu guid="guidTopLevelMenuCmdSet" id="TopLevelMenu" priority="0x700" type="Menu">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_TOOLSADDINS" />
  <Strings>
    <ButtonText>TestMenu</ButtonText>
    <CommandName>TestMenu</CommandName>
  </Strings>
</Menu>

Groups

Grup adalah item yang ditentukan di bagian Groups dari file .vsct. Grup hanyalah kontainer. Mereka tidak muncul di IDE kecuali sebagai garis pembagian pada menu. Oleh karena itu, elemen Grup hanya didefinisikan oleh tanda tangan, prioritas, dan induknya.

Grup dapat memiliki menu, grup lain, atau grup itu sendiri sebagai induk. Namun, induk biasanya merupakan menu atau toolbar. Menu dalam contoh sebelumnya merupakan bagian dari grup IDG_VS_MM_TOOLSADDINS, dan grup tersebut adalah bagian dari bilah menu Visual Studio. Grup dalam contoh berikut adalah anak dari menu dalam contoh sebelumnya.

<Group guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" priority="0x0600">
  <Parent guid="guidTopLevelMenuCmdSet" id="TopLevelMenu"/>
</Group>

Karena merupakan bagian dari menu, grup ini biasanya akan berisi perintah. Namun, itu juga bisa berisi menu lain. Ini adalah bagaimana submenu didefinisikan, seperti yang ditunjukkan dalam contoh berikut.

<Menu guid="guidTopLevelMenuCmdSet" id="SubMenu" priority="0x0100" type="Menu">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup"/>
  <Strings>
    <ButtonText>Sub Menu</ButtonText>
    <CommandName>Sub Menu</CommandName>
  </Strings>
</Menu>

Commands

Perintah yang disediakan untuk IDE didefinisikan sebagai elemen Tombol atau elemen Combo. Untuk muncul pada menu atau bilah alat, perintah harus memiliki grup sebagai induknya.

Buttons

Tombol didefinisikan di bagian Buttons . Setiap item menu, tombol, atau elemen lain yang diklik pengguna untuk menjalankan satu perintah dianggap sebagai tombol. Beberapa jenis tombol juga dapat menyertakan fungsionalitas daftar. Tombol memiliki atribut wajib dan opsional yang sama dengan yang dimiliki menu, dan juga dapat memiliki elemen Ikon yang menentukan GUID dan ID bitmap yang mewakili tombol dalam IDE. Untuk informasi selengkapnya tentang tombol dan atributnya, lihat dokumentasi elemen Tombol .

Tombol dalam contoh berikut adalah anak dari grup dalam contoh sebelumnya, dan akan muncul di IDE sebagai item menu pada menu induk grup tersebut.

<Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidTestCommand</CommandName>
    <ButtonText>Test Command</ButtonText>
  </Strings>
</Button>

Combo

Kombo didefinisikan di bagian Combos . Setiap Combo elemen mewakili kotak daftar drop-down di IDE. Kotak daftar mungkin atau mungkin tidak dapat ditulis oleh pengguna, tergantung pada nilai type atribut kombo. Kombo memiliki elemen dan perilaku yang sama dengan yang dimiliki tombol, dan juga dapat memiliki atribut tambahan berikut:

Atribut defaultWidth yang menentukan lebar piksel.
Atribut idCommandList yang menentukan daftar yang berisi item yang ditampilkan dalam kotak daftar. Daftar perintah harus dideklarasikan dalam simpul yang sama GuidSymbol yang berisi kombo.

Contoh berikut mendefinisikan elemen kombo.

<Combos>
  <Combo guid="guidFirstToolWinCmdSet"
         id="cmdidWindowsMediaFilename"
         priority="0x0100" type="DynamicCombo"
         idCommandList="cmdidWindowsMediaFilenameGetList"
         defaultWidth="130">
    <Parent guid="guidFirstToolWinCmdSet"
            id="ToolbarGroupID" />
    <CommandFlag>IconAndText</CommandFlag>
    <CommandFlag>CommandWellOnly</CommandFlag>
    <CommandFlag>StretchHorizontally</CommandFlag>
    <Strings>
      <CommandName>Filename</CommandName>
      <ButtonText>Enter a Filename</ButtonText>
    </Strings>
  </Combo>
</Combos>

Bitmap

Perintah yang akan ditampilkan bersama dengan ikon harus menyertakan Icon elemen yang mengacu pada bitmap dengan menggunakan GUID dan ID-nya. Setiap bitmap didefinisikan sebagai elemen Bitmap di bagian .Bitmaps Satu-satunya atribut Bitmap yang diperlukan untuk definisi adalah guid dan href, yang menunjuk file sumber. Jika file sumber adalah strip sumber daya, atribut usedList juga diperlukan, untuk mencantumkan gambar yang tersedia di strip. Untuk informasi selengkapnya, lihat dokumentasi elemen Bitmap .

Orangtua

Aturan berikut mengatur bagaimana item dapat memanggil item lain sebagai induknya.

Elemen	Ditentukan di bagian Tabel Perintah ini	Dapat dimuat (sebagai induk, atau berdasarkan penempatan di bagian `CommandPlacements` , atau keduanya)	Mungkin berisi (disebut sebagai induk)
Kelompok	Elemen Grup, IDE, dan VSPackages lainnya	Menu, grup, item itu sendiri	Menu, grup, dan perintah
Daftar Pilihan	Elemen menu, IDE, paket VS lainnya	1 hingga n grup	0 hingga n grup
Toolbar	Elemen menu, IDE, dan VSPackages lainnya	Barang itu sendiri	0 hingga n grup
Menu Item	Elemen tombol, IDE, VSPackages lainnya	Grup 1 hingga n , item itu sendiri	-0 hingga n grup
Button	Elemen tombol, IDE, VSPackages lainnya	Grup 1 hingga n , item itu sendiri
Kombo	Elemen combos, IDE, VSPackages lainnya	Grup 1 hingga n , item itu sendiri

Menu, grup, atau perintah dapat muncul di lebih dari satu lokasi di IDE. Agar item muncul di beberapa lokasi, item harus ditambahkan ke bagian CommandPlacements sebagai elemen CommandPlacement. Menu, grup, atau perintah apa pun dapat ditambahkan sebagai penempatan perintah. Namun, toolbar tidak dapat diposisikan dengan cara ini karena tidak dapat muncul di beberapa lokasi sensitif konteks.

Penempatan perintah memiliki atribut guid, id, dan priority. GUID dan ID harus cocok dengan item yang diposisikan. Atribut priority mengatur penempatan item sehubungan dengan item lain. Ketika IDE menggabungkan dua item atau lebih yang memiliki prioritas yang sama, penempatannya tidak terdefinisi karena IDE tidak menjamin bahwa sumber daya paket dibaca dalam urutan yang sama setiap kali paket dibuat.

Jika menu atau grup muncul di beberapa lokasi, semua turunan menu atau grup tersebut akan muncul di setiap instans.

Visibilitas dan konteks perintah

Ketika beberapa VSPackages diinstal, banyak menu, item menu, dan toolbar dapat memenuhi IDE. Untuk menghindari masalah ini, Anda dapat mengontrol visibilitas elemen UI individual dengan menggunakan batasan visibilitas dan bendera perintah.

Batasan visibilitas

Batasan visibilitas ditetapkan sebagai elemen VisibilityItem di bagian VisibilityConstraints. Batasan visibilitas menentukan konteks UI tertentu di mana item target terlihat. Menu atau perintah yang disertakan di bagian ini hanya terlihat ketika salah satu konteks yang ditentukan aktif. Jika menu atau perintah tidak dirujuk di bagian ini, menu atau perintah selalu terlihat secara default. Bagian ini tidak berlaku untuk grup.

VisibilityItem elemen harus memiliki tiga atribut, sebagai berikut: guid dan id dari elemen UI target, dan context. Atribut context menentukan kapan item target akan terlihat, dan mengambil konteks UI yang valid sebagai nilainya. Konstanta konteks UI untuk Visual Studio adalah anggota VSConstants kelas. Setiap VisibilityItem elemen hanya dapat mengambil satu nilai konteks. Untuk menerapkan konteks kedua, buat elemen kedua VisibilityItem yang menunjuk ke item yang sama, seperti yang ditunjukkan dalam contoh berikut.

<VisibilityConstraints>
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasSingleProject" />
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasMultipleProjects" />
</VisibilityConstraints>

Bendera perintah

Bendera perintah berikut dapat memengaruhi visibilitas menu dan perintah yang diterapkan.

AlwaysCreate Menu dibuat meskipun tidak memiliki grup atau tombol.

Berlaku untuk: Menu

CommandWellOnly Terapkan bendera ini jika perintah tidak muncul di menu tingkat atas dan Anda ingin membuatnya tersedia untuk kustomisasi shell tambahan, misalnya, mengikatnya ke kunci. Setelah VSPackage diinstal, pengguna dapat menyesuaikan perintah ini dengan membuka kotak dialog Opsi lalu mengedit penempatan perintah di bawah kategori Lingkungan Keyboard . Tidak memengaruhi penempatan pada menu pintasan, toolbar, pengontrol menu, atau submenu.

Berlaku untuk: Button, Combo

DefaultDisabled Secara default, perintah dinonaktifkan jika VSPackage yang mengimplementasikan perintah tidak dimuat atau metode QueryStatus belum dipanggil.

Berlaku untuk: Button, Combo

DefaultInvisible Secara default, perintah tidak terlihat jika VSPackage yang mengimplementasikan perintah tidak dimuat atau metode QueryStatus belum dipanggil.

Harus dikombinasikan dengan DynamicVisibility flag.

Berlaku untuk: Button, Combo, Menu

DynamicVisibility Visibilitas perintah dapat diubah dengan menggunakan QueryStatus metode atau GUID konteks yang disertakan dalam bagian VisibilityConstraints .

Berlaku untuk perintah yang muncul pada menu, bukan pada bilah alat. Item toolbar tingkat atas dapat dinonaktifkan, tetapi tidak tersembunyi, ketika bendera OLECMDF_INVISIBLE dikembalikan dari metode QueryStatus.

Pada menu, penanda ini juga menunjukkan bahwa itu harus secara otomatis disembunyikan ketika anggotanya disembunyikan. Bendera ini biasanya ditetapkan ke submenu karena menu tingkat atas sudah memiliki perilaku ini.

Harus dikombinasikan dengan DefaultInvisible flag.

Berlaku untuk: Button, Combo, Menu

NoShowOnMenuController Jika perintah yang memiliki bendera ini diposisikan pada pengontrol menu, perintah tidak muncul di daftar drop-down.

Berlaku untuk: Button

Untuk informasi selengkapnya tentang bendera perintah, lihat dokumentasi elemen CommandFlag .

Persyaratan umum

Perintah Anda harus melewati serangkaian pengujian berikut sebelum dapat ditampilkan dan diaktifkan:

Perintah diposisikan dengan benar.
Bendera DefaultInvisible tidak disetel.
Menu induk atau bilah alat terlihat.
Perintah tidak tersembunyi karena entri konteks dalam bagian elemen VisibilityConstraints.
Kode VSPackage yang mengimplementasikan IOleCommandTarget antarmuka menampilkan dan mengaktifkan perintah Anda. Tidak ada kode antarmuka yang mencegatnya dan mengambil tindakan.
Saat pengguna mengklik perintah Anda, perintah tersebut menjadi tunduk pada prosedur yang diuraikan dalam algoritma Perutean.

Memanggil perintah yang telah ditentukan sebelumnya

Elemen UsedCommands memungkinkan VSPackages mengakses perintah yang disediakan oleh VSPackages lain atau oleh IDE. Untuk melakukan ini, buat elemen UsedCommand yang memiliki GUID dan ID perintah yang akan digunakan. Ini memastikan bahwa perintah akan dimuat oleh Visual Studio, meskipun itu bukan bagian dari konfigurasi Visual Studio saat ini. Untuk informasi selengkapnya, lihat Elemen UsedCommand.

Tampilan elemen antarmuka

Pertimbangan untuk memilih dan memposisikan elemen perintah adalah sebagai berikut:

Visual Studio menawarkan banyak elemen UI yang muncul secara berbeda tergantung pada penempatan.
Elemen UI yang didefinisikan dengan menggunakan DefaultInvisible flag tidak akan ditampilkan dalam IDE kecuali ditampilkan oleh metode QueryStatus yang diimplementasikan oleh VSPackage, atau terkait dengan konteks UI tertentu di bagian VisibilityConstraints.
Bahkan perintah yang telah berhasil ditempatkan mungkin tidak akan ditampilkan. Ini karena IDE secara otomatis menyembunyikan atau menampilkan beberapa perintah, tergantung pada antarmuka yang diimplementasikan vsPackage (atau belum). Misalnya, implementasi VSPackage dari beberapa antarmuka build menyebabkan item menu terkait build ditampilkan secara otomatis.
CommandWellOnly Menerapkan bendera dalam definisi elemen UI berarti bahwa perintah hanya dapat ditambahkan dengan kustomisasi.
Perintah mungkin hanya tersedia dalam konteks UI tertentu, misalnya, hanya ketika kotak dialog ditampilkan saat IDE berada dalam tampilan desain.
Untuk menyebabkan elemen UI tertentu ditampilkan di IDE, Anda harus menerapkan satu atau beberapa antarmuka atau menulis beberapa kode.

Memperluas menu dan perintah

Last updated on 2025-12-12

Bagikan melalui