Alapvető stílusok a widgetekhez

Cikk
04/04/2024

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

Javasoljuk, hogy a Widget SDK-val elérhető alapvető stílusokat használja. Ezekkel a stílusokkal gyorsan és egyszerűen hozhat létre olyan widgetet, amely összhangban van az irányítópult többi vezérlőjével. A stílusok használatához adja hozzá az alábbi sort a VSS.require vezérlő JavaScript-kódjában lévő blokkon belül.

Tipp.

Tekintse meg a bővítményfejlesztéssel kapcsolatos legújabb dokumentációnkat az Azure DevOps Extension SDK használatával.

	WidgetHelpers.IncludeWidgetStyles();

Ez lekéri a sdk-widget.css nevű stíluslapot, és belefoglalja a widget iframe-be. Stílusokat tartalmaz a betűtípuscsaládhoz, a betűmérethez, a margóhoz és a widgethez tartozó kitöltésekhez. Stílusokat is tartalmaz a címsorokhoz (h1, h2, h3 stb.), hivatkozásokhoz és egyebekhez.

Hasonlóképpen, ha a widget-konfigurációban gyakori stílusokat szeretne használni, a vezérlőkonfiguráció JavaScript-kódjában adja meg a VSS.require blokk alatti sort.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Ez lekéri a sdk-widget-configuration.css nevű stíluslapot, és belefoglalja az iframe-be a widget konfigurációjához. Ez magában foglalja a betűtípuscsalád stílusát, a betűméretet és a gyakori űrlapelemek stílusát, például a bemenetet, a textarea-t és a kiválasztást.

Feljegyzés

Ahhoz, hogy ezek a stílusok vonatkozzanak a widgetre, hozzá kell adnia egy "widget" osztályt a widgetet tartalmazó HTML-elemhez. A sdk-widgets.css minden stílusa ebbe az osztályba van beállítva. Hasonlóképpen adjon hozzá egy "widget-configuration" osztályt a widgetkonfigurációt tartalmazó HTML-elemhez. A sdk-widget-configuration.css minden stílusa ebbe az osztályba van beosztva.

Töltse le a bővítménymintát.

Widget törzse, címe és leírása

Ha hozzáadja a widgetet tartalmazó HTML-elemhez a "widget" osztályt, automatikusan beszűkítést, betűtípust és színt kap a widget tartalmához.

Mindig rendelkeznie kell a widget címmel. Ez segít a felhasználónak egy pillantással azonosítani a widgetet és annak funkcióit. Használja <h2> a "title" osztályt. Ez segít a képernyőolvasókat használó felhasználóknak az irányítópult különböző vezérlőinek gyors azonosításában.

Tervezési elv: A widgeteknek címmel kell rendelkezniük. Használja a <h2> címkét a "title" osztálysal.

Előfordulhat, hogy egy kis leírást szeretne megadni a widgetről vagy annak használatáról. Ilyen esetekben használja a "leírás" osztályt a widget leírásához használni kívánt HTML-elemen.

Tervezési alapelv: A widget leírásához használja a "description" osztályt. A leírásoknak akkor is értelmesnek kell lennie, ha kiolvasják a vezérlőkörnyezetből.

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

A feliratok olyan szövegek, amelyek kiegészítik a címet. Lehet, hogy nem mindig van értelme, ha a szövegkörnyezetből olvassák ki a címet.

Tervezési alapelv: Az "alcím" osztály használatával további információkat adhat meg a widgetről. Lehet, hogy nincs értelme a widget környezetéből.

Az alábbi struktúra és osztályok "title", "inner-title" és "alcím" használatával szerezze be a megfelelő betűtípust, színt és margókat egy cím és alcím kombinációhoz. A cím nagyobb betűméretet kap, mint az alcím. Az alcím a widget címéhez vagy többi részéhez képest visszafogott színnel rendelkezik.

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

A cím és az alcím kombinációhoz bármilyen HTML-elemet használhat. Íme néhány tipp:

Ha a címmel megegyező sorban kell megjelenítenie az alcímet, használjon egy olyan beágyazott elemet, mint a <span>
Ha a cím következő sorában meg kell jelennie az alcímnek, használjon egy olyan blokkelemet, mint a <div>

Egyes vezérlők hivatkozásokat tartalmaznak, amelyek hivatkozásonként ikonnal, szövegtel és alszövegekkel rendelkeznek.

Tervezési elv: Ikonnal és alszöveggel ellátott hivatkozások használatával nyilvánvalóvá teheti a hivatkozás célját a felhasználó számára. Győződjön meg arról, hogy az ikon a hivatkozás célját szimbolizálja.

Az alábbi HTML-struktúrát és osztályokat használva ugyanazt a megjelenést és megjelenést érheti el.

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

Egyes vezérlők elsődleges célja egyes adatok számának megjelenítése. A lekérdezéscsempék és a kódcsempe widgetek a widgetek ebbe a kategóriájába tartoznak. Ha ugyanazokat a stílusokat szeretné használni, mint ezek a widgetek, adja hozzá a "big-count" osztályt a számmal rendelkező HTML-elemhez, hogy lekérje a Lekérdezés csempe és a Kódcsempe widgetek által használt nagy betűtípust.

