文字區塊

  • 發行項

文字塊是用來在應用程式中顯示唯讀文字的主要控制件。 您可以使用它來顯示單行或多行文字、內嵌超連結，以及具有粗體、斜體或底線格式的文字。

這是正確的控制項嗎？

文本塊通常更容易使用，並提供比 RTF 區塊更好的文字轉譯效能，因此最適合大部分的應用程式 UI 文字。 您可以藉由取得 Text 屬性的值 ，輕鬆地從應用程式中的文字塊存取和使用文字 。 它也提供許多相同的格式設定選項，以自定義文字的轉譯方式。

儘管您可以在文字中放置分行符號，但文字區塊是設計來顯示單一段落，不支援文字縮排。 當您需要支援多個段落、多欄文字或其他複雜文字版面配置，或影像等內嵌 UI 元素時，請使用 RichTextBlock。

如需如何選擇正確文字控制項的詳細資訊，請參閱文字控制項文章。

UWP 和 WinUI 2

重要

本文中的資訊和範例已針對使用 Windows 應用程式 SDK 和 WinUI 3 的應用程式進行優化，但通常適用於使用 WinUI 2 的 UWP 應用程式。 如需平臺特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控件所需的資訊。

此控件的 API 存在於 Windows.UI.Xaml.Controls 命名空間中。

我們建議使用最新的 WinUI 2 來取得所有控制件的最新樣式、範本和功能。

建立文字塊

開啟 WinUI 3 資源庫應用程式，並查看 TextBlock 運作情形。

WinUI 3 資源 庫 應用程式包含大部分 WinUI 3 控制件、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上 取得原始程式碼

以下說明如何定義簡單的 TextBlock 控制項，並將其 Text 屬性設定為字串。

<TextBlock Text="Hello, world!" />

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";

內容模型

有兩個屬性可用來將內容新增至 TextBlock： Text 和 Inlines。

顯示文字最常見的方式是將 Text 屬性設定為字串值，如上一個範例所示。

您也可以在 TextBox.Inlines 屬性中放置內嵌流程內容元素來新增內容，如下所示。

<TextBlock>Text can be <Bold>bold</Bold>, <Underline>underlined</Underline>, 
    <Italic>italic</Italic>, or a <Bold><Italic>combination</Italic></Bold>.</TextBlock>

衍生自 Inline 類別的專案，例如 Bold、Italic、Run、Span 和 LineBreak，可針對文字的不同部分啟用不同的格式設定。 如需詳細資訊，請參閱 格式化文字 一節。 內嵌 Hyperlink 元素可讓您將超連結新增至文字。 不過，使用 Inlines 也會停用快速路徑文字轉譯，下一節會討論。

效能考量

可能的話，XAML 會使用更有效率的程式代碼路徑來配置文字。 這個快速路徑會降低整體記憶體使用量，並大幅縮短 CPU 時間，以執行文字測量和排列。 此快速路徑僅適用於 TextBlock，因此最好盡可能透過 RichTextBlock 使用。

某些條件需要 TextBlock 回到功能豐富且需要大量 CPU 的程式代碼路徑，才能轉譯文字。 若要在快速路徑上保留文字轉譯，請務必在設定此處所列的屬性時遵循這些指導方針。

  • Text：最重要的條件是，只有在您在 XAML 或程式代碼中明確設定 Text 屬性來設定文字時，才會使用快速路徑（如先前的範例所示）。 透過 TextBlock 的 Inlines 集合 (例如 <TextBlock>Inline text</TextBlock>) 設定文字將會停用快速路徑，原因在於多重格式具有潛在的複雜性。
  • CharacterSpacing：只有預設值 0 是快速路徑。
  • TextTrimming：只有 None、CharacterEllipsis 和 WordEllipsis 值是快速路徑。 Clip 值會停用快速路徑。

注意 在 Windows 10 版本 1607 之前，其他屬性也會影響快速路徑。 如果您的應用程式是在舊版 Windows 上執行，這些條件也會造成文字呈現在緩慢路徑上。 如需版本的相關詳細資訊，請參閱版本調適型程式碼。

