本文档贡献者：sunnylqm(99.66%), hqwlkj(0.34%)

一个用于显示文本的 React 组件，并且它也支持嵌套、样式，以及触摸处理。

在下面的例子里，嵌套的标题和正文文字会继承来自styles.baseText的fontFamily字体样式，不过标题上还附加了它自己额外的样式。标题和文本会在顶部依次堆叠，并且被代码中内嵌的换行符分隔开。

函数组件示例
Class组件示例

import React, { useState } from "react";
import { Text, StyleSheet } from "react-native";

const onPressTitle = () => {
  console.log("title pressed");
};

const TextInANest = () => {
  const titleText = useState("Bird's Nest");
  const bodyText = useState("This is not really a bird nest.");

  return (
    <Text style={styles.baseText}>
      <Text style={styles.titleText} onPress={onPressTitle}>
        {titleText}
        {"\n"}
        {"\n"}
      </Text>
      <Text numberOfLines={5}>{bodyText}</Text>
    </Text>
  );
};

const styles = StyleSheet.create({
  baseText: {
    fontFamily: "Cochin"
  },
  titleText: {
    fontSize: 20,
    fontWeight: "bold"
  }
});

export default TextInANest;

import React, { Component } from "react";
import { Text, StyleSheet } from "react-native";

class TextInANest extends Component {
  constructor(props) {
    super(props);
    this.state = {
      titleText: "Bird's Nest",
      bodyText: "This is not really a bird nest."
    };
  }

  render() {
    return (
      <Text style={styles.baseText}>
        <Text style={styles.titleText} onPress={this.onPressTitle}>
          {this.state.titleText}
          {"\n"}
          {"\n"}
        </Text>
        <Text numberOfLines={5}>{this.state.bodyText}</Text>
      </Text>
    );
  }
}

const styles = StyleSheet.create({
  baseText: {
    fontFamily: "Cochin"
  },
  titleText: {
    fontSize: 20,
    fontWeight: "bold"
  }
});

export default TextInANest;

嵌套文本

在 iOS 和 Android 中显示格式化文本的方法类似，都是提供你想显示的文本内容，然后使用范围标注来指定一些格式（在 iOS 上是用NSAttributedString，Android 上则是SpannableString）。这种用法非常繁琐。在 React Native 中，我们决定采用和 Web 一致的设计，这样你可以把相同格式的文本嵌套包裹起来：

import React from 'react';
import { Text, StyleSheet } from 'react-native';

const BoldAndBeautiful = () => {
  return (
    <Text style={styles.baseText}>
      I am bold
      <Text style={styles.innerText}> and red</Text>
    </Text>
  );
};

const styles = StyleSheet.create({
  baseText: {
    fontWeight: 'bold'
  },
  innerText: {
    color: 'red'
  }
});

export default BoldAndBeautiful;

而实际上在框架内部，这会生成一个扁平结构的NSAttributedString或是SpannableString，包含以下信息：

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

嵌套视图（仅限 iOS）

On iOS, you can nest views within your Text component. Here's an example:

import React, { Component } from 'react';
import { Text, View } from 'react-native';

export default class BlueIsCool extends Component {
  render() {
    return (
      <Text>
        There is a blue square
        <View style={{width: 50, height: 50, backgroundColor: 'steelblue'}} />
        in between my text.
      </Text>
    );
  }
}

In order to use this feature, you must give the view a width and a height.

容器

<Text>元素在布局上不同于其它组件：在 Text 内部的元素不再使用 flexbox 布局，而是采用文本布局。这意味着<Text>内部的元素不再是一个个矩形，而可能会在行末进行折叠。

<Text>
  <Text>First part and </Text>
  <Text>second part</Text>
</Text>
// Text container: the text will be inline if the space allowed 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   |

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

样式继承限制

在 Web 上，要想指定整个文档的字体和大小，我们只需要写：

/* 这段代码是CSS, *不是*React Native */
html {
  font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
  font-size: 11px;
  color: #141823;
}

