Gaya dasar untuk widget Anda

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Kami sarankan Anda menggunakan gaya dasar yang disediakan melalui Widget SDK. Menggunakan gaya ini membantu Anda dengan cepat dan mudah membuat widget yang konsisten dengan widget lainnya di dasbor. Untuk menggunakan gaya ini, tambahkan baris di bawah ini di dalam VSS.require blok dalam kode JavaScript untuk widget Anda.

Tip

Lihat dokumentasi terbaru kami tentang pengembangan ekstensi menggunakan Azure DevOps Extension SDK.

	WidgetHelpers.IncludeWidgetStyles();

Ini menarik lembar gaya dengan nama sdk-widget.css dan menyertakannya dalam iframe untuk widget Anda. Ini termasuk gaya untuk font-family, font-size, margin dan paddings untuk widget Anda. Ini juga termasuk gaya untuk judul (h1, h2, h3 dll.), tautan, dan banyak lagi.

Demikian pula, untuk menggunakan gaya umum dalam konfigurasi widget, sertakan baris di bawah ini di dalam VSS.require blok dalam kode JavaScript untuk konfigurasi widget Anda.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Ini menarik lembar gaya dengan nama sdk-widget-configuration.css dan menyertakannya dalam iframe untuk konfigurasi widget Anda. Ini termasuk gaya untuk font-family, font-size dan styles untuk elemen formulir umum seperti input, textarea, dan select.

Catatan

Agar gaya ini diterapkan ke widget, Anda perlu menambahkan kelas "widget" pada elemen HTML yang berisi widget Anda. Semua gaya dari sdk-widgets.css dilingkup ke kelas ini. Demikian pula, tambahkan kelas "widget-configuration" pada elemen HTML yang berisi konfigurasi widget Anda. Semua gaya dari sdk-widget-configuration.css dilingkup ke kelas ini.

Unduh sampel ekstensi.

Isi, judul, dan deskripsi widget

Dengan menambahkan kelas "widget" pada elemen HTML yang berisi widget Anda, Anda secara otomatis mendapatkan padding, font, dan warna untuk konten widget.

Anda harus selalu memiliki judul untuk widget Anda. Ini membantu pengguna mengidentifikasi widget Anda dan fungsionalitasnya secara sekilas. Gunakan <h2> dengan kelas "judul". Ini juga membantu orang yang menggunakan pembaca layar untuk dengan cepat mengidentifikasi widget yang berbeda di dasbor.

Prinsip desain: Widget harus memiliki judul. <h2> Gunakan tag dengan kelas "judul".

Terkadang Anda mungkin ingin memberikan deskripsi kecil tentang widget Anda atau cara menggunakannya. Dalam kasus seperti itu, gunakan "deskripsi" kelas pada elemen HTML yang ingin Anda gunakan untuk deskripsi widget.

Prinsip desain: Gunakan kelas "deskripsi" untuk deskripsi widget. Deskripsi harus masuk akal bahkan ketika membaca keluar dari konteks widget.

	<div class="widget">
	    <h2 class="title">Widget title</h2>	
		<div class="description">The widget description is used to describe the widget. It makes sense even when read outside of the widget context.</div>
		<p>Place widget content here.</p>
	</div>

Judul dan subtitel widget

Subtitel adalah teks yang melengkapi judul. Mereka mungkin tidak selalu masuk akal ketika membaca di luar konteks tanpa membaca judul.

Prinsip desain: Gunakan kelas "subtitel" untuk memberikan informasi lebih lanjut tentang widget. Ini mungkin tidak masuk akal dari konteks widget.

Gunakan struktur dan kelas "title", "inner-title" dan "subtitle" di bawah ini untuk mendapatkan font, warna, dan margin yang tepat untuk kombinasi judul dan subtitel. Judul mendapatkan ukuran font yang lebih besar dari subtitel. Subtitel memiliki warna subdus relatif terhadap judul atau sisa widget.

	<div class="widget">
	    <h2 class="title">
			<div class="inner-title">Widget title</div>
			<div class="subtitle">Widget subtitle</div>
		</h2>
		<div class="content">
			Place widget content here.  
		</div>
	</div>

Anda dapat menggunakan elemen html apa pun untuk kombinasi judul dan subtitel. Berikut adalah beberapa tipnya:

