Estilos básicos para seus widgets

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

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

Dica

Confira a nossa documentação mais nova sobre desenvolvimento de extensões usando o Azure DevOps Extension SDK.

	WidgetHelpers.IncludeWidgetStyles();

Isso carrega um arquivo de estilo denominado sdk-widget.css e o inclui no iframe para seu widget. Ele inclui estilos para família de fontes, tamanho da fonte, margem e preenchimentos para seu widget. Ele também inclui estilos para títulos (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 VSS.require bloco no código JavaScript para sua configuração de widget.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Isso carrega uma folha de estilos chamada sdk-widget-configuration.css e a inclui para a configuração do seu widget no iframe. Ele inclui estilos para família de fontes, tamanho da fonte e estilos para elementos de formulário comuns, como entrada, textarea e seleção.

Observação

Para que esses estilos se apliquem ao seu widget, você precisa adicionar uma classe "widget" ao elemento HTML que contém o widget. Todos os estilos do sdk-widgets.css têm como escopo essa classe. Da mesma forma, adicione uma classe "widget-configuration" no elemento HTML que contém a configuração do widget. Todos os estilos do sdk-widget-configuration.css têm como escopo essa classe.

Baixe o exemplo de extensão.

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

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

Você sempre deve ter um título para 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: Os widgets devem ter um título. Use o <h2> tag com a classe "title".

Às vezes, talvez você queira 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>

Legendas são texto que complementam o título. Eles podem nem sempre fazer sentido quando lidos fora de contexto sem ler o título.

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

Use a estrutura e as classes "title", "inner-title" e "subtítulo" abaixo para obter a fonte, a cor e as margens certas para uma combinação de título e subtítulo. O título obtém um tamanho de fonte maior que o subtítulo. O subtítulo tem uma cor discreta em relação ao título ou ao restante 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 subtítulo. Aqui estão algumas dicas:

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

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 a finalidade do link óbvia para o usuário. Verifique se o ícone simboliza o destino do link.

Para obter a mesma aparência, use a estrutura HTML e as classes 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>

A principal finalidade de alguns widgets é exibir a contagem de alguns dados. O bloco de consulta e os widgets de bloco de código são exemplos nessa 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 de Query Tile e Code Tile.

Princípio de design: Use a classe "big-count" para apresentar ao usuário números em fontes grandes. Ele 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>

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 de âncora dentro do elemento HTML que atua como o contêiner do seu widget.
Coloque todo o conteúdo do widget dentro da tag de âncora.
Como o widget está hospedado em um iframe, adicione o atributo "target" com o valor "_blank" à marca de âncora 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 "clicável" ao contêiner do widget.

O conteúdo do widget recebe as cores corretas mesmo estando dentro de uma tag âncora. Sem a classe "clicável", a cor azul padrão é aplicada automaticamente a todo o texto dentro do widget. O widget também obtém uma indicação visual personalizada quando estiver em foco para ajudar os usuários que usam o teclado a navegar pelo painel.

Princípio de design: Use a classe "clicável" e a <a> marca para tornar o widget inteiro clicável. Isso é ideal quando o widget é um resumo dos 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>

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

Elemento Form	Elemento de Envoltório	Guidelines
Caixa de texto simples	`div` com a classe "single-line-text-input".	Use um `label` elemento para adicionar texto ao lado da caixa de texto. Use o `input` elemento para criar uma caixa de texto. Use o `placeholder` atributo para fornecer texto de espaço reservado.
Caixa de seleção	`fieldset` com a classe "checkbox"	Use um `label` elemento para adicionar texto ao lado de cada caixa de seleção. Use um `legend` elemento para legendar o grupo de caixas de seleção. Use o `for` atributo em cada `label` elemento para ajudar os leitores de tela a entender o elemento de formulário.
Botão de opção	`fieldset` com a classe "radio"	Use um elemento `label` para adicionar texto ao lado de cada botão de opção. Utilize um elemento `legend` para legendar o grupo de botões de opção. Use o `for` atributo em cada `label` elemento para ajudar os leitores de tela a entender o elemento de formulário.
Dropdown	`div` com a classe "dropdown"	Use o elemento `label` para adicionar texto ao lado da lista suspensa. Se você quer um menu suspenso que ocupe metade da largura, adicione a classe "half" ao elemento de encapsulamento `div`. Se você quiser usar o ícone de seta padrão do sdk em vez do fornecido pelo navegador, encapsule o elemento `select` com outro `div` com a classe "wrapper".
Caixa de texto de várias linhas	`div` com a classe "multi-line-text-input".	Use o elemento `label` para rotular o elemento `textarea` usado como caixa de texto de várias linhas.

O exemplo a seguir 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

É recomendável fornecer erros de validação abaixo dos elementos de formulário relevantes. Para exibir essas mensagens de maneira consistente com widgets de 1ª parte, adicione o snippet de código a seguir 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 snippet de código anterior tem a visibilidade oculta por padrão. Sempre que você quiser exibir uma mensagem de erro, localize o "validation-error-text" correspondente, adicione texto a ele e configure visibility:visible em seu elemento pai.

Exemplo: há uma caixa de texto simples em que o usuário precisa digitar uma cadeia de caracteres. Você precisará 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");
	});

Comentários

Esta página foi útil?

Last updated on 2025-12-17

Compartilhar via

Estilos básicos para seus widgets

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

Títulos e subtítulos do widget

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

Exibir contadores em um widget

Tornar um widget um hiperlink

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

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

Comentários

Recursos adicionais