跳到主要内容
版本：0.83

文本

一个用于显示文本的 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> 内部的元素不再是矩形，而是在遇到行尾时会自动换行。

React TSX
<Text>
  <Text>First part and </Text>
  <Text>second part</Text>
</Text>
// Text 容器：如果空间允许，文本会以内联方式显示
// |First part and second part|

// 否则，文本会像一个整体那样流动
// |First part |
// |and second |
// |part       |

<View>
  <Text>First part and </Text>
  <Text>second part</Text>
</View>
// View 容器：每段文本都是自己的块
// |First part and|
// |second part   |

// 否则，文本会在自己的块中流动
// |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> 下直接放置文本节点。

React TSX
// 错误：会抛出异常，不能将文本节点作为 <View> 的子节点
<View>
  Some text
</View>

// 正确
<View>
  <Text>
    Some text
  </Text>
</View>

你也失去了为整个子树设置默认字体的能力。与此同时，fontFamily 只接受单个字体名称，这与 CSS 中的 font-family 不同。跨应用保持字体和字号一致的推荐方式，是创建一个包含这些样式的 MyAppText 组件，并在应用中广泛使用它。你也可以用这个组件来创建更具体的组件，例如用于其他文本类型的 MyAppHeaderText。

React TSX
<View>
  <MyAppText>
    使用整个应用默认字体样式的文本
  </MyAppText>
  <MyAppHeaderText>作为标题样式的文本</MyAppHeaderText>
</View>

假设 MyAppText 是一个组件，它只会把其 children 作为带样式的 Text 组件渲染出来，那么 MyAppHeaderText 可以定义如下：

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

以这种方式组合 MyAppText 可以确保我们从顶层组件获得样式，同时仍然保留在特定使用场景中添加或覆盖样式的能力。

React Native 仍然具有样式继承的概念，但仅限于文本子树。在这种情况下，第二部分既会是粗体，也会是红色。

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

我们认为，这种更受约束的文本样式设置方式会带来更好的应用：

  • （开发者）React 组件在设计上强调强隔离：你应该能够把一个组件放到应用中的任何位置，并相信只要 props 相同，它的外观和行为就会保持一致。会从 props 之外继承的文本属性会破坏这种隔离性。

  • （实现者）React Native 的实现也更简单了。我们不需要在每个元素上都设置一个 fontFamily 字段，也不需要在每次显示文本节点时都可能向上遍历树直到根节点。样式继承只会编码在原生 Text 组件内部，不会泄漏到其他组件或系统本身。

参考

属性​

accessibilityHint​

无障碍提示有助于用户理解在无障碍元素上执行某个操作时会发生什么，前提是仅从无障碍标签中无法清楚看出该结果。

类型
string

accessibilityLanguage
iOS
​

指示用户与该元素交互时，屏幕阅读器应使用哪种语言。它应遵循 BCP 47 规范。

有关更多信息，请参阅 iOS accessibilityLanguage 文档。

类型
string

accessibilityLabel​

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

类型
string

accessibilityRole​

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

在 iOS 上，这些角色会映射到相应的辅助功能特征。图像按钮的功能与同时设置了 'image' 和 'button' 特征时相同。更多信息请参阅 辅助功能指南。

在 Android 上，这些角色在 TalkBack 中的功能类似于 iOS 中的 VoiceOver 添加辅助功能特征时的表现

类型
AccessibilityRole

accessibilityState​

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

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

类型
AccessibilityState

accessibilityActions​

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

有关更多信息，请参阅 辅助功能指南。

类型必需
array否

onAccessibilityAction​

当用户执行无障碍操作时调用。此函数唯一的参数是一个事件，其中包含要执行的操作名称。

有关更多信息，请参阅 辅助功能指南。

类型必需
function否

accessible​

设置为 true 时，表示该视图是一个无障碍元素。

有关更多信息，请参阅 辅助功能指南。

类型默认值
booleantrue

adjustsFontSizeToFit​

指定在给定样式约束下，字体是否应自动缩小以适配。

类型默认值
booleanfalse

allowFontScaling​

指定字体是否应缩放以遵循文字大小无障碍设置。

类型默认值
booleantrue

android_hyphenationFrequency
Android
​

设置在 Android API 23+ 上确定单词断行时使用的自动连字符频率。

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

aria-busy​

表示某个元素正在被修改，并且辅助技术可能希望等到更改完成后再向用户报告更新。

类型默认值
booleanfalse

aria-checked​

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

类型默认值
boolean, 'mixed'false

aria-disabled​

表示该元素可感知但已禁用，因此不可编辑或无法操作。

类型默认值
booleanfalse

aria-expanded​

表示某个可展开元素当前是展开还是折叠状态。

类型默认值
booleanfalse

aria-label​

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

类型
string

aria-selected​

表示某个可选择元素当前是否已被选中。

类型
boolean

