文字區塊Text block

TextBlock 是在應用程式中顯示唯讀文字的主要控制項。Text block is the primary control for displaying read-only text in apps. 您可以使用它來顯示單行或多行文字、內嵌的超連結,以及已設定格式的文字 (例如,粗體、斜體或加上底線)。You can use it to display single-line or multi-line text, inline hyperlinks, and text with formatting like bold, italic, or underlined.

平台 APITextBlock 類別Text 屬性Inlines 屬性Platform APIs: TextBlock class, Text property, Inlines property

這是正確的控制項嗎?Is this the right control?

文字區塊通常很容易使用,且提供較 RTF 文字區塊更優異的文字轉譯效能,因此使其成為大部分應用程式 UI 文字的首選。A text block is typically easier to use and provides better text rendering performance than a rich text block, so it's preferred for most app UI text. 您可取得 Text 屬性值,以在您的應用程式中透過文字區塊輕鬆存取和使用文字。You can easily access and use text from a text block in your app by getting the value of the Text property. 其還提供許多可用來自訂您文字轉譯方式的相同格式設定選項。It also provides many of the same formatting options for customizing how your text is rendered.

儘管您可以在文字中放置分行符號,但文字區塊是設計來顯示單一段落,不支援文字縮排。Although you can put line breaks in the text, text block is designed to display a single paragraph and doesn't support text indentation. 當您需要支援多個段落、多欄文字或其他複雜的文字配置,或是內嵌的 UI 元素 (例如影像) 時,請使用 RichTextBlockUse a RichTextBlock when you need support for multiple paragraphs, multi-column text or other complex text layouts, or inline UI elements like images.

如需如何選擇正確文字控制項的詳細資訊,請參閱文字控制項文章。For more info about choosing the right text control, see the Text controls article.

範例Examples

XAML 控制項庫XAML Controls Gallery
XAML controls gallery

如果您已安裝 XAML 控制項庫應用程式,請按一下這裡開啟應用程式並查看 TextBlock 運作情形If you have the XAML Controls Gallery app installed, click here to open the app and see the TextBlock in action.

建立文字區塊Create a text block

以下說明如何定義簡易 TextBlock 控制項,以及將其 Text 屬性設定為字串。Here's how to define a simple TextBlock control and set its Text property to a string.

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

內容模型Content model

有兩個屬性可用來將內容新增到 TextBlock:TextInlinesThere are two properties you can use to add content to a TextBlock: Text and Inlines.

顯示文字的最常見方法是將 Text 屬性設為字串值,如先前範例所示。The most common way to display text is to set the Text property to a string value, as shown in the previous example.

您也可以在 TextBox.Inlines 屬性中放置內嵌的流動內容元素來新增內容,如下所示。You can also add content by placing inline flow content elements in the TextBox.Inlines property, like this.

<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) 會針對不同的文字部分啟用不同的格式設定。Elements derived from the Inline class, such as Bold, Italic, Run, Span, and LineBreak, enable different formatting for different parts of the text. 如需詳細資訊,請參閱格式化文字一節。For more info, see the Formatting text section. 內嵌的 Hyperlink 元素讓您能夠在文字中新增超連結。The inline Hyperlink element lets you add a hyperlink to your text. 不過,使用 Inlines 也會停用文字轉譯的快速路徑,如下一節所述。However, using Inlines also disables fast path text rendering, which is discussed in the next section.

效能考量Performance considerations

XAML 會在可行時使用更有效率的程式碼路徑來配置文字。Whenever possible, XAML uses a more efficient code path to layout text. 這個快速路徑會減少整體記憶體使用量,同時大幅減少文字測量和排列的 CPU 時間。This fast path both decreases overall memory use and greatly reduces the CPU time to do text measuring and arranging. 這個快速路徑僅適用於 TextBlock,因此它應該是當 RichTextBlock 可行時的慣用項目。This fast path applies only to TextBlock, so it should be preferred when possible over RichTextBlock.

特定情況需要 TextBlock 針對文字轉譯讓出更豐富的功能和 CPU 密集程式碼路徑。Certain conditions require TextBlock to fall back to a more feature-rich and CPU intensive code path for text rendering. 若要保持在快速路徑上進行文字轉譯,請確定當設定這裡列出的屬性時,遵循這些指導方針。To keep text rendering on the fast path, be sure to follow these guidelines when setting the properties listed here.

  • Text:最重要的條件是,只有當您在 XAML 或程式碼中 (如同前面範例所示) 明確設定 Text 屬性時,才使用快速路徑。Text: The most important condition is that the fast path is used only when you set text by explicitly setting the Text property, either in XAML or in code (as shown in the previous examples). 透過 TextBlock 的 Inlines 集合 (例如 <TextBlock>Inline text</TextBlock>) 設定文字將會停用快速路徑,原因在於多重格式具有潛在的複雜性。Setting the text via TextBlock's Inlines collection (such as <TextBlock>Inline text</TextBlock>) will disable the fast path, due to the potential complexity of multiple formats.
  • CharacterSpacing:只有預設值為 0 才是快速路徑。CharacterSpacing: Only the default value of 0 is fast path.
  • TextTrimming:只有 NoneCharacterEllipsisWordEllipsis 值才是快速路徑。TextTrimming: Only the None, CharacterEllipsis, and WordEllipsis values are fast path. Clip 值會停用快速路徑。The Clip value disables the fast path.

