Styles de base pour vos widgets

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

Conseil / Astuce

Pour obtenir les dernières instructions de développement d’extension, notamment les thèmes et la migration à partir de VSS. Sdk, consultez le portail du kit de développement logiciel (SDK) d’extension Azure DevOps.

Utilisez les styles de base fournis par le Kit de développement logiciel (SDK) widget pour une apparence cohérente entre les widgets de tableau de bord.

Pour inclure des styles de widgets, appelez WidgetHelpers.IncludeWidgetStyles() lors de l’initialisation du widget :

WidgetHelpers.IncludeWidgetStyles();

Cela charge sdk-widget.css dans l'iframe de votre widget, fournissant des styles pour la famille de polices, la taille de police, les marges, les espacements, les en-têtes et les liens.

Pour les panneaux de configuration de widgets, appelez WidgetHelpers.IncludeWidgetConfigurationStyles() à la place :

WidgetHelpers.IncludeWidgetConfigurationStyles();

Cela charge sdk-widget-configuration.css, qui fournit des styles pour la famille de polices, la taille de police et les éléments de formulaire courants tels que input, textareaet select.

Note

Pour que ces styles s’appliquent, ajoutez une widget classe sur l’élément HTML qui contient votre widget. Tous les styles de sdk-widget.css sont limités à cette classe. De même, ajoutez une widget-configuration classe sur l’élément qui contient votre configuration de widget.

Pour obtenir un exemple de travail, consultez l’exemple d’extension.

Corps, titre et description du widget

En ajoutant la classe sur l’élément widget conteneur de votre widget, vous obtenez automatiquement le remplissage, la police et la couleur du contenu du widget.

Incluez toujours un titre pour votre widget afin que les utilisateurs puissent identifier son objectif en un clin d’œil. Utiliser <h2> avec la title classe. Cela permet également aux lecteurs d’écran d’identifier les différents widgets du tableau de bord.

Widget avec titre et description

Principe de conception : Les widgets doivent avoir un titre. Utilisez la <h2> balise avec la title classe.

Pour ajouter une description, utilisez la description classe sur l’élément qui contient la description de votre widget.

Principe de conception : Utilisez la description classe pour la description du widget. Les descriptions doivent être logiques même quand elles sont lues en dehors du contexte du widget.

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

Titres et sous-titres du widget

Les sous-titres complètent le titre et peuvent ne pas être logiques lors de la lecture hors contexte.

Widget avec titre et sous-titre

Principe de conception : Utilisez la subtitle classe pour fournir plus d’informations sur le widget.

Utilisez les classes title, inner-title et subtitle pour obtenir la police, la couleur et les marges appropriées pour une combinaison de titre et de sous-titre. Le sous-titre a une couleur plus douce par rapport au titre.

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

Conseils pour la combinaison de titres et de sous-titres :

  • Utilisez un élément inline comme <span> pour que le sous-titre apparaisse sur la même ligne que le titre.
  • Utilisez un élément de bloc comme <div> pour que le sous-titre apparaisse sur une nouvelle ligne.

Certains widgets incluent des liens avec une icône, un texte et un sous-texte.

Widget qui a un lien avec l’icône et le texte

Principe de conception : Utilisez des liens avec une icône et un sous-texte pour rendre le lien évident à l’utilisateur. Vérifiez que l’icône symbolise la cible du lien.

Pour obtenir la même apparence, utilisez la structure et les classes HTML ci-dessous.

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

Compteurs

Pour les widgets qui affichent un nombre, ajoutez la big-count classe à l’élément contenant le nombre. Les widgets vignette de requête et vignette de code utilisent ce même style.

Widget compteur

Principe de conception : Utilisez la big-count classe pour présenter des nombres dans une police volumineuse. Ne l’utilisez pas avec des caractères non numériques.

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

Widgets cliquables

Pour rendre un widget cliquable afin de le sélectionner n’importe où, accédez à une autre page :

  1. Ajoutez une balise d’ancrage en tant qu’enfant de l’élément conteneur de widgets.
  2. Placez tout le contenu du widget à l’intérieur de la balise d’ancrage.
  3. Ajoutez target="_blank" à la balise d’ancrage pour que le lien s’ouvre dans un nouvel onglet.
  4. Ajoutez la clickable classe au conteneur de widgets.

Sans la clickable classe, la couleur de lien bleu par défaut s’applique à tout le texte à l’intérieur du widget. La clickable classe fournit également un indicateur de focus personnalisé pour la navigation au clavier.

Principe de conception : Utilisez la clickable classe et la <a> balise pour rendre l’intégralité du widget cliquable. Ce modèle fonctionne bien lorsque votre widget récapitule les données disponibles sur une autre page.

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

Éléments de formulaire de configuration

Utilisez les classes suivantes pour les éléments de formulaire courants dans la configuration du widget :

élément de formulaire Élément d'encapsulation Guidelines
Zone de texte simple div avec une classe nommée « single-line-text-input ». Utilisez un label élément pour ajouter du texte en regard de la zone de texte. Utilisez l’élément input pour créer une zone de texte. Utilisez l’attribut placeholder pour fournir du texte d’espace réservé.
Case à cocher fieldset avec la classe « case à cocher » Utilisez un élément label pour ajouter du texte à côté de chaque case à cocher. Utilisez un legend élément pour légender le groupe de cases à cocher. Utilisez l’attribut for sur chaque label élément pour aider les lecteurs d’écran à comprendre l’élément de formulaire.
Case d’option fieldset avec la classe « radio » Utilisez un élément label pour ajouter du texte en regard de chaque case d’option. Utilisez un legend élément pour légender le groupe de boutons radio. Utilisez l’attribut for sur chaque label élément pour aider les lecteurs d’écran à comprendre l’élément de formulaire.
Liste déroulante div avec la classe « dropdown » Utilisez un élément label pour ajouter du texte à côté de la liste déroulante. Si vous souhaitez une liste déroulante occupant la moitié de la largeur, ajoutez la classe « half » à l’élément enveloppant div. Si vous souhaitez utiliser l’icône de flèche standard à partir du SDK au lieu de celle fournie par le navigateur, encapsulez l’élément select dans un autre élément div avec la classe « wrapper ».
Zone de texte à plusieurs lignes div avec la classe « champ-texte-multiligne ». Utilisez l’élément label pour étiqueter l’élément textarea utilisé comme zone de texte à plusieurs lignes.

L’exemple suivant utilise chacun des éléments de formulaire répertoriés dans le tableau.

Exemple de configuration du widget 

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

Messages d’erreur de validation

Pour afficher les erreurs de validation sous les éléments de formulaire d’une manière cohérente avec les widgets internes, ajoutez l’extrait de code suivant sous chaque élément de formulaire :

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

La visibilité est masquée par défaut. Pour afficher un message d’erreur, recherchez l’élément correspondant validation-error-text , définissez son texte et définissez visibility: visible sur son parent.

Par exemple, pour afficher une erreur lorsqu’une zone de texte est vide :

Exemple d’erreur de configuration du widget

Le code html correspondant à ceci serait :

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

Et 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";
    }
});
  • Last updated on