React Native Elements Card 组件实战指南：用法示例、Props 与源码级样式解析-港品优选

React Native Elements Card 组件实战指南：用法示例、Props 与源码级样式解析

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

Card（卡片）是 React Native Elements 中用于集中展示"单一主题"信息的容器组件，可容纳图片、按钮、文本等多种内容，主要承担信息呈现与承载相关操作的作用。本篇指南以仓库中 version-4.0.0-beta.0 的 Card 文档及其内嵌的可运行示例为骨架，结合packages/base下 Card 的完整源码实现，带你掌握 Card 的基本用法、五个内置子组件、全部 Props 参数，以及默认样式背后的平台差异与主题机制。

Card 是什么：定位与适用场景

组件官方描述（见 Card.usage.tsx 中的 info 声明与主文档）明确说明：

Cards 是展示信息的一种绝佳方式，通常承载关于单一主题的内容与操作；
Cards 可以包含图片、按钮、文本等更多内容；
Cards 主要用于信息展示目的。

从定位上看，Card 与 ListItem 的区别在于：Card 强调"一个主题、一块内容"的独立呈现（类似 Web 中的卡片式布局），而 ListItem 强调列表中的逐行条目。在电商详情、新闻快讯、用户简介、词条解释等场景中，Card 都是首选容器。

快速开始：安装与导入

在 4.0.0-beta.0 版本的示例中（见 usage/Card/snack/index.md），Card 与其他组件一同从主包导入：

import { View, ScrollView, StyleSheet, Image } from 'react-native'; import { Text, Card, Button, Icon } from 'react-native-elements';

需要注意：仓库中packages/base对应无主题的基础包，packages/themed对应主题化包。在 version-4.0.0-rc.1 及之后的文档中，导入路径已演进为@rneui/themed：

import { Text, Card, Button, Icon } from '@rneui/themed';

实际使用哪个包取决于你的项目是直接消费组件（base）还是需要内置主题（themed），两者组件 API 保持一致。

完整示例：一张卡片的三类典型场景

以下是文档内嵌 Snack 示例的完整代码（来自 snack/index.md），它演示了 Card 最常见的三种组合形态：标题 + 分割线 + 列表、标题 + 分割线 + 多级标题文本、标题 + 分割线 + 图片 + 按钮：

import React from 'react'; import { View, ScrollView, StyleSheet, Image } from 'react-native'; import { Text, Card, Button, Icon } from 'react-native-elements'; const users = [ { name: 'brynn', avatar: 'https://uifaces.co/our-content/donated/1H_7AxP0.jpg', }, { name: 'thot leader', avatar: 'https://images.pexels.com/photos/598745/pexels-photo-598745.jpeg?crop=faces&fit=crop&h=200&w=200&auto=compress&cs=tinysrgb', }, { name: 'jsa', avatar: 'https://uifaces.co/our-content/donated/bUkmHPKs.jpg', }, { name: 'talhaconcepts', avatar: 'https://randomuser.me/api/portraits/men/4.jpg', }, { name: 'andy vitale', avatar: 'https://uifaces.co/our-content/donated/NY9hnAbp.jpg', }, { name: 'katy friedson', avatar: 'https://images-na.ssl-images-amazon.com/images/M/MV5BMTgxMTc1MTYzM15BMl5BanBnXkFtZTgwNzI5NjMwOTE@._V1_UY256_CR16,0,172,256_AL_.jpg', }, ]; type CardsComponentsProps = {}; const Cards: React.FunctionComponent<CardsComponentsProps> = () => { return ( <> <ScrollView> <View style={styles.container}> <Card> <Card.Title>CARD WITH DIVIDER</Card.Title> <Card.Divider /> {users.map((u, i) => { return ( <View key={i} style={styles.user}> <Image style={styles.image} resizeMode="cover" source={{ uri: u.avatar }} /> <Text style={styles.name}>{u.name}</Text> </View> ); })} </Card> <Card containerStyle={{ marginTop: 15 }}> <Card.Title>FONTS</Card.Title> <Card.Divider /> <Text style={styles.fonts} h1> h1 Heading </Text> <Text style={styles.fonts} h2> h2 Heading </Text> <Text style={styles.fonts} h3> h3 Heading </Text> <Text style={styles.fonts} h4> h4 Heading </Text> <Text style={styles.fonts}>Normal Text</Text> </Card> <Card> <Card.Title>HELLO WORLD</Card.Title> <Card.Divider /> <Card.Image style={{ padding: 0 }} source={{ uri: 'https://awildgeographer.files.wordpress.com/2015/02/john_muir_glacier.jpg', }} /> <Text style={{ marginBottom: 10 }}> The idea with React Native Elements is more about component structure than actual design. </Text> <Button icon={ <Icon name="code" color="#ffffff" iconStyle={{ marginRight: 10 }} /> } buttonStyle={{ borderRadius: 0, marginLeft: 0, marginRight: 0, marginBottom: 0, }} title="VIEW NOW" /> </Card> </View> </ScrollView> </> ); }; const styles = StyleSheet.create({ container: { flex: 1, }, fonts: { marginBottom: 8, }, user: { flexDirection: 'row', marginBottom: 6, }, image: { width: 30, height: 30, marginRight: 10, }, name: { fontSize: 16, marginTop: 5, }, }); export default Cards;