注意  在 Windows 10 版本 1607 之前,其他屬性也會影響快速路徑。Note  Prior to Windows 10, version 1607, additional properties also affect the fast path. 如果應用程式是在舊版 Windows 上執行,這些情況也會造成您的文字在慢速路徑上轉譯。If your app is run on an earlier version of Windows, these conditions will also cause your text to render on the slow path. 如需版本的相關詳細資訊,請參閱版本調適型程式碼For more info about versions, see Version adaptive code.

您可以在偵錯期間將 DebugSettings.IsTextPerformanceVisualizationEnabled 屬性設為 true 以判斷文字是否使用快速路徑轉譯。You can set the DebugSettings.IsTextPerformanceVisualizationEnabled property to true during debugging to determine whether text is using fast path rendering. 當這個屬性設為 true 時,快速路徑上的文字會以亮綠色顯示。When this property is set to true, the text that is on the fast path displays in a bright green color.

提示  Build 2015 的此會議詳細說明此功能 - XAML 效能:最大化使用 XAML 建置的通用 Windows 應用程式體驗的技術Tip  This feature is explained in depth in this session from Build 2015- XAML Performance: Techniques for Maximizing Universal Windows App Experiences Built with XAML.

您通常會在 OnLaunched 方法中設定偵錯設定,覆寫應用程式.xaml 的程式碼後置頁面,如下所示。You typically set debug settings in the OnLaunched method override in the code-behind page for App.xaml, like this.

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

// ...

}

在這個範例中,第一個 TextBlock 是使用快速路徑轉譯,而第二個則不是。In this example, the first TextBlock is rendered using the fast path, while the second is not.

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

當您在偵錯模式中將 IsTextPerformanceVisualizationEnabled 設為 true 以執行此 XAML 時,結果看起來就像這樣。When you run this XAML in debug mode with IsTextPerformanceVisualizationEnabled set to true, the result looks like this.

在偵錯模式中轉譯的文字

注意  不在快速路徑上的文字色彩不會變更。Caution  The color of text that is not on the fast path is not changed. 如果您將應用程式中的文字色彩指定為亮綠色,則在較慢的轉譯路徑上顯示該文字時,仍會將它顯示為亮綠色。If you have text in your app with its color specified as bright green, it is still displayed in bright green when it's on the slower rendering path. 請注意,不要將因為文字位於快速路徑上而在應用程式中設定為綠色的文字,以及因為偵錯設定而設定為綠色的文字相互混淆了。Be careful to not confuse text that is set to green in the app with text that is on the fast path and green because of the debug settings.

格式化文字Formatting text

雖然 Text 屬性會儲存純文字,但是您可以將不同的格式設定選項套用到 TextBlock 控制項,來自訂應用程式中轉譯文字的方式。Although the Text property stores plain text, you can apply various formatting options to the TextBlock control to customize how the text is rendered in your app. 您可以設定標準控制項屬性 (例如,FontFamily、FontSize、FontStyle、Foreground 及 CharacterSpacing) 來變更文字的外觀。You can set standard control properties like FontFamily, FontSize, FontStyle, Foreground, and CharacterSpacing to change the look of the text. 您也可以使用內嵌文字元素和 Typography 附加屬性來設定文字的格式。You can also use inline text elements and Typography attached properties to format your text. 這些選項只會影響 TextBlock 在本機顯示文字的方式,因此舉例來說,如果您複製文字並貼到 RTF 控制項,即不會套用任何格式設定。These options affect only how the TextBlock displays the text locally, so if you copy and paste the text into a rich text control, for example, no formatting is applied.

注意  請記住,如上一節所述,快速路徑上的內嵌文字元素和非預設印刷格式值不會轉譯。Note  Remember, as noted in the previous section, inline text elements and non-default typography values are not rendered on the fast path.

內嵌元素Inline elements

Windows.UI.Xaml.Documents 命名空間提供各種不同的內嵌文字元素,讓您可用來設定文字格式,例如 Bold、Italic、Run、Span 和 LineBreak。The Windows.UI.Xaml.Documents namespace provides a variety of inline text elements that you can use to format your text, such as Bold, Italic, Run, Span, and LineBreak.

您可以在 TextBlock 顯示一連串的字串,其中每個字串的格式都不同。You can display a series of strings in a TextBlock, where each string has different formatting. 透過 Run 元素顯示每個字串及其格式,或是以 LineBreak 元素分開每個 Run 元素,您就可以這麼做。You can do this by using a Run element to display each string with its formatting and by separating each Run element with a LineBreak element.

以下說明如何透過以 LineBreak 分隔的 Run 物件,在 TextBlock 中定義多個不同格式的文字字串。Here's how to define several differently formatted text strings in a TextBlock by using Run objects separated with a LineBreak.

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

結果如下。Here's the result.

使用執行元素格式化的文字

印刷樣式Typography

Typography 類別的附加屬性提供一組 Microsoft OpenType 印刷樣式屬性的存取權。The attached properties of the Typography class provide access to a set of Microsoft OpenType typography properties. 您可以在 TextBlock 或個別的內嵌文字元素上設定這些附加屬性。You can set these attached properties either on the TextBlock, or on individual inline text elements. 這些範例示範如何使用這兩者。These examples show both.

<TextBlock Text="Hello, world!"
           Typography.Capitals="SmallCaps"
           Typography.StylisticSet4="True"/>
TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";
Windows.UI.Xaml.Documents.Typography.SetCapitals(textBlock1, FontCapitals.SmallCaps);
Windows.UI.Xaml.Documents.Typography.SetStylisticSet4(textBlock1, true);
<TextBlock>12 x <Run Typography.Fraction="Slashed">1/3</Run> = 4.</TextBlock>

取得範例程式碼Get the sample code