• Saat Anda memerlukan subtitel untuk muncul di baris yang sama dengan judul, gunakan elemen sebaris seperti <span>
• Saat Anda memerlukan subtitel untuk muncul di baris berikutnya dari judul, gunakan elemen blok seperti <div>

Menampilkan hyperlink, ikon, teks, dan subteks dalam widget

Beberapa widget memiliki tautan yang memiliki ikon, teks, dan subteks per tautan.

Prinsip desain: Gunakan tautan dengan ikon dan subteks untuk membuat tujuan tautan jelas kepada pengguna. Pastikan bahwa ikon melambangkan target tautan.

Untuk mendapatkan tampilan dan nuansa yang sama, gunakan struktur dan kelas HTML di bawah ini.

	<div class="widget">
	    <h2 class="title">Widget title</h2>
		<div class="content">
			<p>Place your content here.</p>
			<a class="link-with-icon-text" href="http://bing.com" target="_blank">
				<span class="icon-container" style="background-color: #68217A"></span>
				<div class="title">
					Primary link text
					<div class="subtitle">Link subtext</div>
				</div>
			</a>		
		</div>
	</div>

Menampilkan penghitung dalam widget

Tujuan utama beberapa widget adalah untuk menampilkan jumlah beberapa data. Petak Peta Kueri dan widget Petak Peta Kode adalah contoh dalam kategori widget ini. Untuk menggunakan gaya yang sama dengan widget ini, tambahkan kelas "big-count" pada elemen HTML yang memegang angka untuk mendapatkan font besar yang digunakan oleh Petak Peta Kueri dan widget Petak Peta Kode.

Prinsip desain: Gunakan kelas "big-count" untuk menyajikan pengguna dengan angka dalam font besar. Ini tidak boleh digunakan dengan karakter non-numerik.

<div class="widget">
    <h2 class="title">Counter widget</h2>
	<div class="big-count">223</div>
	<div>Additional text</div>
</div>

Membuat widget menjadi hyperlink

Mengklik di mana saja pada beberapa widget mengalihkan pengguna ke halaman lain. Agar widget Anda melakukan hal yang sama, Anda dapat:

• Tambahkan tag jangkar sebagai anak ke elemen HTML yang bertindak sebagai kontainer widget Anda.
• Letakkan semua konten widget Anda di dalam tag jangkar.
• Karena widget Anda dihosting dalam iframe, tambahkan atribut "target" dengan nilai "_blank" ke tag jangkar sehingga tautan terbuka di tab/jendela baru alih-alih di dalam iframe yang sama.
• Selain kelas "widget", tambahkan kelas "dapat diklik" ke kontainer widget.

Konten widget Anda mendapatkan warna yang benar meskipun berada di dalam tag jangkar. Tanpa kelas "dapat diklik", warna biru default dipaksa pada semua teks di dalam widget. Widget juga mendapatkan isjin visual kustom pada fokus untuk membantu pengguna yang menggunakan keyboard untuk menavigasi dasbor.

Prinsip desain: Gunakan kelas "dapat diklik" dan <a> tag untuk membuat seluruh widget dapat diklik. Ini sangat ideal ketika widget Anda adalah ringkasan data yang tersedia di halaman lain.

<div class="widget clickable">
    <a href="https://bing.com"  target="_blank">
		<h2 class="title">Counter widget</h2>
		<div class="big-count">223</div>
		<div>Click me!</div>
	</a>
</div>

Gaya untuk elemen formulir umum dalam konfigurasi widget

Untuk menggunakan gaya dasar dari widget sdk untuk elemen formulir umum dalam konfigurasi widget, ikuti panduan berikut:

