react-native-gifted-chat 全功能演示:基于 Expo Snack 的零配置快速上手指南
react-native-gifted-chat 全功能演示:基于 Expo Snack 的零配置快速上手指南
本指南围绕仓库 expoSnack/ 目录下的自包含示例展开:它把 react-native-gifted-chat 的文本气泡、富媒体消息、快捷回复、自定义操作按钮、附件栏、位置消息、暗色模式与"加载更早消息"等全部能力浓缩进一个单文件 ExpoSnack.tsx,可直接粘贴进 Expo Snack 在线运行,也可复制进本地 Expo 项目作为开发起点。读完本文,你将掌握该示例的完整依赖清单、运行步骤、操作方式与定制要点,并透过源码理解 GiftedChat 核心 props 与 append/prepend 等静态工具方法的真实行为。
一、这个示例是什么
expoSnack/ 目录是独立于主包之外的一个最小可运行示例,设计目标是用单个文件演示 react-native-gifted-chat 的全部核心能力,无需任何后端或本地编译环境即可体验。ExpoSnack.tsx 从导入 GiftedChat 组件与 IMessage、User 类型开始,构建了一个包含两位对话者("Developer" 与 "John Doe")的完整聊天界面。
该文件内部按清晰的区块组织(源码中以注释分隔):
- Helpers:
getColorSchemeStyle辅助函数,用于按系统深浅色主题挑选样式; - Data:
initialMessages初始消息与getEarlierMessages更早消息; - Media Utilities:
pickImageAsync、takePictureAsync、getLocationAsync三个媒体工具函数; - CustomView:位置消息的自定义渲染组件;
- CustomActions:带 action sheet 菜单的加号按钮组件;
- AccessoryBar:照片、相机、位置、打字指示四个快捷按钮组成的底部工具栏;
- ChatExample:核心聊天组件,负责状态管理与 props 注入;
- App:根组件,用
ActionSheetProvider包裹整个应用。
这个结构与 README 文档 中 "Code Structure" 一节列出的 8 个部分一一对应,是理解整个示例的最佳索引。
二、快速启动:两种运行方式
方式一:在 Expo Snack 中运行(推荐)
- 打开 https://snack.expo.dev,点击 "Create a new Snack";
- 将本仓库 ExpoSnack.tsx 的全部内容复制;
- 用复制内容替换 Snack 默认的
App.tsx; - 安装下方依赖清单中的全部依赖;
- 在模拟器或真机上运行。
方式二:复制进本地 Expo 项目
直接将 ExpoSnack.tsx 复制到你的 Expo 项目中,并确保以下依赖全部安装完成即可。两种方式的差异仅在于依赖安装途径,代码本身完全一致。
三、完整依赖清单与解析
示例依赖了 11 个 npm 包,ExpoSnack.tsx 的 import 语句(第 1-15 行)与之一一对应:
{
"dependencies": {
"react-native-gifted-chat": "*",
"react-native-gesture-handler": "*",
"react-native-safe-area-context": "*",
"react-native-reanimated": "*",
"@expo/react-native-action-sheet": "*",
"@expo/vector-icons": "*",
"expo-image-picker": "*",
"expo-location": "*",
"expo-linking": "*",
"react-native-maps": "*",
"dayjs": "*"
}
}
各依赖在示例中的实际用途:
| 依赖 | 在示例中的角色 | 对应源码位置 |
|---|---|---|
react-native-gifted-chat |
聊天界面主体,导出 GiftedChat 组件与 IMessage/User 类型 |
ExpoSnack.tsx#L14-L15 |
@expo/react-native-action-sheet |
ActionSheetProvider 全局包裹 + useActionSheet 弹出菜单 |
第 8 行、第 690 行 |
@expo/vector-icons |
附件栏四个按钮的 MaterialIcons 图标 | 第 9 行 |
expo-image-picker |
相册选图与相机拍照(权限申请 + 资源选择) | 第 11 行 |
expo-location |
前台定位权限申请与获取当前坐标 | 第 12 行 |
react-native-gesture-handler |
RectButton 作为可点击组件的基础 |
第 13 行 |
react-native-safe-area-context |
库内部 SafeAreaProvider 依赖(示例未直接 import) |
src/GiftedChat/index.tsx#L358 |
react-native-reanimated |
库内部动画列表 AnimatedList 依赖 |
src/GiftedChat/index.tsx#L27 |
expo-linking、react-native-maps |
官方示例常配套的链接与地图能力,生产项目接入时可替换为自定义实现 | 本示例中 CustomView 以纯文本卡片代替真实地图 |
dayjs |
生成相对时间戳(今天、昨天、一周前、一年前),并配合库内 dayjs 进行日期本地化 |
第 30-32 行 |
注意:react-native-gesture-handler、react-native-safe-area-context、react-native-reanimated 之所以必须安装,是因为库自身在渲染时依赖它们——从 src/GiftedChat/index.tsx 的导入与包装逻辑可以看到,GiftedChatWrapper 会自动用 GestureHandlerRootView 和 SafeAreaProvider 包裹聊天界面(第 356-372 行),内部还内建了 ActionSheetProvider(第 321-343 行)。
在 Expo Snack 中安装依赖时,点击左侧边栏的 "Dependencies" 标签,逐个搜索并添加上表依赖,等待安装完成即可。
四、示例演示了哪些功能
文档把功能划分为四类,而 initialMessages 数据(ExpoSnack.tsx#L34-L192)正是这些功能的"活标本":
核心功能
- 文本消息与气泡:每条消息的
text字段驱动MessageText渲染; - 用户头像与姓名:
user: { _id, name }结构(可扩展avatar字段),两端用户分别为_id: 1(Developer)与_id: 2(John Doe); - 消息时间戳:通过
createdAt字段驱动,示例用dayjs生成"今天/昨天/一周前"三个时间层级,便于观察日期分隔标签; - 打字指示器:
isTyping状态控制TypingIndicator显隐(见下文操作说明); - 加载更早消息:
loadEarlierMessagesProps配置模拟了 1.5 秒延迟的加载过程; - 暗色模式:
useColorScheme()联动全部容器、附件栏与输入框配色。
富媒体消息
IMessage 接口(src/Models.ts#L39-L58)定义了 image、video、audio、location 等可选字段,示例逐一演示:
- 图片消息:
image字段指向埃菲尔铁塔图片 URL(第 160-161 行); - 视频消息:
video字段为 GIF 视频地址(第 48 行); - 音频消息:
audio字段为 MP3 示例文件(第 38-39 行); - 位置消息:
location: { latitude, longitude }(示例为巴黎坐标,第 140-143 行)。
交互元素
- 快捷回复:两条消息分别演示
type: 'checkbox'(多选,不带keepIt)与type: 'radio'(单选,keepIt: true表示点选后保留选项),其类型定义见 src/Models.ts#L24-L28; - 自定义操作按钮(CustomActions):加号按钮弹出 action sheet,提供 "Choose From Library"、"Take Picture"、"Send Location"、"Cancel" 四个选项;
- 自定义附件栏(AccessoryBar):输入框下方的第二行工具栏,提供照片、相机、位置、打字指示四个快捷按钮。
自定义组件
- CustomActions:实现
GiftedChatProps中的renderActions接口(src/GiftedChat/types.ts#L136); - AccessoryBar:实现
renderAccessory接口(src/GiftedChat/types.ts#L140),挂在输入工具栏下方; - CustomView:实现
renderCustomView接口(src/GiftedChat/types.ts#L126),当消息带location字段时渲染位置卡片。示例中以"图标 + 经纬度文本"的形式代替真实地图,规避了react-native-maps在 Web 与部分模拟器上的兼容问题。
此外 getEarlierMessages(第 195-226 行)还包含一条 system: true 的系统消息,演示了 SystemMessage 组件的渲染路径。
五、如何操作:完整交互路径
文档给出的六条操作路径,其背后的状态流转如下:
发送消息:在底部文本输入框输入内容,点击发送按钮。ChatExample 的 onSend 回调(第 608-618 行)为消息补齐 _id 与 user 后,调用 GiftedChat.append(previousMessages, messagesWithIds) 更新列表。
添加图片:点击加号按钮选择 "Choose From Library"(相册)或 "Take Picture"(相机)。底层由 pickImageAsync / takePictureAsync 先请求权限,再调用 ImagePicker.launchImageLibraryAsync / launchCameraAsync(均开启 allowsEditing: true 与 aspect: [4, 3] 裁剪),最终把返回的 URI 组装成 IMessage 发送。
发送位置:点击附件栏的定位图标,getLocationAsync 先调用 requestForegroundPermissionsAsync 申请前台定位权限,再 getCurrentPositionAsync 取坐标,最终以 location 消息发送并由 CustomView 渲染。
加载更早消息:上滑到消息列表顶部,点击 "Load earlier messages"。onPressLoadEarlierMessages(第 620-626 行)先置 isLoadingEarlier 为 true,1.5 秒后调用 GiftedChat.prepend 把 getEarlierMessages() 的结果拼接到现有消息之前。这里的 1.5 秒延迟即文档所述的模拟加载过程,用于演示 loadEarlierMessagesProps.isLoading 的加载态效果。
快捷回复:滚动找到带快捷回复的消息,点击任意选项即可将其文本加入聊天。示例数据中的 checkbox 消息演示多选(选项保留在气泡内),radio 消息演示单选(keepIt: true 时点选后保留)。
切换打字指示器:点击附件栏的聊天气泡图标,触发 setIsTyping(isTyping => !isTyping),isTyping 状态传入 GiftedChat 的 isTyping prop 后,消息列表底部会显示/隐藏打字指示动画。
六、源码层面的实现原理
1. append 与 prepend:消息列表操作的核心
示例的发送与加载更早消息逻辑均依赖 GiftedChat 的静态方法,其实现位于 src/GiftedChat/index.tsx#L375-L399:
GiftedChatWrapper.append = (currentMessages = [], messages, isInverted = true) => {
return isInverted
? messages.concat(currentMessages) // 倒序列表:新消息在前
: currentMessages.concat(messages) // 正序列表:新消息在后
}
GiftedChatWrapper.prepend = (currentMessages = [], messages, isInverted = true) => {
return isInverted
? currentMessages.concat(messages) // 倒序列表:旧消息追加到尾部
: messages.concat(currentMessages)
}
由于聊天列表默认以 isInverted = true 倒序渲染(最新消息在底部、索引为 0),append 在倒序模式下必须把新消息拼在数组头部,prepend 则把更早的消息拼在数组尾部。示例中 onSend 与 onPressLoadEarlierMessages 直接调用这两个静态方法,这也是官方推荐的列表操作方式——切勿在倒序模式下自行用 [...prev, ...new] 追加,否则新消息会显示在错误的位置。
2. isTyping 与打字指示器
ChatExample 将 isTyping 布尔状态直接传给 GiftedChat(ExpoSnack.tsx#L657),而 src/GiftedChat/index.tsx#L162 会将其继续透传给 MessagesContainer,最终驱动内置的 TypingIndicator 组件显隐。这也解释了示例中"聊天图标切换打字指示"这一交互的实现链路。
3. 消息结构:IMessage 接口的完整形态
示例数据完整覆盖了 src/Models.ts#L39-L58 中 IMessage 接口的可选字段,是理解该接口的最佳参照:
export interface IMessage {
_id: string | number
text: string
createdAt: Date | number
user: User
image?: string
video?: string
audio?: string
system?: boolean
sent?: boolean
received?: boolean
pending?: boolean
quickReplies?: QuickReplies
replyMessage?: ReplyMessage
reactions?: MessageReaction[]
location?: { latitude: number; longitude: number }
}
注意示例消息中还使用了 sent: true、received: true 标记(如 第 120-121 行),用于区分消息的投递状态。示例在数据末尾统一通过 .map((message, index) => ({ ...message, _id: index + 1 })).reverse() 自动生成 _id 并转为倒序数组(第 189-192 行),省去了手工编号的麻烦。
七、定制指南
配色与主题
示例通过 useColorScheme() 自动适配设备深浅色模式,这是库内置能力(GiftedChat 的 colorScheme prop 默认为 undefined 即跟随系统,见 src/GiftedChat/types.ts#L51-L52)。文档展示了主题样式的核心写法,实际的 styles 对象 采用 xxx_dark 后缀约定:
const styles = StyleSheet.create({
container: { flex: 1, backgroundColor: '#fff' }, // 浅色背景
container_dark: { backgroundColor: '#000' }, // 深色背景
messagesContainer_dark: { backgroundColor: '#000' }, // 消息区深色
composer_dark: { backgroundColor: '#1a1a1a', color: '#fff' }, // 输入框深色
})
getColorSchemeStyle 辅助函数(第 21-24 行)按 ${baseName}_${colorScheme} 拼接键名取样式。CustomActions 的加号按钮、AccessoryBar 的工具栏也都遵循同样的 _dark 后缀模式(分别见 第 389-417 行 与 第 524-539 行)。
消息数据
initialMessages 数组(第 34-192 行)是修改演示内容的入口。文档给出的最小消息结构如下,注意 _id 必须唯一、createdAt 建议使用 new Date() 或 dayjs 生成:
const initialMessages: IMessage[] = [
{
_id: 1,
text: 'Your message here',
createdAt: new Date(),
user: {
_id: 2,
name: 'Bot Name',
},
},
// ... more messages
]
当前用户配置
user 对象通过 useMemo 定义(第 600-606 行),_id: 1 即"自己"的身份标识:
const user = useMemo(() => ({
_id: 1,
name: 'Developer',
}), [])
GiftedChat 会依据 user._id 判断消息归属并决定气泡的左右对齐。把 _id 换成你后端系统中的用户 ID 即可接入真实登录态。
八、平台支持情况
- iOS(模拟器与真机):完整支持,地图与媒体功能开箱即用;
- Android(模拟器与真机):完整支持,但地图渲染依赖 Google Play Services;
- Web:有限支持——地图与部分媒体功能可能无法正常工作(这也是示例
CustomView选择用文本卡片替代真实地图的原因之一)。
九、常见问题排查
权限问题(图片选择器 / 定位失效)
- 在设备设置中确认已授予相册、相机与定位权限;
- iOS 模拟器需要为定位服务设置自定义位置;
- Android 模拟器需开启位置服务。
依赖安装失败
- 刷新 Snack 页面;
- 清空浏览器缓存;
- 更换浏览器重试;
- 查看 Expo Snack 服务状态页确认是否为平台侧故障。
地图不显示
- 优先使用真机测试;
- Android 模拟器需启用 Google Play Services;
- iOS 模拟器地图默认可用。
十、进阶方向
文档建议在示例跑通后的六个进阶方向,与仓库自身的扩展能力高度对应:
- 定制样式:替换
styles对象、定制renderBubble/renderMessageText等渲染函数; - 接入真实后端:把
onSend与"加载更早消息"回调替换为 Firebase、Socket.io 等实时通道——库本身不绑定任何后端; - 新增自定义消息类型:通过
renderCustomView扩展任意消息形态,仓库的 example-expo/CustomView 目录展示了带真实地图的完整实现(含index.tsx、index.web.tsx与styles.ts); - 消息持久化:结合本地存储或服务端数据库保存消息流;
- 用户认证:将示例中的静态
user对象替换为登录态; - 推送通知:接入系统级推送服务。
此外,仓库 example-expo 与 example-gifted-chat、example-slack-message 目录分别提供了更贴近生产的示例(含自定义输入工具栏、Slack 风格气泡等),可作为 ExpoSnack.tsx 的下一步参考。
十一、已知限制与生产建议
在 Expo Snack 环境中运行时有以下限制:
- 上传文件大小受限;
- 部分原生模块可能不可用;
- 性能比本地应用慢;
- 网络请求可能受限。
因此对于生产应用,建议以本示例为起点,使用 Expo CLI 或 React Native CLI 在本地开发,将定位、地图等能力替换为完整实现。
十二、实用提示
- 尽量用真机测试:定位、相机、地图等功能在物理设备上表现最佳;
- 配合 Expo Go 使用:扫描 Snack 生成的二维码即可在手机端体验;
- 善用控制台:在 Expo Snack 界面打开控制台查看报错,媒体权限问题通常会在此暴露;
- 大胆实验:修改
initialMessages或styles后界面实时刷新,是学习GiftedChatprops 行为最直观的方式。
本示例基于 MIT 协议开源的 react-native-gifted-chat 构建,可自由复制、修改并用于你的项目中。