React Native Elements Text 组件实战：从标题排版（h1–h4）到主题化配色

React Native Elements Text 组件实战：从标题排版（h1–h4）到主题化配色

【免费下载链接】react-native-elementsCross-Platform React Native UI Toolkit项目地址: https://gitcode.com/gh_mirrors/re/react-native-elements

导读

Text是 React Native Elements（RNE）中最基础也最常用的展示型组件，它在 React Native 原生Text之上封装了一套开箱即用的标题体系（h1–h4）与主题化能力。本指南以官方文档中的可运行示例（位于 website/versioned_docs/version-4.0.0-beta.0/main/usage/Text/snack/index.md）为骨架，结合packages/base与packages/themed的真实源码和单元测试，讲解如何快速搭建页面标题层级、如何用useTheme让标题颜色跟随主题变化，以及字号缩放、默认色板等底层细节。读完后你将能够把Text的标题用法和主题化配色方案直接应用到自己的 RNE 项目中。

一、Text 组件在 RNE 中的定位

在 React Native Elements 的包结构中，Text的"无主题基础实现"位于 packages/base/src/Text/Text.tsx，组件定义处的注释明确写道：

Text displays words and characters of various sizes.

即 Text 用于以不同字号展示文字内容。它通过React.forwardRef暴露对底层原生Text的引用，并导出一份扩展后的TextProps：

• 完整继承 React Native 的TextProps（TextProperties），因此原生Text的所有属性（numberOfLines、onPress、selectable等）都可用；
• 额外增加h1/h2/h3/h4四个布尔开关，以及配套的h1Style/h2Style/h3Style/h4Style样式覆盖属性。

同时，组件默认设置了accessibilityRole="text"，帮助无障碍服务正确朗读文本内容，这是一个值得在开发中保留的默认行为。

二、h1–h4 标题体系：字号、加粗与样式覆盖

2.1 四个标题开关的含义

在 Text.tsx 的实现中，样式合并顺序为：

