【React Native for OpenHarmony 实战】搞定底部TabBar开发：从0到1踩坑全记录

📝 社区引导

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrosspatform.csdn.net

🎯 摘要

本文基于React Native for OpenHarmony技术栈，完整记录了6天开发底部TabBar的全流程，包含从项目搭建、布局实现、交互逻辑到状态优化的完整代码，以及开发中遇到的各类错误与解决方案，为开发者提供可落地的实战参考。

---

📋 开发背景与目标

本次开发是项目的第8-13天，核心任务是为React Native for OpenHarmony跨平台应用新增不少于4个底部选项卡（TabBar），覆盖首页、数据列表、我的中心、设置等核心场景。

最终要实现：

• 清晰的视觉区分（默认/选中状态）
• 平滑的页面切换
• 切换时保留页面状态（如列表滚动位置）
• 避免重复加载数据
• 通过开源鸿蒙设备的运行验证

---

📅 开发全流程拆解

：前期准备与项目搭建

核心动作

1. 确认4个选项卡的功能边界，准备图标资源（默认/选中两套）
2. 技术选型：采用react-native-tab-view + react-native-pager-view实现底部TabBar
3. 搭建项目目录，导入资源并验证引用正常
4. 依赖安装：

   npm install @react-navigation/bottom-tabs @react-navigation/native react-native-screens react-native-safe-area-context
   

踩坑记录

• ❌ 错误1：图标资源命名包含中文，导致编译时资源无法识别
  ✅ 解决：将图标重命名为纯英文+下划线格式（如home_default.png），并放入assets/images目录
• ❌ 错误2：依赖版本不兼容，导致项目编译失败
  ✅ 解决：确认@react-navigation/bottom-tabs版本与React Native for OpenHarmony版本匹配，使用npm install --legacy-peer-deps解决依赖冲突

---

：底部TabBar布局搭建

核心动作
配置底部TabBar的基础布局，设置图标与文字的组合展示，适配不同屏幕尺寸。

核心代码

// src/navigation/TabNavigator.tsx
import React from 'react';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { Image, Text, View } from 'react-native';
import HomePage from '../pages/HomePage';
import ListPage from '../pages/ListPage';
import MinePage from '../pages/MinePage';
import SettingPage from '../pages/SettingPage';

const Tab = createBottomTabNavigator();

const TabNavigator = () => {
  return (
    <Tab.Navigator
      screenOptions={({ route }) => ({
        tabBarIcon: ({ focused, color, size }) => {
          let iconName;
          if (route.name === '首页') {
            iconName = focused ? require('../assets/images/home_selected.png') : require('../assets/images/home_default.png');
          } else if (route.name === '数据') {
            iconName = focused ? require('../assets/images/list_selected.png') : require('../assets/images/list_default.png');
          } else if (route.name === '我的') {
            iconName = focused ? require('../assets/images/mine_selected.png') : require('../assets/images/mine_default.png');
          } else if (route.name === '设置') {
            iconName = focused ? require('../assets/images/setting_selected.png') : require('../assets/images/setting_default.png');
          }
          return <Image source={iconName} style={{ width: size, height: size }} />;
        },
        tabBarLabel: ({ focused, color }) => {
          let label;
          if (route.name === '首页') label = '首页';
          else if (route.name === '数据') label = '数据';
          else if (route.name === '我的') label = '我的';
          else if (route.name === '设置') label = '设置';
          return <Text style={{ color: focused ? '#1890FF' : '#666666', fontSize: 12 }}>{label}</Text>;
        },
        tabBarActiveTintColor: '#1890FF',
        tabBarInactiveTintColor: '#666666',
        tabBarStyle: {
          height: 56,
          paddingBottom: 4,
          paddingTop: 4,
          borderTopWidth: 0.5,
          borderTopColor: '#E5E5E5',
        },
      })}
    >
      <Tab.Screen name="首页" component={HomePage} options={{ headerShown: false }} />
      <Tab.Screen name="数据" component={ListPage} options={{ headerShown: false }} />
      <Tab.Screen name="我的" component={MinePage} options={{ headerShown: false }} />
      <Tab.Screen name="设置" component={SettingPage} options={{ headerShown: false }} />
    </Tab.Navigator>
  );
};

export default TabNavigator;

踩坑记录

• ❌ 错误1：使用固定像素值适配，导致在不同设备上显示错位
  ✅ 解决：使用react-native-size-matters库的scale函数实现自适应尺寸
• ❌ 错误2：TabBar图标与文字间距不一致，导致视觉错位
  ✅ 解决：在tabBarIcon中添加统一的marginBottom，并通过预览实时调整

---

：交互状态实现

核心动作
实现TabBar的选中状态切换，优化点击交互逻辑，避免重复触发。

核心代码

// 优化后的TabBar点击逻辑
tabBarButton: (props) => {
  const { onPress, children } = props;
  return (
    <TouchableOpacity
      onPress={() => {
        // 避免重复点击同一选项卡
        if (props.accessibilityState.selected) return;
        onPress();
      }}
      style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}
    >
      {children}
    </TouchableOpacity>
  );
},

