react-native-gifted-chat 全功能演示:基于 Expo Snack 的零配置快速上手指南

原创2026-09-21 20:17:051,417 阅读
文章标签:前端UI组件即时通讯

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")的完整聊天界面。

该文件内部按清晰的区块组织(源码中以注释分隔):

  1. Helpers:getColorSchemeStyle 辅助函数,用于按系统深浅色主题挑选样式;
  2. Data:initialMessages 初始消息与 getEarlierMessages 更早消息;
  3. Media Utilities:pickImageAsync、takePictureAsync、getLocationAsync 三个媒体工具函数;
  4. CustomView:位置消息的自定义渲染组件;
  5. CustomActions:带 action sheet 菜单的加号按钮组件;
  6. AccessoryBar:照片、相机、位置、打字指示四个快捷按钮组成的底部工具栏;
  7. ChatExample:核心聊天组件,负责状态管理与 props 注入;
  8. App:根组件,用 ActionSheetProvider 包裹整个应用。

这个结构与 README 文档 中 "Code Structure" 一节列出的 8 个部分一一对应,是理解整个示例的最佳索引。

二、快速启动:两种运行方式

方式一:在 Expo Snack 中运行(推荐)

  1. 打开 https://snack.expo.dev,点击 "Create a new Snack";
  2. 将本仓库 ExpoSnack.tsx 的全部内容复制;
  3. 用复制内容替换 Snack 默认的 App.tsx;
  4. 安装下方依赖清单中的全部依赖;
  5. 在模拟器或真机上运行。

方式二:复制进本地 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 选择用文本卡片替代真实地图的原因之一)。

九、常见问题排查

权限问题(图片选择器 / 定位失效)

  1. 在设备设置中确认已授予相册、相机与定位权限;
  2. iOS 模拟器需要为定位服务设置自定义位置;
  3. Android 模拟器需开启位置服务。

依赖安装失败

  1. 刷新 Snack 页面;
  2. 清空浏览器缓存;
  3. 更换浏览器重试;
  4. 查看 Expo Snack 服务状态页确认是否为平台侧故障。

地图不显示

  1. 优先使用真机测试;
  2. Android 模拟器需启用 Google Play Services;
  3. iOS 模拟器地图默认可用。

十、进阶方向

文档建议在示例跑通后的六个进阶方向,与仓库自身的扩展能力高度对应:

  1. 定制样式:替换 styles 对象、定制 renderBubble/renderMessageText 等渲染函数;
  2. 接入真实后端:把 onSend 与"加载更早消息"回调替换为 Firebase、Socket.io 等实时通道——库本身不绑定任何后端;
  3. 新增自定义消息类型:通过 renderCustomView 扩展任意消息形态,仓库的 example-expo/CustomView 目录展示了带真实地图的完整实现(含 index.tsx、index.web.tsx 与 styles.ts);
  4. 消息持久化:结合本地存储或服务端数据库保存消息流;
  5. 用户认证:将示例中的静态 user 对象替换为登录态;
  6. 推送通知:接入系统级推送服务。

此外,仓库 example-expo 与 example-gifted-chat、example-slack-message 目录分别提供了更贴近生产的示例(含自定义输入工具栏、Slack 风格气泡等),可作为 ExpoSnack.tsx 的下一步参考。

十一、已知限制与生产建议

在 Expo Snack 环境中运行时有以下限制:

  • 上传文件大小受限;
  • 部分原生模块可能不可用;
  • 性能比本地应用慢;
  • 网络请求可能受限。

因此对于生产应用,建议以本示例为起点,使用 Expo CLI 或 React Native CLI 在本地开发,将定位、地图等能力替换为完整实现。

十二、实用提示

  1. 尽量用真机测试:定位、相机、地图等功能在物理设备上表现最佳;
  2. 配合 Expo Go 使用:扫描 Snack 生成的二维码即可在手机端体验;
  3. 善用控制台:在 Expo Snack 界面打开控制台查看报错,媒体权限问题通常会在此暴露;
  4. 大胆实验:修改 initialMessages 或 styles 后界面实时刷新,是学习 GiftedChat props 行为最直观的方式。

本示例基于 MIT 协议开源的 react-native-gifted-chat 构建,可自由复制、修改并用于你的项目中。

登录后查看全文
react-native-gifted-chat