Клавиатура и безопасные зоны: что здесь рисуется, но мертво

Соберём экран формы так, как его собирают по документации React Native. Весь экран — в SafeAreaView: он должен отодвинуть содержимое от выреза и полосы «домой». Внутри — KeyboardAvoidingView с behavior="padding": когда поднимется клавиатура, он добавит снизу отступ на её высоту. StatusBar просит светлые значки в полосе состояния, а Keyboard.addListener подписывается на появление клавиатуры. Поле повторов получает фокус с первого кадра. Заглянуть в разметку помогает inspectBox из подложки: сам пример document не видит. Прогноз: что напечатается и появится ли строка «клавиатура:»?

declare function inspectBox(testID: string): { padding: string; asked: string } | null;
const { TextInput, SafeAreaView, KeyboardAvoidingView, StatusBar, Keyboard } = ReactNative;

function SetScreen() {
  const reps = React.useRef<React.ComponentRef<typeof TextInput>>(null);
  // фокус с первого кадра — чтобы клавиатура поднялась сразу, как только откроется экран
  React.useEffect(() => reps.current?.focus(), []);
  return (
    <SafeAreaView testID="safe" style={{ flex: 1 }}>
      <StatusBar barStyle="light-content" />
      <KeyboardAvoidingView testID="avoid" behavior="padding" style={{ flex: 1, justifyContent: "flex-end" }}>
        <TextInput ref={reps} testID="reps" placeholder="повторы" onFocus={() => console.log("фокус в повторах")} />
      </KeyboardAvoidingView>
    </SafeAreaView>
  );
}

Keyboard.addListener("keyboardDidShow", (e) => console.log("клавиатура:", e.endCoordinates.height));
mount(<SetScreen />);
setTimeout(() => {
  console.log("SafeAreaView просит:", inspectBox("safe")?.asked);
  console.log("SafeAreaView получил:", inspectBox("safe")?.padding);
  console.log("KeyboardAvoidingView:", inspectBox("avoid")?.padding);
  console.log("Keyboard.isVisible():", Keyboard.isVisible());
  console.log("Keyboard.metrics:", typeof Keyboard.metrics);
  console.log("StatusBar.currentHeight:", StatusBar.currentHeight);
}, 100);

Строки «клавиатура:» нет, а ошибок нет ни одной — ни у компилятора, ни в консоли. Поле в фокусе, но Keyboard.isVisible() говорит false. SafeAreaView попросил у браузера отступы с четырёх сторон и получил четыре нуля. Начнём с него — вот он весь в react-native-web:

// react-native-web 0.21.2 · exports/SafeAreaView/index.js, сокращено
var cssFunction = function () {
  if (canUseDOM && window.CSS && window.CSS.supports && window.CSS.supports('top: constant(safe-area-inset-top)')) {
    return 'constant';
  }
  return 'env';
}();
var SafeAreaView = React.forwardRef((props, ref) => {
  var style = props.style, rest = _objectWithoutPropertiesLoose(props, _excluded);
  return React.createElement(View, _extends({}, rest, { ref: ref, style: [styles.root, style] }));
});
var styles = StyleSheet.create({
  root: {
    paddingTop: cssFunction + "(safe-area-inset-top)",
    paddingRight: cssFunction + "(safe-area-inset-right)",
    paddingBottom: cssFunction + "(safe-area-inset-bottom)",
    paddingLeft: cssFunction + "(safe-area-inset-left)"
  }
});

Это обычный View с отступами из CSS-функции env() (старому Safari — constant()). Числа за ней знает браузер, и не нулями они бывают только на телефоне с вырезом и только у страницы, которая разрешила рисовать под ним, — viewport-fit=cover в метатеге viewport. Кадр примера на компьютере — не тот случай, отсюда нули. Остальные трое пусты уже по исходнику:

Keyboard.metrics — снова случай из статьи «Что в этой песочнице настоящее», где типы шире любого рантайма: в типах react-native это метод, в предпросмотре — undefined, и вызов упал бы с TypeError. А StatusBar.currentHeight не всегда число и на телефоне: по StatusBar.js react-native 0.86 это высота полосы на Android и null на iOS.

