Estilos básicos para seus widgets

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

Recomendamos que você use os estilos básicos fornecidos através do SDK do Widget. O uso desses estilos ajuda você a criar rápida e facilmente um widget consistente com o restante dos widgets no painel. Para usar esses estilos, adicione a linha abaixo dentro do bloco VSS.require no código JavaScript do widget.

	WidgetHelpers.IncludeWidgetStyles();

Isto carrega uma folha de estilo com o nome sdk-widget.css e a inclui no iframe do seu widget. Inclui estilos para família de fontes, tamanho de fonte, margem e preenchimentos para seu widget. Também inclui estilos para cabeçalhos (h1, h2, h3 etc.), links e muito mais.

Da mesma forma, para usar estilos comuns na configuração do widget, inclua a linha abaixo dentro do bloco VSS.require no código JavaScript para sua configuração do widget.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Isso puxa uma folha de estilo pelo nome sdk-widget-configuration.css e a inclui no iframe para a configuração do widget. Ele inclui estilos para família de fontes, tamanho de fonte e estilos para elementos de formulário comuns, como entrada, área de texto e seleção.

Faça o download do exemplo de extensão .

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

Ao adicionar a classe "widget" no elemento HTML que contém seu widget, você obtém automaticamente preenchimento, fonte e cor para o conteúdo do widget.

Você sempre deve ter um título para o seu widget. Isso ajuda o usuário a identificar seu widget e sua funcionalidade rapidamente. Use <h2> com a classe "title". Isso também ajuda as pessoas que usam leitores de tela a identificar rapidamente os diferentes widgets no painel.

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

Às vezes, você pode querer fornecer uma pequena descrição sobre seu widget ou como usá-lo. Nesses casos, use a classe "description" no elemento HTML que você deseja usar para a descrição do widget.

Princípio de design: Use a classe "description" 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 são textos que complementam o título. Podem nem sempre fazer sentido quando lidos fora de contexto sem ler o título.

Princípio de design: Utilize a classe "subtítulo" para fornecer informações adicionais sobre o widget. Pode não fazer sentido fora do contexto do widget.

Use a estrutura abaixo e as classes "title", "inner-title" e "subtitle" para obter a fonte, cor e margens corretas para uma combinação de título e legenda. O título recebe um tamanho de fonte maior do que a legenda. A legenda tem uma cor moderada em relação ao título ou ao resto do widget.

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

Você pode usar qualquer elemento html para a combinação de título e legenda. Aqui ficam algumas dicas:

• Quando precisar que a legenda apareça na mesma linha que o título, use um elemento embutido como <span>
• Quando precisar que a legenda apareça na próxima linha do título, use um elemento de bloco como <div>

Exibir hiperlinks, ícones, texto e subtexto em um widget

Alguns widgets têm links que têm um ícone, texto e subtexto por link.

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>

Exibir contadores em um widget

O objetivo principal de alguns widgets é exibir a contagem de alguns dados. Os widgets Bloco de consulta e Bloco de código são exemplos nesta categoria de widgets. Para usar os mesmos estilos desses widgets, adicione a classe "big-count" no elemento HTML que contém o número para obter a fonte grande usada pelos widgets Bloco de Consulta e Bloco de Código.

Princípio de design: Use a classe "big-count" para apresentar ao usuário números em fonte grande. Não deve ser usado 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>

Tornar um widget um hiperlink

Clicar em qualquer lugar em alguns widgets redireciona o usuário para outra página. Para que seu widget faça o mesmo, você pode:

• Adicione uma tag âncora como descendente ao elemento HTML que atua como o seu contêiner de widget.
• Coloque todo o conteúdo do widget dentro da tag âncora.
• Como seu widget está hospedado em um iframe, adicione o atributo "target" com o valor "_blank" à tag anchor para que o link seja aberto em uma nova guia/janela em vez de dentro do mesmo iframe.
• Além da classe "widget", adicione a classe "clickable" ao contêiner do widget.

O conteúdo do widget recebe as cores corretas, mesmo que elas estejam dentro de uma tag âncora. Sem a classe "clicável", a cor azul padrão é aplicada a todo o texto dentro do widget. O widget também recebe um indicador visual personalizado quando está em foco para ajudar os utilizadores que usam o teclado a navegar no dashboard.

Princípio de design: Use a classe "clicável" e a tag <a> para tornar todo o widget clicável. Isso é ideal quando seu widget é um resumo de dados disponíveis em outra 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>

Estilos para elementos de formulário comuns na configuração do widget

Para usar estilos básicos do widget sdk para elementos de formulário comuns na configuração do widget, siga estas diretrizes:

O exemplo abaixo usa cada um dos elementos de formulário 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>

Exibir erros de validação abaixo de um elemento de formulário

Recomendamos fornecer erros de validação abaixo dos elementos de formulário relevantes. Para exibir essas mensagens de maneira consistente com widgets de 1º partido, adicione o seguinte trecho de código em cada elemento de formulário para o qual você deseja mostrar a mensagem de erro.

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

O trecho de código anterior tem a visibilidade oculta por padrão. Sempre que quiseres exibir uma mensagem de erro, identifica o "validation-error-text" correspondente, adiciona texto a ele e aplica visibility:visible no elemento pai.

Exemplo: Há uma caixa de texto simples onde o usuário precisa digitar uma cadeia de caracteres. Você precisa mostrar uma mensagem de erro se a caixa de texto estiver vazia.

O html para isso seria:

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

E o código JavaScript por trás disso seria:

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