小工具的基本樣式

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

建議您使用透過 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 中。它包括字型系列、字型大小的樣式，以及常見表單元素（如輸入、文字區域和選取）的樣式。

備註

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

下載延伸模組範例。

小工具內文、標題和說明

透過在包含小工具的 HTML 元素上新增類別「widget」，您可以自動取得小工具內容的內嵌、字型和顏色。

您應該始終為小部件設定一個標題。這有助於用戶一目了然地識別您的小工具及其功能。 <h2>與類別「title」一起使用。這也有助於使用螢幕助讀程式的人員快速識別儀表板上的不同小工具。

設計原則： 小工具應該有一個標題。使用具有『title』類別的<h2>標籤。

有時您可能想要提供小部件本身或其使用方法的簡短描述。在這種情況下，請在要用於小部件描述的 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 字型。

設計原則： 使用 “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 容器。

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

若要將Widget SDK中的基本樣式用於Widget設定中的常見表單元素，請遵循下列准則：

表單元素	包裝元素	指導方針
簡單文字方塊	`div` 類別為「single-line-text-input」。	使用 `label` 元素在文字方塊旁邊添加文字。使用元素 `input` 來建立文字方塊。使用屬性 `placeholder` 來提供預留位置文字。
核取方塊	`fieldset` 使用類別「複選框」	使用 `label` 元素，在每個核取方塊旁邊新增文字。使用 `legend` 元素為核取方塊群組添加標題。使用每個`for`元素上的屬性`label`來協助螢幕助讀程式瞭解表單元素。
選項按鈕	`fieldset` 與“無線電”類	使用 `label` 元素在每個選項按鈕旁邊新增文字。使用 `legend` 元素為選項按鈕群組加上標題。使用每個`for`元素上的屬性`label`來協助螢幕助讀程式瞭解表單元素。
下拉式選單	`div` 使用類別「下拉式清單」	使用 `label` 元素在下拉式清單旁邊新增文字。如果您想要佔一半寬度的下拉式選單，請將類別「half」新增至包裝 `div` 元素。如果您想使用 SDK 中的標準箭頭圖示而不是瀏覽器提供的箭頭圖標，請使用類別「wrapper」將元素與另一個`select`元素包裝`div`。
多行文字方塊	`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");
	});

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17

共用方式為

小工具的基本樣式

小工具內文、標題和說明

小工具標題和副標題

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

在小工具中顯示計數器

將小工具設為超連結

Widget 組態中常見表單元素的樣式

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

意見反應

其他資源