Estilos básicos para seus widgets

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

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 VSS.require bloco no código JavaScript do seu widget.

Gorjeta

Confira nossa documentação mais recente sobre desenvolvimento de extensões usando o SDK de Extensão do Azure DevOps.

	WidgetHelpers.IncludeWidgetStyles();

Isso puxa uma folha de estilo pelo 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 VSS.require bloco no código JavaScript para sua configuração de widget.

	WidgetHelpers.IncludeWidgetConfigurationStyles();

Isso puxa uma folha de estilo pelo nome sdk-widget-configuration.css e a inclui no iframe para sua configuração de 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.

Nota

Para que esses estilos se apliquem ao widget, você precisa adicionar uma classe "widget" no 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 sua configuração de widget. Todos os estilos do sdk-widget-configuration.css têm escopo para esta classe.

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: Os widgets devem ter um título. Use a <h2> tag 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: Use a classe "legenda" para fornecer mais informações 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 do 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 a finalidade do link óbvia 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 marca âncora como filho ao elemento HTML que atua como 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 é forçada em todo o texto dentro do widget. O widget também recebe uma sugestão visual personalizada em foco para ajudar os usuários que usam o teclado a navegar no painel.

Princípio de design: Use a classe "clicável" e a <a> tag 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:

Elemento de formulário	Elemento de embrulho	Diretrizes
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 verificação	fieldset com 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.
Radio button	fieldset com classe "rádio"	Use um label elemento para adicionar texto ao lado de cada botão de opção. Use um legend elemento 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.
Lista pendente	div com classe "dropdown"	Use um label elemento para adicionar texto ao lado da lista suspensa. Se você quiser uma lista suspensa ocupando metade da largura, adicione a classe "metade" ao elemento de encapsulamento div . Se você quiser usar o ícone de seta padrão do sdk em vez do fornecido pelo navegador, envolva o select elemento com outro com a div classe "wrapper".
Caixa de texto com várias linhas	div com classe "multi-line-text-input".	Use label o elemento para rotular o textarea elemento usado como caixa de texto de várias linhas.

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 você quiser exibir uma mensagem de erro, encontre o correspondente "validation-error-text", adicione texto a ele e defina visibility:visible em seu 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");
	});