Elemen formulir	Elemen pembungkusan	Panduan
Kotak teks sederhana	div dengan kelas "single-line-text-input".	label Gunakan elemen untuk menambahkan teks di samping kotak teks. input Gunakan elemen untuk membuat kotak teks. placeholder Gunakan atribut untuk menyediakan teks tempat penampung.
Kotak centang	fieldset dengan kelas "kotak centang"	label Gunakan elemen untuk menambahkan teks di samping setiap kotak centang. legend Gunakan elemen untuk memberi keterangan grup kotak centang. for Gunakan atribut pada setiap label elemen untuk membantu pembaca layar memahami elemen formulir.
Tombol radio	fieldset dengan kelas "radio"	label Gunakan elemen untuk menambahkan teks di samping setiap tombol radio. legend Gunakan elemen untuk memberi keterangan sekelompok tombol radio. for Gunakan atribut pada setiap label elemen untuk membantu pembaca layar memahami elemen formulir.
Menurun	div dengan kelas "dropdown"	label Gunakan elemen untuk menambahkan teks di samping dropdown. Jika Anda ingin dropdown menempati setengah lebar, tambahkan kelas "setengah" ke elemen pembungkus div . Jika Anda ingin menggunakan ikon panah standar dari sdk alih-alih yang disediakan oleh browser, bungkus elemen dengan yang lain div dengan kelas "pembungkusselect".
Kotak teks multibaris	div dengan kelas "multi-line-text-input".	Gunakan label elemen untuk memberi label elemen yang textarea digunakan sebagai kotak teks multibaris.

Contoh di bawah ini menggunakan setiap elemen formulir yang tercantum dalam tabel.

<div class="widget-configuration">

    <div class="single-line-text-input" id="name-input">
        <label>Your name</label>
        <input type="text" value="Contoso"></input>
    </div>

    <div class="dropdown" id="query-path-dropdown">
        <label>Drop down</label>
        <div class="wrapper">
            <select>						
				<option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
				<option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
				<option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>							
			</select>
        </div>

        <fieldset class="checkbox" id="select-results">
            <legend>Select results to display</legend>
            <input type="checkbox" id="check-option1" value="id" name="check" checked="true">
            <label for="check-option1">Query ID</label><br/>
            <input type="checkbox" id="check-option2" value="name" name="check" checked="true">
            <label for="check-option2">Query Name</label><br/>
            <input type="checkbox" id="check-option3" value="createdBy" name="check" checked="true">
            <label for="check-option3">Created By</label><br/>
        </fieldset>

        <fieldset class="radio" id="display-options">
            <legend>Display as </legend>
            <input type="radio" id="radio-option1" value="ordered" name="radio" checked="true">
            <label for="radio-option1">Ordered List</label><br/>
            <input type="radio" id="radio-option2" value="unordered" name="radio">
            <label for="radio-option2">Unordered List</label><br/>
        </fieldset>

        <div class="multi-line-text-input">
            <label>Comments</label>
            <textarea></textarea>
        </div>
    </div>
</div>

Menampilkan kesalahan validasi di bawah elemen formulir

Sebaiknya berikan kesalahan validasi di bawah elemen formulir yang relevan. Untuk menampilkan pesan ini dengan cara yang konsisten dengan widget pihak ke-1, tambahkan cuplikan kode berikut di bawah setiap elemen formulir yang ingin Anda tampilkan pesan kesalahannya.

<span class="validation-error">
	<span class="icon-error-exclamation"></span>
	<span class="validation-error-text"></span>
</span>

Cuplikan kode sebelumnya memiliki visibilitas yang disembunyikan secara default. Setiap kali Anda ingin menampilkan pesan kesalahan, temukan "validation-error-text" yang sesuai, tambahkan teks ke dalamnya dan atur visibility:visible pada induknya.

Contoh: Ada kotak teks sederhana di mana pengguna perlu mengetik string. Anda perlu menampilkan pesan kesalahan jika kotak teks kosong.

Html untuk ini adalah:

<div class="widget-configuration">
	<div class="single-line-text-input">
		<label>Your name</label>
		<input type="text">Type Here</input>		

		<span class="validation-error">
			<span class="icon-error-exclamation"></span>
			<span class="validation-error-text"></span>
		</span>
	</div>
</div>

Dan kode JavaScript di balik ini adalah:

var $singleLineInput = $(".single-line-text-input input");
var $errorSingleLineInput = $(".single-line-text-input input .validation-error-text");

$singleLineInput.on("input", function(){
		if ($singleLineInput.val() == ""){
			$errorSingleLineInput.text("Please enter your name.");
			$errorSingleLineInput.parent().css("visibility", "visible");
			return;
		}
		$errorSingleLineInput.parent().css("visibility", "hidden");
	});