Text

用於顯示文字的 React 組件。

Text 支援巢狀結構、樣式和觸控處理。

在以下範例中，巢狀標題和內文文字將繼承來自 styles.baseText 的 fontFamily，但標題提供了其自身的額外樣式。標題和內文將由於字面換行而彼此堆疊

巢狀文字

Android 和 iOS 都允許您透過使用特定格式（如粗體或彩色文字）（iOS 上的 NSAttributedString，Android 上的 SpannableString）註釋字串範圍來顯示格式化文字。實際上，這非常繁瑣。對於 React Native，我們決定使用網路範例來實現此目的，您可以在其中巢狀文字以達到相同的效果。

在幕後，React Native 會將其轉換為平面 NSAttributedString 或 SpannableString，其中包含以下資訊

"I am bold and red"
0-9: bold
9-17: bold, red

容器

相對於佈局，<Text> 元素是獨一無二的：內部的所有內容都不再使用 Flexbox 佈局，而是使用文字佈局。這表示 <Text> 內部的元素不再是矩形，而是在看到行尾時換行。

tsx
<Text>
  <Text>First part and </Text>
  <Text>second part</Text>
</Text>
// Text container: the text will be inline, if the space allows it
// |First part and second part|

// otherwise, the text will flow as if it was one
// |First part |
// |and second |
// |part       |

<View>
  <Text>First part and </Text>
  <Text>second part</Text>
</View>
// View container: each text is its own block
// |First part and|
// |second part   |

// otherwise, the text will flow in its own block
// |First part |
// |and        |
// |second part|

有限的樣式繼承

在網路上，為整個文件設定字型系列和大小的常用方法是利用繼承的 CSS 屬性，如下所示

css
html {
  font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
  font-size: 11px;
  color: #141823;
}

除非文件中的所有元素或其父元素之一指定了新規則，否則它們都將繼承此字型。

在 React Native 中，我們對此更加嚴格：您必須將所有文字節點包裝在 <Text> 組件內。您不能在 <View> 下直接擁有文字節點。

tsx
// BAD: will raise exception, can't have a text node as child of a <View>
<View>
  Some text
</View>

// GOOD
<View>
  <Text>
    Some text
  </Text>
</View>

您也會失去為整個子樹設定預設字型的能力。同時，fontFamily 僅接受單一字型名稱，這與 CSS 中的 font-family 不同。在您的應用程式中跨應用程式使用一致的字型和大小的建議方法是建立一個包含它們的 MyAppText 組件，並在您的應用程式中跨應用程式使用此組件。您也可以使用此組件來製作更具體的組件，例如用於其他文字類型的 MyAppHeaderText。

tsx
<View>
  <MyAppText>
    Text styled with the default font for the entire application
  </MyAppText>
  <MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

假設 MyAppText 是一個僅將其子項呈現到具有樣式的 Text 組件中的組件，則 MyAppHeaderText 可以定義如下

tsx
const MyAppHeaderText = ({children}) => {
  return (
    <MyAppText>
      <Text style={{fontSize: 20}}>{children}</Text>
    </MyAppText>
  );
};

以這種方式組合 MyAppText 可確保我們從頂層組件取得樣式，但讓我們能夠在特定用例中新增/覆寫它們。

React Native 仍然具有樣式繼承的概念，但僅限於文字子樹。在這種情況下，第二部分將同時為粗體和紅色。

tsx
<Text style={{fontWeight: 'bold'}}>
  I am bold
  <Text style={{color: 'red'}}>and red</Text>
</Text>

我們相信，這種更受約束的樣式化文字方式將產生更好的應用程式

（開發人員）React 組件在設計時考慮了強隔離性：您應該能夠將組件放置在應用程式中的任何位置，並信任只要 props 相同，它就會看起來和行為方式相同。可以從 props 外部繼承的文字屬性會破壞這種隔離性。
（實作者）React Native 的實作也得到了簡化。我們不需要在每個元素上都有 fontFamily 欄位，也不需要在每次顯示文字節點時都可能遍歷樹狀結構直到根目錄。樣式繼承僅在原生 Text 組件內部編碼，並且不會洩漏到其他組件或系統本身。

參考

Props

`accessibilityHint`

協助工具提示可協助使用者瞭解當他們對協助工具元素執行動作時會發生什麼事，如果從協助工具標籤中不明確說明結果。

類型
字串

`accessibilityLanguage`
iOS

一個值，指示當使用者與元素互動時，螢幕閱讀器應使用哪種語言。它應遵循 BCP 47 規範。

