Základní styly widgetů

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

Doporučujeme používat základní styly poskytované prostřednictvím sady SDK widgetů. Použití těchto stylů vám pomůže rychle a snadno vytvořit widget, který je konzistentní se zbytkem widgetů na řídicím panelu. Pokud chcete tyto styly použít, přidejte do bloku následující řádek VSS.require v kódu JavaScriptu pro widget.

Tip

Projděte si nejnovější dokumentaci k vývoji rozšíření pomocí sady SDK rozšíření Azure DevOps.

	WidgetHelpers.IncludeWidgetStyles();

Tím se stáhne šablona stylů podle názvu sdk-widget.css a zahrne ji do prvku iframe widgetu. Obsahuje styly pro rodinu písem, velikost písma, okraj a odsazení widgetu. Obsahuje také styly nadpisů (h1, h2, h3 atd.), odkazy a další.

Podobně pokud chcete použít běžné styly v konfiguraci widgetu, zahrňte řádek pod VSS.require blokem do kódu JavaScriptu pro konfiguraci widgetu.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Tím se stáhne šablona stylů podle názvu sdk-widget-configuration.css a zahrne ji do prvku iframe pro konfiguraci widgetu. Obsahuje styly pro rodinu písem, velikost písma a styly pro běžné prvky formuláře, jako jsou vstup, textarea a výběr.

Poznámka:

Aby se tyto styly použily u widgetu, musíte přidat třídu widgetu do elementu HTML, který obsahuje váš widget. Všechny styly z sdk-widgets.css jsou vymezeny na tuto třídu. Podobně přidejte třídu widget-configuration do elementu HTML, který obsahuje konfiguraci widgetu. Všechny styly z sdk-widget-configuration.css jsou vymezeny na tuto třídu.

Stáhněte si ukázku rozšíření.

Text widgetu, název a popis

Přidáním "widgetu" třídy do elementu HTML, který obsahuje váš widget, automaticky dostanete odsazení, písmo a barvu pro obsah widgetu.

Vždy byste měli mít název widgetu. To uživateli pomůže na první pohled identifikovat váš widget a jeho funkce. Používá se <h2> se třídou "title". To také pomáhá lidem používajícím čtečky obrazovky rychle identifikovat různé widgety na řídicím panelu.

Princip návrhu: Widgety by měly mít název. <h2> Použijte značku s třídou "title".

Někdy můžete chtít zadat malý popis widgetu nebo jeho použití. V takových případech použijte třídu "description" u elementu HTML, který chcete použít pro popis widgetu.

Princip návrhu: Pro popis widgetu použijte třídu "description". Popisy by měly dávat smysl i při čtení z kontextu widgetu.

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

Nadpisy a titulky widgetů

Titulky jsou text, který doplňuje název. Nemusí vždy dávat smysl při čtení z kontextu bez čtení názvu.

Princip návrhu: K poskytnutí dalších informací o widgetu použijte třídu "podnadpis". Nemusí to dávat smysl z kontextu widgetu.

Pomocí následující struktury a tříd "title", "inner-title" a "podnadpis" získáte správné písmo, barvu a okraje pro kombinaci nadpisů a titulků. Nadpis získá větší velikost písma než podnadpis. Podnadpis má subduovanou barvu vzhledem k názvu nebo zbytku widgetu.

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

Pro kombinaci názvu a podnadpisu můžete použít libovolný element HTML. Tady je několik tipů:

• Pokud potřebujete, aby se podnadpis zobrazoval na stejném řádku jako název, použijte vložený prvek, například <span>
• Pokud potřebujete, aby se podnadpis zobrazoval na dalším řádku názvu, použijte blokový prvek, například <div>

Zobrazení hypertextových odkazů, ikon, textu a podtextu ve widgetu

Některé widgety obsahují odkazy, které mají ikonu, text a podtext na odkaz.

Princip návrhu: Použití odkazů s ikonou a podtextem k tomu, aby byl účel odkazu pro uživatele zřejmé. Ujistěte se, že ikona symbolizuje cíl odkazu.

Pokud chcete získat stejný vzhled a chování, použijte následující strukturu a třídy HTML.

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

Zobrazení čítačů ve widgetu