对这个示例做三点拆解：

列表型卡片：Card.Title提供居中加粗标题，Card.Divider生成分隔线，随后在卡片内直接渲染用户头像与姓名列表——Card 内部就是普通 View 布局，可以放入任意子元素；
多级标题卡片：借助containerStyle={{ marginTop: 15 }}控制卡片间距，配合 Text 组件的h1~h4属性演示层级标题（该能力来自 Text 组件而非 Card 本身）；
图文按钮卡片：Card.Image渲染大图，下方文本说明，最后用带code图标的 Button 作为行动入口，buttonStyle将按钮铺满卡片宽度（四边圆角与边距归零）。

另外，Card.usage.tsx 还提供了一个更精简的"每日一词"示例，展示最基础的卡片形态——标题文本 + 正文 + 清除样式按钮：

<Card> <Text>Word of the Day</Text> <Text h4>be-nev-o=lent</Text> <Text>adjective</Text> <Text> well meaning and kindly. <br /> {'"a benevolent smile"'} </Text> <Button size="sm" type="clear"> Learn More </Button> </Card>

五个内置子组件详解

主文档的 Components 章节列出了 Card 挂载的五个静态子组件，其组装方式见 Card/index.tsx：通过Object.assign将各子组件挂到CardBase上，从而得到Card.Title、Card.Divider、Card.Image、Card.FeaturedTitle、Card.FeaturedSubtitle五个命名空间组件。

Card.Title —— 常规标题

实现见 Card.Title.tsx。它本质上是对Text 组件的一层封装，接收 Text 的全部 Props。默认样式包括：

字号normalize(14)（经 normalizeText 按设备宽度缩放）；
颜色取自主题色colors.grey1；
字体加粗：Android 使用fonts.android.black，其他平台使用fontWeight: 'bold'；
textAlign: 'center'居中，marginBottom: 15。

Card.Divider —— 内容分隔线

实现见 Card.Divider.tsx，接收Divider 组件的全部 Props，仅追加marginBottom: 15的默认样式。它作为卡片内部元素之间的分隔线，典型用法就是示例中的<Card.Title>...</Card.Title><Card.Divider />。

Card.Image —— 卡片配图

实现见 Card.Image.tsx，接收Image 组件的全部 Props，默认样式为width: null（撑满容器）、height: 150。除了示例中的普通用法，它还可以与 Featured 系列组件组合实现"图文封面"效果。

Card.FeaturedTitle / Card.FeaturedSubtitle —— 封面标题与副标题

实现分别见 Card.FeaturedTitle.tsx 与 Card.FeaturedSubtitle.tsx。二者同样接收 Text 的全部 Props，默认使用白色字体（colors.white），专为叠加在图片/深色背景上设计的封面文案：

FeaturedTitle：字号normalize(18)，非 Android 平台fontWeight: '800'；
FeaturedSubtitle：字号normalize(13)，非 Android 平台fontWeight: '400'。

典型组合（图片 + 白色封面文字 + 行动按钮）：

<Card containerStyle={{ padding: 0 }}> <Card.Image source={{ uri: '...' }}> <Card.FeaturedTitle>Featured Title</Card.FeaturedTitle> <Card.FeaturedSubtitle>Featured Subtitle</Card.FeaturedSubtitle> </Card.Image> <View style={{ padding: 15 }}> <Text>正文内容</Text> <Button title="查看详情" /> </View> </Card>

Props 完整参考