style={StyleSheet.flatten([ { ...Platform.select({ android: { ...(fonts.android.regular as TextStyle) }, }), color: theme?.colors?.black, }, style, // 用户传入的 style 覆盖默认颜色 (h1 || h2 || h3 || h4) && (styles.bold as TextStyle), h1 && StyleSheet.flatten([{ fontSize: normalize(40) }, h1Style]), h2 && StyleSheet.flatten([{ fontSize: normalize(34) }, h2Style]), h3 && StyleSheet.flatten([{ fontSize: normalize(28) }, h3Style]), h4 && StyleSheet.flatten([{ fontSize: normalize(22) }, h4Style]), ])}

关键点有三：

1. 默认文本颜色为theme.colors.black，可被外部style覆盖；
2. 只要设置了任意一个标题开关，就会附加bold字重。Android 平台下默认字体为sans-serif常规字重，加粗后切换为sans-serif+bold（定义见 packages/base/src/helpers/fonts.tsx）；
3. h1Style等属性只作用于对应标题开关，且排在style之后、拥有更高优先级，可用于单独调整某个标题的细节样式。

2.2 字号并非写死的数字：normalize 缩放

源码中标题字号没有直接使用fontSize: 40，而是经过normalize(40)处理。normalize定义在 packages/base/src/helpers/normalizeText.tsx：

import { moderateScale } from 'react-native-size-matters'; function normalize(number: number, factor = 0.25) { return moderateScale(number, factor); }

也就是说，Text的标题字号基于react-native-size-matters的moderateScale按设备屏幕宽度做中等程度缩放（factor 0.25），让小屏设备上的标题不至于过大、大屏设备上的标题不至于过小。这也解释了为什么在单元测试 packages/base/src/Text/tests/Text.test.tsx 中，测试环境下实际断言的字号是51.4（h1）、43.7（h2）、36（h3）、28.3（h4）——它们与源码注释中的基准值 40/34/28/22 不同，正是normalize按测试环境屏幕尺寸缩放后的结果。因此在实际设备上，标题最终字号会随屏幕宽度在基准值上下浮动。

2.3 测试如何验证标题行为

Text.test.tsx 覆盖了Text的关键契约：

• accessibilityRole="text"存在（通过getByRole('text')获取元素）；
• h1–h4各自的缩放后字号断言；
• children正常渲染为文本内容；
• style支持以数组形式传入并被正确扁平化合并。

这些测试从侧面印证了本文档示例中h1Style、h4等写法的正确性。

三、示例代码逐段精讲：标题 + 主题配色

官方示例（snack/index.md）用一段完整的 SnackPlayer 代码演示了Text最核心的实战组合：四档标题 + 通过useTheme获取主题色来给标题上色。完整代码如下：

import React from 'react'; import { StyleSheet, View } from 'react-native'; import { Text, useTheme } from 'react-native-elements'; type TextComponentProps = {}; const TextComponent: React.FunctionComponent<TextComponentProps> = () => { const { theme } = useTheme(); return ( <> <View style={styles.view}> <Text style={styles.text} h1 h1Style={{ color: theme?.colors?.secondary }} > Heading 1 </Text> <Text style={styles.text} h2 h2Style={{ color: theme?.colors?.success }} > Heading 2 </Text> <Text style={styles.text} h3 h3Style={{ color: theme?.colors?.warning }} > Heading 3 </Text> <Text style={styles.text} h4 h4Style={{ color: theme?.colors?.primary }} > Heading 4 </Text> </View> </> ); }; const styles = StyleSheet.create({ view: { margin: 10, }, text: { textAlign: 'center', padding: 5, }, more: { marginVertical: 20, }, button: { width: 120, marginLeft: 'auto', marginRight: 'auto', }, }); export default TextComponent;

逐段拆解：

• import { Text, useTheme } from 'react-native-elements'：在 RNE 的公开入口中，Text导出的是经过withTheme包装的主题化版本（见 packages/themed/src/Text/index.tsx），它会自动消费外层ThemeProvider提供的主题；useTheme则由 packages/themed/src/config/ThemeProvider.tsx 导出，返回{ theme, updateTheme, ... }。
• const { theme } = useTheme()：解构出当前主题对象。theme.colors即主题色板，用于给标题动态上色。
• h1+h1Style={{ color: theme?.colors?.secondary }}：开启一级标题，并用h1Style将字号缩放后的默认样式叠加主题色。?.可选链保证了在没有主题上下文时不会抛错。

这里还展示了Text的双层样式体系：style负责通用布局（居中、内边距），h1Style–h4Style负责标题专属的配色。二者互不干扰、按需组合，是 RNEText的推荐用法。

四、主题色板：示例中出现的颜色从哪里来

示例用到的theme.colors.secondary / success / warning / primary均来自主题默认色板。packages/base中定义了完整的明暗两套色板，见 packages/base/src/helpers/colors.ts：

注意darkColors.black在深色模式下被反转为浅色#f2f2f2，这正是Text默认文字颜色取theme.colors.black的原因——它随主题明暗自动反转，保证可读性。因此，示例中这种"用theme.colors取色"的写法天然支持浅色/深色主题切换，无需为每个主题手写颜色分支。lightColors与darkColors各自还包含完整的grey0–grey5、disabled、divider及平台相关色值，均可通过同样的方式在h1Style等样式中使用。

五、上手运行：在真实项目中复现示例

5.1 环境前提

• 已按官方方式安装@rneui/themed（或使用统一入口react-native-elements）并完成 React Native 项目初始化；
• 应用根节点被<ThemeProvider>包裹，useTheme才能在组件树内生效；
• Text组件本身不依赖额外原生模块，Android/iOS/Web 均可用（源码中通过patchWebProps对 Web 环境做兼容处理）。

5.2 最小化改造

将上文示例组件放入任意页面，替换默认渲染内容即可。如果项目尚未配置自定义主题，直接使用默认主题色板也能跑通；需要定制时，可在ThemeProvider的theme中覆盖colors字段（如colors: { primary: '#ff0000' }），示例代码中所有theme.colors.primary引用会同步更新。

5.3 常见调整

• 只想改字号不改色：<Text h1 h1Style={{ fontSize: 48 }}>；
• 想让某个标题不居中：去掉style={styles.text}或覆盖textAlign；
• 需要标题可点击：Text继承原生TextProps，直接传onPress即可。

仓库中还提供了一份等价的展示用法文件 packages/base/src/Text/Text.usage.tsx，其中用<Text h1>Heading 1</Text>的极简形式展示了纯标题排版效果，可作为对照参考。

六、总结

围绕 RNEText组件，本文完整继承了官方示例并做了源码级展开：

• 标题体系：h1–h4提供 40/34/28/22 的基准字号，经normalize（moderateScale）按屏幕缩放，且自带加粗；
• 主题化：useTheme+theme.colors让标题颜色跟随主题（浅色/深色）自动切换，默认色板见 colors.ts；
• 样式分层：通用布局用style，标题专属用h1Style–h4Style；
• 可验证性：字号与行为均有 Text.test.tsx 的单元测试背书。

按此模式，你可以在不写任何硬编码颜色的前提下，快速搭建出一套随主题自适应、跨平台一致的页面标题层级。

【免费下载链接】react-native-elementsCross-Platform React Native UI Toolkit项目地址: https://gitcode.com/gh_mirrors/re/react-native-elements