Что в этой песочнице настоящее

Начнём с вопроса, который приложение задаёт само себе: на чём я запущено? Ответ хранит Platform с нижнего этажа, из React Native. Platform.OS — имя платформы, Platform.Version — версия системы, Platform.select выбирает значение по платформе. Рядом лежит NativeModules — реестр, через который JavaScript находит нативный код, скомпилированный в приложение. Прогноз: что напечатают пять строк? Особенно третья — у select в ней ключи только для iOS и Android.

const { Platform, NativeModules } = ReactNative;

console.log("платформа:", Platform.OS);
console.log("версия системы:", Platform.Version);
console.log("отступ шапки:", Platform.select({ ios: 44, android: 24 }));
console.log("отступ с запасным:", Platform.select({ ios: 44, android: 24, default: 16 }));
console.log("нативные модули:", Object.keys(NativeModules));

Песочница называет себя честно — web. Это не телефон и не эмулятор, а react-native-web: те же компоненты, нарисованные в HTML. Версия системы — константа "0.0.0" из геттера react-native-web: у браузера нет ни уровня API Android, ни версии iOS. На телефоне здесь было бы одно из двух, и типы это знают: у Android Version — число, у iOS — строка.

Platform.select в react-native-web умещается в одну строку: obj => "web" in obj ? obj.web : obj.default. Нет ни web, ни default — выходит undefined. Компилятор такое предвидел: для вызова без default в типах есть отдельная перегрузка, и она возвращает number | undefined. NativeModules — объект с единственным ключом UIManager, и тот написан на JavaScript: нативного кода в предпросмотре нет ни строчки. Что лежит в этом реестре на телефоне и как в нём ищут модули — статья «Модуль — это запись в реестре» в главе 9.

Платформенная ветка есть в любом приложении, и самая частая — отступ шапки под вырез экрана. Напишем её двумя привычными способами и спросим у браузера, какой отступ получила каждая шапка. Спрашивает hostStyle — помощник из подложки прошлой статьи: сам пример в DOM не заглядывает. Прогноз: какие два значения он напечатает?

declare function hostStyle(testID: string, prop: string): string | null;
const { View, Text, Platform, StyleSheet } = ReactNative;

const styles = StyleSheet.create({
  // шапка под вырез экрана: на iOS он выше, чем на Android
  byTernary: { paddingTop: Platform.OS === "ios" ? 44 : 24, backgroundColor: "#2a2735" },
  bySelect: { paddingTop: Platform.select({ ios: 44, android: 24 }), backgroundColor: "#2a2735" },
  title: { color: "#fff", fontSize: 18, padding: 12 },
});

function TwoHeaders() {
  return (
    <View style={{ gap: 8 }}>
      <View testID="ternary" style={styles.byTernary}>
        <Text style={styles.title}>Тренировка</Text>
      </View>
      <View testID="select" style={styles.bySelect}>
        <Text style={styles.title}>Тренировка</Text>
      </View>
    </View>
  );
}

mount(<TwoHeaders />);
setTimeout(() => {
  console.log("тернарник:", hostStyle("ternary", "padding-top"));
  console.log("select:", hostStyle("select", "padding-top"));
}, 100);

Два способа — два разных промаха. Тернарник знает две платформы: всё, что не iOS, для него Android, и веб получил отступ Android. select без web и default не вернул ничего, и отступа нет вовсе. На телефоне оба способа дают одно и то же и расходятся ровно там, где платформ больше двух. А у проекта на Expo их три: iOS, Android и веб-версия. Поэтому default в select — не педантизм, а третья платформа, о которой вспомнили заранее. Разводить платформы можно и файлами вместо веток — это статья «Одно приложение, три платформы» во второй главе.

Platform в типах — размеченное объединение из части III с меткой OS. Поэтому Platform.isPad компилятор не пропустит: у Android такого поля нет. После проверки Platform.OS === "ios" — пропустит.

Теперь попросим у песочницы то, чего у браузера точно нет. «Подход» умеет снимать технику упражнения на видео, а на Android камере нужно разрешение, которое спрашивают у пользователя системным диалогом. Для этого в пакете react-native есть PermissionsAndroid: request показывает диалог и возвращает промис со статусом "granted", "denied" или "never_ask_again". Код ниже написан так, как его пишут в проекте, — с объяснением, которое Android покажет пользователю, если тот уже однажды отказал.