根据主文档的 Props/Reference 章节，各组件 Props 如下：

Card

Props	说明	类型	默认值
`containerStyle`	外层容器样式	View style(Object)	None
`wrapperStyle`	内层容器样式	View style(Object)	None

Card.Divider

无额外 Props（透传 Divider 的全部 Props）。

Card.FeaturedSubtitle

无额外 Props（透传 Text 的全部 Props）。

Card.FeaturedTitle

无额外 Props（透传 Text 的全部 Props）。

Card.Image

Props	说明	类型	默认值
`pressableProps`	传递给底层按压容器的属性	`Omit<PressableProps, "onPress" or "onLongPress" or "onPressIn" or "onPressOut">`	None

Card.Image除透传 Image 的全部 Props 外，还额外暴露pressableProps，用于在图片上附加点击等按压行为，同时刻意排除了onPress、onLongPress、onPressIn、onPressOut四个回调（它们应由更上层的卡片交互逻辑统一管理）。

Card.Title

无额外 Props（透传 Text 的全部 Props）。

源码级解析：默认样式与平台差异

Card.tsx 揭示了 Card 的完整默认样式与双层结构，理解它有助于准确预估"不传任何样式时卡片长什么样"：

<View {...rest} style={StyleSheet.flatten([ { backgroundColor: theme?.colors?.white, borderWidth: 1, padding: 15, margin: 15, marginBottom: 0, borderColor: theme?.colors?.grey5, ...Platform.select({ android: { elevation: 1, }, default: { shadowColor: 'rgba(0,0,0, .2)', shadowOffset: { height: 0, width: 0 }, shadowOpacity: 1, shadowRadius: 1, }, }), }, containerStyle && containerStyle, ])} > <View style={StyleSheet.flatten([ styles.wrapper, // { backgroundColor: 'transparent' } wrapperStyle && wrapperStyle, ])} > {children} </View> </View>

关键点：

默认外观：白色背景（theme.colors.white）、1px 边框（theme.colors.grey5浅灰）、内边距padding: 15、外边距margin: 15（marginBottom归零，卡片间距离需靠containerStyle自行补充，示例中正是用marginTop: 15实现的）；
平台差异阴影：Android 走elevation: 1（Material 阴影），iOS 与 Web 等平台走shadowColor: 'rgba(0,0,0,.2)'+shadowRadius: 1的浅投影。如果你在 Android 上发现卡片投影与 iOS 不一致，这是Platform.select的刻意设计；
双层容器：外层 View 负责边框、背景与阴影（对应containerStyle），内层 wrapper View 默认透明背景（对应wrapperStyle）。containerStyle控制"卡片外壳"，wrapperStyle控制"内容区域"，两者均可独立覆盖，且后传入的自定义样式会通过StyleSheet.flatten与默认样式合并；
主题接入：背景色与边框色均来自theme.colors（见默认主题），因此通过ThemeProvider修改colors.white、colors.grey5即可全局影响所有卡片外观，无需逐张覆盖；
displayName 约定：CardBase.displayName = 'Card'、各子组件如CardTitle.displayName = 'Card.Title'，这保证了开发工具（React DevTools）中的组件名清晰可读。

测试与验证

Card 组件在 packages/base/src/Card/tests/ 下配有单元测试与渲染快照（Card.test.tsx+Card.snap），覆盖了默认渲染、子组件挂载与样式输出等行为。你可以在仓库中查看这些测试来确认组件的实际输出结构，也可在packages/base目录下按 jest.config.ts 的配置运行测试套件进行验证。若你在自己的项目中覆盖样式后出现异常，可优先对照快照中的默认输出定位差异来源。

小结

Card 是 React Native Elements 中"结构大于设计"理念的典型代表：组件本身只做轻量的容器职责（默认边框、留白、平台化阴影），把内容组织完全交给Card.Title、Card.Divider、Card.Image、Card.FeaturedTitle、Card.FeaturedSubtitle五个透传型子组件，并预留containerStyle/wrapperStyle两个扩展点。掌握默认样式与双层结构后，无论是快速搭建信息卡片，还是打造图文封面式的高级卡片，都能做到心中有数。

相关资源：主文档 main/Card.md｜可运行示例 usage/Card/snack/index.md｜源码 packages/base/src/Card/｜后续版本示例 version-4.0.0-rc.1/component_usage/Card.mdx

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析