Grundläggande format för dina widgetar

Artikel
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Vi rekommenderar att du använder de grundläggande formatmallarna som tillhandahålls via Widget SDK. Med de här formaten kan du snabbt och enkelt skapa en widget som är konsekvent med resten av widgetarna på instrumentpanelen. Om du vill använda dessa formatmallar lägger du till raden nedan i VSS.require blocket i JavaScript-koden för widgeten.

Dricks

Läs vår senaste dokumentation om tilläggsutveckling med hjälp av Azure DevOps Extension SDK.

	WidgetHelpers.IncludeWidgetStyles();

Detta hämtar en formatmall med namnet sdk-widget.css och inkluderar den i iframe för widgeten. Den innehåller format för teckensnittsfamilj, teckenstorlek, marginal och utfyllnad för widgeten. Den innehåller även formatmallar för rubriker (h1, h2, h3 osv.), länkar med mera.

Om du vill använda vanliga format i widgetkonfigurationen inkluderar du på samma sätt raden nedan i VSS.require blocket i JavaScript-koden för widgetkonfigurationen.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Detta hämtar en formatmall med namnet sdk-widget-configuration.css och inkluderar den i iframe för widgetkonfigurationen. Den innehåller format för teckensnittsfamilj, teckenstorlek och formatmallar för vanliga formulärelement som indata, textområde och välj.

Kommentar

För att dessa format ska gälla för widgeten måste du lägga till en "widget"-klass i HTML-elementet som innehåller widgeten. Alla format från sdk-widgets.css är begränsade till den här klassen. På samma sätt lägger du till en "widget-configuration"-klass i HTML-elementet som innehåller din widgetkonfiguration. Alla format från sdk-widget-configuration.css är begränsade till den här klassen.

Ladda ned tilläggsexemplet.

Widgettext, rubrik och beskrivning

Genom att lägga till klassen "widget" i HTML-elementet som innehåller widgeten får du automatiskt utfyllnad, teckensnitt och färg för widgetinnehåll.

Du bör alltid ha en rubrik för widgeten. Detta hjälper användaren att snabbt identifiera din widget och dess funktioner. Använd <h2> med klassen "title". Detta hjälper också användare som använder skärmläsare att snabbt identifiera de olika widgetarna på instrumentpanelen.

Designprincip: Widgetar ska ha en rubrik. Använd taggen <h2> med klassen "title".

Ibland kanske du vill ange en liten beskrivning av widgeten eller hur du använder den. I sådana fall använder du klassen "description" på det HTML-element som du vill använda för widgetbeskrivning.

Designprincip: Använd klassen "description" för widgetbeskrivningen. Beskrivningar bör vara meningsfulla även när de läss ut ur widgetkontexten.

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

Undertexter är text som kompletterar rubriken. De kanske inte alltid är meningsfulla när de läss ur sitt sammanhang utan att läsa rubriken.

Designprincip: Använd klassen "underrubrik" för att ge mer information om widgeten. Det kanske inte är meningsfullt ur widgetkontexten.

Använd strukturen nedan och klasserna "title", "inner-title" och "subtitle" för att få rätt teckensnitt, färg och marginaler för en kombination av rubrik och underrubrik. Rubriken får en större teckenstorlek än underrubriken. Underrubriken har en dämpad färg i förhållande till rubriken eller resten av widgeten.

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

Du kan använda valfritt html-element för kombinationen rubrik och underrubrik. Här följer några tips:

När du behöver underrubriken på samma rad som rubriken använder du ett infogat element som <span>
När du behöver underrubriken för att visas på nästa rad från rubriken använder du ett blockelement som <div>

Vissa widgetar har länkar som har en ikon, text och undertext per länk.

Designprincip: Använd länkar med en ikon och undertext för att göra syftet med länken uppenbar för användaren. Se till att ikonen symboliserar länkens mål.

Använd HTML-strukturen och klasserna nedan för att få samma utseende och känsla.

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

Det primära syftet med vissa widgetar är att visa antalet data. Frågepanelen och kodpanelwidgetarna är exempel i den här kategorin med widgetar. Om du vill använda samma formatmallar som dessa widgetar lägger du till klassen "big-count" i HTML-elementet som innehåller numret för att hämta det stora teckensnitt som används av frågepanelen och kodpanelwidgetarna.