Primárním účelem některých widgetů je zobrazení počtu některých dat. Dlaždice dotazu a widgety Dlaždice kódu jsou příklady v této kategorii widgetů. Pokud chcete použít stejné styly jako tyto widgety, přidejte třídu "big-count" do elementu HTML, který obsahuje číslo, abyste získali velké písmo, které používá dlaždice dotazu a widgety Dlaždice kódu.

Princip návrhu: Použití třídy "big-count" k prezentaci uživatele s čísly ve velkém písmu. Neměl by se používat s nečíselnými znaky.

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

Vytvoření widgetu jako hypertextového odkazu

Kliknutím kamkoli na některé widgety uživatele přesměruje na jinou stránku. Pokud chcete, aby widget udělal totéž, můžete:

• Přidejte značku ukotvení jako podřízenou k elementu HTML, který funguje jako kontejner widgetu.
• Vložte veškerý obsah widgetu do značky ukotvení.
• Vzhledem k tomu, že je widget hostovaný v prvku iframe, přidejte do značky ukotvení atribut "target" s hodnotou "_blank", aby se odkaz otevře na nové kartě nebo okně namísto uvnitř stejného prvku iframe.
• Kromě třídy widget přidejte do kontejneru widgetu třídu "clickable".

Obsah widgetu získá správné barvy, i když jsou uvnitř značky ukotvení. Bez třídy "klikni" je výchozí modrá barva vynucena pro veškerý text uvnitř widgetu. Widget také získá vlastní vizuální upozornění na fokus, který uživatelům, kteří používají klávesnici k navigaci na řídicím panelu.

Princip návrhu: Použijte třídu "clickable" a <a> značku, aby bylo možné kliknout na celý widget. To je ideální, když je widget souhrnem dat dostupných na jiné stránce.

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

Styly pro běžné prvky formuláře v konfiguraci widgetu

Pokud chcete použít základní styly ze sady SDK widgetu pro běžné prvky formuláře v konfiguraci widgetu, postupujte podle těchto pokynů:

Prvek formuláře	Wrapping – element	Pokyny
Jednoduché textové pole	div s třídou "single-line-text-input".	label K přidání textu vedle textového pole použijte prvek. Pomocí elementu input vytvořte textové pole. Pomocí atributu placeholder zadejte zástupný text.
Checkbox	fieldset with class "checkbox"	Pomocí elementu label přidejte text vedle každého zaškrtávacího políčka. Pomocí elementu legend popis skupinu zaškrtávacích políček. for Atribut u každého label prvku vám pomůže čtečky obrazovky pochopit prvek formuláře.
Radio button	fieldset s třídou "radio"	label Pomocí prvku můžete přidat text vedle každého přepínače. legend Pomocí prvku popis skupinu přepínačů. for Atribut u každého label prvku vám pomůže čtečky obrazovky pochopit prvek formuláře.
Rozevírací nabídka	div with class "dropdown"	Pomocí elementu label přidejte text vedle rozevíracího seznamu. Pokud chcete, aby rozevírací seznam zabíral polovinu šířky, přidejte do elementu wrapping div třídu "half". Pokud chcete místo ikony standardní šipky ze sady SDK, kterou poskytuje prohlížeč, zabalte select prvek jinou div třídou "wrapper".
Víceřádkové textové pole	div s třídou "multi-line-text-input".	Element použijte label k označení prvku použitého textarea jako víceřádkové textové pole.

Následující příklad používá všechny prvky formuláře uvedené v tabulce.

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

Zobrazení chyb ověření pod prvkem formuláře

Doporučujeme poskytnout chyby ověření pod příslušnými prvky formuláře. Chcete-li tyto zprávy zobrazit způsobem konzistentním s widgety 1. strany, přidejte následující fragment kódu do každého prvku formuláře, pro který chcete zobrazit chybovou zprávu.

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

Předchozí fragment kódu má ve výchozím nastavení skrytou viditelnost. Pokaždé, když chcete zobrazit chybovou zprávu, vyhledejte odpovídající text "validation-error-text", přidejte do něj text a nastavte visibility:visible ho na nadřazené.

Příklad: Existuje jednoduché textové pole, do kterého musí uživatel zadat řetězec. Pokud je textové pole prázdné, musíte zobrazit chybovou zprávu.

Kód HTML pro toto by byl:

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

Kód JavaScriptu by za tímto kódem byl:

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