請參閱 iOS accessibilityLanguage 文件以取得更多資訊。

類型
字串

`accessibilityLabel`

覆寫使用者與元素互動時螢幕閱讀器讀取的文字。預設情況下，標籤是透過遍歷所有子項並累積所有以空格分隔的 Text 節點來建構的。

類型
字串

`accessibilityRole`

告知螢幕閱讀器將目前焦點元素視為具有特定角色。

在 iOS 上，這些角色對應到相應的「協助工具特徵」。影像按鈕的功能與將特徵設定為「影像」和「按鈕」相同。請參閱協助工具指南以取得更多資訊。

在 Android 上，這些角色在 TalkBack 上的功能與在 iOS 的 Voiceover 中新增「協助工具特徵」的功能類似

類型
AccessibilityRole

`accessibilityState`

告知螢幕閱讀器將目前焦點元素視為處於特定狀態。

您可以提供一個狀態、無狀態或多個狀態。狀態必須透過物件傳入，例如 {selected: true, disabled: true}。

類型
AccessibilityState

`accessibilityActions`

協助工具動作允許輔助技術以程式方式叫用組件的動作。accessibilityActions 屬性應包含動作物件的清單。每個動作物件都應包含欄位名稱和標籤。

請參閱協助工具指南以取得更多資訊。

類型	必要
陣列	否

`onAccessibilityAction`

當使用者執行協助工具動作時叫用。此函式的唯一引數是一個包含要執行動作名稱的事件。

請參閱協助工具指南以取得更多資訊。

類型	必要
函式	否

`accessible`

當設定為 true 時，表示檢視為協助工具元素。

請參閱協助工具指南以取得更多資訊。

類型	預設
布林值	`true`

`adjustsFontSizeToFit`

指定是否應自動縮小字型以符合給定的樣式限制。

類型	預設
布林值	`false`

`allowFontScaling`

指定是否應縮放字型以符合「文字大小」協助工具設定。

類型	預設
布林值	`true`

`android_hyphenationFrequency`
Android

設定在 Android API Level 23+ 上判斷單字斷行時要使用的自動斷字頻率。

類型	預設
列舉(`'none'`, `'normal'`,`'full'`)	`'none'`

`aria-busy`

表示元素正在修改中，且輔助技術可能想要等到變更完成後再通知使用者更新。

類型	預設
布林值	false

`aria-checked`

表示可勾選元素的狀態。此欄位可以採用布林值或 "mixed" 字串來表示混合核取方塊。

類型	預設
布林值、'mixed'	false

`aria-disabled`

表示元素可感知但已停用，因此無法編輯或以其他方式操作。

類型	預設
布林值	false

`aria-expanded`

表示可展開的元素目前是展開還是摺疊。

類型	預設
布林值	false

`aria-label`

定義標籤互動式元素的字串值。

類型
字串

`aria-selected`

表示可選取的元素目前是否已選取。

類型
布林值

`dataDetectorType`
Android

決定在文字元素中轉換為可點擊 URL 的資料類型。預設情況下，不會偵測到任何資料類型。

您只能提供一種類型。