Прогноз: сколько диагностик покажет компилятор и что будет в консоли после нажатия?

const { Pressable, Text, PermissionsAndroid } = ReactNative;

async function askCamera() {
  const status = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA, {
    title: "Камера",
    message: "Снять технику упражнения на видео",
    buttonPositive: "Разрешить",
  });
  console.log("камера:", status);
}

function RecordButton() {
  const onPress = () => {
    console.log("нажали «Снять подход»");
    askCamera();
  };
  return (
    <Pressable testID="record" onPress={onPress}>
      <Text>Снять подход</Text>
    </Pressable>
  );
}

mount(<RecordButton />);
setTimeout(() => fireEvent.press("record"), 100);

Диагностик ноль. В типах react-native 0.86 PermissionsAndroid объявлен целиком: request, PERMISSIONS.CAMERA, тип объяснения Rationale с обязательными title, message и buttonPositive, — и наш объект с ним сошёлся. А запуск упал: PermissionsAndroid здесь undefined, и чтение его request даёт TypeError. Упало внутри async-функции, поэтому ошибка пришла отклонённым промисом, которого никто не ждал, — это «Uncaught (in promise)» из статьи «Ошибки в промисах». Обработчик нажатия отработал до конца, строка «нажали» успела напечататься, и кнопка на экране по-прежнему жива.

Причина — в том, из чего сделана глобаль ReactNative. Тип у неё — typeof import("react-native"), настоящие типы пакета. А значение — react-native-web, где PermissionsAndroid нет, как нет и других модулей, которым в браузере нечего делать. Деструктуризация получает имя, которое пообещали типы, и значение, которое нашлось в рантайме. Это тот же случай, что в статье «.d.ts и @types: пакет без типов» из части III: объявление — обещание о рантайме, а не его проверка, и здесь выполнять обещание некому.

Граница предпросмотра — заодно граница веб-версии вашего приложения. Собирая её, Expo подменяет react-native на react-native-web: в @expo/cli 57 это словарь aliases.web в файле withMetroMultiPlatform.js. Это тот же react-native-web, что работает в песочнице, и PermissionsAndroid в нём тоже нет.

А на телефоне? Типы react-native одни на все платформы: в них лежат и API только для Android, и API только для iOS. На Android request покажет диалог. На iPhone объект PermissionsAndroid существует, но request первым делом проверяет платформу:

// react-native 0.86.0, Libraries/PermissionsAndroid/PermissionsAndroid.js
// сокращено: типы Flow убраны, строки приведены к двойным кавычкам
async request(permission, rationale) {
  if (Platform.OS !== "android") {
    console.warn("\"PermissionsAndroid\" module works only for Android platform.");
    return Promise.resolve(this.RESULTS.DENIED);
  }
  invariant(NativePermissionsAndroid, "PermissionsAndroid is not installed correctly.");
  // …дальше объяснение для пользователя и системный диалог
}

Выходит три рантайма и три исхода: на Android — диалог, на iPhone — предупреждение в консоли и честное "denied", в предпросмотре и в веб-версии — TypeError. И всё это против одних и тех же типов, где ни одна строка не намекает на разницу. Сам Platform компилятор по платформам различает, а PermissionsAndroid для него просто есть. Поэтому проверка платформы перед платформенным API — ваша работа, и компилятор о ней не напомнит. Её вы допишете в задаче к статье, а как спрашивать разрешения на обеих платформах и жить с отказом — статья «Разрешения: спросить, получить отказ, жить с ним» в главе 9.

PermissionsAndroid такой не один. Чтобы не ловить эти имена по одному, соберём проверку: пройдём по списку и спросим у рантайма, что лежит под каждым именем. Список типизирован как keyof typeof ReactNative, так что попасть в него могут только имена из типов. Последней строкой спросим имя, которого в типах нет. Прогноз: сколько строк скажут «нет в рантайме» и сколько диагностик покажет компилятор?

type RNName = keyof typeof ReactNative;

// список типизирован ключами типов: опечатку в имени поймает компилятор, а не запуск
function probe(names: RNName[]) {
  for (const name of names) {
    const value: unknown = ReactNative[name];
    console.log(name + ":", value === undefined ? "нет в рантайме" : typeof value);
  }
}

