React Native Gifted Chat 全功能接入与深度定制指南
React Native Gifted Chat 全功能接入与深度定制指南
导读:本文以
react-native-gifted-chat官方 README 为主线,系统讲解这个 React Native 聊天 UI 库的完整接入流程:从环境要求、Expo / 裸 RN 项目的安装配置,到消息数据模型、全量 Props 参考、回复、表情反应、链接解析、消息状态等高级特性的实战用法。同时结合仓库源码(src/目录)与示例应用(example/目录)进行纵深验证,帮助读者在阅读后能够独立搭建一个可运行、可深度定制的聊天界面,并理解各配置项背后的实现原理。
项目概述与定位
react-native-gifted-chat 是目前 React Native 生态中功能最完整的聊天 UI 库之一,同时支持 iOS、Android 与 Web(react-native-web),并内置完整的 TypeScript 类型定义,与 Expo 兼容。官方将自身定位为 "The most complete chat UI for React Native & Web"。
它提供的开箱即用能力包括:
- 🎨 完全可定制:几乎所有组件都可以通过
renderXxx系列 Props 替换为自己的实现; - 📎 Composer Actions:在输入工具栏左侧附加图片、文件或自定义操作按钮;
- ↩️ 回复消息:滑动消息触发回复,带回复预览与消息引用(线程)效果;
- ⏮️ 加载更早消息:无限滚动与分页支持;
- 📋 复制到剪贴板:长按消息弹出复制操作;
- 🔗 智能链接解析:自动识别 URL、邮箱、电话、话题标签(hashtag)与 @ 提及(mention);
- 👤 头像:支持用户首字母或自定义头像图片;
- 🌍 本地化日期:基于 Day.js 的完整 i18n 支持;
- ⌨️ 键盘处理:基于 react-native-keyboard-controller 的跨平台智能避让;
- 💬 系统消息:在聊天流中插入系统通知;
- ⚡ 快捷回复:机器人风格的快捷回复按钮;
- 😀 表情反应:长按消息添加 emoji 反应,支持反应药丸与可选的全量表情浏览器;
- ✍️ 正在输入指示器:展示对方正在输入的状态;
- ✅ 消息状态:已发送 / 已送达 / 已读勾选标记;
- ⬇️ 回到底部按钮:快速回到最新消息;
- 🌐 Web 支持:与 react-native-web 配合使用;
- 📱 Expo 支持:与 Expo SDK 50+ 无缝集成;
- 📝 TypeScript:随库发布完整类型定义。
⚠️ 维护状态说明:根据 README 顶部的说明,本包目前已进入 维护模式(maintenance mode),不再接收新特性。开发工作已迁移到一个维护中的 fork(
@kesha-antonov/react-native-chat),新项目被建议优先使用该 fork,迁移成本主要是包名替换(fork 中提供迁移指南)。对于既有项目,本仓库仍持续获得修复与维护,可放心继续使用。
环境要求(Requirements)
在安装前,请确认项目满足以下版本要求:
| 依赖项 | 最低版本要求 |
|---|---|
| React Native | >= 0.70.0 |
| iOS | >= 13.4 |
| Android | API 21+(Android 5.0) |
| Expo | SDK 50+ |
| TypeScript | >= 5.0(可选) |
安装指南
react-native-gifted-chat 有四个必需的运行时依赖,其中 react-native-reanimated 与 react-native-gesture-handler 承担滑动回复、表情反应选择器等动画与手势能力,react-native-safe-area-context 提供安全区 insets,react-native-keyboard-controller 负责键盘避让。
Expo 项目
npx expo install react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
npx expo install 会自动选取与当前 Expo SDK 兼容的版本,是 Expo 项目最稳妥的安装方式。
裸 React Native 项目
Step 1:安装依赖包
使用 yarn:
yarn add react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
使用 npm:
npm install --save react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
Step 2:安装 iOS Pods
npx pod-install
Step 3:配置 react-native-reanimated
按照 react-native-reanimated 官方安装指南,在 Babel 配置中(babel.config.cjs)添加其 Babel 插件:
module.exports = {
presets: ['babel-preset-expo'],
plugins: ['react-native-reanimated/plugin'],
}
注意:Reanimated 的 Babel 插件必须放在插件列表的最后一位。
快速开始:最小可用聊天界面
安装完成后,下面的代码即可渲染一个功能完整的聊天界面:
import React, { useState, useCallback, useEffect } from 'react'
import { GiftedChat } from 'react-native-gifted-chat'
import { useHeaderHeight } from '@react-navigation/elements'
export function Example() {
const [messages, setMessages] = useState([])
// keyboardVerticalOffset = 从屏幕顶部到 GiftedChat 容器的距离
// useHeaderHeight() 返回状态栏 + 导航栏高度之和
const headerHeight = useHeaderHeight()
useEffect(() => {
setMessages([
{
_id: 1,
text: 'Hello developer',
createdAt: new Date(),
user: {
_id: 2,
name: 'John Doe',
avatar: 'https://placeimg.com/140/140/any',
},
},
])
}, [])
const onSend = useCallback((messages = []) => {
setMessages(previousMessages =>
GiftedChat.append(previousMessages, messages),
)
}, [])
return (
<GiftedChat
messages={messages}
onSend={messages => onSend(messages)}
user={{
_id: 1,
}}
keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight }}
/>
)
}
💡 提示:仓库的
example目录下有更多完整示例,包括 Slack 风格消息、快捷回复、自定义组件等,可直接作为开发参考。
GiftedChat.append(previousMessages, messages) 是一个静态工具方法,负责把新消息插入到消息数组的前端(因为列表默认采用倒序渲染,isInverted 默认 true)。
消息数据模型(Data Structure)
消息、系统消息与快捷回复的数据结构统一由 src/Models.ts 定义。完整的消息对象结构如下:
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
}
interface User {
_id: string | number
name?: string
avatar?: string | number | (() => React.ReactNode)
}
对照 src/Models.ts 的源码,IMessage 还包含以下可选高级字段(README 中亦有相应章节展开):
replyMessage?: ReplyMessage:消息引用的被回复消息(_id、text、user、audio、image五个字段,见 src/Models.ts);reactions?: MessageReaction<a href="https://link.gitcode.com/i/e6aba565bbf28aa43214f9d7126c43bd" target="_blank">]:消息上的表情反应,结构为{ emoji: string, userIds: (string | number)[] }(见 [src/Models.ts);location?: { latitude, longitude }:消息附带的地理位置。
快捷回复(QuickReplies)的结构为:
interface QuickReplies {
type: 'radio' | 'checkbox'
values: Reply[]
keepIt?: boolean
}
Props 参考:全量配置速查
所有 Props 的 TypeScript 签名定义在 src/GiftedChat/types.ts 中,GiftedChat 组件本身是泛型组件(GiftedChat<TMessage extends IMessage>),下文按模块分组介绍。
核心配置(Core Configuration)
| Prop | 类型 | 说明 |
|---|---|---|
messages |
Array | 要展示的消息数组 |
user |
Object | 当前发送消息的用户:{ _id, name, avatar } |
onSend |
Function | 发送消息时的回调 |
messageIdGenerator |
Function | 为新消息生成 id。默认是一个简单随机字符串生成器 |
locale |
String | 日期本地化语言。使用前需先导入对应 locale,如 require('dayjs/locale/de') 或 import 'dayjs/locale/fr' |
colorScheme |
'light' | 'dark' | 强制明/暗色模式。设置后覆盖系统配色;undefined 时跟随系统。默认 undefined |
关于 messageIdGenerator 的默认实现,src/GiftedChat/index.tsx 中可以看到源码使用的是 (Math.random() + 1).toString(36).substring(7),并注释说明:刻意不引入 uuid,以避免额外增加原生依赖;库的使用者可以自行传入任意算法(如基于数据库自增 id 或 UUID)覆盖。locale 默认值为 'en'。
Refs
| Prop | 类型 | 说明 |
|---|---|---|
messagesContainerRef |
FlatList ref | 指向消息列表的 ref |
textInputRef |
TextInput ref | 指向文本输入框的 ref |
键盘与布局(Keyboard & Layout)
| Prop | 类型 | 说明 |
|---|---|---|
keyboardProviderProps |
Object | 透传给 KeyboardProvider 的 Props。默认值:statusBarTranslucent: true(Android 状态栏半透明 / edge-to-edge 模式下正确计算键盘高度所必需)、navigationBarTranslucent: true(导航栏同理) |
disableKeyboardProvider |
Bool | 跳过内置的 KeyboardProvider 包装;默认 false。当你的应用已在根部挂载自己的 KeyboardProvider,或默认 edge-to-edge 行为在 Android/Expo 上引起布局位移、挂载闪烁、头部跳动时,开启此选项 |
keyboardAvoidingViewProps |
Object | 透传给 KeyboardAvoidingView 的 Props,配合 keyboardVerticalOffset 正确处理键盘 |
isAlignedTop |
Boolean | 消息气泡是否从聊天顶部开始排列(默认 false,气泡底部对齐) |
isInverted |
Bool | 反转 messages 的显示顺序;默认 true |
深入理解 keyboardVerticalOffset
keyboardVerticalOffset 告诉 KeyboardAvoidingView 它的容器相对屏幕顶部从何处开始。当 GiftedChat 不在屏幕最顶端(例如存在导航栏)时,这一配置是必需的。
- 默认值:
insets.top(来自useSafeAreaInsets()的状态栏高度)。该默认值只有在 GiftedChat 全屏填充、没有导航栏时才正确。 - 值的含义:偏移量等于从屏幕顶部到 GiftedChat 容器顶部的距离(pt),通常包含:
- 状态栏高度;
- 导航栏高度(iOS 上
useHeaderHeight()已包含状态栏)。
- 使用方法:
import { useHeaderHeight } from '@react-navigation/elements'
function ChatScreen() {
// iOS 上 useHeaderHeight() 返回状态栏 + 导航栏高度
const headerHeight = useHeaderHeight()
return (
<GiftedChat
keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight }}
// ... 其他 props
/>
)
}
注意:
useHeaderHeight()要求聊天组件渲染在真正的导航 Screen 内(而非条件渲染)。如果它返回0,请确认聊天页是带可见 header 的真实导航页面。
为什么重要:偏移量不正确时,键盘会遮挡输入框或留下多余空白——
KeyboardAvoidingView正是依靠这个值来计算键盘弹出时内容需要上移多少。
使用自己的 KeyboardProvider
默认情况下 GiftedChat 会用一个启用了 statusBarTranslucent 与 navigationBarTranslucent 的 KeyboardProvider 包裹自身。在某些 Android/Expo(edge-to-edge)环境中,这可能造成屏幕整体下移、挂载时闪烁、或导航栏变形——尤其是树上已经存在另一个 KeyboardProvider 时。
设置 disableKeyboardProvider 即可跳过内置包装:
import { KeyboardProvider } from 'react-native-keyboard-controller'
// 在应用根部只挂载一个 KeyboardProvider
function App() {
return (
<KeyboardProvider>
{/* ...导航/页面... */}
</KeyboardProvider>
)
}
function ChatScreen() {
return (
<GiftedChat
disableKeyboardProvider
// ... 其他 props
/>
)
}
重要:GiftedChat 的键盘避让依赖树中存在
KeyboardProvider。设置disableKeyboardProvider后,你必须在 GiftedChat 上方自行挂载KeyboardProvider,否则键盘会遮挡输入框。全局只挂载一个 provider(你自己的),正是为了避免双重 edge-to-edge 位移。
文本输入与输入工具栏(Text Input & Composer)
| Prop | 类型 | 说明 |
|---|---|---|
text |
String | 输入文本;默认 undefined。一旦指定,将覆盖 GiftedChat 内部状态,适合用 Redux 等外部管理文本状态。别忘了在 textInputProps.onChangeText 中同步更新文本状态 |
initialText |
String | 输入框的初始文本 |
isSendButtonAlwaysVisible |
Bool | 是否始终显示发送按钮;默认 false(仅在输入非空时显示) |
isTextOptional |
Bool | 允许发送无文本消息(适合纯媒体消息);默认 false。配合 isSendButtonAlwaysVisible 可用于媒体附件场景 |
minComposerHeight |
Object | Composer 的最小高度 |
maxComposerHeight |
Object | Composer 的最大高度 |
minInputToolbarHeight |
Integer | 输入工具栏最小高度;默认 44 |
renderInputToolbar |
Component | Function | 自定义消息输入容器 |
renderComposer |
Component | Function | 自定义文本输入 Composer |
renderSend |
Component | Function | 自定义发送按钮;可直接给原 Send 组件传 children 实现自定义图标 |
renderActions |
Component | Function | 消息 Composer 左侧的自定义操作按钮 |
renderAccessory |
Component | Function | Composer 下方的自定义第二行操作 |
textInputProps |
Object | 透传给 <TextInput> 的 Props |
在 src/GiftedChat/index.tsx 中可以看到 _onChangeText 的实现逻辑:它总是调用用户传入的 textInputProps.onChangeText 转发事件,并且只有当 props.text 为 undefined(非受控)时才更新内部状态,这与"text 是受控 prop"的语义完全一致。发送流程(_onSend,见 src/GiftedChat/index.tsx)会自动为新消息补充 createdAt: new Date()、生成的 _id、当前 user,并在存在回复消息时附加 replyMessage,发送完成后自动清空输入框并滚动到底部。
Actions 与 Action Sheet
| Prop | 类型 | 说明 |
|---|---|---|
onPressActionButton |
Function | 点击 Action 按钮时的回调(设置后默认的 actionSheet 将不再使用) |
actionSheet |
Function | 自定义展示操作选项的 action sheet 接口 |
actions |
Array | 输入工具栏操作按钮的自定义操作项:{ title: string, action: () => void }[] |
actionSheetOptionTintColor |
String | Action sheet 选项的 tint 颜色 |
消息与消息容器(Messages & Message Container)
| Prop | 类型 | 说明 |
|---|---|---|
messagesContainerStyle |
Object | 消息容器自定义样式 |
renderMessage |
Component | Function | 自定义单条消息容器 |
renderLoading |
Component | Function | 初始化时的加载视图 |
renderChatEmpty |
Component | Function | 消息列表为空时渲染的自定义组件 |
renderChatFooter |
Component | Function | 渲染在 MessagesContainer 下方(独立于 ListView)的自定义组件 |
listProps |
Object | 透传给消息 <FlatList> 的额外 Props,支持全部 FlatList 属性,包括用于 AI 聊天机器人场景的 maintainVisibleContentPosition |
消息气泡与内容(Message Bubbles & Content)
| Prop | 类型 | 说明 |
|---|---|---|
renderBubble |
Component | Function(props: BubbleProps) |
自定义消息气泡。接收 src/Bubble/types.ts 中定义的 BubbleProps |
renderMessageText |
Component | Function | 自定义消息文本 |
renderMessageImage |
Component | Function | 自定义消息图片 |
renderMessageVideo |
Component | Function | 自定义消息视频 |
renderMessageAudio |
Component | Function | 自定义消息音频 |
renderCustomView |
Component | Function | 气泡内部的自定义视图 |
isCustomViewBottom |
Bool | renderCustomView 是否在文本、图片、视频视图之后展示;默认 false |
onPressMessage |
Function(context, message) |
点击消息气泡的回调 |
onLongPressMessage |
Function(context, message) |
长按消息气泡的回调;可在此弹出 action sheet(如复制、删除、回复) |
imageProps |
Object | 透传给默认 renderMessageImage 创建的 <Image> 的额外 Props |
imageStyle |
Object | 消息图片的自定义样式 |
videoProps |
Object | 透传给必需的 renderMessageVideo 所创建视频组件的额外 Props |
messageTextProps |
Object | 透传给 MessageText 组件的额外 Props,用于定制链接解析行为、文本样式与 matchers |
messageTextProps 支持的子属性包括:
| 子属性 | 说明 |
|---|---|
matchers |
自定义链接匹配器(URL、电话、hashtag、mention 等) |
linkStyle |
链接的自定义样式 |
email |
是否解析邮箱(默认 true) |
phone |
是否解析电话号码(默认 true) |
url |
是否解析 URL(默认 true) |
hashtag |
是否解析 hashtag(默认 false) |
mention |
是否解析 @ 提及(默认 false) |
hashtagUrl |
hashtag 的基础 URL(如 'https://x.com/hashtag') |
mentionUrl |
mention 的基础 URL(如 'https://x.com') |
stripPrefix |
显示链接时是否去掉 http:// / https:// 前缀(默认 false) |
TextComponent |
自定义用于渲染的 Text 组件(如来自 react-native-gesture-handler 的 TextInput 场景) |
自定义 matchers 的完整示例:
<GiftedChat
messageTextProps={{
phone: false, // 关闭默认的电话号码链接
matchers: [
{
type: 'phone',
pattern: /\+?[1-9][0-9\-\(\) ]{7,}[0-9]/g,
getLinkUrl: (replacerArgs: ReplacerArgs): string => {
return replacerArgs[0].replace(/[\-\(\) ]/g, '')
},
getLinkText: (replacerArgs: ReplacerArgs): string => {
return replacerArgs[0]
},
style: styles.linkStyle,
onPress: (match: CustomMatch) => {
const url = match.getAnchorHref()
const options: {
title: string
action?: () => void
}[] = [
{ title: 'Copy', action: () => setStringAsync(url) },
{ title: 'Call', action: () => Linking.openURL(`tel:${url}`) },
{ title: 'Send SMS', action: () => Linking.openURL(`sms:${url}`) },
{ title: 'Cancel' },
]
showActionSheetWithOptions({
options: options.map(o => o.title),
cancelButtonIndex: options.length - 1,
}, (buttonIndex?: number) => {
if (buttonIndex === undefined)
return
const option = options[buttonIndex]
option.action?.()
})
},
},
],
linkStyle: { left: { color: 'blue' }, right: { color: 'lightblue' } },
}}
/>
完整示例参见 example/components/chat-examples/LinksExample.tsx。
头像(Avatars)
| Prop | 类型 | 说明 |
|---|---|---|
renderAvatar |
Component | Function | 自定义消息头像;设为 null 则不渲染任何头像 |
isUserAvatarVisible |
Bool | 是否为当前用户渲染头像;默认 false,只显示其他用户的头像 |
isAvatarVisibleForEveryMessage |
Bool | 为 false 时,仅在连续消息来自同一用户且同一天时显示头像;默认 false |
onPressAvatar |
Function(user) |
点击消息头像的回调 |
onLongPressAvatar |
Function(user) |
长按消息头像的回调 |
isAvatarOnTop |
Bool | 在连续消息顶部(而非底部)渲染头像;默认 false |
用户名(Username)
| Prop | 类型 | 说明 |
|---|---|---|
isUsernameVisible |
Bool | 是否在消息气泡内展示用户名;默认 false |
renderUsername |
Component | Function | 自定义用户名容器 |
日期与时间(Date & Time)
| Prop | 类型 | 说明 |
|---|---|---|
timeFormat |
String | 时间的渲染格式;默认 'LT'(Day.js Format) |
dateFormat |
String | 日期的渲染格式;默认 'D MMMM'(Day.js Format) |
dateFormatCalendar |
Object | 相对时间的渲染格式;默认 { sameDay: '[Today]' }(Day.js Calendar 插件) |
renderDay |
Component | Function | 自定义消息上方的日期分隔。同一函数同时负责内联日期分隔与"悬浮/带动画的吸顶日期头";读取 props.isAnimated(true 为悬浮头,false 为内联分隔)可分别定制外观 |
dayProps |
Object | 透传给 Day 组件的 Props:containerStyle、wrapperStyle、textProps(如 style、allowFontScaling、numberOfLines) |
renderTime |
Component | Function | 消息内的时间自定义渲染 |
timeTextStyle |
Object | 消息内时间的文本样式(支持 left/right 两侧) |
isDayAnimationEnabled |
Bool | 是否启用滚动时出现的动画日期标签;默认 true |
常量 DATE_FORMAT = 'D MMMM' 与 TIME_FORMAT = 'LT' 定义在 src/Constant.ts 中,与上述默认值一一对应。动画日期头的详细规格可参考仓库内的 docs/DAY_ANIMATED_SPEC.md 与实现 src/MessagesContainer/components/DayAnimated/index.tsx。
系统消息(System Messages)
| Prop | 类型 | 说明 |
|---|---|---|
renderSystemMessage |
Component | Function | 自定义系统消息 |
加载更早消息(Load Earlier Messages)
| Prop | 类型 | 说明 |
|---|---|---|
loadEarlierMessagesProps |
Object | 透传给 LoadEarlierMessages 组件的 Props,按钮仅在 isAvailable 为 true 时可见 |
loadEarlierMessagesProps 支持的子属性:
| 子属性 | 说明 |
|---|---|
isAvailable |
控制按钮可见性(默认 false) |
onPress |
点击按钮的回调 |
isLoading |
显示加载指示器(默认 false) |
isInfiniteScrollEnabled |
启用滚到消息顶部时自动触发 onPress 的无限滚动(Web 暂不支持) |
label |
覆盖默认的 "Load earlier messages" 文本 |
containerStyle |
按钮容器样式 |
wrapperStyle |
按钮 wrapper 样式 |
textStyle |
按钮文本样式 |
activityIndicatorStyle |
加载指示器样式 |
activityIndicatorColor |
加载指示器颜色(默认 'white') |
activityIndicatorSize |
加载指示器大小(默认 'small') |
对照 src/LoadEarlierMessages.tsx 源码可以看到这些默认值(label = 'Load earlier messages'、activityIndicatorColor = 'white'、activityIndicatorSize = 'small')的真实落点,加载期间按钮会通过 enabled={!isLoading} 禁用并显示 ActivityIndicator,同时声明了 accessibilityRole='button' 以保证无障碍语义。
Typing Indicator(正在输入指示器)
| Prop | 类型 | 说明 |
|---|---|---|
isTyping |
Bool | 正在输入状态;默认 false。如果使用 renderFooter 会覆盖此行为 |
renderTypingIndicator |
Component | Function | 自定义正在输入指示器 |
typingIndicatorStyle |
StyleProp<ViewStyle> | TypingIndicator 组件的自定义样式 |
renderFooter |
Component | Function | ListView 底部的自定义 footer 组件(例如 "User is typing...")。使用后覆盖 isTyping 触发的默认指示器 |
快捷回复(Quick Replies)
快捷回复的消息数据示例见 example/example-expo/data/messages.ts。
| Prop | 类型 | 说明 |
|---|---|---|
onQuickReply |
Function | 发送快捷回复时的回调(用于通知后端) |
renderQuickReplies |
Function | 自定义整个快捷回复视图 |
quickReplyStyle |
StyleProp<ViewStyle> | 快捷回复视图样式 |
quickReplyTextStyle |
StyleProp<TextStyle> | 快捷回复按钮文本样式 |
quickReplyContainerStyle |
StyleProp<ViewStyle> | 快捷回复容器样式 |
renderQuickReplySend |
Function | 自定义快捷回复的 发送 视图 |
深度功能实战
↩️ 回复消息(Reply to Messages)
Gifted Chat 开箱即用地支持滑动回复:用户滑动消息即可回复,输入工具栏会显示回复预览,新消息气泡上方会展示被回复的消息。
注意:该功能使用
react-native-gesture-handler的ReanimatedSwipeable与react-native-reanimated实现流畅的动画效果。
基本用法
<GiftedChat
messages={messages}
onSend={onSend}
user={{ _id: 1 }}
reply={{
swipe: {
isEnabled: true,
direction: 'left', // 左滑回复
},
}}
/>
Reply Props(分组结构)
reply prop 接受一个对象,结构定义在 src/Reply/types.ts:
interface ReplyProps<TMessage> {
// 滑动手势配置
swipe?: {
isEnabled?: boolean // 启用滑动回复;默认 false
direction?: 'left' | 'right' // 滑动方向;默认 'left'
onSwipe?: (message: TMessage) => void // 滑动触发后的回调
renderAction?: ( // 自定义滑动操作组件
progress: SharedValue<number>,
translation: SharedValue<number>,
position: 'left' | 'right'
) => React.ReactNode
actionContainerStyle?: StyleProp<ViewStyle>
}
// 回复预览样式(输入工具栏上方)
previewStyle?: {
containerStyle?: StyleProp<ViewStyle>
textStyle?: StyleProp<TextStyle>
imageStyle?: StyleProp<ImageStyle>
}
// 气泡内回复引用样式
messageStyle?: {
containerStyle?: StyleProp<ViewStyle>
containerStyleLeft?: StyleProp<ViewStyle>
containerStyleRight?: StyleProp<ViewStyle>
textStyle?: StyleProp<TextStyle>
textStyleLeft?: StyleProp<TextStyle>
textStyleRight?: StyleProp<TextStyle>
imageStyle?: StyleProp<ImageStyle>
}
// 回调与状态
message?: ReplyMessage // 受控的回复状态
onClear?: () => void // 回复被清除时调用
onPress?: (message: TMessage) => void // 点击回复预览时调用
// 自定义渲染
renderPreview?: (props: ReplyPreviewProps) => React.ReactNode
renderMessageReply?: (props: MessageReplyProps) => React.ReactNode
}
ReplyMessage 结构
当消息包含回复时,它会携带 replyMessage 属性:
interface ReplyMessage {
_id: string | number
text: string
user: User
image?: string
audio?: string
}
(源码定义见 src/Models.ts:ReplyMessage extends Pick<IMessage, '_id' | 'text' | 'user' | 'audio' | 'image'>。)
结合外部状态的高级示例
const [replyMessage, setReplyMessage] = useState<ReplyMessage | null>(null)
<GiftedChat
messages={messages}
onSend={messages => {
const newMessages = messages.map(msg => ({
...msg,
replyMessage: replyMessage || undefined,
}))
setMessages(prev => GiftedChat.append(prev, newMessages))
setReplyMessage(null)
}}
user={{ _id: 1 }}
reply={{
swipe: {
isEnabled: true,
direction: 'right',
onSwipe: setReplyMessage,
},
message: replyMessage,
onClear: () => setReplyMessage(null),
onPress: (msg) => scrollToMessage(msg._id),
}}
/>
从 src/GiftedChat/index.tsx 的源码可以看到,回复状态支持受控/非受控两种模式:当 reply.message prop 为 undefined 时,组件内部用 internalReplyMessage 自行管理状态(非受控);一旦传入 reply.message 则完全由外部控制,onSwipe 回调里也只做转发。
平滑动画
回复预览会自动动画:
- 出现时:从零高度平滑展开并伴随淡入效果;
- 消失时:平滑收起并伴随淡出效果;
- 内容变化时:切换到回复另一条消息时平滑过渡。
这些动画基于 react-native-reanimated 实现,可达到 60fps 性能。
⬇️ 回到底部(Scroll to Bottom)
| Prop | 类型 | 说明 |
|---|---|---|
isScrollToBottomEnabled |
Bool | 启用回到底部组件(默认 false) |
scrollToBottomComponent |
Function | 自定义回到底部组件容器 |
scrollToBottomOffset |
Integer | 开始显示回到底部组件的偏移阈值(默认 200) |
scrollToBottomStyle |
Object | 回到底部 wrapper 样式(position、bottom、right 等) |
scrollToBottomContentStyle |
Object | 回到底部内容样式(尺寸、背景、阴影等) |
🤖 保持滚动位置(AI 聊天机器人场景)
在 AI 聊天界面中,长回复到达时不应打断用户的阅读位置。通过 listProps 使用 maintainVisibleContentPosition:
// 基础用法 - 始终维持滚动位置
<GiftedChat
listProps={{
maintainVisibleContentPosition: {
minIndexForVisible: 0,
},
}}
/>
// 带自动滚动阈值 - 距离最新内容 10 像素内时自动滚动
<GiftedChat
listProps={{
maintainVisibleContentPosition: {
minIndexForVisible: 0,
autoscrollToTopThreshold: 10,
},
}}
/>
// 根据滚动状态条件启用(推荐用于聊天机器人)
const [isScrolledUp, setIsScrolledUp] = useState(false)
<GiftedChat
listProps={{
onScroll: (event) => {
setIsScrolledUp(event.contentOffset.y > 50)
},
maintainVisibleContentPosition: isScrolledUp
? { minIndexForVisible: 0, autoscrollToTopThreshold: 10 }
: undefined,
}}
/>
😀 Emoji 表情反应(Emoji Reactions)
长按消息可打开快速表情选择器;选中的反应以药丸(pill)形式展示在气泡下方,点击可切换开关。核心库自带轻量级快速选择器(基于 react-native-gesture-handler 与 react-native-reanimated,无额外依赖);完整表情浏览器是可选项,示例应用中通过 renderReactionPicker 覆盖实现。
(仓库 media 目录中的 reactions-picker.png 与 reactions-pills.png 展示了上述两个界面的真实效果。)
反应状态存放在每条消息的 reactions 数组上,启用该功能并处理 toggle 即可。反应状态由你(业务方)持有,因此可以适配任意后端:
interface IChatMessage extends IMessage {
reactions?: MessageReaction[] // { emoji: string, userIds: (string | number)[] }[]
}
const CURRENT_USER_ID = 1
const handleReactionPress = useCallback((message: IChatMessage, emoji: string) => {
setMessages(prev =>
prev.map(m => {
if (m._id !== message._id)
return m
const existing = (m.reactions ?? []).find(r => r.emoji === emoji)
if (!existing)
return { ...m, reactions: [...(m.reactions ?? []), { emoji, userIds: [CURRENT_USER_ID] }] }
const userIds = existing.userIds.includes(CURRENT_USER_ID)
? existing.userIds.filter(id => id !== CURRENT_USER_ID)
: [...existing.userIds, CURRENT_USER_ID]
return {
...m,
reactions: userIds.length === 0
? (m.reactions ?? []).filter(r => r.emoji !== emoji)
: (m.reactions ?? []).map(r => (r.emoji === emoji ? { ...r, userIds } : r)),
}
})
)
}, [])
<GiftedChat
messages={messages}
onSend={onSend}
user={{ _id: CURRENT_USER_ID }}
reactions={{
isEnabled: true,
onReactionPress: handleReactionPress,
// 可选:提供更丰富的选择器(如全量表情浏览器)。
// 参见 example/components/chat-examples/ReactionsExample.tsx
// renderReactionPicker: props => <MyEmojiPicker {...props} />,
}}
/>
完整示例见 example/components/chat-examples/ReactionsExample.tsx。
Reactions Props(分组结构)
reactions prop 的类型定义在 src/Reactions/types.ts:
| Prop | 说明 |
|---|---|
isEnabled |
启用表情反应(默认 false) |
emojis |
快速选择器中展示的表情(默认 ['👍', '❤️', '😂', '😮', '😢', '👎']) |
onReactionPress |
(message, emoji) => void,选中表情或点击药丸时调用。toggle 逻辑由你实现 |
renderReactions |
覆盖气泡下方反应展示组件 |
renderReactionPicker |
覆盖长按弹出的选择器(用于接入全量表情浏览器) |
containerStyle / reactionStyle / reactionActiveStyle / reactionTextStyle / reactionCountStyle |
反应药丸相关样式 |
pickerContainerStyle / pickerEmojiStyle |
快速选择器样式 |
默认表情列表以常量 DEFAULT_REACTION_EMOJIS 的形式定义在 src/Reactions/index.ts 中。类型层面,选择器组件接收的 ReactionPickerProps 还包含 visible、pageX、pageY、bubbleWidth、bubbleHeight 等几何信息(见 src/Reactions/types.ts),方便自定义选择器在气泡附近精确定位。
🔗 智能链接解析(Smart Link Parsing)
消息文本会自动扫描 URL、邮箱与电话号码;hashtag 与 @ 提及默认关闭、按需开启。通过 messageTextProps 配置:
<GiftedChat
messageTextProps={{
url: true, // 默认 true
email: true, // 默认 true
phone: true, // 默认 true
hashtag: true, // 默认 false
mention: true, // 默认 false
hashtagUrl: 'https://example.com/hashtag',
mentionUrl: 'https://example.com',
linkStyle: { left: { color: '#1d9bf0' }, right: { color: '#fff' } },
onPress: (message, url, type) => {
// type: 'url' | 'email' | 'phone' | 'mention' | 'hashtag'
Linking.openURL(url)
},
}}
/>
底层实现:链接解析逻辑集中在 src/linkParser.tsx。源码定义了 DEFAULT_MATCHERS 数组(src/linkParser.tsx),为五种类型提供了默认正则与 URL 转换规则:
- url:匹配
https?://、www.前缀与裸域名;非http(s)开头的自动补全为http://前缀; - email:标准邮箱正则,生成
mailto:链接; - phone:宽松的电话号码正则,去除空格/括号/连字符后生成
tel:链接; - hashtag:匹配
#[\w]+,可配合hashtagUrl拼出完整跳转地址; - mention:匹配
@[\w-]+,可配合mentionUrl拼出完整跳转地址。
解析流程(parseLinks,src/linkParser.tsx)遍历每个 matcher 收集全部命中,按索引排序后用 removeOverlaps 去重重叠区间,保证同一段文本不会被多个规则重复包裹。需要完全控制时,可传入自定义 matchers({ type, pattern, getLinkUrl?, getLinkText?, renderLink?, onPress? }[])来新增或覆盖规则,详见 example/components/chat-examples/LinksExample.tsx。
📋 复制到剪贴板(Copy to Clipboard)
长按处理通过 onLongPressMessage 暴露。GiftedChat 内部封装了 @expo/react-native-action-sheet,因此你可以弹出 "Copy Text" 操作并配合任意剪贴板库完成复制:
import { useActionSheet } from '@expo/react-native-action-sheet'
import { setStringAsync } from 'expo-clipboard'
const { showActionSheetWithOptions } = useActionSheet()
<GiftedChat
onLongPressMessage={(_context, message) => {
showActionSheetWithOptions(
{ options: ['Copy Text', 'Cancel'], cancelButtonIndex: 1 },
buttonIndex => {
if (buttonIndex === 0)
setStringAsync(message.text)
}
)
}}
/>
✅ 消息状态(Message Status)
为消息设置 sent、received 或 pending 即可展示投递状态。默认情况下它们以勾选标记渲染在时间戳旁边(✓ 已发送、✓✓ 已送达、🕓 发送中):
const message: IMessage = {
_id: 1,
text: 'Delivered!',
createdAt: new Date(),
user: { _id: 1 },
sent: true,
received: true,
}
使用 renderTicks(整体覆盖)或 tickStyle(仅样式)定制指示器:
<GiftedChat
renderTicks={message => (message.received ? <MyReadIcon /> : null)}
tickStyle={{ color: '#1d9bf0' }}
/>
📝 TypeScript:端到端类型安全
GiftedChat 随库发布完整类型定义,并且泛型化于你的消息类型。扩展 IMessage 添加自定义字段后,全程保持类型推导:
import { GiftedChat, IMessage } from 'react-native-gifted-chat'
interface MyMessage extends IMessage {
reactions?: { emoji: string, userIds: (string | number)[] }[]
}
<GiftedChat<MyMessage>
messages={messages}
onSend={msgs => {/* msgs 被推导为 MyMessage[] */}
user={{ _id: 1 }}
/>
onSend 中 msgs 的静态类型将自动是 MyMessage<a href="https://link.gitcode.com/i/805daf4b2512705e02dee27c91b16a9b" target="_blank">],自定义字段在消息构造、渲染回调(如 renderBubble、onPressMessage)中都能获得完整补全。所有公共组件(Bubble、MessageText、InputToolbar、Send、Time、Day 等)也从 [src/index.ts 统一导出,方便组合复用。
📱 平台注意事项
Android:键盘配置
如果使用 Create React Native App / Expo,无需额外的 Android 配置。否则建议修改项目配置:
确保 AndroidManifest.xml 中有 android:windowSoftInputMode="adjustResize":
<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:windowSoftInputMode="adjustResize"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
对于 Expo,可以在 GiftedChat 之后追加 KeyboardAvoidingView(仅 Android):
<View style={{ flex: 1 }}>
<GiftedChat />
{Platform.OS === 'android' && <KeyboardAvoidingView behavior="padding" />}
</View>
🌐 Web(react-native-web)
配合 create-react-app 使用时:
- 安装 react-app-rewired:
yarn add -D react-app-rewired - 创建
config-overrides.js:
module.exports = function override(config, env) {
config.module.rules.push({
test: /\.js$/,
exclude: /node_modules/\\/,
use: {
loader: 'babel-loader',
options: {
babelrc: false,
configFile: false,
presets: [
['@babel/preset-env', { useBuiltIns: 'usage' }],
'@babel/preset-react',
],
plugins: ['@babel/plugin-proposal-class-properties'],
},
},
})
return config
}
该配置的核心是让 babel-loader 处理 react-native-gifted-chat 包内的 ESM/JSX 源码(通过 exclude 正则放行),使其能在 web 构建链中被正确转译。
🧪 测试:触发布局事件
TEST_ID 以常量形式导出(定义在 src/Constant.ts:WRAPPER、LOADING_WRAPPER、SEND_TOUCHABLE),可配合任意测试库使用。
GiftedChat 通过 onLayout 确定聊天容器高度。测试中手动触发 onLayout:
const WIDTH = 200
const HEIGHT = 2000
const loadingWrapper = getByTestId(TEST_ID.LOADING_WRAPPER)
fireEvent(loadingWrapper, 'layout', {
nativeEvent: {
layout: {
width: WIDTH,
height: HEIGHT,
},
},
})
仓库内的测试用例(见 src/tests)覆盖了 Bubble、MessageText、Day、ReplyPreview、MessagesContainer 等核心组件,可作参考。
📦 运行示例应用(Example App)
仓库内置了展示全部特性的综合示例应用:
# 安装依赖(在 example 目录下)
cd example
yarn install
# 运行 iOS
npx expo run:ios
# 运行 Android
npx expo run:android
# 运行 Web
npx expo start --web
示例应用覆盖了以下功能:
- 💬 基础聊天功能(example/components/chat-examples/BasicExample.tsx)
- 🎨 自定义消息气泡与头像(example/components/chat-examples/CustomizedRenderingExample.tsx)
- ↩️ 滑动回复消息(example/components/chat-examples/ReplyExample.tsx)
- ⚡ 快捷回复(机器人风格)
- ✍️ 正在输入指示器
- 📎 附件操作
- 🔗 链接解析与自定义 matchers(example/components/chat-examples/LinksExample.tsx)
- 🌐 Web 兼容性
❓ 常见问题(Troubleshooting)
TextInput 在 Android 上被遮挡
确保 AndroidManifest.xml 中配置了 android:windowSoftInputMode="adjustResize",详见上文 Android 配置。
如何为不同用户设置不同的气泡颜色?
可以通过 renderBubble 根据 currentMessage.user._id 判断发送方,为左右气泡返回不同的 wrapperStyle。参考社区 issue 中的做法,核心思路是让气泡样式成为 user 的函数。
如何定制 InputToolbar 样式?
使用 renderInputToolbar 或 renderComposer 覆盖组件,或利用 minInputToolbarHeight、minComposerHeight、maxComposerHeight 调整尺寸;样式上的微调可以通过 renderAccessory、textInputProps 完成。
如何手动收起键盘?
通过 textInputRef 拿到输入框实例后调用 blur(),或在页面层使用 Keyboard.dismiss()。
如何使用 renderLoading?
传入 renderLoading={() => <ActivityIndicator />} 即可在初始化阶段渲染自定义加载视图;测试时可结合上文 TEST_ID.LOADING_WRAPPER 触发 onLayout 完成初始化。
提问前的准备顺序:先查阅本 README,再搜索既有 issue,然后可在 StackOverflow 等平台按 react-native-gifted-chat 标签提问,最后如需可新建 issue。
开发与贡献
仓库欢迎任何形式的贡献,核心流程为:
- Fork 仓库
- 创建特性分支(
git checkout -b feature/amazing-feature) - 安装依赖(
yarn install) - 修改代码
- 运行测试(
yarn test) - 运行 Lint(
yarn lint) - 构建库(
yarn build) - 提交(
git commit -m 'Add amazing feature') - 推送分支并提交 Pull Request
开发环境常用命令:
yarn install # 安装依赖
yarn build # 构建库
yarn test # 运行测试
yarn lint # 运行 Lint
yarn prepublishOnly # 完整校验
项目采用 MIT 许可,由 React Native 社区共同维护。
结语
react-native-gifted-chat 的价值在于把聊天界面中最繁琐、最容易出错的工程问题(键盘避让、消息分页、手势动画、链接解析、日期本地化)全部封装为声明式 Props,同时保留从组件到渲染函数的全链路可定制性。本文以官方 README 为骨架、仓库源码为印证,完整覆盖了从安装到高级特性的全部环节。在实际项目中,建议从 example 目录的示例出发按需裁剪,并在升级依赖时留意 README 中关于维护模式与迁移 fork 的说明。

