Estilos básicos para seus widgets

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

Use os estilos básicos fornecidos pelo SDK do Widget para uma aparência consistente entre widgets do painel.

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

WidgetHelpers.IncludeWidgetStyles();

O sdk-widget.css é carregado no iframe do widget, fornecendo estilos para família de fontes, tamanho da fonte, margens, recuos, títulos e links.

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

WidgetHelpers.IncludeWidgetConfigurationStyles();

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

Para obter um exemplo de trabalho, consulte o exemplo de extensão.

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

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

Sempre inclua um título para seu widget para que os usuários possam identificar sua finalidade rapidamente. Use <h2> com a title classe. Isso também ajuda os leitores de tela a identificar os diferentes widgets no painel.

Princípio de design: Os widgets devem ter um título. Use a <h2> marca com a title classe.

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

Princípio de design: Use 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 subtítulos do widget

Subtítulos complementam o título e podem não fazer sentido quando lidos 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 corretas para uma 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 subtítulo:

• Use um elemento embutido como <span> para o subtítulo aparecer na mesma linha que o título.
• Use um elemento de bloco como <div> para que o subtítulo apareça em uma nova linha.

Links com ícones e subtexto

Alguns widgets incluem links com um ícone, texto e subtexto.

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>

Contadores

Para widgets que exibem uma contagem, adicione a big-count classe no elemento que contém o número. Os widgets bloco de consulta e bloco de código usam esse mesmo estilo.

Princípio de design: Use a big-count classe para apresentar números em fontes grandes. Não use-o 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 selecioná-lo em qualquer lugar, navegue até outra página:

1. Adicione uma tag de âncora como filho do elemento contêiner do widget.
2. Coloque todo o conteúdo do widget dentro da tag de âncora.
3. Adicione target="_blank" à marca de âncora para que o link seja aberto em uma nova guia.
4. Adicione a clickable classe ao contêiner de widget.

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

Princípio de design: Use clickable class e o <a> tag para tornar todo o widget clicável. Esse padrão funciona bem quando o widget resume os 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>

Elementos de formulário de configuração

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

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>

Mensagens de erro de validação

Para exibir erros de validação abaixo dos elementos de formulário de maneira consistente com widgets de primeira parte, adicione o seguinte snippet em cada elemento de formulário:

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

A visibilidade está oculta por padrão. Para exibir uma mensagem de erro, localize o elemento correspondente validation-error-text, configure o texto nele e ajuste o visibility: visible no seu elemento pai.

Por exemplo, para mostrar um erro quando uma 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" 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";
    }
});