probe([
  "Platform",
  "Pressable",
  "Alert",
  "PermissionsAndroid",
  "ToastAndroid",
  "ActionSheetIOS",
  "PlatformColor",
  "useAnimatedValue",
  "TurboModuleRegistry",
]);
console.log("CheckBox:", typeof ReactNative.CheckBox);

Шесть имён из девяти есть только в типах, а десятое, CheckBox, — только в рантайме, и компилятор заметил лишь его: в react-native-web он остался, а из React Native давно убран. Остальные шесть промахов прошли молча. Три имени нашлись, и среди них Alert — к нему вернёмся ниже.

Посчитаем целиком — по тем типам, что возит с собой песочница. У модуля react-native в них 116 имён-значений, в react-native-web 0.21.2 — 61, общих — 52. Только в типах — 64 имени, и 37 из них нет даже в рантайме телефона: это служебные имена самих объявлений вроде ViewBase и TextComponent. Остальные 27 — настоящие API телефона, которых нет в предпросмотре. Только в рантайме — 9: CheckBox и Picker, веб-помощники вроде render и unmountComponentAtNode и VirtualizedList, который есть и на телефоне: его типы react-native реэкспортирует из отдельного пакета @react-native/virtualized-lists, а оснастка песочницы этот пакет не возит — потому имя и не попало в наши 116.

Третий вид самый коварный: имя есть и в типах, и в рантайме, а поведение разное. Alert проверка нашла, и это действительно класс со статическим alert. Но «есть» ещё не значит «работает». Таких мест в react-native-web немного, и каждое разберём там, где до него дойдём:

probe стоит держать под рукой: имя из документации React Native сначала покажите ей, а потом зовите. «Нет в рантайме» значит, что в предпросмотре и в веб-версии проекта этот вызов упадёт, а на телефоне его судьбу решит платформа.

Граница проходит не только по модулям. В коде на React Native часто встречается __DEV__ — флаг отладочной сборки: показать плашку «dev», включить подробный лог. Типы react-native объявляют его глобальной константой в src/types/globals.d.ts, с примером if (__DEV__) console.log(…) прямо в комментарии. Прогноз: что напечатает пример и появится ли на экране «Подход»?

const { Text } = ReactNative;

console.log("проверяем сборку");
if (__DEV__) {
  console.log("отладочная: покажем плашку dev");
}
mount(<Text>Подход</Text>);
console.log("экран смонтирован");

Диагностик ноль, в консоли ReferenceError, экран пуст: исключение оборвало пример раньше mount. На этот раз модуль ни при чём: __DEV__ — не экспорт react-native, а переменная, которую объявляет сборщик. Metro вставляет в начало каждого бандла прелюдию, и начинается она с объявления переменных:

// metro 0.84.5, src/lib/getPreludeCode.js — сокращено
const vars = [
  "__BUNDLE_START_TIME__=globalThis.nativePerformanceNow?nativePerformanceNow():Date.now()",
  `__DEV__=${String(isDev)}`,
  ...formatExtraVars(extraVars),
  "process=globalThis.process||{}",
  // …и служебные переменные самого Metro
];
return `var ${vars.join(",")};${processEnv(isDev ? "development" : "production")}`;

Metro собирает и приложение для телефона, и веб-версию проекта на Expo, поэтому в проекте __DEV__ есть на всех трёх платформах: true в отладке, false в релизе. В песочнице Metro нет: рантайм учебника собран esbuild, а пример выполняется сам по себе, без бандла, — и прелюдии нет ни у того, ни у другого. Это граница другого рода: не «телефон или браузер», а «проект или песочница». В примерах части __DEV__ не встретится, а в своём проекте пользуйтесь им свободно.

Соберём опись: у каждой части песочницы — откуда она и насколько она настоящая. По ней дальше удобно взвешивать вывод любого примера.

Пакетов Expo в песочнице нет вовсе. Пример — один файл без npm и сборщика, и всё, что у него есть, лежит в глобалях ReactNative и React. Как Expo находит нативный код и почему этот путь в песочнице обрывается на TurboModuleRegistry, которого, как показала probe, здесь нет, — глава 9. Поэтому expo-router, expo-secure-store, expo-notifications и сервисы EAS приходят в часть листингами и записями.

Оговорки дальше в части бывают четырёх видов, и все они — про то, что вы увидели в этой статье:

Следующая статья — последняя в главе. Заведём свой проект на Expo, запустим Metro и откроем первый экран на телефоне, а стек разложим на этажи: что здесь React Native, а что Expo.