React Native Elements 的 AirbnbRating 组件:从 Snack 示例到源码级实现解析
React Native Elements 的 AirbnbRating 组件:从 Snack 示例到源码级实现解析
本篇技术指南围绕 react-native-elements 文档中 AirbnbRating 的官方交互示例(位于 website/versioned_docs/version-4.0.0-beta.0/main/usage/AirbnbRating/snack/index.md)展开,完整讲解其默认用法、禁用状态、自定义星级与文案三种典型场景,并深入到 packages/base/src/AirbnbRating 的源码与测试,剖析其 Props 语义、内部组件结构与点击动画原理。读完本文,你将能够在一个可运行示例的基础上,熟练配置星级数量、评论文案、颜色尺寸与回调,并理解该组件在库内的真实实现方式。
一、示例总览:一个文件展示三种典型用法
官方文档通过一个 SnackPlayer 内联示例(即 snack/index.md 中的完整 React 组件)集中演示了 AirbnbRating 的三类常见形态。该示例以 Ratings 函数组件为核心,在 ScrollView 中依次渲染三个 <AirbnbRating />,每个实例对应一种配置思路:
import React from 'react';
import { StyleSheet, Text, View, Platform, ScrollView } from 'react-native';
import { AirbnbRating } from 'react-native-elements';
type RatingsComponentProps = {};
const Ratings: React.FunctionComponent<RatingsComponentProps> = () => {
const ratingCompleted = (rating: number) => {
console.log('Rating is: ' + rating);
};
const ratingProps = {};
return (
<View style={styles.container}>
<ScrollView style={styles.viewContainer}>
<View
style={{
justifyContent: 'center',
alignItems: 'center',
marginBottom: 30,
}}
>
<AirbnbRating />
<AirbnbRating isDisabled={true}/>
<AirbnbRating
count={11}
reviews={[
'Terrible',
'Bad',
'Meh',
'OK',
'Good',
'Hmm...',
'Very Good',
'Wow',
'Amazing',
'Unbelievable',
'Jesus',
]}
defaultRating={11}
size={20}
/>
</View>
</ScrollView>
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
},
headingContainer: {
paddingTop: 50,
},
titleText: {
fontSize: 25,
fontWeight: 'bold',
textAlign: 'center',
paddingVertical: 5,
fontFamily: Platform.OS === 'ios' ? 'Menlo-Bold' : '',
color: '#27ae60',
},
subtitleText: {
fontSize: 18,
fontWeight: '400',
textAlign: 'center',
fontFamily: Platform.OS === 'ios' ? 'Trebuchet MS' : '',
color: '#34495e',
},
viewContainer: {
flex: 1,
},
rating: {
paddingVertical: 10,
},
});
export default Ratings;
三个实例分别覆盖了:
- 零配置使用:
<AirbnbRating />直接采用全部默认值; - 只读展示:
<AirbnbRating isDisabled={true}/>关闭用户交互,适合展示已有评分; - 完全自定义:
count、reviews、defaultRating、size四个 Props 协同,构造 11 星、11 级文案的评分器。
需要说明的是,示例中定义的 ratingCompleted 回调与 ratingProps 对象在当前代码中并未挂接到组件上,它们只是为扩展预留的写法;真实的回调绑定通过 onFinishRating Prop 完成,后文会结合源码说明。
二、AirbnbRating 的 Props 全景与默认值
AirbnbRating 的完整类型定义位于 packages/base/src/AirbnbRating/TapRating.tsx#L13-L114(TapRatingProps),下面按用途分组列出全部可配置项及其默认值,默认值以源码中的解构赋值为准(见 TapRating.tsx#L116-L132)。
2.1 结构与数量
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
count |
number |
5 |
显示的星星总数 |
defaultRating |
number |
3 |
初始评分值(第 N 颗星被点亮);当传入 null 或 undefined 时内部回退为 3 |
reviews |
string[] |
['Terrible', 'Bad', 'Okay', 'Good', 'Great'] |
点击/命中第 i 颗星时,评分上方显示的文案(索引从 0 开始) |
showRating |
boolean |
true |
是否在星星上方显示评分文案 |
2.2 视觉样式
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
size |
number |
40 |
每颗星星图片的宽高 |
selectedColor |
string |
#f1c40f(源码实现层) |
已点亮星星的着色(tintColor);类型定义注释中标注为 #004666,实际生效值以 components/Star.tsx#L29 的 #f1c40f 为准 |
unSelectedColor |
string |
#BDC3C7 |
未点亮星星的着色(tintColor) |
reviewColor |
string |
rgba(230, 196, 46, 1) |
评分文案的颜色 |
reviewSize |
number |
25 |
评分文案的字体大小 |
starImage |
string |
内置 airbnb-star.png |
自定义星星图片资源 |
starStyle |
ImageStyle |
无 | 追加到星星图片的样式 |
starContainerStyle |
StyleProp<ViewStyle> |
无 | 星星排列行的容器样式 |
ratingContainerStyle |
StyleProp<ViewStyle> |
无 | 整个评分组件(含文案)的容器样式 |
2.3 行为回调
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
onFinishRating |
(value: number) => void |
无 | 用户完成一次点击时回调,参数为被点中的星级序号(从 1 开始) |
isDisabled |
boolean |
false |
为 true 时禁止用户修改评分,星星点击无响应 |
默认值一致性提示:类型注释中的 reviewColor 默认值写为 #f1c40f,而实际代码解构值为 rgba(230, 196, 46, 1),两者视觉上等价;selectedColor 在类型注释与实现层也存在 #004666 与 #f1c40f 的出入。如果你的样式依赖精确色值,应以 TapRating.tsx 中解构赋值处的实际默认值为准。
三、示例逐例拆解:默认、禁用与自定义
3.1 零配置:<AirbnbRating />
不传任何 Props 时,组件等价于:
- 渲染 5 颗 40×40 的星;
- 初始点亮第 3 颗(
defaultRating = 3); - 星星上方显示文案
Okay(reviews[2]); - 用户可点击任意星星,点击后文案同步切换为对应文案。
3.2 只读:<AirbnbRating isDisabled={true}/>
isDisabled 最终传递到每颗星的 TouchableOpacity 的 disabled 属性(见 components/Star.tsx#L55-L59)。此时 onPress 不再触发,动画与回调均被屏蔽,适合在商品详情页等场景展示"已评分"状态。
3.3 自定义:11 星 11 级文案
<AirbnbRating
count={11}
reviews={['Terrible','Bad','Meh','OK','Good','Hmm...','Very Good','Wow','Amazing','Unbelievable','Jesus']}
defaultRating={11}
size={20}
/>
count={11}让渲染循环生成 11 颗星(源码见 TapRating.tsx#L154-L171 的for循环);reviews提供 11 个与星级一一对应的文案,点击第 N 颗星时展示reviews[N-1];defaultRating={11}使初始即全部点亮;size={20}将星星缩小到 20px,适合在紧凑布局中使用。
四、源码级实现:AirbnbRating → TapRating → Star 的调用链
4.1 AirbnbRating 是 TapRating 的别名
从源码看,AirbnbRating 并非独立实现,而是对 TapRating 的一层薄封装。完整定义在 packages/base/src/AirbnbRating/AirbnbRating.tsx:
export interface TapRatingProps extends RatingProps {}
export const AirbnbRating: RneFunctionComponent<TapRatingProps> = (props) => {
return <TapRating {...props} />;
};
AirbnbRating.displayName = 'AirbnbRating';
其中 RatingProps 来自同目录的 TapRating(import TapRating, { type TapRatingProps as RatingProps } from './TapRating')。所有传入 AirbnbRating 的 Props 都会被原样透传给 TapRating。入口聚合文件 packages/base/src/AirbnbRating/index.tsx 同时导出了 AirbnbRating 组件与 TapRatingProps 类型,供外部消费。示例中的 import { AirbnbRating } from 'react-native-elements' 最终即指向该入口。
4.2 TapRating:状态管理与渲染循环
TapRating 的核心逻辑在 packages/base/src/AirbnbRating/TapRating.tsx:
- 用
useState(defaultRating)维护当前评分位置position; - 用
useEffect监听defaultRating变化并同步position(null/undefined时回退到 3),因此外部受控更新初始评分也能生效; - 渲染循环根据
position >= index + 1决定每颗星是否填充,并把isDisabled、颜色、尺寸等逐项下发给Star; - 点击回调
starSelectedInPosition会先调用onFinishRating(selectedPosition)(若传入),再更新position; - 外层容器与文案分别带
testID:RNEUI__TapRating、RNEUI__TapRating-showRating、RNEUI__TapRating-starContainer,便于测试定位。
4.3 Star:弹簧动画与着色
单颗星实现在 packages/base/src/AirbnbRating/components/Star.tsx:
- 默认图片资源为
airbnb-star.png,填充模式为airbnb-star-selected.png; - 每个
TouchableOpacity内嵌一个Animated.Image,点击时springValue从 1.2 弹性回落到 1(Animated.spring,friction: 2, tension: 1,使用原生驱动),产生轻快的回弹反馈; - 填充色通过
tintColor实现:fill && selectedColor ? selectedColor : unSelectedColor; - 星星图片宽高由
size(默认常量STAR_SIZE = 40)决定,并允许starStyle追加自定义样式。
因此"点击星星 → 弹簧动画 + 文案切换 + 回调通知"这一完整交互链路,是由 TapRating 的状态管理与 Star 的动画组件协作完成的。
五、主题化版本:AirbnbRating 也支持 Theme
仓库的 themed 包同样为 AirbnbRating 提供了主题化入口(packages/themed/src/AirbnbRating/index.tsx),使其可以在 <ThemeProvider> 体系下使用统一的主题配色。若你的应用启用了 RNE 的主题功能,优先从 themed 包导入以保持主题一致性;基础场景则直接使用 base 包(即示例中的 react-native-elements 顶层导出)即可。
六、测试用例对行为的验证
仓库在 packages/base/src/AirbnbRating/tests/TapRating.test.tsx 中对上述行为做了系统验证,可作为你使用时的行为契约参考:
- 星级数量:
count={4}时渲染 4 个RNEUI__Star; - 文案联动:
defaultRating=1时文案为reviews[0](Terrible); - 尺寸:
reviewSize控制文案fontSize,size同时控制每颗星图片的宽高; - 回调:点击第 2 颗星后
onFinishRating以2为参数被调用;isDisabled为真时回调不被触发; - 自定义资源:
starImage、selectedColor、unSelectedColor、starStyle、starContainerStyle、ratingContainerStyle均按预期生效(测试中分别断言了图片source、tintColor、背景色等)。
这些测试直接印证了本文第二节 Props 表格中的各项行为语义。
七、实际接入建议与注意事项
- 导入路径:示例采用
import { AirbnbRating } from 'react-native-elements',这是顶层统一出口;若需类型提示,可导入TapRatingProps类型。 - 回调接入:把
ratingCompleted挂到onFinishRating上即可拿到整数评分,例如onFinishRating={(r) => console.log('Rating is: ' + r)},这与示例中预留的ratingCompleted意图一致。 - 受控更新:
defaultRating支持后续变更并自动同步(useEffect监听),可用来实现"回显服务端评分"。 - 只读场景:展示态务必设置
isDisabled,避免用户误触。 - 文案与星级对齐:
reviews数组长度建议与count一致,否则超出部分星级的文案会取到undefined(源码中直接以reviews[position - 1]取值,不做兜底)。 - 颜色默认值的坑:如 2.2 节所述,
selectedColor的文档注释值与实现默认值不同,需要精确颜色时请显式传入。
通过官方 Snack 示例(snack/index.md)、类型定义(TapRating.tsx)、动画实现(Star.tsx)与测试用例(TapRating.test.tsx)四份材料的对照阅读,你可以完整掌握 AirbnbRating 从使用到实现的每个细节,并直接复制示例代码到自己的项目中快速落地。