ウィジェットの基本的なスタイル

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Widget SDK を使用して提供される基本的なスタイルを使用することをお勧めします。 これらのスタイルを使用すると、ダッシュボード上の他のウィジェットと一貫性のあるウィジェットをすばやく簡単に作成できます。 これらのスタイルを使用するには、ウィジェットの JavaScript コードの ブロック内 VSS.require に次の行を追加します。

	WidgetHelpers.IncludeWidgetStyles();

これにより、sdk-widget.css という名前でスタイルシートがプルされ、ウィジェットの iframe に含まれます。 これには、ウィジェットのフォント ファミリ、フォント サイズ、余白、パディングのスタイルが含まれます。 見出し (h1、h2、h3 など)、リンクなどのスタイルも含まれます。

同様に、ウィジェット構成で一般的なスタイルを使用するには、ウィジェット構成の JavaScript コードの ブロック内 VSS.require に以下の行を含めます。

	WidgetHelpers.IncludeWidgetConfigurationStyles();

これにより、sdk-widget-configuration.css という名前でスタイルシートがプルされ、ウィジェット構成の iframe に含まれます。 これには、フォント ファミリのスタイル、フォント サイズ、入力、テキストエリア、選択などの一般的なフォーム要素のスタイルが含まれます。

拡張機能の サンプルをダウンロードします。

ウィジェットの本文、タイトル、説明

ウィジェットを含む HTML 要素にクラス "widget" を追加すると、ウィジェットの内容のパディング、フォント、色が自動的に取得されます。

ウィジェットには常にタイトルが必要です。 これは、ユーザーがウィジェットとその機能を一目で識別するのに役立ちます。 クラス "title" で を使用 <h2> します。 また、スクリーン リーダーを使用するユーザーは、ダッシュボードのさまざまなウィジェットをすばやく識別するのにも役立ちます。

設計原則: ウィジェットにはタイトルが必要です。 タグを <h2> "title" クラスと共に使用します。

ウィジェットに関する簡単な説明や使用方法を入力したい場合があります。 このような場合は、ウィジェットの説明に使用する HTML 要素でクラス "description" を使用します。

設計原則: ウィジェットの説明には "description" クラスを使用します。 ウィジェット コンテキストから読み取った場合でも、説明が意味をなします。

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

ウィジェットのタイトルとサブタイトル

字幕はタイトルを補足するテキストです。 タイトルを読まずにコンテキストから読み取ると、必ずしも意味をなさない場合があります。

設計原則: ウィジェットに関する詳細情報を提供するには、"subtitle" クラスを使用します。 ウィジェットコンテキストから意味をなさない場合があります。

次の構造体とクラス "title"、"inner-title"、"subtitle" を使用して、タイトルとサブタイトルの組み合わせに適したフォント、色、余白を取得します。 タイトルは、サブタイトルよりも大きなフォント サイズを取得します。 サブタイトルには、ウィジェットのタイトルまたは残りの部分に対して相対的な落ち着いた色があります。

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

タイトルとサブタイトルの組み合わせには、任意の html 要素を使用できます。 いくつかのヒントを次に示します。

• タイトルと同じ行にサブタイトルを表示する必要がある場合は、 のようなインライン要素を使用します。 <span>
• タイトルの次の行にサブタイトルを表示する必要がある場合は、 のようなブロック要素を使用します。 <div>

ウィジェットにハイパーリンク、アイコン、テキスト、サブテキストを表示する

一部のウィジェットには、リンクごとにアイコン、テキスト、サブテキストを含むリンクがあります。

設計原則: アイコンとサブテキストを含むリンクを使用して、リンクの目的をユーザーに明らかにします。 アイコンがリンクのターゲットをシンボル表示していることを確認します。

同じ外観を得るには、次の HTML 構造とクラスを使用します。

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

ウィジェットにカウンターを表示する

一部のウィジェットの主な目的は、一部のデータの数を表示することです。 クエリ タイルウィジェットとコード タイル ウィジェットは、このカテゴリのウィジェットの例です。 これらのウィジェットと同じスタイルを使用するには、数値を保持する HTML 要素に "big-count" クラスを追加して、クエリ タイルウィジェットとコード タイル ウィジェットで使用される大きなフォントを取得します。

設計原則: "big-count" クラスを使用して、ユーザーに大きなフォントで数値を表示します。 数値以外の文字では使用しないでください。

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

ウィジェットをハイパーリンクにする

一部のウィジェットの任意の場所をクリックすると、ユーザーは別のページにリダイレクトされます。 ウィジェットで同じ操作を行うには、次の操作を行います。

• ウィジェット コンテナーとして機能する HTML 要素に、アンカー タグを子として追加します。
• すべてのウィジェット コンテンツをアンカー タグ内に配置します。
• ウィジェットは iframe でホストされるため、値 "_blank" の属性 "target" をアンカー タグに追加して、リンクが同じ iframe 内ではなく新しいタブ/ウィンドウで開きます。
• "widget" クラスに加えて、ウィジェット コンテナーに "clickable" クラスを追加します。

ウィジェットのコンテンツは、アンカー タグ内にあるにもかかわらず、正しい色を取得します。 "clickable" クラスがない場合、ウィジェット内のすべてのテキストに対して既定の青い色が強制されます。 このウィジェットには、キーボードを使用してダッシュボードを移動するユーザーを支援するために、フォーカスに関するカスタム ビジュアル キューも取得されます。

設計原則: "clickable" クラスと タグを <a> 使用して、ウィジェット全体をクリック可能にします。 これは、ウィジェットが別のページで使用可能なデータの概要である場合に最適です。

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

ウィジェット構成の一般的なフォーム要素のスタイル

ウィジェット構成の一般的なフォーム要素にウィジェット SDK の基本スタイルを使用するには、次のガイドラインに従います。

次の例では、表に示されている各フォーム要素を使用します。

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

フォーム要素の下に検証エラーを表示する

関連するフォーム要素の下に検証エラーを指定することをお勧めします。 これらのメッセージをファースト パーティ ウィジェットと一致する方法で表示するには、エラー メッセージを表示する各フォーム要素の下に次のコード スニペットを追加します。

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

前のコード スニペットでは、既定で表示が非表示になっています。 エラー メッセージを表示する場合は常に、対応する "validation-error-text" を見つけ、それにテキストを追加し、その親に設定 visibility:visible します。

例: ユーザーが文字列を入力する必要がある単純なテキスト ボックスがあります。 テキスト ボックスが空の場合は、エラー メッセージを表示する必要があります。

この html は次のようになります。

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

この背後にある JavaScript コードは次のようになります。

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