react-native-zero-sheet

react-native-zero-sheet

Мощный и гибкий компонент bottom sheet для React Native с поддержкой drag-to-close, автоматической обработкой клавиатуры и адаптивными размерами.

Примечание: Название "zero" означает, что библиотека работает без дополнительных зависимостей (кроме стандартных для React Native).

Особенности

• 🎯 Drag to Close - перетаскивание для закрытия модального окна
• ⌨️ Автоматическая обработка клавиатуры - автоматическая адаптация высоты при появлении клавиатуры
• 📱 Safe Area Support - автоматическая поддержка safe area insets
• 🎨 Гибкая структура - разделение на Header, Content и Footer
• ⚡ Производительность - оптимизированные анимации с использованием Animated API
• 🎛️ Полная кастомизация - настройка стилей, цветов и поведения
• 📏 Фиксированные размеры - поддержка фиксированных высот для секций
• 🔄 Контролируемое состояние - поддержка controlled и uncontrolled режимов

Установка

npm install react-native-zero-sheet
# или
yarn add react-native-zero-sheet

Требования

Библиотека требует react-native-safe-area-context для работы с safe area insets:

npm install react-native-safe-area-context
# или
yarn add react-native-safe-area-context

Убедитесь, что ваш корневой компонент обернут в SafeAreaProvider:

import { SafeAreaProvider } from 'react-native-safe-area-context';

function App() {
  return <SafeAreaProvider>{/* Ваш код */}</SafeAreaProvider>;
}

Быстрый старт

import React, { useRef } from 'react';
import { View, Button, Text } from 'react-native';
import ZeroSheet, { ZeroSheetHandle } from 'react-native-zero-sheet';

function App() {
  const sheetRef = useRef<ZeroSheetHandle>(null);

  return (
    <View>
      <Button title="Открыть Sheet" onPress={() => sheetRef.current?.open()} />

      <ZeroSheet
        ref={sheetRef}
        header={
          <View style={{ padding: 20 }}>
            <Text style={{ fontSize: 20, fontWeight: 'bold' }}>Заголовок</Text>
          </View>
        }
        footer={
          <View style={{ padding: 20 }}>
            <Button title="Закрыть" onPress={() => sheetRef.current?.close()} />
          </View>
        }
      >
        <View style={{ padding: 20 }}>
          <Text>Контент модального окна</Text>
        </View>
      </ZeroSheet>
    </View>
  );
}

Использование с провайдером для глобальных настроек

Вы можете обернуть ваше приложение в ZeroSheetProvider для установки настроек по умолчанию для всех ZeroSheet компонентов. Если настройки не заданы напрямую в компоненте, они будут браться из провайдера:

import React from 'react';
import { ZeroSheetProvider } from 'react-native-zero-sheet';

function App() {
  return (
    <ZeroSheetProvider
      backgroundColor="#f5f5f5"
      draggableHeight={30}
      customStyles={{
        container: { borderTopLeftRadius: 30, borderTopRightRadius: 30 },
        draggableIcon: { backgroundColor: '#ccc' },
      }}
    >
      {/* Ваше приложение */}
    </ZeroSheetProvider>
  );
}

Теперь все ZeroSheet компоненты будут использовать эти настройки по умолчанию, но вы можете переопределить их для конкретного компонента:

// Использует настройки из провайдера
<ZeroSheet visible={visible}>
  <Content />
</ZeroSheet>

// Переопределяет backgroundColor из провайдера
<ZeroSheet visible={visible} backgroundColor="#ffffff">
  <Content />
</ZeroSheet>

Примеры использования

Базовое использование с контролируемым состоянием

import React, { useState } from 'react';
import { View, Button, Text } from 'react-native';
import ZeroSheet from 'react-native-zero-sheet';

function App() {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <Button title="Открыть" onPress={() => setVisible(true)} />

      <ZeroSheet
        visible={visible}
        onChange={(open) => setVisible(open)}
        header={
          <View style={{ padding: 20 }}>
            <Text style={{ fontSize: 20 }}>Заголовок</Text>
          </View>
        }
      >
        <View style={{ padding: 20 }}>
          <Text>Контент</Text>
        </View>
      </ZeroSheet>
    </View>
  );
}

Использование с фиксированными размерами

<ZeroSheet
  visible={visible}
  fixedHeaderHeight={60}
  fixedFooterHeight={80}
  fixedContentHeight={400}
  header={<HeaderComponent />}
  footer={<FooterComponent />}
>
  <ContentComponent />
</ZeroSheet>

Кастомизация стилей

<ZeroSheet
  visible={visible}
  backgroundColor="#f5f5f5"
  buttonColor="#ffffff"
  draggableHeight={30}
  customStyles={{
    wrapper: { backgroundColor: 'rgba(0,0,0,0.5)' },
    container: { borderTopLeftRadius: 30, borderTopRightRadius: 30 },
    draggableIcon: { backgroundColor: '#ccc', width: 40, height: 4 },
  }}
>
  <ContentComponent />
</ZeroSheet>

Отключение drag-to-close и backdrop

<ZeroSheet
  visible={visible}
  draggable={false}
  backdrop={false}
  closeByBackdropClick={false}
>
  <ContentComponent />
</ZeroSheet>

Обработка событий жизненного цикла