当浏览器尝试渲染一个文本节点的时候，它会在树中一路向上查询，直到根节点，来找到一个具备font-size属性的元素。这个系统一个不好的地方在于任何节点都可能会有font-size属性，包括<div>标签。这个设计为了方便而设计，但实际上语义上并不太正确。

在 React Native 中，我们把这个问题设计的更加严谨：你必须把你的文本节点放在<Text>组件内。你不能直接在<View>下放置一段文本。

// 错误的做法：会导致一个错误。<View>下不能直接放一段文本。
<View>
  一些文本
</View>

// 正确的做法
<View>
  <Text>
    一些文本
  </Text>
</View>

并且你也不能直接设置一整颗子树的默认样式。此外，fontFamily样式只接受一种字体名称，这一点和 CSS 也不一样。使用一个一致的文本和尺寸的推荐方式是创建一个包含相关样式的组件MyAppText，然后在你的 App 中反复使用它。你还可以创建更多特殊的组件譬如MyAppHeaderText来表达不同样式的文本。

<View>
  <MyAppText>
    这个组件包含了一个默认的字体样式，用于整个应用的文本
  </MyAppText>
  <MyAppHeaderText>这个组件包含了用于标题的样式</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that simply renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
  render() {
    return (
      <MyAppText>
        <Text style={{ fontSize: 20 }}>
          {this.props.children}
        </Text>
      </MyAppText>
    );
  }
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native 实际上还是有一部分样式继承的实现，不过仅限于文本标签的子树。在下面的代码里，第二部分会在加粗的同时又显示为红色：

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

我们相信这种看起来不太舒服的给文本添加样式的方法反而会帮助我们生产更好的 App：

(对开发者来说) React 组件在概念上被设计为强隔离性的：你应当可以在应用的任何位置放置一个组件，而且只要属性相同，其外观和表现都将完全相同。文本如果能够继承外面的样式属性，将会打破这种隔离性。
(对实现者来说) React Native 的实现也被简化了。我们不需要在每个元素上都添加一个fontFamily字段，并且我们也不需要隐含地在显示文本的时候向上遍历树。唯一的样式继承在原生 Text 组件中编码，也不会影响到其它组件或者系统本身。

文档

Props

`selectable`

决定用户是否可以长按选择文本，以便复制和粘贴。

类型	必填
bool	否

`accessibilityHint`

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label.

类型	必填
string	否

`accessibilityLabel`

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

类型	必填
string	否

`accessible`

When set to true, indicates that the view is an accessibility element. The default value for a Text element is true.

See the Accessibility guide for more information.

类型	必填
bool	否

`ellipsizeMode`

这个属性通常和下面的 numberOfLines 属性配合使用，表示当 Text 组件无法全部显示需要显示的字符串时如何用省略号进行修饰。

该属性有如下 4 种取值:

head - 从文本内容头部截取显示省略号。例如： "...efg"
middle - 在文本内容中间截取显示省略号。例如： "ab...yz"
tail - 从文本内容尾部截取显示省略号。例如： "abcd..."
clip - 不显示省略号，直接从尾部截断。

The default is tail.

类型	必填
enum('head', 'middle', 'tail', 'clip')	否

`nativeID`

Used to locate this view from native code.

类型	必填
string	否

`numberOfLines`

用来当文本过长的时候裁剪文本。包括折叠产生的换行在内，总的行数不会超过这个属性的限制。

此属性一般和ellipsizeMode搭配使用。

类型	必填
number	否

`onLayout`

在加载时或者布局变化以后调用，参数为如下的内容：

{nativeEvent: {layout: {x, y, width, height}}}

类型	必填
function	否

`onLongPress`

当文本被长按以后调用此回调函数。

例如：onLongPress={this.increaseSize}>

类型	必填
function	否

`onPress`

当文本被点击以后调用此回调函数。

例如：onPress={() => console.log('1st')}

类型	必填
function	否

`onTextLayout`

Invoked on Text layout