Мёртвое в предпросмотре выдаёт себя не ошибкой, а тишиной: подписка не срабатывает, аргумент проглочен, число — ноль. Ни одна строка примера не вызвала предупреждения, и компилятор тоже промолчал.

У телефона отступы знает система, а не CSS, и получить их можно только у неё. Как это делает сам React Native, видно по SafeAreaView.js из react-native 0.86. Файл короткий:

// react-native 0.86 · Libraries/Components/SafeAreaView/SafeAreaView.js, без шапки и типов
/**
 * @deprecated Use `react-native-safe-area-context` instead. This component will be removed in a future release.
 */
const SafeAreaView = Platform.select({
  ios: require('./RCTSafeAreaViewNativeComponent').default,
  default: View,
});

export default SafeAreaView;

На iOS это нативный компонент, который сам ставит себе отступы. На Android и всюду ещё — просто View, и отступов он не даст вовсе. К тому же компонент помечен устаревшим, с советом брать react-native-safe-area-context. Пометку @deprecated компилятор в предпросмотре знает, но в список ошибок не выносит: редактор просто зачеркнул бы имя.

react-native-safe-area-context — библиотека сообщества, не часть React Native и не пакет Expo. Отступы в ней — не padding одного компонента, а числа для всего приложения. В корне стоит SafeAreaProvider. Его нативный вид сообщает отступы событием onInsetsChange — при запуске и всякий раз, когда они меняются, например при повороте. Провайдер кладёт их в контекст, а экраны читают хуком useSafeAreaInsets() и ставят туда, куда нужно: шапке сверху, панели снизу, строкам списка по бокам. Кто что даёт на трёх платформах:

В проекте на Expo провайдер руками не ставят: это делает expo-router. Вот корень, который он рисует вокруг всего приложения:

// expo-router 57.0.16 · build/ExpoRoot.js, сокращено и переписано из скомпилированного
const INITIAL_METRICS = Platform.OS === 'web' || isTestEnv
  ? {
      frame: { x: 0, y: 0, width: 0, height: 0 },
      insets: { top: 0, left: 0, right: 0, bottom: 0 },
    }
  : undefined;

function ExpoRoot({ wrapper: ParentWrapper = Fragment, ...props }) {
  const wrapper = useMemo(() => ({ children }) => (
    <ParentWrapper>
      <LinkPreviewContextProvider>
        {/* SSR support */}
        <SafeAreaProvider initialMetrics={INITIAL_METRICS}>{children}</SafeAreaProvider>
      </LinkPreviewContextProvider>
    </ParentWrapper>
  ), [ParentWrapper]);
  return <ContextNavigator {...props} wrapper={wrapper} />;
}

Отсюда две вещи для своего провайдера. Он один на всё приложение и стоит выше навигации, поэтому любой экран достаёт отступы, не зная, где он в дереве. И у него есть initialMetrics: на вебе и в тестах expo-router подставляет нули, на телефоне — ничего. Зачем, увидим в следующем разделе.

В предпросмотре не помогла бы и библиотека, будь здесь npm: на вебе она читает те же env() и получила бы те же нули. Чтобы увидеть отступы в работе, нужен телефон. Его в песочнице нет, поэтому телефон изобразит подложка, а провайдер соберём сами.

В подложке появился device — телефон для примеров, как finger был пальцем. Числа у него от iPhone 15: экран 393 × 852 точки, в портрете сверху 59 — полоса состояния с «островом» камеры, — снизу 34, полоса «домой». Отступы он шлёт так же, как нативный вид библиотеки: событием insetsChange с отступами и рамкой, и первое приходит уже после раскладки. rotate() поворачивает телефон.

Провайдер — контекст из части IV (статья «Контекст: данные без пробрасывания») и состояние, которое обновляет событие телефона. Имена и форму берём у библиотеки: SafeAreaProvider с необязательным initialMetrics и хук useSafeAreaInsets(), который без провайдера бросает ошибку с её же текстом. Тогда экран, написанный под наш провайдер, заработает и с настоящим. Прогноз: сколько раз и с какими числами напечатается «экран» — до поворота и после?

