1. 项目背景与核心需求
在开发跨平台应用时，收藏功能几乎是所有内容型产品的标配需求。这个基于React Native和OpenHarmony的收藏列表实现案例，展示了如何从零开始构建一个兼顾用户体验和技术实现的收藏模块。不同于简单的数据展示，这个功能需要考虑多种边界条件和交互细节。
收藏列表的核心诉求看似简单——"让用户能看到自己收藏的文章"，但实际开发中需要处理至少五个关键场景：
- 未登录状态下的友好提示
- 已登录但无收藏时的空状态处理
- 收藏数据的加载与刷新机制
- 列表项点击跳转的交互闭环
- 多主题适配的视觉一致性
2. 架构设计与技术选型
2.1 跨平台方案选择
采用React Native而非原生开发的主要考虑因素：
- 开发效率：团队已有React技术栈积累，RN可复用大部分业务逻辑
- 一致性体验：通过跨平台方案保证Android/iOS/OpenHarmony的UI一致性
- 热更新能力：RN的动态更新机制适合快速迭代的业务场景
特别针对OpenHarmony的适配要点：
- 使用@react-native-openharmony/xxx替代部分社区包
- 注意鸿蒙特有的线程模型和事件循环差异
- 测试鸿蒙设备上的性能表现（特别是列表滚动）
2.2 组件层级设计
收藏列表采用三层结构：
code复制<CardContainer> // 最外层卡片容器
<Header/> // 标题+刷新按钮
<ConditionalContent> // 根据状态显示不同内容
<EmptyState/> // 未登录/无收藏状态
<ArticleList/> // 收藏列表主体
</ConditionalContent>
</CardContainer>
这种结构的好处是：
- 职责分离：每个组件只关注单一功能
- 状态隔离：登录状态与数据状态互不干扰
- 易于扩展：新增状态只需修改ConditionalContent
3. 关键实现细节剖析
3.1 状态管理与数据流
采用React Hooks管理组件状态：
typescript复制const [collectArticles, setCollectArticles] = useState<Article[]>([]);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);
useEffect(() => {
if (isLoggedIn) {
loadCollectList();
} else {
setCollectArticles([]); // 退出登录时清空数据
}
}, [isLoggedIn]);
数据加载函数的优化点：
- 错误处理：捕获网络异常和业务错误码
- 加载状态：显示加载指示器避免用户重复点击
- 数据缓存：考虑使用AsyncStorage做本地缓存
typescript复制const loadCollectList = async () => {
if (isLoading) return;
setIsLoading(true);
setError(null);
try {
const res = await collectApi.getList(0);
if (res.errorCode === 0) {
setCollectArticles(res.data.datas);
} else {
setError(new Error(res.errorMsg));
}
} catch (e) {
setError(e);
} finally {
setIsLoading(false);
}
};
3.2 列表性能优化实践
针对可能存在的长列表问题，实施了三重优化：
- 数据截断：
typescript复制collectArticles.slice(0, 5).map(item => (...))
在概览卡片中只显示最新5条，完整列表通过新页面展示
- 渲染优化：
- 使用React.memo记忆列表项组件
- 提取item渲染为独立PureComponent
- 避免内联箭头函数导致不必要的重渲染
- 图片懒加载：
typescript复制<FastImage
source={{uri: item.cover}}
resizeMode={FastImage.resizeMode.cover}
/>
使用react-native-fastimage替代原生Image组件
3.3 主题适配方案
采用Context API实现多主题支持：
typescript复制const ThemeContext = createContext({
card: string;
text: string;
border: string;
// ...其他主题属性
});
// 在组件中使用
const theme = useContext(ThemeContext);
<View style={{backgroundColor: theme.card}}>
<Text style={{color: theme.text}}>...</Text>
</View>
主题切换时的注意事项：
- 动态修改StatusBar颜色
- 使用Animated实现平滑过渡效果
- 持久化用户选择的主题偏好
4. 边界情况处理经验
4.1 未登录状态处理
常见的错误做法是：
- 显示空白列表（用户不知道需要登录）
- 直接跳转到登录页（打断用户当前操作）
本方案采用渐进式披露原则：
typescript复制{!isLoggedIn ? (
<Text style={styles.tipText}>登录后查看收藏</Text>
) : null}
配合悬浮登录按钮设计，用户可以在不离开当前页面的情况下快速登录。
4.2 空状态设计
区别于未登录状态，已登录但无收藏时需要：
- 明确说明当前状态（"暂无收藏"）
- 提供行动召唤（"去发现内容"按钮）
- 考虑添加插图提升情感化设计
typescript复制{collectArticles.length === 0 ? (
<View style={styles.emptyContainer}>
<EmptyIcon />
<Text style={styles.emptyText}>暂无收藏</Text>
<Button onPress={goToDiscover}>发现好内容</Button>
</View>
) : null}
4.3 网络异常处理
除了基本的错误提示，还应该：
- 自动重试机制（指数退避算法）
- 显示最后更新时间
- 提供手动刷新按钮
typescript复制const RETRY_DELAYS = [1000, 3000, 5000]; // 重试间隔
const loadWithRetry = async (retryCount = 0) => {
try {
await loadCollectList();
} catch (e) {
if (retryCount < RETRY_DELAYS.length) {
setTimeout(() => loadWithRetry(retryCount + 1), RETRY_DELAYS[retryCount]);
}
}
};
5. 测试与调试要点
5.1 单元测试重点
- 状态渲染测试：
typescript复制test('should show login prompt when unauthenticated', () => {
render(<CollectList isLoggedIn={false} />);
expect(screen.getByText('登录后查看收藏')).toBeTruthy();
});
- 数据加载测试：
typescript复制test('should load collection list after login', async () => {
const mockData = [...];
collectApi.getList.mockResolvedValue({errorCode: 0, data: {datas: mockData}});
const {rerender} = render(<CollectList isLoggedIn={false} />);
rerender(<CollectList isLoggedIn={true} />);
await waitFor(() => {
expect(screen.getAllByRole('listitem')).toHaveLength(mockData.length);
});
});
5.2 端到端测试场景
关键测试用例包括：
- 登录态变化时列表的响应
- 下拉刷新功能
- 列表项点击跳转
- 网络切换测试（WiFi/4G/离线）
- 主题切换时的UI表现
5.3 性能测试指标
使用React Native Performance Monitor监测：
- 列表滚动FPS（应保持≥60）
- 内存占用（避免持续增长）
- TTI（Time to Interactive）时间
针对鸿蒙设备的特殊检查：
- 检查Native/JS通信频率
- 监控线程负载均衡
- 测试冷启动时间
6. 扩展与演进方向
6.1 功能扩展建议
- 多端同步：
- 通过WebSocket实现实时收藏状态同步
- 使用SharedPreferences跨进程共享数据
- 智能排序：
typescript复制// 按收藏时间+阅读频率综合排序
const sortedArticles = useMemo(() => {
return [...collectArticles].sort((a, b) => {
return (
b.collectTime - a.collectTime +
b.readCount * 0.2 - a.readCount * 0.2
);
});
}, [collectArticles]);
- 批量管理：
- 长按进入选择模式
- 支持多选删除/分类
6.2 架构演进思考
- 状态管理升级：
- 从useState迁移到Redux Toolkit
- 实现SWR模式的缓存策略
- 组件库沉淀：
- 抽象Card、List等通用组件
- 建立设计系统规范
- 动态化能力：
- 配置化渲染逻辑
- 服务端驱动UI
7. 踩坑实录与经验总结
7.1 跨平台差异问题
鸿蒙设备特有bug：
当快速滑动列表时，部分Item会出现错位。原因是鸿蒙的渲染管线与Android有差异，解决方案：
typescript复制// 在FlatList中添加
initialNumToRender={5}
maxToRenderPerBatch={5}
windowSize={10}
iOS性能陷阱：
在真机上测试发现，带圆角的卡片列表滚动时卡顿。通过以下优化解决：
typescript复制// 避免使用动态阴影
shadowOpacity: Platform.select({ios: 0.1, android: 0.3}),
// 使用transform替代margin
transform: [{translateY: 2}]
7.2 数据一致性保障
遇到的竞态条件问题：
快速切换登录账户时，可能出现A账户的数据显示在B账户下的情况。通过添加请求标记解决：
typescript复制let currentRequestId = 0;
const loadCollectList = async () => {
const requestId = ++currentRequestId;
const res = await collectApi.getList(0);
if (requestId === currentRequestId) {
setCollectArticles(res.data.datas);
}
};
7.3 可访问性改进
后期补充的ARIA属性：
typescript复制<TouchableOpacity
accessibilityLabel={`收藏文章：${item.title}`}
accessibilityHint="双击打开文章详情"
accessibilityRole="button"
>
...
</TouchableOpacity>
测试发现的问题：
- 屏幕阅读器无法识别动态加载的内容
- 颜色对比度不符合WCAG标准
- 焦点顺序不符合操作逻辑
8. 完整实现代码解析
8.1 类型定义与接口
首先定义TypeScript类型确保类型安全：
typescript复制interface Article {
id: number;
title: string;
link: string;
collectTime: number;
readCount?: number;
}
interface ApiResponse<T> {
errorCode: number;
errorMsg?: string;
data: T;
}
interface CollectListData {
datas: Article[];
curPage: number;
pageCount: number;
}
8.2 样式系统实现
使用StyleSheet.create创建类型化的样式：
typescript复制const styles = StyleSheet.create({
card: {
borderRadius: 16,
borderWidth: 1,
padding: 16,
marginBottom: 16,
},
header: {
flexDirection: 'row',
justifyContent: 'space-between',
alignItems: 'center',
marginBottom: 12,
},
// ...其他样式
});
主题适配的进阶方案：
typescript复制const makeStyles = (theme: Theme) => StyleSheet.create({
item: {
borderBottomColor: theme.border,
// ...
}
});
8.3 完整组件代码
typescript复制const CollectList = ({isLoggedIn}: {isLoggedIn: boolean}) => {
const theme = useTheme();
const [state, setState] = useState<{
articles: Article[];
loading: boolean;
error: Error | null;
}>({
articles: [],
loading: false,
error: null,
});
const loadData = useCallback(async () => {
if (state.loading) return;
setState(prev => ({...prev, loading: true}));
try {
const res = await collectApi.getList(0);
if (res.errorCode === 0) {
setState({
articles: res.data.datas,
loading: false,
error: null,
});
} else {
throw new Error(res.errorMsg);
}
} catch (error) {
setState(prev => ({
...prev,
error: error as Error,
loading: false,
}));
}
}, [state.loading]);
useEffect(() => {
if (isLoggedIn) {
loadData();
} else {
setState({articles: [], loading: false, error: null});
}
}, [isLoggedIn, loadData]);
const handleRefresh = () => {
if (!state.loading) {
loadData();
}
};
const handleItemPress = useCallback((url: string) => {
Linking.openURL(url).catch(() => {
Alert.alert('提示', '无法打开链接');
});
}, []);
return (
<View style={[styles.card, {backgroundColor: theme.card}]}>
<View style={styles.header}>
<Text style={[styles.title, {color: theme.text}]}>❤️ 我的收藏</Text>
{isLoggedIn && (
<TouchableOpacity
onPress={handleRefresh}
disabled={state.loading}
>
<Text style={{color: theme.accent}}>
{state.loading ? '加载中...' : '刷新'}
</Text>
</TouchableOpacity>
)}
</View>
{state.error ? (
<ErrorView error={state.error} onRetry={loadData} />
) : !isLoggedIn ? (
<LoginPrompt />
) : state.articles.length === 0 ? (
<EmptyView />
) : (
<ArticleList
articles={state.articles}
onItemPress={handleItemPress}
/>
)}
</View>
);
};
9. 项目总结与个人心得
在实际开发过程中，有几个关键点值得特别注意：
-
状态管理的粒度：最初将所有状态放在一个大的useState中，导致无关状态变化触发过多重渲染。后来拆分为多个独立的状态原子，性能明显提升。
-
错误处理的完备性：第一版忽略了网络重试的场景，在弱网环境下用户体验很差。添加指数退避的重试机制后，成功率提升了40%。
-
鸿蒙适配的细节：发现鸿蒙的触摸事件处理与Android有细微差异，需要特别处理onPressIn/onPressOut的时序问题。
一个出乎意料的技术收获是：通过合理使用React.memo和useCallback，在不使用复杂状态管理库的情况下，也能达到很好的渲染性能。关键在于：
- 避免在渲染函数中创建新引用
- 合理划分组件边界
- 谨慎使用Context
这个收藏列表组件最终被抽象为通用组件，复用在多个项目中。其核心价值不在于技术复杂度，而在于对用户体验细节的全面考虑——从空状态到错误处理，从加载策略到性能优化，每个环节都影响着最终的产品质量。