類型	預設
列舉(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`)	`'none'`

`disabled`
Android

指定文字檢視的停用狀態，以用於測試目的。

類型	預設
bool	`false`

`dynamicTypeRamp`
iOS

要套用至 iOS 上此元素的動態類型 ramp。

類型	預設
列舉(`'caption2'`, `'caption1'`, `'footnote'`, `'subheadline'`, `'callout'`, `'body'`, `'headline'`, `'title3'`, `'title2'`, `'title1'`, `'largeTitle'`)	`'body'`

`ellipsizeMode`

當設定 numberOfLines 時，此 prop 定義如何截斷文字。numberOfLines 必須與此 prop 一起設定。

這可以是下列值之一

head - 顯示行，使結尾適合容器，並且行開頭的遺失文字以省略符號字形表示。例如，"...wxyz"
middle - 顯示行，使開頭和結尾適合容器，並且中間的遺失文字以省略符號字形表示。 "ab...yz"
tail - 顯示行，使開頭適合容器，並且行結尾的遺失文字以省略符號字形表示。例如，"abcd..."
clip - 行不會繪製超過文字容器的邊緣。

在 Android 上，當 numberOfLines 設定為高於 1 的值時，只有 tail 值才能正確運作。

類型	預設
列舉(`'head'`, `'middle'`, `'tail'`, `'clip'`)	`tail`

`id`

用於從原生程式碼尋找此檢視。優先於 nativeID prop。

類型
字串

`maxFontSizeMultiplier`

指定啟用 allowFontScaling 時字型可以達到的最大可能比例。可能的值

null/undefined：從父節點或全域預設值 (0) 繼承
0：無最大值，忽略父項/全域預設值
>= 1：將此節點的 maxFontSizeMultiplier 設定為此值

類型	預設
數字	`未定義`

`minimumFontScale`
iOS

指定啟用 adjustsFontSizeToFit 時字型可以達到的最小可能比例。（值 0.01-1.0）。

類型
數字

`nativeID`

用於從原生程式碼尋找此檢視。

類型
字串

`numberOfLines`

用於在計算文字佈局（包括換行）後，使用省略符號截斷文字，使總行數不超過此數字。將此屬性設定為 0 將導致取消設定此值，這表示不會套用任何行數限制。

此 prop 通常與 ellipsizeMode 一起使用。

類型	預設
數字	`0`

`onLayout`

在掛載和佈局變更時叫用。

類型
`({nativeEvent: LayoutEvent}) => void`

`onLongPress`

此函式在長按時呼叫。

類型
`({nativeEvent: PressEvent}) => void`

`onMoveShouldSetResponder`

此檢視是否想要「聲明」觸控回應能力？當 View 不是回應者時，會針對 View 上的每次觸控移動呼叫此函式。

類型
`({nativeEvent: PressEvent}) => boolean`

`onPress`

在使用者按下時呼叫的函式，在 onPressOut 之後觸發。

類型
`({nativeEvent: PressEvent}) => void`

`onPressIn`

在觸控開始時立即呼叫，在 onPressOut 和 onPress 之前。

類型
`({nativeEvent: PressEvent}) => void`

`onPressOut`

在觸控釋放時呼叫。

類型
`({nativeEvent: PressEvent}) => void`

`onResponderGrant`

View 現在正在回應觸控事件。現在是醒目提示並向使用者顯示正在發生的情況的時候了。

在 Android 上，從此回呼傳回 true 以防止任何其他原生組件成為回應者，直到此回應者終止。

類型
`({nativeEvent: PressEvent}) => void ｜ boolean`

`onResponderMove`

使用者正在移動手指。

類型
`({nativeEvent: PressEvent}) => void`

`onResponderRelease`

在觸控結束時觸發。

類型
`({nativeEvent: PressEvent}) => void`

`onResponderTerminate`

回應者已從 View 中取得。可能會在呼叫 onResponderTerminationRequest 後由其他檢視取得，或者可能會在未經要求的情況下由作業系統取得（例如，在 iOS 上使用控制中心/通知中心時會發生這種情況）

類型
`({nativeEvent: PressEvent}) => void`

`onResponderTerminationRequest`

某些其他 View 想要成為回應者，並且正在要求此 View 釋放其回應者。傳回 true 允許其釋放。

類型
`({nativeEvent: PressEvent}) => boolean`

`onStartShouldSetResponderCapture`

如果父 View 想要防止子 View 在觸控開始時成為回應者，則它應該具有此處理常式，該處理常式傳回 true。

類型
`({nativeEvent: PressEvent}) => boolean`

`onTextLayout`

在文字佈局變更時叫用。

類型
(`TextLayoutEvent`) => mixed

`pressRetentionOffset`

當捲動檢視停用時，這會定義您的觸控可以在按鈕上移動多遠，然後停用按鈕。停用後，嘗試將其移回，您會看到按鈕再次重新啟用！在捲動檢視停用時，來回移動幾次。確保您傳入一個常數以減少記憶體配置。

類型
Rect, number

`role`

role 向輔助技術的使用者傳達組件的用途。優先於 accessibilityRole prop。

類型
Role

`selectable`

讓使用者選取文字，以使用原生複製和貼上功能。

類型	預設
布林值	`false`

`selectionColor`
Android

文字的醒目提示色彩。

類型
色彩

`style`

類型
文字樣式, 檢視樣式 Props

`suppressHighlighting`
iOS

當 true 時，按下文字時不會進行視覺變更。預設情況下，灰色橢圓形會在按下時醒目提示文字。

類型	預設
布林值	`false`

`testID`

用於在端對端測試中尋找此檢視。

類型
字串

`textBreakStrategy`
Android

在 Android API Level 23+ 上設定文字斷行策略，可能的值為 simple、highQuality、balanced。

類型	預設
列舉(`'simple'`, `'highQuality'`, `'balanced'`)	`highQuality`

`lineBreakStrategyIOS`
iOS

在 iOS 14+ 上設定換行策略。可能的值為 none、standard、hangul-word 和 push-out。

類型	預設
列舉(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`)	`'none'`

