Grundlegende Stile für Ihre Widgets

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

Verwenden Sie die grundlegenden Stile, die vom Widget SDK bereitgestellt werden, um ein einheitliches Erscheinungsbild für Dashboard-Widgets zu erhalten.

Um Widgetstile einzuschließen, rufen Sie während der Widgetinitialisierung auf WidgetHelpers.IncludeWidgetStyles() :

WidgetHelpers.IncludeWidgetStyles();

Ihr Widget-iFrame wird mit sdk-widget.css geladen, das Formatvorlagen für Schriftart, Schriftgröße, Ränder, Abstände, Überschriften und Links bereitstellt.

Rufen Sie stattdessen für Widget-Konfigurationspanels Folgendes auf: WidgetHelpers.IncludeWidgetConfigurationStyles()

WidgetHelpers.IncludeWidgetConfigurationStyles();

Diese lädt sdk-widget-configuration.css, das Stilvorlagen für Schriftfamilie, Schriftgröße und allgemeine Formelemente wie input, textarea und select bereitstellt.

Ein funktionierendes Beispiel finden Sie im Erweiterungsbeispiel.

Widgettext, Titel und Beschreibung

Durch Hinzufügen der widget Klasse zum Containerelement Ihres Widgets erhalten Sie automatisch Abstand, Schriftart und Farbe für Widgetinhalte.

Fügen Sie immer einen Titel für Ihr Widget ein, damit Benutzer ihren Zweck auf einen Blick identifizieren können. Verwenden Sie <h2> mit der title-Klasse. So können Bildschirmsprachausgaben die verschiedenen Widgets im Dashboard identifizieren.

Designprinzip: Widgets sollten einen Titel haben. Verwenden Sie <h2> Tag mit title Klasse.

Um eine Beschreibung hinzuzufügen, verwenden Sie die description Klasse für das Element, das Ihre Widgetbeschreibung enthält.

Designprinzip: Verwenden Sie die description Klasse für die Widgetbeschreibung. Beschreibungen sollten auch dann sinnvoll sein, wenn sie außerhalb des Widgetkontexts gelesen werden.

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

Widgettitel und Untertitel

Untertitel ergänzen den Titel und sind möglicherweise nicht sinnvoll, wenn sie aus dem Kontext herausgelesen werden.

Designprinzip: Verwenden Sie die subtitle Klasse, um weitere Informationen zum Widget bereitzustellen.

Verwenden Sie die Klassen title, inner-title und subtitle, um die richtigen Schriftarten, Farben und Ränder für eine Kombination aus Titel und Untertitel zu erhalten. Der Untertitel hat eine gedämpfte Farbe im Vergleich zum 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>

Tipps für die Titel- und Untertitelkombination:

• Verwenden Sie ein Inlineelement wie <span> für den Untertitel, damit er in derselben Zeile wie der Titel angezeigt wird.
• Verwenden Sie ein Blockelement wie <div> für den Untertitel, damit er in einer neuen Zeile angezeigt wird.

Links mit Symbolen und Untertext

Einige Widgets enthalten Links mit einem Symbol, Text und Untertext.

Designprinzip: Verwenden Sie Links mit einem Symbol und Untertext, um den Zweck des Links für den Benutzer offensichtlich zu machen. Stellen Sie sicher, dass das Symbol das Ziel des Links symbolisiert.

Verwenden Sie die folgende HTML-Struktur und -Klassen, um das gleiche Erscheinungsbild zu erzielen.

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

Zähler

Fügen Sie für Widgets, die eine Anzahl anzeigen, die big-count Klasse für das Element hinzu, das die Zahl enthält. Die Widgets "Abfragekachel" und "Codekachel" verwenden denselben Stil.

Designprinzip: Verwenden Sie die big-count Klasse, um Zahlen in großer Schriftart darzustellen. Verwenden Sie sie nicht mit nicht numerischen Zeichen.

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

Klickbare Widgets

Um ein Widget anklickbar zu machen, sodass das Auswählen an einer beliebigen Stelle zu einer anderen Seite navigiert:

1. Fügen Sie ein Anker-Tag als Kindelement des Widget-Container-Elements hinzu.
2. Platzieren Sie alle Widgetinhalte innerhalb des Ankertags.
3. Fügen Sie target="_blank" dem Ankertag hinzu, damit der Link auf einer neuen Registerkarte geöffnet wird.
4. Fügen Sie die clickable Klasse zum Widgetcontainer hinzu.

Ohne die clickable Klasse gilt die blaue Standardverknüpfungsfarbe für den gesamten Text innerhalb des Widgets. Die clickable Klasse bietet auch eine benutzerdefinierte Fokusanzeige für die Tastaturnavigation.

Designprinzip: Verwenden Sie die clickable Klasse und das <a> Tag, um das gesamte Widget klickbar zu machen. Dieses Muster eignet sich gut, wenn Ihr Widget Daten zusammenfasst, die auf einer anderen Seite verfügbar sind.

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

Konfigurationsformularelemente

Verwenden Sie die folgenden Klassen für allgemeine Formularelemente in der Widgetkonfiguration:

Im folgenden Beispiel werden die einzelnen Formularelemente verwendet, die in der Tabelle aufgeführt sind.

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

Überprüfungsfehlermeldungen

Um Validierungsfehler unterhalb von Formularelementen in übereinstimmung mit Erstanbieter-Widgets anzuzeigen, fügen Sie den folgenden Codeausschnitt unter jedem Formularelement hinzu:

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

Die Sichtbarkeit ist standardmäßig ausgeblendet. Um eine Fehlermeldung anzuzeigen, suchen Sie das entsprechende validation-error-text-Element, setzen Sie dessen Text und wenden Sie visibility: visible auf das übergeordnete Element an.

So zeigen Sie z. B. einen Fehler an, wenn ein Textfeld leer ist:

Der HTML-Code hierfür wäre:

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

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