dataDetectorType
Android
​

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

你只能提供一种类型。

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

disabled
Android
​

指定文本视图的禁用状态，供测试使用。

类型默认值
boolfalse

dynamicTypeRamp
iOS
​

要在 iOS 上应用于该元素的 Dynamic Type 层级。

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

ellipsizeMode​

当设置了 numberOfLines 时，此属性定义文本将如何被截断。numberOfLines 必须与此属性一起设置。

它可以是以下值之一：

  • head - 显示该行时会让末尾适配容器，而行首缺失的文本用省略号表示。例如，"...wxyz"
  • middle - 显示该行时会让开头和结尾适配容器，而中间缺失的文本用省略号表示。"ab...yz"
  • tail - 显示该行时会让开头适配容器，而行尾缺失的文本用省略号表示。例如，"abcd..."
  • clip - 不会绘制超出文本容器边缘的行。
备注

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

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

id​

用于从原生代码中定位此视图。优先级高于 nativeID 属性。

类型
string

maxFontSizeMultiplier​

指定在启用 allowFontScaling 时字体可达到的最大缩放比例。可选值：

  • null/undefined：继承自父节点或全局默认值（0）
  • 0：没有最大值，忽略父级/全局默认值
  • >= 1：将此节点的 maxFontSizeMultiplier 设置为该值
类型默认值
numberundefined

minimumFontScale​

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

类型
number

nativeID​

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

类型
string

numberOfLines​

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

此属性通常与 ellipsizeMode 一起使用。

类型默认值
number0

onLayout​

在挂载时以及布局变化时调用。

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

onLongPress​

长按时调用此函数。

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

onMoveShouldSetResponder​

这个视图是否想要“抢占”触摸响应？当它不是 responder 时，会在 View 上的每次触摸移动时调用此函数。

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

onPress​

用户按下时调用的函数，在 onPressOut 之后触发。

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

onPressIn​

在触摸刚接触时立即调用，早于 onPressOut 和 onPress。

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

onPressOut​

在触摸释放时调用。

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

onResponderGrant​

View 现在正在响应触摸事件。这是高亮显示并告诉用户正在发生什么的时机。

在 Android 上，从此回调中返回 true 可防止任何其他原生组件在该 responder 结束之前成为 responder。

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

onResponderMove​

用户正在移动手指。

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

onResponderRelease​

在触摸结束时触发。

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

onResponderTerminate​

responder 已经从 View 手中被取走。可能是在调用 onResponderTerminationRequest 后被其他视图取走，也可能是在未询问的情况下被操作系统取走（例如在 iOS 上发生于控制中心/通知中心）。

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

onResponderTerminationRequest​

某个其他 View 想要成为 responder，并请求此 View 释放其 responder。返回 true 可允许释放。

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

onStartShouldSetResponderCapture​

如果父级 View 想要阻止子级 View 在触摸开始时成为 responder，它应当带有此处理函数并返回 true。

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

onTextLayout​

在 Text 布局变化时调用。

类型
(TextLayoutEvent) => mixed

pressRetentionOffset​

当滚动视图被禁用时，这定义了你的触摸在使按钮失效之前可以偏离按钮多远。一旦失效，尝试将其移回，你会看到按钮会再次被激活！在滚动视图被禁用时，来回移动几次。请确保传入一个常量以减少内存分配。

类型
Rect, number

ref​

挂载时会被分配为一个 元素节点 的 ref setter。

注意，Text 组件不会提供文本节点，这与 Web 上的段落元素（<p>）类似，它们是元素节点而不是文本节点。文本节点可以在其子节点中找到。

role​

role 会向辅助技术的用户传达组件的用途。优先级高于 accessibilityRole 属性。

类型
Role

selectable​

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

类型默认值
booleanfalse

selectionColor
Android
​

文本的高亮颜色。

类型
color

style​

类型
Text Style, View Style Props

suppressHighlighting
iOS
​

当为 true 时，按下文本不会产生任何视觉变化。默认情况下，按下时会用灰色椭圆高亮文本。

类型默认值
booleanfalse

testID​

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

类型
string

textBreakStrategy
Android
​

在 Android API 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 行的测量数据。

示例​

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

属性​

名称类型可选描述
ascendernumber否文本布局变化后，该行的上升高度。
capHeightnumber否基线以上大写字母的高度。
descendernumber否文本布局变化后，该行的下降高度。
heightnumber否文本布局变化后该行的高度。
widthnumber否文本布局变化后该行的宽度。
xnumber否Text 组件内该行的 X 坐标。
xHeightnumber否基线与该行中线（字符主体大小）之间的距离。
ynumber否Text 组件内该行的 Y 坐标。

TextLayoutEvent​

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

示例​

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

属性​

名称类型可选描述
linesTextLayout 数组否为每一条渲染后的文本行提供 TextLayout 数据。
targetnumber否元素的节点 id。