小工具的基本樣式

發行項
04/04/2024

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

建議您使用透過 Widget SDK 提供的基本樣式。使用這些樣式可協助您快速且輕鬆地建立與儀錶板上其餘小工具一致的小工具。若要使用這些樣式，請在小工具的 JavaScript 程式代碼中，於區塊內 VSS.require 新增下列程式代碼行。

提示

請參閱使用 Azure DevOps 擴充功能 SDK 進行擴充功能開發的最新檔。

	WidgetHelpers.IncludeWidgetStyles();

這會依名稱提取樣式表單sdk-widget.css，並將其包含在小工具的 iframe 中。它包含字型系列、字型大小、邊界和小工具邊框間距的樣式。它也包含標題樣式（h1、h2、h3 等）、連結等等。

同樣地，若要在小工具組態中使用一般樣式，請在小工具組態的 JavaScript 程式代碼中包含下列 VSS.require 程式碼內的行。

	WidgetHelpers.IncludeWidgetConfigurationStyles();

這會依名稱sdk-widget-configuration.css提取樣式表單，並將其包含在小工具設定的 iframe 中。它包含字型系列、字型大小和通用表單元素的樣式，例如 input、textarea 和 select。

注意

若要將這些樣式套用至您的小工具，您必須在包含小工具的 HTML 元素上新增「小工具」類別。 sdk-widgets.css的所有樣式都限定於這個類別。同樣地，在包含小工具組態的 HTML 元素上新增「widget-configuration」類別。 sdk-widget-configuration.css的所有樣式都限定於這個類別。

下載延伸模組範例。

小工具主體、標題和描述

藉由在包含小工具的 HTML 元素上新增類別「widget」，即可自動取得小工具內容的填補、字型和色彩。

您應該一律會有小工具的標題。這有助於使用者一目了然地識別您的小工具及其功能。搭配類別「title」使用 <h2> 。這也有助於使用螢幕助讀程式的人員快速識別儀錶板上的不同小工具。

設計原則： 小工具應該有標題。搭配 <h2> 「title」類別使用標記。

有時候，您可能會想要提供小描述您的小工具，或如何使用小工具。在這種情況下，請在您想要用於小工具描述的 HTML 元素上使用類別「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」類別新增至 Widget 容器。

即使小工具內容位於錨點標籤內，仍會取得正確的色彩。如果沒有「可點選」類別，則小工具內的所有文字上都會強制使用預設的藍色色彩。小工具也會取得焦點的自定義視覺效果提示，以協助使用鍵盤瀏覽儀錶板的使用者。

設計原則： 使用「可點選」類別和 <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 中通用窗體元素的基本樣式，請遵循下列指導方針：

表單項目	Wrapping 元素	指導方針
簡單文字框	`div` 具有「single-line-text-input」類別。	`label`使用元素來新增文字框旁的文字。 `input`使用專案來建立文字框。 `placeholder`使用屬性來提供佔位元文字。
核取方塊	`fieldset` 具有類別「checkbox」	`label`使用元素來新增每個複選框旁的文字。 `legend`使用專案來標題複選框群組。 `for`使用每個`label`元素上的屬性，協助螢幕助讀程式了解表單元素。
選項按鈕	`fieldset` 具有類別 “radio”	`label`使用元素來新增每個單選按鈕旁的文字。 `legend`使用專案來標題單選按鈕群組。 `for`使用每個`label`元素上的屬性，協助螢幕助讀程式了解表單元素。
下拉式清單	`div` 具有類別 “dropdown”	`label`使用元素來新增下拉式清單旁的文字。如果您想要將下拉式清單佔用一半的寬度，請將類別「half」新增至 wrapping `div` 元素。如果您想要從 sdk 使用標準箭號圖示，而不是瀏覽器所提供的箭號圖示，請使用類別 `div` 「wrapper」包裝`select`專案。
多行文字框	`div` 具有類別「multi-line-text-input」。。	使用 `label` 元素來標記 `textarea` 用作多行文字框的專案。

下列範例會使用表格中列出的每個表單專案。

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

共用方式為

小工具的基本樣式

小工具主體、標題和描述

小工具標題和字幕

在小工具中顯示超連結、圖示、文字和子文字

在小工具中顯示計數器

將小工具設為超連結

小工具組態中通用表單項目的樣式

在表單元素下方顯示驗證錯誤

意見反應

其他資源