企业官网建设流程全解析

@rneui/themed 主题化组件库使用指南：React Native Elements 主题系统与跨端实践

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

本文围绕@rneui/themed主题化组件包展开，讲解其安装方式、基础用法、主题定制（明暗色板、组件级主题）、HOC/组件 API 以及 React Native Web 跨端支持，并结合作品源码揭示其底层实现原理，帮助你真正掌握 React Native Elements 的"主题驱动开发"工作流。

@rneui/themed是 React Native Elements 官方拆分出的主题化（themed）组件包：它把@rneui/base中的每一个组件用withTheme包装一层，使所有组件都能自动消费主题上下文，开箱即用地支持明暗模式切换、全局配色覆盖与组件级样式定制。本文将从安装、使用、主题 API、底层原理到 Web 端实践，完整带你上手这套主题体系。

安装

@rneui/themed通过 npm 直接安装即可：

npm install @rneui/themed

从仓库的 packages/themed/package.json 可以看到，@rneui/themed以@rneui/base为peerDependency（当前仓库中版本为5.0.0）：

{ "name": "@rneui/themed", "version": "5.0.0", "peerDependencies": { "@rneui/base": "5.0.0" }, "main": "dist/index.js", "types": "dist/index.d.ts" }

这意味着你需要同时安装@rneui/base（基础无主题组件）与@rneui/themed（主题化组件），且两者版本需要匹配。base 包同样位于本仓库：packages/base/README.md：

npm install @rneui/base

基础用法：一行代码引入主题化组件

安装完成后，直接从@rneui/themed导入组件即可使用：

import { Button } from '@rneui/themed'; const App = () => <Button title="Hello World" />;

与 base 包的用法（import { Button } from '@rneui/base'）几乎一致，唯一的区别是 themed 包导出的组件会自动挂载主题上下文。若你尚未包裹ThemeProvider，组件也不会报错——从源码 packages/themed/src/config/withTheme.tsx 看，ThemedComponent在检测到没有 ThemeProvider 时会自动回退到lightColors+ 默认spacing作为兜底主题，保证组件开箱即用。

完整组件清单

从 packages/themed/src/index.ts 可以看到，themed 包导出了 base 包的全部核心组件：

同时导出的还有全部组件的 TypeScript Props 类型（ButtonProps、CardProps等），方便类型安全开发。

主题系统：明暗模式与全局定制

@rneui/themed相比 base 包的核心差异，在于它内置了一整套主题（Theme）基础设施。所有主题 API 都从包的入口直接导出，包括：ThemeProvider、ThemeConsumer、ThemeContext、useTheme、useThemeMode、withTheme、makeStyles、createTheme、lightColors、darkColors。

ThemeProvider：注入主题上下文

ThemeProvider通过 React Context 向下层组件注入主题。它的核心类型定义与实现位于 packages/themed/src/config/ThemeProvider.tsx：

export interface CreateThemeOptions extends RecursivePartial<Theme> { lightColors?: RecursivePartial<Colors>; darkColors?: RecursivePartial<Colors>; components?: ComponentFunctionProps; } export type ThemeMode = 'light' | 'dark';

其中Theme接口（packages/themed/src/config/theme.ts）只包含两个字段：

