Estilos básicos para seus widgets

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Use os estilos básicos fornecidos pelo Widget SDK para um aspeto consistente entre os widgets do dashboard.

Para incluir estilos de widgets, chame WidgetHelpers.IncludeWidgetStyles() durante a inicialização do widget:

WidgetHelpers.IncludeWidgetStyles();

Isto carrega sdk-widget.css no iframe do seu widget, fornecendo estilos para família de fontes, tamanho de letra, margens, preenchimentos, cabeçalhos e links.

Para painéis de configuração de widgets, chame WidgetHelpers.IncludeWidgetConfigurationStyles() em vez disso:

WidgetHelpers.IncludeWidgetConfigurationStyles();

Isto carrega sdk-widget-configuration.css, que fornece estilos para a família de fontes, o tamanho da fonte e elementos comuns de formulário como input, textarea, e select.

Para um exemplo prático, veja a amostra de extensão.

Corpo, título e descrição do widget

Ao adicionar a classe widget no elemento de contentor do seu widget, obtém automaticamente o padding, a fonte e a cor para os conteúdos do widget.

Inclua sempre um título para o seu widget para que os utilizadores possam identificar o seu propósito num instante. Utilize <h2> com a classe title. Isto também ajuda os leitores de ecrã a identificar os diferentes widgets no painel de controlo.

Princípio de design: Widgets devem ter um título. Utilize a <h2> tag com a title classe.

Para adicionar uma descrição, use a description classe no elemento que contém a descrição do seu widget.

Princípio de design: Usa a description classe para a descrição do widget. As descrições devem fazer sentido mesmo quando lidas fora do contexto do 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>

Títulos e legendas de widgets

As legendas complementam o título e podem não fazer sentido quando lidas fora de contexto.

Princípio de design: Use a subtitle classe para fornecer mais informações sobre o widget.

Use as classes title, inner-title e subtitle para obter a fonte, cor e margens certas para a combinação de título e subtítulo. O subtítulo tem uma cor suave em relação ao título.

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

Dicas para a combinação de título e legendas:

• Use um elemento inline, como <span> para a legenda aparecer na mesma linha do título.
• Usa um elemento de bloco, como <div> para a legenda aparecer numa nova linha.

Ligações com ícones e subtexto

Alguns widgets incluem ligações com um ícone, texto e subtexto.

Princípio de design: Use links com um ícone e subtexto para tornar o propósito do link óbvio para o usuário. Certifique-se de que o ícone simboliza o destino do link.

Para obter a mesma aparência, use a estrutura e as classes HTML abaixo.

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

Contadores

Para widgets que mostram uma contagem, adicione a big-count classe no elemento que contém o número. Os widgets Query Tile e Code Tile usam este mesmo estilo.

Princípio de design: Use a big-count classe para apresentar números em letra grande. Não o uses com caracteres não numéricos.

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

Widgets clicáveis

Para tornar um widget clicável para que ao o selecionar em qualquer lugar se navegue para outra página:

1. Adicione uma etiqueta de âncora como filho do elemento do contentor de widget.
2. Coloque todo o conteúdo do widget dentro da tag âncora.
3. Adicione target="_blank" à etiqueta âncora para que o link abra numa nova aba.
4. Adicione a clickable classe ao contentor de widgets.

Sem a clickable classe, a cor azul padrão do link aplica-se a todo o texto dentro do widget. A clickable classe também disponibiliza um indicador de foco personalizado para a navegação por teclado.

Princípio de design: Usa a clickable classe e a <a> etiqueta para tornar todo o widget clicável. Este padrão funciona bem quando o seu widget resume dados disponíveis noutra página.

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

Elementos do formulário de configuração

Use as seguintes classes para elementos de formulário comuns na configuração de widgets:

O exemplo seguinte utiliza cada um dos elementos da forma listados na tabela.

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

Mensagens de erro de validação

Para mostrar erros de validação abaixo dos elementos do formulário de forma consistente com widgets de primeira parte, adicione o seguinte excerto sob cada elemento do formulário:

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

A visibilidade está oculta por defeito. Para mostrar uma mensagem de erro, encontre o elemento correspondente validation-error-text, defina o seu texto, e aplique visibility: visible ao seu elemento pai.

Por exemplo, para mostrar um erro quando uma caixa de texto está vazia:

O html para isso seria:

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

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