This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

文本

一个用于显示样式化文本的 Jetpack Compose Text 组件。

Android

Included in Expo Go

GitHub

npm

更新日志

有关跨平台用法，请参阅通用的 Text — 它会根据平台渲染相应的原生组件。

Expo UI Text 与官方 Jetpack Compose 文本样式 API 相匹配，并使用 Material 3 排版样式、自定义字体和文本格式选项来显示文本。

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

基本文本

BasicTextExample.tsx

import {
  Host,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';

export default function BasicTextExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Text color={colors.onBackground}>Hello, world!</Text>
    </Host>
  );
}

排版样式

使用带有 typography 的 style 属性来应用 Material 3 排版预设。

TypographyExample.tsx

import {
  Host,
  Text,
  Column,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function TypographyExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Column modifiers={[paddingAll(16)]}>
        <Text
          color={colors.onBackground}
          style={{ typography: 'displayLarge' }}>
          Display Large
        </Text>
        <Text
          color={colors.onBackground}
          style={{ typography: 'headlineMedium' }}>
          Headline Medium
        </Text>
        <Text
          color={colors.onBackground}
          style={{ typography: 'bodySmall' }}>
          Body Small
        </Text>
        <Text
          color={colors.onBackground}
          style={{ typography: 'labelLarge' }}>
          Label Large
        </Text>
      </Column>
    </Host>
  );
}

带有 maxLines 和 overflow 的文本

使用 maxLines 和 overflow 控制文本截断。

TextOverflowExample.tsx

import {
  Host,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { width } from '@expo/ui/jetpack-compose/modifiers';

export default function TextOverflowExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Text
        color={colors.onBackground}
        maxLines={2}
        overflow="ellipsis"
        modifiers={[width(200)]}>
        This is a long paragraph of text that will be truncated
        after two lines with an ellipsis at the end to indicate
        there is more content.
      </Text>
    </Host>
  );
}

设置文本样式

应用自定义文本样式，包括字重、样式、大小和装饰。

StyledTextExample.tsx

import {
  Host,
  Text,
  Column,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function StyledTextExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Column modifiers={[paddingAll(16)]}>
        <Text
          color={colors.onBackground}
          style={{ fontWeight: 'bold', fontSize: 20 }}>
          Bold text
        </Text>
        <Text
          color={colors.onBackground}
          style={{ fontStyle: 'italic' }}>
          Italic text
        </Text>
        <Text
          color={colors.onBackground}
          style={{ textDecoration: 'underline' }}>
          Underlined text
        </Text>
        <Text
          color={colors.onBackground}
          style={{ letterSpacing: 4 }}>
          Spaced out text
        </Text>
        <Text
          color="#E91E63"
          style={{ fontSize: 18, textAlign: 'center' }}>
          Colored and centered
        </Text>
      </Column>
    </Host>
  );
}

嵌套文本

嵌套 <Text> 组件，以便对句子中的部分内容应用行内样式。子 span 会继承其父级样式。例如，粗体父级配合斜体子级时，子级会同时呈现粗体和斜体。

NestedTextExample.tsx

import {
  Host,
  Text,
  Column,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function NestedTextExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Column modifiers={[paddingAll(16)]}>
        {/* Bold parent, italic child inherits bold */}
        <Text
          color={colors.onBackground}
          style={{ fontWeight: 'bold' }}>
          Hello <Text style={{ fontStyle: 'italic' }}>world</Text>!
        </Text>

        {/* Mixed inline styles */}
        <Text color={colors.onBackground} style={{ fontSize: 16 }}>
          Normal,{' '}
          <Text style={{ fontStyle: 'italic' }}>italic</Text>,{' '}
          <Text style={{ fontWeight: 'bold' }}>bold</Text>, and{' '}
          <Text style={{ textDecoration: 'underline' }}>
            underlined
          </Text>
        </Text>

        {/* Color and background overrides per span */}
        <Text color={colors.onBackground} style={{ fontSize: 18 }}>
          Click{' '}
          <Text color="#007AFF" style={{ fontWeight: 'bold' }}>
            这里
          </Text>{' '}
          or{' '}
          <Text style={{ background: '#FFEB3B' }}>highlighted</Text>
        </Text>

        {/* Deep nesting — styles accumulate */}
        <Text
          color={colors.onBackground}
          style={{ fontWeight: 'bold' }}>
          Bold{' '}
          <Text style={{ fontStyle: 'italic' }}>
            bold+italic{' '}
            <Text style={{ textDecoration: 'underline' }}>
              bold+italic+underline
            </Text>
          </Text>
        </Text>
      </Column>
    </Host>
  );
}

自定义字体

通过将字体族名称传递给 style.fontFamily，使用通过 expo-font 加载的字体。

CustomFontExample.tsx

