React Native集成Bottom Sheet到首页createRef报错修复方案

报错根因 #

bs = React.createRef();行抛出错误、点击按钮无法唤起弹窗，90%以上是ref创建/绑定方式和组件类型不匹配，或是依赖配置缺失导致的，对照以下场景逐一排查即可。

场景1：Home Screen 为函数式组件 #

直接在函数组件内写bs = React.createRef();属于语法错误，函数组件必须使用useRef钩子创建实例引用，参考以下正确写法：

// 顶部引入对应依赖
import React, { useRef } from 'react';
import { View, Button } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

const HomeScreen = () => {
  // 正确创建ref，指定对应类型可避免TS报错
  const bs = useRef<BottomSheet>(null);

  // 按钮点击唤起弹窗逻辑
  const handleOpenFilters = () => {
    bs.current?.snapToIndex(0);
  };

  return (
    <View style={{flex: 1}}>
      {/* 页面原有业务内容 */}
      <Button title="Filters" onPress={handleOpenFilters} />

      {/* 底部弹窗组件 */}
      <BottomSheet
        ref={bs}
        snapPoints={['25%', '50%', '90%']}
        index={-1}
        enablePanDownToClose
      >
        {/* 弹窗内的筛选表单内容 */}
      </BottomSheet>
    </View>
  )
}

export default HomeScreen;

场景2：Home Screen 为类组件 #

类组件下该报错通常是ref创建位置错误、或是绑定ref时漏写this导致，参考以下正确写法：

import React from 'react';
import { View, Button } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

class HomeScreen extends React.Component {
  // 在类属性位置创建ref，不要写到render函数内部
  bs = React.createRef<BottomSheet>();

  handleOpenFilters = () => {
    this.bs.current?.snapToIndex(0);
  };

  render() {
    return (
      <View style={{flex: 1}}>
        {/* 页面原有业务内容 */}
        <Button title="Filters" onPress={this.handleOpenFilters} />

        <BottomSheet
          ref={this.bs}
          snapPoints={['25%', '50%', '90%']}
          index={-1}
          enablePanDownToClose
        >
          {/* 弹窗内的筛选表单内容 */}
        </BottomSheet>
      </View>
    )
  }
}

export default HomeScreen;

高频踩坑排查点 #

如果改完ref写法还是无法唤起弹窗，逐一检查以下配置：

• 必须通过.current取到组件实例再调用方法，直接访问ref对象本身拿不到挂载的实例，调用方法会直接抛错
• ref必须正确绑定到BottomSheet组件上，漏绑会导致所有方法调用无响应
• 初始index值必须设为-1才会默认隐藏，漏写会导致组件初始化状态异常，无法正常唤起
• 必须在App根组件外层包裹手势容器和BottomSheet上下文提供者，漏配会导致所有弹窗方法失效：

// App.jsx 根文件配置
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';

export default function App() {
  return (
    <GestureHandlerRootView style={{flex: 1}}>
      <BottomSheetModalProvider>
        {/* 你的导航容器/页面栈 */}
      </BottomSheetModalProvider>
    </GestureHandlerRootView>
  )
}

• BottomSheet组件不要放在设置了overflow: hidden的容器内部，会导致弹窗被裁切无法看到
• 检查snapPoints配置和调用snapToIndex传入的索引是否对应，索引值不能超过snapPoints数组的最大长度
• 确认已经安装了所有peerDependencies依赖，包括react-native-gesture-handler、react-native-reanimated，并且完成了reanimated的babel插件配置

内容的提问来源于stack exchange，提问作者Ram01