文本
一个用于显示样式化文本的 Jetpack Compose Text 组件。
For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.
Expo UI Text 与官方 Jetpack Compose Text styling API 一致,并使用 Material 3 的排版样式、自定义字体和文本格式选项来显示文本。
安装
- npx expo install @expo/uiIf you are installing this in an existing React Native app, make sure to install expo in your project.
使用
基本文本
import { Host, Text } from '@expo/ui/jetpack-compose'; export default function BasicTextExample() { return ( <Host matchContents> <Text>你好,世界!</Text> </Host> ); }
排版样式
将 style 属性与 typography 一起使用,以应用 Material 3 排版预设。
import { Host, Text, Column } from '@expo/ui/jetpack-compose'; import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; export default function TypographyExample() { return ( <Host matchContents> <Column modifiers={[paddingAll(16)]}> <Text style={{ typography: 'displayLarge' }}>超大显示</Text> <Text style={{ typography: 'headlineMedium' }}>中等标题</Text> <Text style={{ typography: 'bodySmall' }}>小号正文</Text> <Text style={{ typography: 'labelLarge' }}>大号标签</Text> </Column> </Host> ); }
带有 maxLines 和 overflow 的文本
使用 maxLines 和 overflow 控制文本截断。
import { Host, Text } from '@expo/ui/jetpack-compose'; import { width } from '@expo/ui/jetpack-compose/modifiers'; export default function TextOverflowExample() { return ( <Host matchContents> <Text maxLines={2} overflow="ellipsis" modifiers={[width(200)]}> 这是一段很长的文本段落,它将在两行之后被截断,并在末尾显示省略号,表示还有更多内容。 </Text> </Host> ); }
样式化文本
应用自定义文本样式,包括字重、样式、大小和装饰。
import { Host, Text, Column } from '@expo/ui/jetpack-compose'; import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; export default function StyledTextExample() { return ( <Host matchContents> <Column modifiers={[paddingAll(16)]}> <Text style={{ fontWeight: 'bold', fontSize: 20 }}>粗体文本</Text> <Text style={{ fontStyle: 'italic' }}>斜体文本</Text> <Text style={{ textDecoration: 'underline' }}>带下划线的文本</Text> <Text style={{ letterSpacing: 4 }}>间距加大的文本</Text> <Text color="#E91E63" style={{ fontSize: 18, textAlign: 'center' }}> 有颜色且居中 </Text> </Column> </Host> ); }
嵌套文本
嵌套 <Text> 组件以对句子的一部分应用行内样式。子级 span 会继承其父级样式。例如,粗体父级配合斜体子级时,子级会同时显示为粗体和斜体。
import { Host, Text, Column } from '@expo/ui/jetpack-compose'; import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; export default function NestedTextExample() { return ( <Host matchContents> <Column modifiers={[paddingAll(16)]}> {/* 粗体父级,斜体子级继承粗体 */} <Text style={{ fontWeight: 'bold' }}> 你好 <Text style={{ fontStyle: 'italic' }}>世界</Text>! </Text> {/* 混合行内样式 */} <Text style={{ fontSize: 16 }}> 普通,<Text style={{ fontStyle: 'italic' }}>斜体</Text>,{' '} <Text style={{ fontWeight: 'bold' }}>粗体</Text>,以及{' '} <Text style={{ textDecoration: 'underline' }}>下划线</Text> </Text> {/* 每个 span 的颜色和背景覆盖 */} <Text style={{ fontSize: 18 }}> 点击{' '} <Text color="#007AFF" style={{ fontWeight: 'bold' }}> 这里 </Text>{' '} 或 <Text style={{ background: '#FFEB3B' }}>高亮显示</Text> </Text> {/* 深层嵌套 — 样式会累积 */} <Text style={{ fontWeight: 'bold' }}> 粗体{' '} <Text style={{ fontStyle: 'italic' }}> 粗体+斜体 <Text style={{ textDecoration: 'underline' }}>粗体+斜体+下划线</Text> </Text> </Text> </Column> </Host> ); }
自定义字体
通过将字体族名称传递给 style.fontFamily,使用通过 expo-font 加载的字体。
import { Host, Text, Column } from '@expo/ui/jetpack-compose'; import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; export default function CustomFontExample() { return ( <Host matchContents> <Column modifiers={[paddingAll(16)]}> <Text style={{ fontFamily: 'serif', fontSize: 16 }}>系统衬线字体</Text> <Text style={{ fontFamily: 'monospace', fontSize: 16 }}>系统等宽字体</Text> <Text style={{ fontFamily: 'Inter-Bold', fontSize: 16 }}>自定义 Inter Bold 字体</Text> </Column> </Host> ); }
API
import { Text } from '@expo/ui/jetpack-compose';
Component
Type: React.Element<TextProps>
Renders a Text component using Jetpack Compose.
React.ReactNodeThe text content to display. Can be a string, number, or nested Text components
for inline styled spans.
numberAn 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.
numberThe minimum height in terms of minimum number of visible lines.
booleanWhether 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.
TextStyleStyle configuration for the text. Corresponds to Jetpack Compose's TextStyle parameter.
Types
Literal Type: string
Text alignment options.
Acceptable values are: 'left' | 'right' | 'center' | 'justify' | 'start' | 'end'
Literal Type: string
Text decoration options.
Acceptable values are: 'none' | 'underline' | 'lineThrough'
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'
Literal Type: string
Font style options for text styling.
Acceptable values are: 'normal' | 'italic'
Literal Type: string
Font weight options for text styling.
Acceptable values are: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
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'
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'
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) | string | 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. |
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) | string | 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. |
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. |
Literal Type: string
Material 3 Typography scale styles. Corresponds to MaterialTheme.typography in Jetpack Compose.
Acceptable values are: 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall' | 'labelLarge' | 'labelMedium' | 'labelSmall'