Designprincip: Använd klassen "big-count" för att presentera användaren med tal i stort teckensnitt. Den ska inte användas med icke-numeriska tecken.

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

Om du klickar någonstans på vissa widgetar omdirigeras användaren till en annan sida. Om du vill att widgeten ska göra samma sak kan du:

Lägg till en fästpunktstagg som underordnad till HTML-elementet som fungerar som din widgetcontainer.
Placera allt widgetinnehåll i fästpunktstaggen.
Eftersom widgeten finns i en iframe lägger du till attributet "target" med värdet "_blank" i fästpunktstaggen så att länken öppnas i en ny flik/ett nytt fönster i stället för inuti samma iframe.
Utöver klassen "widget" lägger du till klassen "klickbar" i widgetcontainern.

Widgetinnehållet får rätt färger trots att de finns i en fästpunktstagg. Utan klassen "klickbar" tvingas den blå standardfärgen på all text i widgeten. Widgeten får också en anpassad visuell referens i fokus för att hjälpa användare som använder tangentbordet att navigera på instrumentpanelen.

Designprincip: Använd klassen "klickbar" och taggen <a> för att göra hela widgeten klickbar. Detta är perfekt när widgeten är en sammanfattning av tillgängliga data på en annan sida.

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

Följ dessa riktlinjer om du vill använda grundläggande format från widgetens sdk för vanliga formulärelement i widgetkonfigurationen:

Formulärelement	Omslutningselement	Riktlinjer
Enkel textruta	`div` med klassen "single-line-text-input".	Använd ett `label` element för att lägga till text bredvid textrutan. Använd elementet `input` för att skapa en textruta. `placeholder` Använd attributet för att ange platshållartext.
Kryssruta	`fieldset` med klassens "kryssruta"	Använd ett `label` element för att lägga till text bredvid varje kryssruta. Använd ett `legend` element för att bildtext gruppen med kryssrutor. `for` Använd attributet för varje `label` element för att hjälpa skärmläsare att förstå formulärelementet.
Radio button	`fieldset` med klassen "radio"	Använd ett `label` element för att lägga till text bredvid varje alternativknapp. Använd ett `legend` element för att bildtext gruppen med alternativknappar. `for` Använd attributet för varje `label` element för att hjälpa skärmläsare att förstå formulärelementet.
Listruta	`div` med klassen "dropdown"	Använd ett `label` element för att lägga till text bredvid listrutan. Om du vill ha en listruta som upptar halva bredden lägger du till klassen "half" i omslutningselementet `div` . Om du vill använda standardpilikonen från sdk:en i stället för den som tillhandahålls av webbläsaren, omsluter du elementet `select` med en annan `div` med klassen "wrapper".
Textruta med flera rader	`div` med klassen "multi-line-text-input".	Använd `label` element för att märka elementet `textarea` som används som textruta med flera rader.

I exemplet nedan används vart och ett av formulärelementen som anges i tabellen.

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

Visa valideringsfel under ett formulärelement

Vi rekommenderar att du anger valideringsfel under de relevanta formulärelementen. Om du vill visa dessa meddelanden på ett sätt som överensstämmer med widgetar från första part lägger du till följande kodfragment under varje formulärelement som du vill visa felmeddelandet för.

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

Det tidigare kodfragmentet har synligheten dold som standard. När du vill visa ett felmeddelande letar du upp motsvarande "validation-error-text" och lägger till text i den och anger visibility:visible den överordnade texten.

Exempel: Det finns en enkel textruta där användaren måste skriva in en sträng. Du måste visa ett felmeddelande om textrutan är tom.

Html för detta skulle vara:

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

Och JavaScript-koden bakom detta skulle vara:

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");
	});

Dela via

Grundläggande format för dina widgetar

Widgettext, rubrik och beskrivning

Widgetrubriker och undertexter

Visa hyperlänkar, ikoner, text och undertext i en widget

Visa räknare i en widget

Göra en widget till en hyperlänk

Format för vanliga formulärelement i widgetkonfiguration

Visa valideringsfel under ett formulärelement

Feedback

Ytterligare resurser