import {
  Host,
  Text,
  Column,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function CustomFontExample() {
  const colors = useMaterialColors();

  return (
    <Host matchContents>
      <Column modifiers={[paddingAll(16)]}>
        <Text
          color={colors.onBackground}
          style={{ fontFamily: 'serif', fontSize: 16 }}>
          System serif font
        </Text>
        <Text
          color={colors.onBackground}
          style={{ fontFamily: 'monospace', fontSize: 16 }}>
          System monospace font
        </Text>
        <Text
          color={colors.onBackground}
          style={{ fontFamily: 'Inter-Bold', fontSize: 16 }}>
          Custom Inter Bold font
        </Text>
      </Column>
    </Host>
  );
}

API

import { Text } from '@expo/ui/jetpack-compose';

Component

`Text`

Android

Type: React.Element<TextProps>

Renders a Text component using Jetpack Compose.

TextProps

`children`

Android

Optional • Type: ReactNode

The text content to display. Can be a string, number, or nested Text components for inline styled spans.

`color`

Android

Optional • Type: ColorValue

The color of the text.

`maxLines`

Android

Optional • Type: number

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated according to overflow.

`minLines`

Android

Optional • Type: number

The minimum height in terms of minimum number of visible lines.

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`overflow`

Android

Optional • Type: TextOverflow

How visual overflow should be handled.

`softWrap`

Android

Optional • Type: boolean

Whether the text should break at soft line breaks. If false, the glyphs in the text will be positioned as if there was unlimited horizontal space.

`style`

Android

Optional • Type: TextStyle

Style configuration for the text. Corresponds to Jetpack Compose's TextStyle parameter.

Types

`TextAlign`

Android

Literal type: string

Text alignment options.

`TextDecoration`

Android

Literal type: string

Text decoration options.

Acceptable values are: 'none' | 'underline' | 'lineThrough'

`TextFontFamily`

Android

Literal type: string

Font family for text styling. Built-in system families: 'default', 'sansSerif', 'serif', 'monospace', 'cursive'. Custom font families loaded via expo-font can be referenced by name (for example, 'Inter-Bold').

Acceptable values are: 'default' | 'sansSerif' | 'serif' | 'monospace' | 'cursive'

`TextFontStyle`

Android

Literal type: string

Font style options for text styling.

Acceptable values are: 'normal' | 'italic'

`TextFontWeight`

Android

Literal type: string

Font weight options for text styling.

Acceptable values are: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'

`TextLineBreak`

Android

Literal type: string

Line break strategy options.

'simple': Basic line breaking.
'heading': Optimized for short text like headings.
'paragraph': Produces more balanced line lengths for body text.

Acceptable values are: 'simple' | 'heading' | 'paragraph'

`TextOverflow`

Android

Literal type: string

Text overflow behavior options.

'clip': Clips the overflowing text to fit its container
'ellipsis': Uses an ellipsis to indicate that the text has overflowed
'visible': Renders overflow text outside its container

Acceptable values are: 'clip' | 'ellipsis' | 'visible'

`TextShadow`

Android

Text shadow configuration. Corresponds to Jetpack Compose's Shadow class.

Property	Type	Description
blurRadius(optional)	`number`	The blur radius of the shadow in dp.
color(optional)	`ColorValue`	The color of the shadow.
offsetX(optional)	`number`	The horizontal offset of the shadow in dp.
offsetY(optional)	`number`	The vertical offset of the shadow in dp.

`TextSpanStyleBase`

Android

Shared span-level style properties used by both TextStyle and TextSpanRecord. Adding a property here ensures it's available on both parent text and nested spans.

Property	Type	Description
background(optional)	`ColorValue`	The background color behind the text.
fontFamily(optional)	`TextFontFamily`	The font family.
fontSize(optional)	`number`	The font size in sp (scale-independent pixels).
fontStyle(optional)	`TextFontStyle`	The font style of the text.
fontWeight(optional)	`TextFontWeight`	The font weight of the text.
letterSpacing(optional)	`number`	The letter spacing in sp.
shadow(optional)	`TextShadow`	The shadow applied to the text.
textDecoration(optional)	`TextDecoration`	The text decoration.

`TextStyle`

Android

Text style properties that can be applied to text. Corresponds to Jetpack Compose's TextStyle.

Type: TextSpanStyleBase extended by:

Property	Type	Description
lineBreak(optional)	`TextLineBreak`	The line break strategy.
lineHeight(optional)	`number`	The line height in sp.
textAlign(optional)	`TextAlign`	The text alignment.
typography(optional)	`TypographyStyle`	Material 3 Typography style to use as the base style. When specified, applies the predefined Material 3 typography style. Other properties in this style object will override specific values from the typography.

`TypographyStyle`

Android

Literal type: string

Material 3 Typography scale styles. Corresponds to MaterialTheme.typography in Jetpack Compose.