Type	Required
function: (event: TextLayoutEvent) => mixed	No

TextLayoutEvent - SyntheticEvent object that contains a key called lines with a value which is an array containing objects with the following properties
- { x: number, y: number, width: number, height: number, ascender: number, capHeight: number, descender: number, text: string, xHeight: number,}

`pressRetentionOffset`

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

类型	必填
object: {top: number, left: number, bottom: number, right: number}	否

`allowFontScaling`

控制字体是否要根据系统的“字体大小”辅助选项来进行缩放。默认值为true。

类型	必填
bool	否

`style`

类型	必填
style	否

View Style Props...
textShadowOffset: object: {width: number,height: number}
color: color
fontSize: number
fontStyle: enum('normal', 'italic')
fontWeight: enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')

指定字体的粗细。大多数字体都支持'normal'和'bold'值。并非所有字体都支持所有的数字值。如果某个值不支持，则会自动选择最接近的值。
lineHeight: number
textAlign: enum('auto', 'left', 'right', 'center', 'justify')

指定文本的对齐方式。其中'justify'值仅 iOS 和 Android>=8.0 支持，在 Android8.0 以下会变为left。
textDecorationLine: enum('none', 'underline', 'line-through', 'underline line-through')
textShadowColor: color
fontFamily: string
textShadowRadius: number
includeFontPadding: bool (Android)

Android 在默认情况下会为文字额外保留一些 padding，以便留出空间摆放上标或是下标的文字。对于某些字体来说，这些额外的 padding 可能会导致文字难以垂直居中。如果你把textAlignVertical设置为center之后，文字看起来依然不在正中间，那么可以尝试将本属性设置为false。默认值为 true。

textAlignVertical: enum('auto', 'top', 'bottom', 'center') (Android)
fontVariant: array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums') (iOS)
letterSpacing: number

Increase or decrease the spacing between characters. The default is 0, for no extra letter spacing.

iOS: The additional space will be rendered after each glyph.

Android: Only supported since Android 5.0 - older versions will ignore this attribute. Please note that additional space will be added around the glyphs (half on each side), which differs from the iOS rendering. It is possible to emulate the iOS rendering by using layout attributes, e.g. negative margins, as appropriate for your situation.

textDecorationColor: color (iOS)
textDecorationStyle: enum('solid', 'double', 'dotted', 'dashed') (iOS)
textTransform: enum('none', 'uppercase', 'lowercase', 'capitalize')
writingDirection: enum('auto', 'ltr', 'rtl') (iOS)

`testID`

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

类型	必填
string	否

`disabled`

Specifies the disabled state of the text view for testing purposes

类型	必填	平台
bool	否	Android

`selectionColor`

The highlight color of the text.

类型	必填	平台
color	否	Android

`textBreakStrategy`

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

类型	必填	平台
enum('simple', 'highQuality', 'balanced')	否	Android

`adjustsFontSizeToFit`

指定字体是否随着给定样式的限制而自动缩放。

类型	必填	平台
bool	否	iOS

`minimumFontScale`

当 adjustsFontSizeToFit 开启时，指定最小的缩放比（即不能低于这个值）。可设定的值为 0.01 - 1.

类型	必填	平台
number	否	iOS

`suppressHighlighting`

设为 true 时，当文本被按下会没有任何视觉效果。默认情况下，文本被按下时会有一个灰色的、椭圆形的高光。

类型	必填	平台
bool	否	iOS

`dataDetectorType`

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

'phoneNumber'
'link'
'email'
'none'
'all'

Type	Required	Platform
enum('phoneNumber', 'link', 'email', 'none', 'all')	No	Android

`android_hyphenationFrequency`

Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+, possible values are none, full, balanced, high, normal. The default value is none.

Type	Required	Platform
enum('none', 'full', 'balanced', 'high')	No	Android

Known issues

react-native#22811: Nested Text elements do not support numberOfLines attribute

React Native 中文网

0.63

Android 组件

iOS 组件

Text