Basisstijlen voor uw widgets

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Gebruik de basisstijlen van de Widget-SDK voor een consistent uiterlijk in dashboardwidgets.

Als u widgetstijlen wilt opnemen, roept u WidgetHelpers.IncludeWidgetStyles() aan tijdens de initialisatie van de widget:

WidgetHelpers.IncludeWidgetStyles();

Hiermee wordt sdk-widget.css in het iframe van uw widget geladen, inclusief stijlen voor lettertypefamilie, tekengrootte, marges, vulling, koppen en links.

Voor widgetconfiguratiepanelen roep WidgetHelpers.IncludeWidgetConfigurationStyles() in plaats daarvan aan.

WidgetHelpers.IncludeWidgetConfigurationStyles();

Hiermee worden sdk-widget-configuration.css stijlen voor de lettertypefamilie, de tekengrootte, en algemene formulierelementen zoals input, textarea, en select.

Zie het voorbeeld van de extensie voor een werkend voorbeeld.

Hoofdtekst, titel en beschrijving van widget

Door de klasse toe te voegen aan het widget containerelement van uw widget, krijgt u automatisch opvulling, lettertype en kleur voor widgetinhoud.

Voeg altijd een titel voor uw widget toe, zodat gebruikers het doel ervan in één oogopslag kunnen identificeren. Gebruik <h2> met de title klasse. Dit helpt schermlezers ook om de verschillende widgets op het dashboard te identificeren.

Ontwerpprincipe: Widgets moeten een titel hebben. Gebruik de <h2> tag met de title klasse.

Als u een beschrijving wilt toevoegen, gebruikt u de description klasse op het element dat uw widgetbeschrijving bevat.

Ontwerpprincipe: Gebruik de description klasse voor de beschrijving van de widget. Beschrijvingen moeten zinvol zijn, zelfs wanneer ze buiten de widgetcontext worden gelezen.

	<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>

Widgettitels en ondertitels

Ondertitels vormen een aanvulling op de titel en zijn mogelijk niet zinvol wanneer ze uit de context worden gelezen.

Ontwerpprincipe: Gebruik de subtitle klasse voor meer informatie over de widget.

Gebruik de titleen inner-titlesubtitle klassen om het juiste lettertype, de juiste kleur en marges op te halen voor een combinatie van titel en ondertitel. De ondertitel heeft een subtiele kleur ten opzichte van de titel.

	<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>

Tips voor de combinatie van titel en ondertitel:

• Gebruik een inline-element, zoals <span> voor de ondertitel, op dezelfde regel als de titel.
• Gebruik een blokelement zoals <div> zodat de ondertitel op een nieuwe regel wordt weergegeven.

Koppelingen met pictogrammen en subtekst

Sommige widgets bevatten koppelingen met een pictogram, tekst en subtekst.

Ontwerpprincipe: Gebruik koppelingen met een pictogram en subtekst om het doel van de koppeling duidelijk te maken voor de gebruiker. Zorg ervoor dat het pictogram het doel van de koppeling symboliseert.

Gebruik de onderstaande HTML-structuur en klassen om hetzelfde uiterlijk te krijgen.

	<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>

Tellers

Voor widgets die een telling weergeven, voegt u de big-count klasse toe aan het element dat het getal bevat. De widgets querytegel en codetegel gebruiken dezelfde stijl.

Ontwerpprincipe: Gebruik de big-count klasse om getallen in een groot lettertype weer te geven. Gebruik deze niet met niet-numerieke tekens.

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

Klikbare widgets

Om een widget klikbaar te maken zodat het selecteren ervan overal naar een andere pagina navigeert:

1. Voeg een ankertag toe als onderliggend element van het widgetcontainerelement.
2. Plaats alle widgetinhoud in de ankertag.
3. Voeg toe target="_blank" aan de ankertag, zodat de koppeling wordt geopend op een nieuw tabblad.
4. Voeg de clickable klasse toe aan de widgetcontainer.

Zonder de clickable klasse is de standaardkleur voor blauwe koppelingen van toepassing op alle tekst in de widget. De clickable klasse biedt ook een aangepaste focusindicator voor toetsenbordnavigatie.

Ontwerpprincipe: Gebruik de clickable klasse en de <a> tag om de hele widget klikbaar te maken. Dit patroon werkt goed wanneer uw widget gegevens samenvat die beschikbaar zijn op een andere pagina.

<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>

Formulierelementen voor configuratie

Gebruik de volgende klassen voor algemene formulierelementen in widgetconfiguratie:

In het volgende voorbeeld worden alle formulierelementen gebruikt die in de tabel worden vermeld.

<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>

Validatie-foutmeldingen

Als u validatiefouten onder formulierelementen wilt weergeven op een manier die consistent is met widgets van de eerste partij, voegt u het volgende fragment toe onder elk formulierelement:

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

De zichtbaarheid is standaard verborgen. Als u een foutbericht wilt weergeven, zoekt u het bijbehorende validation-error-text element, stelt u de tekst ervan in, en stelt u visibility: visible in op het bovenliggende element.

Als u bijvoorbeeld een fout wilt weergeven wanneer een tekstvak leeg is:

De HTML hiervoor is:

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

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

En javaScript:

const input = document.querySelector(".single-line-text-input input");
const errorText = document.querySelector(".single-line-text-input .validation-error-text");

input.addEventListener("input", function () {
    if (input.value === "") {
        errorText.textContent = "Please enter your name.";
        errorText.parentElement.style.visibility = "visible";
    } else {
        errorText.parentElement.style.visibility = "hidden";
    }
});