踩坑记录

• ❌ 错误1：选中状态图标颜色未动态变化
  ✅ 解决：通过focused参数判断状态，动态绑定图标资源
• ❌ 错误2：点击同一选项卡时重复触发页面刷新
  ✅ 解决：在tabBarButton中添加判断，仅当未选中时执行点击事件

---

：页面绑定与切换

核心动作
开发4个选项卡对应的页面，通过createBottomTabNavigator实现页面与TabBar的绑定，优化切换动画。

核心代码（ListPage示例）

// src/pages/ListPage.tsx
import React, { useState, useEffect } from 'react';
import { View, Text, FlatList, StyleSheet } from 'react-native';

const ListPage = () => {
  const [dataList, setDataList] = useState<string[]>([]);
  const [isFirstLoad, setIsFirstLoad] = useState(true);

  useEffect(() => {
    if (isFirstLoad) {
      loadData();
      setIsFirstLoad(false);
    }
  }, []);

  const loadData = () => {
    // 模拟网络请求
    setTimeout(() => {
      setDataList(Array.from({ length: 20 }, (_, i) => `列表项 ${i + 1}`));
    }, 1000);
  };

  return (
    <View style={styles.container}>
      <FlatList
        data={dataList}
        renderItem={({ item }) => (
          <View style={styles.item}>
            <Text style={styles.itemText}>{item}</Text>
          </View>
        )}
        keyExtractor={(item, index) => index.toString()}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#FFFFFF',
  },
  item: {
    padding: 16,
    borderBottomWidth: 0.5,
    borderBottomColor: '#F0F0F0',
  },
  itemText: {
    fontSize: 16,
    color: '#333333',
  },
});

export default ListPage;

踩坑记录

• ❌ 错误1：页面路由配置错误，导致切换时白屏
  ✅ 解决：检查Tab.Screen的name与route.name是否一一对应
• ❌ 错误2：页面切换时出现闪屏
  ✅ 解决：为所有页面设置统一的背景色，避免透明背景导致的视觉闪烁

---

：状态保留与性能优化

核心动作
实现列表页面的滚动位置保留，优化数据加载逻辑，避免重复请求。

核心代码

// src/pages/ListPage.tsx 滚动状态保留优化
import React, { useState, useEffect, useRef } from 'react';
import { View, Text, FlatList, StyleSheet } from 'react-native';

const ListPage = () => {
  const [dataList, setDataList] = useState<string[]>([]);
  const [isFirstLoad, setIsFirstLoad] = useState(true);
  const flatListRef = useRef<FlatList>(null);
  const [scrollOffset, setScrollOffset] = useState(0);

  useEffect(() => {
    if (isFirstLoad) {
      loadData();
      setIsFirstLoad(false);
    }
  }, []);

  const loadData = () => {
    setTimeout(() => {
      setDataList(Array.from({ length: 20 }, (_, i) => `列表项 ${i + 1}`));
    }, 1000);
  };

  const handleScroll = (event: any) => {
    setScrollOffset(event.nativeEvent.contentOffset.y);
  };

  useEffect(() => {
    if (flatListRef.current && scrollOffset > 0) {
      flatListRef.current.scrollToOffset({ offset: scrollOffset, animated: false });
    }
  }, [dataList]);

  return (
    <View style={styles.container}>
      <FlatList
        ref={flatListRef}
        data={dataList}
        renderItem={({ item }) => (
          <View style={styles.item}>
            <Text style={styles.itemText}>{item}</Text>
          </View>
        )}
        keyExtractor={(item, index) => index.toString()}
        onScroll={handleScroll}
        scrollEventThrottle={16}
      />
    </View>
  );
};

export default ListPage;

踩坑记录

• ❌ 错误1：切换选项卡后列表滚动位置丢失
  ✅ 解决：使用useRef保存FlatList实例，通过scrollToOffset恢复滚动位置
• ❌ 错误2：每次切换选项卡都触发数据请求
  ✅ 解决：添加isFirstLoad标志位，仅在首次进入页面时加载数据

---

：设备验证与收尾

核心动作

1. 全功能回归测试（交互/切换/状态/适配）
2. 打包生成hap文件，安装到开源鸿蒙设备验证
3. 修复设备专属问题，整理开发文档

踩坑记录

• ❌ 错误1：打包时未配置权限，导致设备安装失败
  ✅ 解决：在module.json5中添加网络权限等必要配置
• ❌ 错误2：真实设备上图标模糊
  ✅ 解决：提供多分辨率图标资源（1x/2x/3x），适配不同设备像素密度

---

📌 关键知识点总结

1. 组件选型：优先使用@react-navigation/bottom-tabs，适配React Native for OpenHarmony生态
2. 状态管理：通过useRef和useState结合，实现页面状态持久化
3. 性能优化：通过标志位控制数据加载时机，避免重复请求
4. 设备验证：必须在真实鸿蒙设备上测试，模拟器无法覆盖所有场景

---

📦 代码托管

完整代码已上传至AtomGit：https://atomgit.com/xxx/react-native-oh-tabbar

---

🧪 运行验证