Text

用于显示文本的 React 组件。

Text 支持嵌套、样式设置和触摸处理。

在下面的示例中，嵌套的标题和正文文本将继承 styles.baseText 的 fontFamily，但标题提供了自己的附加样式。由于字面上的换行符，标题和正文将相互堆叠。

嵌套文本

Android 和 iOS 都允许你通过使用特定的格式（如粗体或彩色文本）标注字符串范围来显示格式化文本（iOS 上为 NSAttributedString，Android 上为 SpannableString）。在实践中，这非常繁琐。对于 React Native，我们决定为此采用 Web 范例，你可以通过嵌套文本来达到相同的效果。

在底层，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|

有限的样式继承

在 Web 上，为整个文档设置字体族和大小的常用方法是利用 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，并在你的应用中 everywhere 使用此组件。你还可以使用此组件创建更具体的组件，如 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

可访问性提示帮助用户理解当对可访问性元素执行操作时会发生什么，当可访问性标签不清楚结果时。

类型
string

---

accessibilityLanguage

iOS

一个值，指示屏幕阅读器在用户与元素交互时应使用的语言。它应遵循 BCP 47 规范。

有关详细信息，请参阅 iOS accessibilityLanguage 文档。

类型
string

---

accessibilityLabel

覆盖用户与元素交互时屏幕阅读器朗读的文本。默认情况下，标签是通过遍历所有子元素并累积所有用空格分隔的 Text 节点构建的。

类型
string

---

accessibilityRole

告诉屏幕阅读器将当前聚焦的元素视为具有特定角色。

在 iOS 上，这些角色映射到相应的辅助功能特性 (Accessibility Traits)。图像按钮的功能与将特性设置为“图像”和“按钮”时相同。有关详细信息，请参阅辅助功能指南。

在 Android 上，这些角色在 TalkBack 上的功能类似于在 iOS 的 Voiceover 上添加辅助功能特性。

类型
AccessibilityRole

---

accessibilityState

告诉屏幕阅读器将当前聚焦的元素视为处于特定状态。

你可以提供一个状态、无状态或多个状态。状态必须通过一个对象传入，例如 {selected: true, disabled: true}。

类型
AccessibilityState

---

accessibilityActions

辅助功能操作允许辅助技术以编程方式调用组件的操作。accessibilityActions 属性应包含一个操作对象列表。每个操作对象应包含字段名和标签。

有关详细信息，请参阅辅助功能指南。

类型	必需
array	否

---

onAccessibilityAction

用户执行辅助功能操作时调用。此函数唯一的参数是一个事件，其中包含要执行的操作名称。

有关详细信息，请参阅辅助功能指南。

类型	必需
function	否

---

accessible

设置为 true 时，表示该视图是可访问性元素。

有关详细信息，请参阅辅助功能指南。

类型	默认值
boolean	true

---

adjustsFontSizeToFit

指定是否应自动缩小字体以适应给定的样式约束。

类型	默认值
boolean	false

---

allowFontScaling

指定字体是否应根据文本大小辅助功能设置进行缩放。

类型	默认值
boolean	true

---

android_hyphenationFrequency

Android

设置 Android API Level 23+ 上确定单词断开时的自动连字符频率。

类型	默认值
enum('none', 'normal','full')	'none'

---

aria-busy

指示元素正在被修改，并且辅助技术可能希望等到更改完成后再通知用户更新。

类型	默认值
boolean	false

---

aria-checked

指示可勾选元素的状态。此字段可以是一个布尔值或字符串 "mixed"，用于表示混合状态的复选框。

类型	默认值
boolean, 'mixed'	false

---

aria-disabled

指示元素可见但已禁用，因此不可编辑或进行其他操作。

类型	默认值
boolean	false

---

aria-expanded

指示可展开元素当前是展开还是折叠状态。

类型	默认值
boolean	false

---

aria-label

定义一个字符串值，用于标记交互元素。

类型
string

---

aria-selected

指示可选元素当前是否被选中。

类型
boolean

dataDetectorType

Android

确定文本元素中转换为可点击 URL 的数据类型。默认情况下，不检测任何数据类型。

你只能提供一种类型。

类型	默认值
enum('phoneNumber', 'link', 'email', 'none', 'all')	'none'

---

disabled

Android

指定文本视图的禁用状态，用于测试目的。

类型	默认值
bool	false

---

dynamicTypeRamp

iOS

应用于 iOS 上此元素的 动态类型 坡度。