類型定義

TextLayout

TextLayout 物件是 TextLayoutEvent 回呼的一部分，並包含 Text 行的測量資料。

範例

js
{
    capHeight: 10.496,
    ascender: 14.624,
    descender: 4,
    width: 28.224,
    height: 18.624,
    xHeight: 6.048,
    x: 0,
    y: 0
}

屬性

名稱	類型	選用	描述
ascender	數字	否	文字佈局變更後，行的上升高度。
capHeight	數字	否	基準線上方大寫字母的高度。
descender	數字	否	文字佈局變更後，行的下降高度。
height	數字	否	文字佈局變更後，行的高度。
width	數字	否	文字佈局變更後，行的寬度。
x	數字	否	文字組件內的行 X 座標。
xHeight	數字	否	基準線與行中位數（語料庫大小）之間的距離。
y	數字	否	文字組件內的行 Y 座標。

TextLayoutEvent

TextLayoutEvent 物件在回呼中作為組件佈局變更的結果傳回。它包含一個名為 lines 的索引鍵，其值是一個陣列，其中包含對應於每個呈現文字行的 TextLayout 物件。

範例

js
{
  lines: [
    TextLayout,
    TextLayout,
    // ...
  ];
  target: 1127;
}

屬性

名稱	類型	選用	描述
lines	TextLayout 的陣列 TextLayouts	否	為每個呈現的行提供 TextLayout 資料。
target	數字	否	元素的節點 ID。

巢狀文字
容器
有限的樣式繼承
Props
類型定義
- TextLayout
- TextLayoutEvent

巢狀文字​

容器​

有限的樣式繼承​

參考

Props​

accessibilityHint​

accessibilityLanguage iOS​

accessibilityLabel​

accessibilityRole​

accessibilityState​

accessibilityActions​

onAccessibilityAction​

accessible​

adjustsFontSizeToFit​

allowFontScaling​

android_hyphenationFrequency Android​

aria-busy​

aria-checked​

aria-disabled​

aria-expanded​

aria-label​

aria-selected​

dataDetectorType Android​

disabled Android​

dynamicTypeRamp iOS​

ellipsizeMode​

id​

maxFontSizeMultiplier​

minimumFontScale iOS​

nativeID​

numberOfLines​

onLayout​

onLongPress​

onMoveShouldSetResponder​

onPress​

onPressIn​

onPressOut​

onResponderGrant​

onResponderMove​

onResponderRelease​

onResponderTerminate​

onResponderTerminationRequest​

onStartShouldSetResponderCapture​

onTextLayout​

pressRetentionOffset​

role​

selectable​

selectionColor Android​

style​

suppressHighlighting iOS​

testID​

textBreakStrategy Android​

lineBreakStrategyIOS iOS​

類型定義​

TextLayout​

範例​

屬性​

TextLayoutEvent​

範例​

屬性​

巢狀文字

容器

有限的樣式繼承

Props

`accessibilityHint`

`accessibilityLanguage`
iOS

`accessibilityLabel`

`accessibilityRole`

`accessibilityState`

`accessibilityActions`

`onAccessibilityAction`

`accessible`

`adjustsFontSizeToFit`

`allowFontScaling`

`android_hyphenationFrequency`
Android

`aria-busy`

`aria-checked`

`aria-disabled`

`aria-expanded`

`aria-label`

`aria-selected`

`dataDetectorType`
Android

`disabled`
Android

`dynamicTypeRamp`
iOS

`ellipsizeMode`

`id`

`maxFontSizeMultiplier`

`minimumFontScale`
iOS

`nativeID`

`numberOfLines`

`onLayout`

`onLongPress`

`onMoveShouldSetResponder`

`onPress`

`onPressIn`

`onPressOut`

`onResponderGrant`

`onResponderMove`

`onResponderRelease`

`onResponderTerminate`

`onResponderTerminationRequest`

`onStartShouldSetResponderCapture`

`onTextLayout`

`pressRetentionOffset`

`role`

`selectable`

`selectionColor`
Android

`style`

`suppressHighlighting`
iOS

`testID`

`textBreakStrategy`
Android

`lineBreakStrategyIOS`
iOS

類型定義

TextLayout

範例

屬性

TextLayoutEvent

範例

屬性