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，并在您的应用程序中引用它。您还可以使用此组件创建更具体的组件，例如用于其他类型文本的 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 组件内部，不会泄漏到其他组件或系统本身。

参考

属性

`accessibilityHint`

无障碍提示可帮助用户了解当他们在无障碍元素上执行操作时会发生什么，如果该结果无法从无障碍标签中清楚得知。

类型
字符串

`无障碍语言`
iOS

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

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

类型
字符串

`accessibilityLabel`

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

类型
字符串

`accessibilityRole`

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

在 iOS 上，这些角色映射到相应的辅助功能特性（Accessibility Traits）。图像按钮的功能与特性同时设置为“image”和“button”时相同。更多信息请参阅辅助功能指南。

在 Android 上，这些角色的功能与 iOS 上 Voiceover 添加无障碍特性（Accessibility Traits）在 TalkBack 上具有类似的功能。

类型
AccessibilityRole

`accessibilityState`

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

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

类型
AccessibilityState

`accessibilityActions`

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

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

类型	必需
数组	否

`onAccessibilityAction`

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

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

类型	必需
函数	否

`accessible`

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

更多信息请参见辅助功能指南。

类型	默认
布尔值	`true`

`adjustsFontSizeToFit`

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

类型	默认
布尔值	`false`

`allowFontScaling`

指定字体是否应根据文本大小无障碍设置进行缩放。

类型	默认
布尔值	`true`

`android_hyphenationFrequency`
安卓

在 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`
安卓

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

您只能提供一种类型。

类型	默认
枚举（`'phoneNumber'`、`'link'`、`'email'`、`'none'`、`'all'`）	`'none'`

`disabled`
安卓

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

类型	默认
布尔值	`false`

`dynamicTypeRamp`
iOS

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

类型	默认
枚举（`'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 值才能正常工作。

类型	默认
枚举（`'head'`、`'middle'`、`'tail'`、`'clip'`）	`tail`

`id`

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

类型
字符串

`maxFontSizeMultiplier`

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

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

类型	默认
数字	`未定义`

`minimumFontScale`
iOS

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

类型
数字

`nativeID`

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

类型
字符串

`numberOfLines`

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

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

类型	默认
数字	`0`

`onLayout`

在挂载和布局更改时调用。

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

`onLongPress`

此函数在长按时调用。

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

`onMoveShouldSetResponder`

此视图是否希望“声明”触摸响应性？当视图不是响应者时，每次触摸移动都会调用此方法。

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

`onPress`

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

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

`onPressIn`

当触摸被接合时立即调用，在 onPressOut 和 onPress 之前。

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

`onPressOut`

当触摸被释放时调用。

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

`onResponderGrant`

视图现在正在响应触摸事件。现在是高亮显示并向用户展示正在发生的事情的时候了。

在 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 属性。

类型
角色

`selectable`

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

类型	默认
布尔值	`false`

`selectionColor`
安卓

文本的高亮颜色。

类型
颜色

`style`

类型
文本样式, 视图样式属性

`suppressHighlighting`
iOS

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

类型	默认
布尔值	`false`

`testID`

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

类型
字符串

`textBreakStrategy`
安卓

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

类型	默认
枚举（`'simple'`、`'highQuality'`、`'balanced'`）	`高品质`

`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	数字	否	Text 组件内部的行 X 坐标。
xHeight	数字	否	基线与行中线之间的距离（主体字大小）。
y	数字	否	Text 组件内部的行 Y 坐标。

TextLayoutEvent

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

示例

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

属性

姓名	类型	可选	描述
行	TextLayouts 数组	否	提供每条渲染线的 TextLayout 数据。
目标	数字	否	元素的节点 ID。

嵌套文本
容器
有限的样式继承
属性
类型定义
- 文本布局
- 文本布局事件

嵌套文本​

容器​

有限的样式继承​

参考

属性​

accessibilityHint​

无障碍语言 iOS​

accessibilityLabel​

accessibilityRole​

accessibilityState​

accessibilityActions​

onAccessibilityAction​

accessible​

adjustsFontSizeToFit​

allowFontScaling​

android_hyphenationFrequency 安卓​

aria-busy​

aria-checked​

aria-disabled​

aria-expanded​

aria-label​

aria-selected​

dataDetectorType 安卓​

disabled 安卓​

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 安卓​

style​

suppressHighlighting iOS​

testID​

textBreakStrategy 安卓​

lineBreakStrategyIOS iOS​

类型定义​

TextLayout​

示例​

属性​

TextLayoutEvent​

示例​

属性​