类型	默认值
enum('caption2', 'caption1', 'footnote', 'subheadline', 'callout', 'body', 'headline', 'title3', 'title2', 'title1', 'largeTitle')	'body'

---

ellipsizeMode

设置 numberOfLines 时，此 prop 定义文本将如何截断。必须与此 prop 同时设置 numberOfLines。

这可以是以下值之一

• head - 显示文本行，使其末尾适合容器，行开头的缺失文本由省略号 (...) 表示。例如，"...wxyz"
• middle - 显示文本行，使其开头和末尾适合容器，中间的缺失文本由省略号 (...) 表示。"ab...yz"
• tail - 显示文本行，使其开头适合容器，行末尾的缺失文本由省略号 (...) 表示。例如，"abcd..."
• clip - 文本行不会超出文本容器边缘绘制。

在 Android 上，当 numberOfLines 设置为大于 1 的值时，只有 tail 值才能正常工作。

类型	默认值
enum('head', 'middle', 'tail', 'clip')	tail

---

id

用于从原生代码定位此视图。优先于 nativeID prop。

类型
string

---

maxFontSizeMultiplier

当启用 allowFontScaling 时，指定字体可以达到的最大缩放比例。可能的值

• null/undefined: 从父节点或全局默认值 (0) 继承
• 0: 无最大值，忽略父级/全局默认值
• >= 1: 将此节点的 maxFontSizeMultiplier 设置为此值

类型	默认值
number	undefined

---

minimumFontScale

iOS

当启用 adjustsFontSizeToFit 时，指定字体可以达到的最小缩放比例。（值为 0.01-1.0）。

类型
number

---

nativeID

用于从原生代码定位此视图。

类型
string

---

numberOfLines

用于在计算文本布局（包括换行）后用省略号截断文本，使总行数不超过此数字。将此属性设置为 0 将取消设置此值，这意味着不应用任何行数限制。

此 prop 常与 ellipsizeMode 一起使用。

类型	默认值
number	0

---

onLayout

在挂载和布局变化时调用。

类型
({nativeEvent: LayoutEvent}) => void

---

onLongPress

长按时调用此函数。

类型
({nativeEvent: PressEvent}) => void

---

onMoveShouldSetResponder

此视图是否想“声明”触摸响应能力？当 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

在 Text 布局变化时调用。

类型
(TextLayoutEvent) => mixed

---

pressRetentionOffset

当滚动视图被禁用时，这定义了你的触摸可以离开按钮多远才会取消激活按钮。一旦取消激活，尝试将其移回，你会看到按钮再次被激活！在滚动视图被禁用时，反复移动它几次。确保传入一个常量以减少内存分配。

类型
Rect, number

---

role

role 向辅助技术用户传达组件的用途。优先于 accessibilityRole prop。

类型
Role

---

selectable

允许用户选择文本，以使用原生复制粘贴功能。

类型	默认值
boolean	false

---

selectionColor

Android

文本的高亮颜色。

类型
color

---

style

类型
Text Style, View Style Props

---

suppressHighlighting

iOS

当 true 时，按下文本时不会有视觉变化。默认情况下，按下时会有一个灰色椭圆高亮显示文本。

类型	默认值
boolean	false

---

testID

用于在端到端测试中定位此视图。

类型
string

---

textBreakStrategy

Android

在 Android API Level 23+ 上设置文本断行策略，可能的值为 simple, highQuality, balanced。

类型	默认值
enum('simple', 'highQuality', 'balanced')	highQuality

---

lineBreakStrategyIOS

iOS

在 iOS 14+ 上设置换行策略。可能的值为 none, standard, hangul-word 和 push-out。

类型	默认值
enum('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	number	否	文本布局改变后的行上行高度。
capHeight	number	否	大写字母在基线上方的高度。
descender	number	否	文本布局改变后的行下行高度。
height	number	否	文本布局改变后的行高度。
width	number	否	文本布局改变后的行宽度。
x	number	否	Text 组件内的行 X 坐标。
xHeight	number	否	行的基线与中线之间的距离（字高）。
y	number	否	Text 组件内的行 Y 坐标。

TextLayoutEvent

TextLayoutEvent 对象作为组件布局改变的结果在回调中返回。它包含一个名为 lines 的键，其值是一个数组，其中包含与每个渲染文本行对应的 TextLayout 对象。

示例

js

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

属性

名称	类型	可选	描述
lines	TextLayout 数组	否	提供每个渲染行的 TextLayout 数据。
target	number	否	元素的节点 ID。