type EdgeInsets = { top: number; right: number; bottom: number; left: number };
type Metrics = { insets: EdgeInsets; frame: { x: number; y: number; width: number; height: number } };
declare const device: {
  addListener(type: "insetsChange", listener: (metrics: Metrics) => void): { remove(): void };
  rotate(): void;
};
const { View, Text } = ReactNative;

const SafeAreaInsetsContext = React.createContext<EdgeInsets | null>(null);

interface SafeAreaProviderProps {
  children: React.ReactNode;
  initialMetrics?: Metrics | null;
}

function SafeAreaProvider({ children, initialMetrics }: SafeAreaProviderProps) {
  const [insets, setInsets] = React.useState(initialMetrics?.insets ?? null);
  React.useEffect(() => {
    // отступы шлёт телефон: при запуске и всякий раз, когда они меняются
    const subscription = device.addListener("insetsChange", (metrics) => setInsets(metrics.insets));
    return () => subscription.remove();
  }, []);
  console.log("провайдер:", insets ? "отступы есть" : "отступов ещё нет");
  // так делает и библиотека: с нулями шапка встала бы под вырез
  return <SafeAreaInsetsContext value={insets}>{insets ? children : null}</SafeAreaInsetsContext>;
}

function useSafeAreaInsets(): EdgeInsets {
  const insets = React.use(SafeAreaInsetsContext);
  if (insets === null) {
    throw new Error("No safe area value available. Make sure you are rendering `<SafeAreaProvider>` at the top of your app.");
  }
  return insets;
}

function Workout() {
  const { top, right, bottom, left } = useSafeAreaInsets();
  console.log("экран:", top, right, bottom, left);
  return (
    <View style={{ flex: 1, paddingTop: top, paddingRight: right, paddingBottom: bottom, paddingLeft: left }}>
      <Text>Тренировка</Text>
    </View>
  );
}

mount(
  <SafeAreaProvider>
    <Workout />
  </SafeAreaProvider>,
);
setTimeout(() => { console.log("— повернули"); device.rotate(); }, 100);

Первая отрисовка провайдера прошла без отступов, и экрана в ней не было вовсе: Workout впервые напечатался только после события телефона. Так устроена и библиотека — в её SafeAreaProvider дети рисуются под условием insets != null. Нарисовать экран с нулями было бы хуже: первый кадр поставил бы шапку под вырез, второй сдвинул бы её на 59 точек вниз.

После поворота отступы переехали: сверху 0 — в альбомной ориентации iPhone прячет полосу состояния, — слева и справа по 59, потому что вырез ушёл вбок, а система держит поле с обеих сторон. Полоса «домой» снизу стала тоньше, 21. Экран перерисовался сам: он читает отступы из контекста, и новое событие дошло до него без единой строки кода.

Пустой первый кадр чинит initialMetrics: если отступы известны до первой отрисовки, провайдер кладёт их в состояние сразу. На телефоне их знают заранее — библиотека при запуске синхронно читает константы своего нативного модуля и отдаёт их как initialWindowMetrics. На остальных платформах того же имени файл другой:

// react-native-safe-area-context 5.7.0 · src/InitialWindow.native.ts — телефон
export const initialWindowMetrics = (NativeSafeAreaContext?.getConstants?.()
  ?.initialWindowMetrics ?? null) as Metrics | null;

// src/InitialWindow.ts — все остальные платформы, веб в том числе
export const initialWindowMetrics: Metrics | null = null;

Это тот же приём, что в статье «Одно приложение, три платформы», только в чужом пакете: сборщик для телефона берёт файл с .native, для веба — без. На вебе отступы заранее не знает никто: env() читается из стилей уже нарисованной страницы. Поэтому expo-router там подставляет нули, а рядом стоит комментарий «SSR support»: странице, отрисованной на сервере, экран нужен с первого кадра. Как убрать пустой кадр в своём провайдере — вторая задача.

useSafeAreaInsets без провайдера бросает ошибку, а не отдаёт нули. Нули выглядели бы как «телефон без выреза», и шапка тихо уехала бы под полосу состояния.