export interface Theme { mode: ThemeMode; // 'light' | 'dark' spacing: ThemeSpacing; // 间距 token }

而FullTheme则在Theme基础上叠加了colors: Colors与各组件主题（ComponentTheme）。

createTheme：合并默认主题

createTheme使用deepmerge将你传入的主题与内置默认主题深度合并，源码如下：

export const createTheme = (theme: CreateThemeOptions = {}): CreateThemeOptions => { return { ...theme, ...deepmerge<CreateThemeOptions>( { lightColors, darkColors, spacing: defaultSpacing }, { lightColors: theme.lightColors || {}, darkColors: theme.darkColors || {}, mode: theme.mode || 'light', spacing: theme.spacing || {}, components: theme.components || {}, } ), }; };

默认的lightColors与darkColors色板定义在 base 包（packages/themed/src/config/colors.ts 直接从@rneui/base/dist/helpers转发导出）。ThemeProvider内部会依据mode选择当前生效的色板：separateColors在mode === 'dark'时使用darkColors，否则使用lightColors，合并进theme.colors。

明暗模式切换：useThemeMode

切换到暗色模式只需一行代码。useThemeMode返回{ mode, setMode }：

import { ThemeProvider, Button, useThemeMode } from '@rneui/themed'; const Toggle = () => { const { mode, setMode } = useThemeMode(); return ( <Button title={`当前模式：${mode}`} onPress={() => setMode(mode === 'light' ? 'dark' : 'light')} /> ); }; const App = () => ( <ThemeProvider> <Toggle /> </ThemeProvider> );

其实现（ThemeProvider.tsx）本质是调用updateTheme({ mode: colorMode })，ThemeProvider的useEffect监听theme.mode变化并重新计算上下文值，所有已包裹的组件随即响应式重渲染。

运行时更新与整体替换

ThemeProvider 的 Context 值还包含两个更新函数：

• updateTheme：与当前主题深度合并（deepmerge），适合局部修改，例如updateTheme({ mode: 'dark' })；
• replaceTheme：整体替换为基于默认主题合并的新主题，适合场景化主题切换。

两者均支持传入函数形式(oldTheme) => newTheme，以便基于旧值做增量计算。

组件级主题：为单个组件定制样式

CreateThemeOptions的components字段支持为每个组件单独指定主题属性。在 packages/themed/src/config/ThemeProvider.tsx 中，components的值可以是对象，也可以是接收 props 与 theme 的函数：

type ComponentFunctionProps = { [Key in keyof ComponentTheme]?: | ComponentTheme[Key] | ((props: ComponentTheme[Key], theme: Theme & { colors: Colors }) => ComponentTheme[Key]); };

示例：全局统一所有Button的圆角与配色：

import { createTheme, ThemeProvider, Button } from '@rneui/themed'; const theme = createTheme({ lightColors: { primary: '#e7e74c', }, components: { Button: { raised: true, titleStyle: { color: 'red' }, buttonStyle: { borderRadius: 10 }, }, }, }); const App = () => ( <ThemeProvider theme={theme}> <Button title="自定义主题按钮" /> </ThemeProvider> );

在withTheme的 ThemedComponent 实现中，组件级主题会通过deepmerge与传入的 props 合并，并且对*Style/*style结尾的属性使用combineByStyles自定义合并策略——将主题样式与 props 样式拼接成数组（而非覆盖），从而保证传入的 style 总能在主题样式之上生效。

自定义组件接入主题：makeStyles 与 withTheme

@rneui/themed不仅让官方组件支持主题，也让你自己的业务组件轻松接入主题体系。

makeStyles：函数式样式工厂

makeStyles接收一个"主题感知"的样式函数，返回一个 Hook，在组件中调用后即可拿到经过StyleSheet.create的样式对象。其实现位于 packages/themed/src/config/makeStyles.ts：

export const makeStyles = <T extends StyleSheet.NamedStyles<T>, V>( styles: T | ((theme: { colors: Colors } & Theme, props: V) => T) ) => (props?: V): T => { const { theme } = useTheme(); return useMemo(() => { const css = typeof styles === 'function' ? styles(theme, props ?? {}) : styles; return StyleSheet.create(css); }, [props, theme]); };

使用示例：

import { makeStyles, Text } from '@rneui/themed'; const useStyles = makeStyles((theme, props) => ({ container: { backgroundColor: theme.colors.grey5, padding: theme.spacing.md, }, title: { color: theme.colors.primary, }, })); const MyComponent = ({ title }) => { const styles = useStyles(); return <Text style={styles.title}>{title}</Text>; };

注意makeStyles内部使用了useMemo，依赖[props, theme]，当主题或 props 变化时样式会重新计算，保证响应式。

withTheme：HOC 高阶组件

对于类组件或需要在渲染期拿到theme/updateTheme/replaceTheme的场景，可以使用withThemeHOC（packages/themed/src/config/withTheme.tsx）：

import { withTheme, ThemeProps, Button } from '@rneui/themed'; type Props = ThemeProps & { title: string }; const MyButton = ({ title, theme, updateTheme }: Props) => ( <Button title={title} color={theme.colors.primary} /> ); export default withTheme(MyButton);

从源码可以看到，withTheme对类组件会额外执行hoistNonReactStatics并包裹React.forwardRef，保证静态方法与 ref 的正常传递。

themed 组件如何封装 base 组件

理解@rneui/themed的架构，只需看任意一个组件的入口。以 Button 为例（packages/themed/src/Button/index.tsx）：

import { withTheme } from '../config'; import { Button, ButtonProps } from '@rneui/base/dist/Button/Button'; export { Button }; export type { ButtonProps }; export default withTheme<ButtonProps>(Button, 'Button');

整个 themed 包的设计模式非常统一：从 base 包导入无主题组件，用withTheme(Component, themeKey)包装，themeKey与createTheme中components的键名一一对应（如'Button'、'Card'）。这也解释了为什么@rneui/base是 peerDependency——themed 包本身不重复实现组件，只做主题层包装。

React Native Web 跨端支持

@rneui/themed作为跨平台 UI Toolkit 的组成部分，组件天然适配 Web 端渲染。仓库中的示例工程example/专门配置了 Web 构建：example/webpack.config.js 与 example/metro.config.js，同时 example/src/components/LinearGradient.ts 等文件提供了 Web 环境的降级实现。

要实现"一套代码同时跑 iOS / Android / Web"，典型做法是：

1. 使用 React Native for Web 作为 Web 渲染后端；
2. 业务代码统一从@rneui/themed导入组件与主题 API；
3. 通过 webpack（或 Metro）分别构建各端产物。

example/中的 App.tsx 与 src/navigation/RootNavigator.tsx 就是同一套代码多端运行的参考实现，其中的 theme.tsx 展示了主题页面的实际用法。官方还提供了 Expo 演示 App（@rn_elements/react-native-elements），覆盖了全部组件与主题切换场景，可直接在 Expo 上体验或本地运行 example 工程。

开发提效：VS Code 扩展

官方为@rneui/themed提供了 VS Code Snippets 扩展（rne.snippets），安装后可以快速插入组件模板，加速日常开发。此外本仓库还附带一整套自动化文档工具（scripts/docgen），组件 Props 文档由源码类型自动生成，你可以在 website/docs/components 与 website/docs/component_usage 中查阅全部组件 API 与使用示例。

注意事项与最佳实践

1. 版本匹配：@rneui/themed与@rneui/base必须使用匹配的版本（本仓库当前均为5.0.0），否则会出现类型或运行时不一致；
2. 主题入口统一：建议在应用根节点只包裹一次ThemeProvider，通过createTheme一次性声明全局色板、组件主题与间距 token；
3. 明暗模式：useThemeMode().setMode是切换明暗模式的标准方式，配合lightColors/darkColors色板即可实现全局深色模式；
4. 样式合并语义：组件级主题中的 style 类属性与调用方传入的 style 会做数组合并，调用方样式优先，无需担心主题覆盖自定义样式；
5. Web 端：主题 API（useTheme、makeStyles、withTheme）与组件在 Web 端行为一致，可直接复用同一套业务代码。

总结

@rneui/themed是 React Native Elements 的"主题层"：它以@rneui/base为基底，通过withTheme统一包装全部组件，配合ThemeProvider、createTheme、useTheme、useThemeMode、makeStyles等 API，构建出一套完整、响应式的主题系统。无论你是想快速切换明暗模式、全局统一品牌色，还是为自定义组件接入主题能力，都可以在本仓库的 packages/themed/src 中找到可直接参考的实现。

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