您可以設定 [偵錯 設定]。在偵錯期間，IsTextPerformanceVisualizationEnabled 屬性為 true，以判斷文字是否使用快速路徑轉譯。 當此屬性設定為 true 時，快速路徑上的文字會以亮綠色顯示。

秘訣 ：此功能會在本課程中深入說明 2015- XAML 效能：最大化使用 XAML 建置的通用 Windows 應用程式體驗的技術。

您通常會在 App.xaml 的程式代碼後置頁面中，於 OnLaunched 方法覆寫中設定偵錯設定，如下所示。

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
#if DEBUG
    if (System.Diagnostics.Debugger.IsAttached)
    {
        this.DebugSettings.IsTextPerformanceVisualizationEnabled = true;
    }
#endif

// ...

}

在此範例中，第一個 TextBlock 會使用快速路徑轉譯，而第二個則不是。

<StackPanel>
    <TextBlock Text="This text is on the fast path."/>
    <TextBlock>This text is NOT on the fast path.</TextBlock>
<StackPanel/>

當您使用IsTextPerformanceVisualizationEnabled 在偵錯模式中執行此 XAML 時，結果看起來會像這樣。

Text rendered in debug mode

警告

不在快速路徑上的文字色彩不會變更。 如果您的應用程式中有文字，其色彩指定為亮綠色，當它在較慢的轉譯路徑上時，它仍然以明亮的綠色顯示。 請小心不要混淆應用程式中設定為綠色的文字，以及因為偵錯設定而處於快速路徑和綠色的文字。

格式化文字

雖然 Text 屬性會儲存純文字，但您可以將各種格式選項套用至 TextBlock 控制件，以自定義如何在應用程式中轉譯文字。 您可以設定標準控件屬性，例如 FontFamily、FontSize、FontStyle、Foreground 和 CharacterSpacing 來變更文字的外觀。 您也可以使用內嵌文字元素和印刷樣式附加屬性來格式化文字。 這些選項只會影響 TextBlock 在本機顯示文字的方式，因此，如果您複製文字並貼到 RTF 控件中，例如，不會套用任何格式設定。

注意

請記住，如上一節所述，內嵌文字元素和非預設印刷樣式值不會在快速路徑上呈現。

內嵌專案

Microsoft.UI.Xaml.Documents 命名空間提供各種不同的內嵌文字元素，可讓您用來格式化文字，例如 Bold、Italic、Run、Span 和 LineBreak。

您可以在 TextBlock 中顯示一系列字串，其中每個字串都有不同的格式設定。 您可以使用 Run 元素來顯示每個字串及其格式，以及將每個 Run 元素與 LineBreak 元素分開，即可執行此動作。

以下說明如何使用以LineBreak分隔的 Run 物件，在 TextBlock 中定義數個不同格式的文字字串。

<TextBlock FontFamily="Segoe UI" Width="400" Text="Sample text formatting runs">
    <LineBreak/>
    <Run Foreground="Gray" FontFamily="Segoe UI Light" FontSize="24">
        Segoe UI Light 24
    </Run>
    <LineBreak/>
    <Run Foreground="Teal" FontFamily="Georgia" FontSize="18" FontStyle="Italic">
        Georgia Italic 18
    </Run>
    <LineBreak/>
    <Run Foreground="Black" FontFamily="Arial" FontSize="14" FontWeight="Bold">
        Arial Bold 14
    </Run>
</TextBlock>

結果如下。

Text formatted with run elements

印刷樣式

Typography 類別的附加屬性可讓您存取一組 Microsoft OpenType 印刷樣式屬性。 您可以在 TextBlock 或個別的內嵌文字元素上設定這些附加屬性。 這些範例顯示這兩者。

<TextBlock Text="Hello, world!"
           Typography.Capitals="SmallCaps"
           Typography.StylisticSet4="True"/>

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";
Typography.SetCapitals(textBlock1, FontCapitals.SmallCaps);
Typography.SetStylisticSet4(textBlock1, true);

<TextBlock>12 x <Run Typography.Fraction="Slashed">1/3</Run> = 4.</TextBlock>

取得範例程式碼