На iPhone клавиатура выезжает поверх экрана и ничего в нём не сжимает — ровно туда, где у формы подхода поле повторов и «Записать». На Android это зависит от того, как окно приложения настроено отвечать клавиатуре (android:windowSoftInputMode). От этой же настройки, как предупреждает описание Keyboard.addListener в типах react-native, зависит и то, какие события клавиатуры вообще придут. Как клавиатуру обходит KeyboardAvoidingView, видно по его исходнику:

// react-native 0.86 · Libraries/Components/Keyboard/KeyboardAvoidingView.js, сокращено
componentDidMount() {
  if (Platform.OS === 'ios') {
    this._subscriptions = [
      Keyboard.addListener('keyboardWillHide', this._onKeyboardHide),
      Keyboard.addListener('keyboardWillShow', this._onKeyboardChange),
    ];
  } else {
    this._subscriptions = [
      Keyboard.addListener('keyboardDidHide', this._onKeyboardHide),
      Keyboard.addListener('keyboardDidShow', this._onKeyboardChange),
    ];
  }
}

async _relativeKeyboardHeight(keyboardFrame) {
  const frame = this._frame; // своя рамка из onLayout
  // …
  const keyboardY = keyboardFrame.screenY - (this.props.keyboardVerticalOffset ?? 0);
  // …
  return Math.max(frame.y + frame.height - keyboardY, 0);
}

На iOS он слушает «клавиатура сейчас появится», keyboardWillShow, и сдвигает экран вместе с ней одной анимацией: длительность и кривую берёт из события и отдаёт в LayoutAnimation.configureNext. На Android событий Will нет — в описании addListener так и сказано, — и там он ждёт keyboardDidShow, когда клавиатура уже на месте. Сдвиг — не вся высота клавиатуры, а только то, на сколько она залезла на сам вид: низ вида минус верхний край клавиатуры. Результат уходит в paddingBottom, height или bottom — смотря по behavior.

Нам нужно то же, но числом, а не компонентом: сколько отступить, решает сама форма. У device в подложке есть и клавиатура, show(height) и hide(); её высота в примере условная, 300 точек, — настоящая зависит от телефона и вида клавиатуры. Её addListener той же формы, что у Keyboard из react-native, и мы приписываем её к тому же типу — Pick<KeyboardStatic, "addListener">, как MyAlert к AlertStatic в прошлой статье. На телефоне вместо неё встанет настоящий Keyboard, а хук не заметит подмены. Провайдер из прошлого раздела и FormField из формы подхода — в подложке. Прогноз: какой отступ окажется под формой, пока клавиатура поднята?

type EdgeInsets = { top: number; right: number; bottom: number; left: number };
type KeyboardStatic = import("react-native").KeyboardStatic;
type TextInputProps = import("react-native").TextInputProps;
interface FormFieldProps extends TextInputProps {
  error?: string;
}
declare const fieldKinds: Record<"weight" | "reps", TextInputProps>;
declare function FormField(props: FormFieldProps): React.ReactElement;
declare function SafeAreaProvider(props: { children: React.ReactNode }): React.ReactElement;
declare function useSafeAreaInsets(): EdgeInsets;
declare const device: { keyboard: Pick<KeyboardStatic, "addListener"> & { show(height: number): void; hide(): void } };
const { View, Text } = ReactNative;

// на телефоне здесь встанет Keyboard из react-native: тип у них один
const keyboard: Pick<KeyboardStatic, "addListener"> = device.keyboard;

function useKeyboardHeight() {
  const [height, setHeight] = React.useState(0);
  React.useEffect(() => {
    const subscriptions = [
      keyboard.addListener("keyboardDidShow", (e) => setHeight(e.endCoordinates.height)),
      keyboard.addListener("keyboardDidHide", () => setHeight(0)),
    ];
    return () => subscriptions.forEach((s) => s.remove());
  }, []);
  return height;
}

function SetForm() {
  const insets = useSafeAreaInsets();
  const keyboardHeight = useKeyboardHeight();
  const bottom = insets.bottom + keyboardHeight;
  console.log("отступ под формой:", bottom);
  return (
    <View style={{ flex: 1, justifyContent: "flex-end", paddingBottom: bottom }}>
      <FormField {...fieldKinds.reps} testID="reps" />
      <Text>Записать</Text>
    </View>
  );
}