<ZeroSheet
  visible={visible}
  onSheetOpen={() => console.log('Sheet открывается')}
  onSheetOpened={() => console.log('Sheet открыт')}
  onSheetClose={() => console.log('Sheet закрывается')}
  onSheetClosed={() => console.log('Sheet закрыт')}
  onManualClose={() => console.log('Закрытие вручную')}
  onChange={(open) => console.log('Состояние изменилось:', open)}
>
  <ContentComponent />
</ZeroSheet>

Использование с кастомным фоном

<ZeroSheet
  visible={visible}
  renderBackground={
    <Image
      source={require('./background.png')}
      style={{ width: '100%', height: '100%' }}
    />
  }
>
  <ContentComponent />
</ZeroSheet>

Отключение safe area insets

<ZeroSheet visible={visible} noTopInset={true} noBottomInset={true}>
  <ContentComponent />
</ZeroSheet>

Управление скроллом контента

По умолчанию скролл включается автоматически, если контент превышает доступную область. Вы можете принудительно управлять скроллом:

// Автоматическое определение (по умолчанию)
<ZeroSheet visible={visible}>
  <ContentComponent />
</ZeroSheet>

// Принудительно включить скролл
<ZeroSheet visible={visible} scrollEnabled={true}>
  <ContentComponent />
</ZeroSheet>

// Принудительно отключить скролл
<ZeroSheet visible={visible} scrollEnabled={false}>
  <ContentComponent />
</ZeroSheet>

API

ZeroSheetProvider Props

Провайдер для установки настроек по умолчанию для всех ZeroSheet компонентов.

Prop	Type	Default	Description
draggable	boolean	true	Включить возможность перетаскивания для закрытия
draggableHeight	number	25	Высота области для перетаскивания
backdrop	boolean	true	Показывать затемненный фон
closeByBackdropClick	boolean	true	Закрывать при клике на фон
backgroundColor	string	'#fff'	Цвет фона sheet
buttonColor	string	-	Цвет нижней области (safe area)
noTopInset	boolean	false	Не добавлять верхний safe area inset
noBottomInset	boolean	false	Не добавлять нижний safe area inset
customStyles	CustomStyles	{}	Кастомные стили

Примечание: Все настройки из провайдера могут быть переопределены в конкретном компоненте ZeroSheet. При объединении customStyles стили из props имеют приоритет над стилями из провайдера.

ZeroSheet Props

Prop	Type	Default	Description
visible	boolean	-	Контролируемое состояние видимости
onChange	(open: boolean) => void	-	Колбэк при изменении состояния
draggable	boolean	true	Включить возможность перетаскивания для закрытия
draggableHeight	number	25	Высота области для перетаскивания
backdrop	boolean	true	Показывать затемненный фон
closeByBackdropClick	boolean	true	Закрывать при клике на фон
backgroundColor	string	'#fff'	Цвет фона sheet
buttonColor	string	-	Цвет нижней области (safe area)
noTopInset	boolean	false	Не добавлять верхний safe area inset
noBottomInset	boolean	false	Не добавлять нижний safe area inset
header	React.ReactNode	-	Контент заголовка
footer	React.ReactNode	-	Контент футера
fixedHeaderHeight	number	-	Фиксированная высота заголовка
fixedFooterHeight	number	-	Фиксированная высота футера
fixedContentHeight	number	-	Фиксированная высота контента (будет ограничена максимальной доступной высотой с учетом header, footer, keyboard, insets и draggable области)
before	React.ReactNode	-	Элемент перед контентом
renderBackground	React.ReactNode	-	Кастомный фон sheet
customStyles	CustomStyles	{}	Кастомные стили
scrollEnabled	boolean	-	Управление скроллом контента (если не задано, определяется автоматически по размеру контента)
onSheetOpen	() => void	-	Колбэк при начале открытия
onSheetOpened	() => void	-	Колбэк после открытия
onSheetClose	() => void	-	Колбэк при начале закрытия
onSheetClosed	() => void	-	Колбэк после закрытия
onManualClose	() => void	-	Колбэк при ручном закрытии (drag или backdrop)
children	React.ReactNode	-	Контент sheet

CustomStyles

type CustomStyles = {
  wrapper?: ViewStyle;
  container?: ViewStyle;
  draggableIcon?: ViewStyle;
};

ZeroSheetHandle (Ref методы)

interface ZeroSheetHandle {
  open: () => void;
  close: () => void;
  expand: () => void; // Алиас для open()
}

Компоненты

Библиотека также экспортирует внутренние компоненты для более гибкого использования:

• ZeroSheetHeader - компонент заголовка с автоматической анимацией высоты
• ZeroSheetContent - компонент контента с поддержкой скролла
• ZeroSheetFooter - компонент футера с автоматической анимацией высоты

Эти компоненты автоматически используются внутри ZeroSheet, но могут быть использованы напрямую при необходимости.

Типы

Библиотека полностью типизирована с TypeScript. Все типы экспортируются:

import ZeroSheet, {
  ZeroSheetHandle,
  ZeroSheetProvider,
  ZeroSheetProviderProps,
} from 'react-native-zero-sheet';

Требования

• React Native >= 0.60
• react-native-safe-area-context
• React >= 16.8 (для hooks)