Tervezési alapelv: Használja a "nagy darabszám" osztályt, hogy nagy betűtípusú számokat jelenítsen meg a felhasználónak. Nem numerikus karakterekkel nem használható.

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

Egyes widgetekre kattintva a felhasználó egy másik oldalra kerül. Ha ugyanezt szeretné tenni a widgettel, a következő műveleteket végezheti el:

Adjon hozzá egy horgonycímkét gyermekként a widgettárolóként működő HTML-elemhez.
Helyezze az összes widget-tartalmat a horgonycímkére.
Mivel a widget egy iframe-ben van üzemeltetve, adja hozzá a "target" attribútumot "_blank" értékkel a horgonycímkéhez, hogy a hivatkozás egy új lapon/ablakban nyíljon meg, és ne ugyanabban az iframe-ben.
A "widget" osztály mellett adja hozzá a "kattintható" osztályt a widgettárolóhoz.

A widget tartalma akkor is megkapja a megfelelő színeket, ha egy horgonycímkében vannak. A "kattintható" osztály nélkül a rendszer az alapértelmezett kék színt a widgeten belüli összes szövegre kényszeríti. A widget egy egyéni vizuális jelzést is kap a fókuszban, hogy segítse a billentyűzetet használó felhasználókat az irányítópulton való navigálásban.

Tervezési alapelv: Használja a "kattintható" osztályt és a címkét, <a> hogy a teljes widget kattintható legyen. Ez akkor ideális, ha a widget egy másik oldalon elérhető adatok összegzése.

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

Ha alapvető stílusokat szeretne használni a widget-sdk-ből a widgetkonfiguráció gyakori űrlapelemeihez, kövesse az alábbi irányelveket:

Űrlapelem	Burkolóelem	Irányelvek
Egyszerű szövegdoboz	`div` az "egysoros szövegbevitel" osztálysal.	`label` A szövegdoboz melletti szöveg hozzáadásához használjon elemet. `input` Az elem használatával hozzon létre egy szövegdobozt. `placeholder` Az attribútum használatával helyőrző szöveget adhat meg.
Jelölőnégyzet	`fieldset` a "checkbox" osztálysal	`label` Az egyes jelölőnégyzetek melletti szöveg hozzáadásához használjon elemet. `legend` Egy elem használatával képaláírás a jelölőnégyzetek csoportját. Az egyes `label` elemek attribútumával `for` segíthet a képernyőolvasóknak megérteni az űrlapelemet.
Választógomb	`fieldset` osztály "rádió"	`label` Az egyes választógombok melletti szöveg hozzáadásához használjon elemet. `legend` Egy elem használatával képaláírás a választógombok csoportját. Az egyes `label` elemek attribútumával `for` segíthet a képernyőolvasóknak megérteni az űrlapelemet.
Legördülő menü	`div` a "dropdown" osztálysal	`label` A legördülő lista melletti szöveg hozzáadásához használjon elemet. Ha azt szeretné, hogy egy legördülő lista a szélesség felét foglalja el, adja hozzá a "fele" osztályt a körbefuttatási `div` elemhez. Ha az sdk standard nyíl ikonját szeretné használni a böngésző által biztosított helyett, csomagolja az `select` elemet egy másikkal `div` a "burkoló" osztályba.
Többsoros szövegmező	`div` a "többsoros szövegbevitel" osztálysal.	Többsoros szövegdobozként használt elem címkézése `textarea` elem használatával`label`.

Az alábbi példa a táblázatban felsorolt űrlapelemek mindegyikét használja.

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

Érvényesítési hibák megjelenítése űrlapelem alatt

Javasoljuk, hogy a megfelelő űrlapelemek alatt adja meg az érvényesítési hibákat. Ha az első féltől származó widgetekkel összhangban szeretné megjeleníteni ezeket az üzeneteket, adja hozzá az alábbi kódrészletet minden olyan űrlapelemhez, amelynek a hibaüzenetét meg szeretné jeleníteni.

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

Az előző kódrészlet alapértelmezés szerint rejtett láthatóságot biztosít. Amikor hibaüzenetet szeretne megjeleníteni, keresse meg a megfelelő "validation-error-text" szöveget, adjon hozzá szöveget, és állítsa be visibility:visible a szülőjét.

Példa: Van egy egyszerű szövegmező, amelyben a felhasználónak sztringet kell beírnia. Ha a szövegmező üres, hibaüzenetet kell megjelenítenie.

Ennek html-címe a következő:

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

A JavaScript-kód pedig a következő lenne:

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

Megosztás a következőn keresztül:

Alapvető stílusok a widgetekhez

Widget törzse, címe és leírása

Widgetcímek és feliratok

Hivatkozások, ikonok, szöveg és alszöveg megjelenítése widgetben

Számlálók megjelenítése widgetben

Widget létrehozása hivatkozásként

Stílusok a widgetkonfiguráció gyakori űrlapelemeinek stílusaihoz

Érvényesítési hibák megjelenítése űrlapelem alatt

Visszajelzés

További források