mount(
  <SafeAreaProvider>
    <SetForm />
  </SafeAreaProvider>,
);
setTimeout(() => { console.log("— клавиатура поднялась"); device.keyboard.show(300); }, 100);
setTimeout(() => { console.log("— клавиатура ушла"); device.keyboard.hide(); }, 200);

В библиотеке для этого есть режим края. Её SafeAreaView принимает edges, и у каждого края свой режим: "additive" прибавляет отступ системы к вашему padding, "maximum" берёт больший из двух, "off" край не трогает:

// react-native-safe-area-context 5.7.0 · src/SafeAreaView.web.tsx
function getEdgeValue(inset: number, current: number, mode: EdgeMode | undefined) {
  switch (mode) {
    case 'maximum':
      return Math.max(current, inset);
    case 'additive':
      return current + inset;
    case 'off':
    default:
      return current;
  }
}

Форме над клавиатурой подходит edges={{ bottom: "maximum" }} и высота клавиатуры в собственном paddingBottom; остальные края при такой записи выключены. Без edges все четыре края работают как "additive" — ровно та ошибка, что в примере. Для клавиатуры тоже есть своя библиотека на случай, когда KeyboardAvoidingView уже мало, — react-native-keyboard-controller. Она стоит на полке React Native и Expo, и там же видно, что Expo Go ей не помеха: её модуль в него уже вшит, а вся цена — обязательный сосед, Reanimated.

В веб-версии «Подхода» на телефоне KeyboardAvoidingView и Keyboard так же глухи, но клавиатуру видно по высоте окна: react-native-web берёт её у visualViewport, а он при открытой клавиатуре меньше. Ради этого его и взяли — так сказано в комментарии в исходнике Dimensions.

Четыре имени из первого раздела не единственные. За эту главу набралось достаточно, чтобы свести всё в одну таблицу. Каждая строка сверена с исходниками react-native-web 0.21.2 и react-native 0.86:

Бывает и наоборот: onDismiss у Modal в предпросмотре зовётся, а на Android не позовётся никогда. Такое место опаснее мёртвого — пример работает, и проверять не хочется.

Строка про LayoutAnimation — повод для последнего прогноза. KeyboardAvoidingView на телефоне анимирует свой отступ через LayoutAnimation.configureNext: тот настраивает анимацию следующей раскладки и зовёт колбэк, когда она закончится. Пресет easeInEaseOut длится 300 мс и в react-native, и в react-native-web. Прогноз: в каком порядке напечатаются три строки?

const { LayoutAnimation } = ReactNative;

console.log("до");
LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut, () => console.log("анимация закончилась"));
console.log("после");

«Конец анимации» пришёл раньше, чем configureNext вернул управление. В react-native-web за ним стоит UIManager.configureNextLayoutAnimation, и тело у него в одну строку — onAnimationDidEnd(). Анимации нет, а конец есть. Код, который по этому колбэку, скажем, прокручивает к полю, в предпросмотре сработает мгновенно, а на телефоне — когда раскладка доанимируется.

Что это значит для «Подхода». Библиотека безопасных зон работает на всех трёх платформах: на телефоне у неё нативный провайдер, на вебе — те же env(), и в мобильном браузере они не нулевые, если страница разрешила viewport-fit=cover. Поэтому в проекте стоит она, а провайдер ей ставит expo-router. Наш провайдер остаётся предпросмотру — и чертежом: экран, написанный под useSafeAreaInsets, одинаково работает с обоими. Клавиатуру на телефоне обходит KeyboardAvoidingView или наш хук поверх настоящего Keyboard; в веб-версии оба глухи, и там остаётся высота окна из плашки выше.

Провайдер, хук useKeyboardHeight и device остаются в подложке этой статьи. Следующая глава, про навигацию, начинает со своей: экранов станет больше одного, и важнее станет не то, что у экрана по краям, а то, как экраны сменяют друг друга. Приём при этом не пропадёт. Экран, написанный под useSafeAreaInsets(), в проекте получит отступы от настоящего провайдера, а его руками не ставят: это делает expo-router.