Reanimated и gesture-handler: как это читать

Первая причина — та же, что у пакетов Expo: пример — один файл без npm и сборщика, и у него есть только глобали ReactNative и React. Но это причина песочницы, а не библиотеки: react-native-web — тоже npm-пакет, и в песочницу он попал, потому что его собрали заранее. Попробуем так же собрать Reanimated — тем же esbuild, которым собран рантайм предпросмотра, с той же подменой react-native на react-native-web. Файл app.js — одна строка import "react-native-reanimated";, пакеты — из мобильного приложения автора: Reanimated 4.5.1 и react-native-worklets 0.10.1. Сначала соберём так, как собирают для телефона, — без платформенных расширений:

$ esbuild app.js --bundle --alias:react-native=react-native-web \
    --main-fields=react-native,browser,module,main --loader:.js=jsx \
    --define:process.env.NODE_ENV='"development"' --define:__DEV__=true \
    --outfile=/dev/null --log-level=info

Сборка встала на строке, знакомой по главе 1: TurboModuleRegistry.get('ReanimatedModule') из src/specs/NativeReanimatedModule.ts. Это нативная половина Reanimated — модуль на C++, который на телефоне поднимает второй рантайм и отдаёт JS ручки к нему. Реестра турбомодулей в react-native-web нет вовсе — это показала probe в статье «Что в этой песочнице настоящее». Теперь соберём так, как собирает веб-версию Expo: с платформенными расширениями, когда файл .web.ts берётся раньше обычного, — тот же резолвер, что в статье главы 2 про файлы платформ:

$ esbuild app.js --bundle --alias:react-native=react-native-web \
    --resolve-extensions=.web.tsx,.web.ts,.web.js,.tsx,.ts,.js,.json \
    --main-fields=react-native,browser,module,main --loader:.js=jsx \
    --define:process.env.NODE_ENV='"development"' --define:__DEV__=true \
    --outfile=/dev/null --log-level=info

Собралось. Для веба у Reanimated свои файлы, и в одном из них прямо написано, зачем он заведён:

// react-native-reanimated 4.5.1, src/ReanimatedModule/index.web.ts (с сокращениями)
'use strict';
// this file was created to prevent NativeReanimated from being included in the web bundle
import { createJSReanimatedModule } from './js-reanimated';

export const ReanimatedModule = createJSReanimatedModule();

Значит, точнее так: собранный как для телефона, Reanimated падает на TurboModuleRegistry, а собранный для веба собирается — но это другой Reanimated. В нём нет ровно того, ради чего библиотеку берут и о чём эта статья:

Последняя строка таблицы — третья стена. Предпросмотр компилирует пример TypeScript'ом, Babel с плагином worklet-ов в нём не участвует. Веб-сборка Reanimated это переживает, но только если хуку дать массив зависимостей вручную; иначе отладочная сборка бросает прямо в useAnimatedStyle:

// react-native-reanimated 4.5.1, src/hook/useAnimatedStyle.ts (с сокращениями)
let inputs = Object.values(updater.__closure ?? {});
if (SHOULD_BE_USE_WEB) {
  if (!inputs.length && dependencies?.length) {
    // let web work without a Babel plugin
    inputs = dependencies;
  }
  if (
    __DEV__ &&
    !inputs.length &&
    !dependencies &&
    !isWorkletFunction(updater)
  ) {
    throw new Error(
      `[Reanimated] \`useAnimatedStyle\` was used without a dependency array or Babel plugin. Please explicitly pass a dependency array, or enable the Babel plugin.
For more, see the docs: …`
    );
  }
}

Здесь видна вторая работа замыкания: __closure от плагина служит хуку и списком зависимостей. В вебе второго потока нет, и хватает перечислить зависимости руками, как у эффекта из части IV. На телефоне руками не обойтись: без плагина функция не станет worklet-ом и не уедет вовсе. А второго JS-рантайма в том потоке, где рисуется экран, браузер не даёт совсем: там живёт сама страница, а второй поток у неё один — Worker, который рисовать не умеет. Поэтому Reanimated здесь не исполняется: собранный для телефона — не собирается, собранный для веба — показал бы библиотеку без второго рантайма, то есть без предмета статьи.

В своём проекте на Expo всё это ставится одной командой, а плагин сборки подключается сам:

$ npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler

// babel-preset-expo 57.0.8, build/configs/expo.js (с сокращениями)
// Automatically add worklets or reanimated plugin when package is installed.
if (options.worklets !== false && options.reanimated !== false) {
    const workletsPluginPath = (0, resolveModule_1.resolveModule)(api, 'react-native-worklets/plugin');
    if (workletsPluginPath) {
        plugins.push([require(workletsPluginPath)]);
    }
}

Пресет Expo ищет react-native-worklets среди установленных пакетов и, если нашёл, ставит его плагин в сборку. Поэтому в babel.config.js проекта на Expo плагина обычно не видно, а работает он всегда. И ещё одно требование записано в исходнике Reanimated строкой ошибки: «Reanimated 4 supports only the React Native New Architecture and web.» — старой архитектуры четвёртая версия не поддерживает.

Вот строка подхода из статьи про жесты, переписанная на Reanimated и gesture-handler. Поведение то же: жест берётся только горизонтальный, после 10 точек; строка не уезжает правее нуля; после отпускания пружина везёт её назад или за край, и тогда подход удаляется. Прочитайте её сначала сами: какие функции, по-вашему, будут выполняться не в JS-потоке?

import { Text, View } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";
import { scheduleOnRN } from "react-native-worklets";

const WIDTH = 300;

interface SwipeRowProps {
  title: string;
  onDelete(): void;
}

export function SwipeRow({ title, onDelete }: SwipeRowProps) {
  const x = useSharedValue(0);
  const pan = Gesture.Pan()
    // горизонтальный жест — строке, вертикальный — списку
    .activeOffsetX([-10, 10])
    .failOffsetY([-10, 10])
    .onUpdate((e) => {
      x.value = Math.min(0, e.translationX);
    })
    .onEnd((e) => {
      const gone = e.translationX < -WIDTH / 3;
      x.value = withSpring(gone ? -WIDTH : 0, {}, (finished) => {
        // onDelete — обычная функция JS: её вызов уезжает в JS-поток
        if (finished && gone) scheduleOnRN(onDelete);
      });
    });
  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }));

  return (
    <View style={{ width: WIDTH, backgroundColor: "#e4572e" }}>
      <GestureDetector gesture={pan}>
        <Animated.View style={[{ padding: 12, backgroundColor: "#e6e1d6" }, style]}>
          <Text>{title}</Text>
        </Animated.View>
      </GestureDetector>
    </View>
  );
}

Директивы "worklet" здесь нет ни одной, а плагин нашёл четыре worklet-а. Вот его настоящий вывод для этого файла — сначала тексты, которые он кладёт в сборку, потом то, во что превратился колбэк onUpdate:

// swipe-row.tsx после Babel-плагина react-native-worklets 0.10.1, сборка production (с сокращениями)
const WIDTH = 300;
const _worklet_10567899002777_init_data = {
  code: "function swipeRowTsx1(e){const{WIDTH,x,withSpring,scheduleOnRN,onDelete}=this.__closure;const gone=e.translationX<-WIDTH/3;x.value=withSpring(gone?-WIDTH:0,{},function(finished){if(finished&&gone)scheduleOnRN(onDelete);});}"
};
const _worklet_9739407165078_init_data = {
  code: "function swipeRowTsx2(e){const{x}=this.__closure;x.value=Math.min(0,e.translationX);}"
};
const _worklet_5253186493556_init_data = {
  code: "function swipeRowTsx3(finished){const{gone,scheduleOnRN,onDelete}=this.__closure;if(finished&&gone)scheduleOnRN(onDelete);}"
};
const _worklet_83738350599_init_data = {
  code: "function swipeRowTsx4(){const{x}=this.__closure;return{transform:[{translateX:x.value}]};}"
};
export function SwipeRow({
  title,
  onDelete
}) {
  const x = useSharedValue(0);
  const pan = Gesture.Pan()
  // горизонтальный жест — строке, вертикальный — списку
  .activeOffsetX([-10, 10]).failOffsetY([-10, 10]).onUpdate(function swipeRowTsx2Factory({
    _worklet_9739407165078_init_data,
    x
  }) {
    const swipeRowTsx2 = function (e) {
      x.value = Math.min(0, e.translationX);
    };
    swipeRowTsx2.__closure = {
      x
    };
    swipeRowTsx2.__workletHash = 9739407165078;
    swipeRowTsx2.__initData = _worklet_9739407165078_init_data;
    return swipeRowTsx2;
  }({
    _worklet_9739407165078_init_data,
    x
  })).onEnd(function swipeRowTsx1Factory({
  // … так же обёрнуты колбэк onEnd, колбэк withSpring внутри него и функция для useAnimatedStyle

Четыре текста — четыре функции, которые уедут в UI-рантайм: колбэк onEnd (swipeRowTsx1), колбэк onUpdate (swipeRowTsx2), колбэк пружины внутри onEnd (swipeRowTsx3) и функция стиля (swipeRowTsx4). Устройство знакомо по прошлой статье: __closure с внешними именами и __initData.code с текстом, где эти имена читаются из this.__closure. Новое — как плагин их нашёл. Директивы нет, и он узнал функции по месту, куда их передали. Таких мест у плагина список:

Отсюда правило чтения: во втором рантайме выполняется функция, переданная в одно из этих мест, вместе со всем, что она вызывает изнутри. Остальной компонент — вызовы хуков, сборка объекта жеста, разметка — обычный React в JS-потоке. Место решает всё: та же стрелка, переданная в useEffect, осталась бы обычной функцией.

Теперь прочитаем замыкания — что поедет с каждой функцией. У onUpdate одно имя, x. У onEnd пять: WIDTH, x, withSpring, scheduleOnRN и onDelete. Число WIDTH уедет копией, снятой однажды, как порог в прошлой статье. withSpring в исходнике Reanimated сам помечен директивой "worklet" и переезжает целиком. x — shared value, о нём следующий раздел. А onDelete — обычная функция JS из родителя, и перенести её нельзя по той же причине, по которой postMessage не принял функцию: текста в сборке у неё нет, окружение — в чужой куче. Исключения при переносе не будет: react-native-worklets кладёт на её место заглушку — «удалённую функцию». Но вызвать заглушку в UI-рантайме нельзя, она бросает «[Worklets] Tried to synchronously call a Remote Function…» — это вторая задача. Её можно только отдать scheduleOnRN, и тот поставит вызов в очередь JS-потока — как второй поток нашей миниатюры ставил в очередь свой ответ.

И последнее, что видно из вывода: объект жеста собирается в каждой отрисовке, а с ним и worklet-ы. Значит, onDelete в их замыкании — из этой отрисовки. Ловушки второй задачи статьи про жесты — колбэков, навсегда видящих первую отрисовку, — здесь нет: она держалась на PanResponder, созданном однажды.

В замыкании onUpdate лежит x, и x.value = … пишет в него из UI-рантайма, а функция стиля каждый кадр читает оттуда же. Прошлая статья кончилась тем, что копия замыкания снимается однажды: порог, поменянный после первой отправки, до второго потока не доходил. Будь x числом, функция стиля так и видела бы ноль. Shared value устроен иначе: у значения один хозяин, живёт он во втором рантайме, а в замыкание уезжает не значение, а то, по чему хозяина найти.

Соберём это поверх второго потока из прошлой статьи — он лежит в подложке вместе с runOnWorker и worklet. Хозяева живут в памяти второго потока, в таблице hosts; этот поток её не видит, поэтому она только объявлена. put и take уезжают туда текстом и трогают хозяина на месте. Возьмём задачу про порог из настроек из прошлой статьи — теперь порог будет shared value. Прогноз: что ответит второй поток после writeShared, ответа от которой никто не ждал, и что прочтёт этот поток?

// второй поток, runOnWorker и worklet — в подложке примера
declare function runOnWorker<A extends unknown[], R>(fn: (...args: A) => R, ...args: A): Promise<Awaited<R>>;
declare function worklet<F extends Function>(fn: F, closure: Record<string, unknown>): F;
// память второго потока: хозяева shared value живут там и только там
declare var hosts: Record<string, number>;

interface Shared {
  key: string;
}
// эти две функции уезжают во второй поток и трогают хозяина на месте
const put = (key: string, value: number) => {
  globalThis.hosts ??= {};
  hosts[key] = value;
};
const take = (key: string) => hosts[key];

function sharedValue(key: string, initial: number): Shared {
  runOnWorker(put, key, initial);
  // отсюда видно только имя хозяина
  return { key };
}
// запись — сообщение хозяину, ответа не ждём; чтение — вопрос хозяину
const writeShared = (sv: Shared, value: number) => void runOnWorker(put, sv.key, value);
const readShared = (sv: Shared) => runOnWorker(take, sv.key);

const limit = sharedValue("swipe", 100);
// в замыкание уезжает адрес хозяина, а не число
const decide = worklet((dx: number) => (dx < -hosts[limit.key] ? "удаляем" : "назад"), { limit });

async function scenario() {
  console.log("порог 100, свайп -150:", await runOnWorker(decide, -150));
  writeShared(limit, 200);
  console.log("порог 200, свайп -150:", await runOnWorker(decide, -150));
  console.log("порог, прочитанный отсюда:", await readShared(limit));
}
scenario();

Второй ответ — «назад»: второй поток решил по новому порогу. Копия замыкания по-прежнему снята однажды, но в ней { key: "swipe" } — имя хозяина, а число worklet берёт у хозяина при каждом вызове. И запись без await успела раньше решения: сообщения одному потоку выполняются в том порядке, в каком отправлены, и запись встала в очередь первой. Прочитать значение отсюда можно только вопросом хозяину — и ответ пришёл сообщением.

Настоящий shared value в Reanimated 4.5 устроен так же, только хозяин живёт в UI-рантайме, а в JS-потоке — гость. makeMutableNative создаёт его через createShareable(UIRuntimeId, …) из react-native-worklets, а свойство value у гостя описано так:

// react-native-reanimated 4.5.1, src/mutables.ts — гость (с сокращениями)
value: {
  get() {
    // …
    if (globalThis.__RUNTIME_KIND !== 1 || dirtyFlag === undefined) {
      latest = mutable.getSync();
    } else if (dirtyFlag.getBlocking()) {
      const uiValueGetter = (svArg: Mutable<TValue>) =>
        runOnUISync((sv) => {
          sv.setDirty?.(false);
          return sv.value;
        }, svArg);
      latest = uiValueGetter(mutable as Mutable<TValue>);
    }
    return latest;
  },
  set(newValue) {
    if (globalThis.__RUNTIME_KIND === 1) {
      checkInvalidWriteDuringRender();
      scheduleOnUI(() => {
        mutable.value = newValue;
      });
    } else {
      mutable.setAsync(newValue);
    }
  },
},

// react-native-worklets 0.10.1, src/memory/shareableGuestUnpacker.native.ts
shareableGuest.getSync = () => {
  return runOnRuntimeSyncFromId(hostId, get);
};

__RUNTIME_KIND === 1 — это JS-поток React Native. Запись оттуда — scheduleOnUI: присваивание уезжает к хозяину и выполнится, когда до него дойдёт очередь UI-рантайма, — как наш writeShared. Чтение — единственное место, где Reanimated расходится с миниатюрой. getSync и runOnUISync синхронные: JS-поток останавливается и ждёт, пока UI-рантайм выполнит функцию-читателя и вернёт число (с флагом USE_SYNCHRONIZABLE_FOR_MUTABLES — только когда значение помечено изменённым, иначе отдаётся последнее прочитанное). Миниатюре так нельзя: синхронного ответа у Worker нет, поэтому readShared отдаёт промис.

Для чтения кода отсюда три следствия. x.value в JS-потоке — не чтение поля, а синхронная поездка в другой рантайм; поэтому его не читают при отрисовке, и отладочная сборка это ловит — третья задача. Изменение shared value отрисовку не вызывает: React о нём не узнаёт, как не узнавал об Animated.Value. И x.value = withSpring(…) присваивает не число, а анимацию: объект, который хозяин сам выполняет кадр за кадром прямо в UI-рантайме. Прошлую анимацию того же значения присваивание отменяет само — поэтому в строке нет stopAnimation, который версия на PanResponder звала при захвате:

// react-native-reanimated 4.5.1, src/valueSetter.ts (с сокращениями)
const previousAnimation = mutable._animation;
if (previousAnimation) {
  mutable._animation = null;
  if (!previousAnimation.finished) {
    previousAnimation.cancelled = true;
    previousAnimation.callback?.(false);
  }
}

Колбэк отменённой анимации получает false. Для строки подхода это значит: схватили строку, пока пружина везла её за край, — onUpdate присвоил новое значение, пружина отменена, её колбэк пришёл с finished, равным false, и подход не удалится.

Теперь можно ответить на вопрос, которым кончилась статья про жесты. Там строку вёл setValue из колбэка PanResponder, а колбэк выполнялся в JS-потоке: занят поток — строка стоит. Нативный драйвер не выручал: он увозит только описание из своего словаря, а жест на ответчике рождается в JS. Проследим касание в строке на Reanimated.

JS-потока в этой цепочке нет ни на одном шаге. Пусть он занят разбором ответа — строка всё равно едет за пальцем. В него попадает только то, что вы туда отправили сами: scheduleOnRN(onDelete) в конце пружины. Если JS-поток занят, подход исчезнет из списка позже, но строка к этому моменту уже за краем, и палец этого не заметит.

Второй шаг видно в исходнике gesture-handler. Раздаёт события колбэкам функция, которая сама — worklet:

// react-native-gesture-handler 2.32.0, src/handlers/gestures/GestureDetector/useAnimatedGesture.ts (с сокращениями)
function runWorklet(
  type: CALLBACK_TYPE,
  gesture: HandlerCallbacks<Record<string, unknown>>,
  event: GestureStateChangeEvent | GestureUpdateEvent | GestureTouchEvent,
  ...args: unknown[]
) {
  'worklet';
  const handler = getHandler(type, gesture);
  if (gesture.isWorklet[type]) {
    // @ts-ignore Logic below makes sure the correct event is send to the
    // correct handler.
    handler?.(event, ...args);
  } else if (handler) {
    console.warn(tagMessage('Animated gesture callback must be a worklet'));
  }
}
// …
  const event = Reanimated.useEvent(
    callback,
    ['onGestureHandlerStateChange', 'onGestureHandlerEvent'],
    needsRebuild
  );

Колбэк, который не стал worklet-ом, отсюда не вызвать — он получит только предупреждение. Если нужно наоборот, у жеста есть модификатор .runOnJS(true): тогда колбэки выполняются в JS-потоке, и строка снова ждёт его, как на PanResponder. А если колбэки случайно смешались — часть worklet-ы, часть нет, — отладочная сборка печатает ошибку «Some of the callbacks in the gesture are worklets and some are not…».

Первая статья главы начиналась с провала: CSS-переход transition в стиле React Native на телефоне не двигает ничего — ключа нет в списке атрибутов, и телефон молча его отбрасывает, а едет полоса только в предпросмотре, силами браузера. В Reanimated 4 этот стиль вернулся. Компоненты Reanimated — Animated.View и всё, что сделано createAnimatedComponent, — понимают в стиле свойства CSS-переходов, и полосу отдыха можно написать почти как в вебе:

import Animated from "react-native-reanimated";

// полоса отдыха из первой статьи главы: переход объявлен в стиле, как в CSS
<Animated.View
  style={{
    height: 12,
    width: resting ? 0 : 300,
    backgroundColor: "#e4572e",
    transitionProperty: "width",
    transitionDuration: 1000,
    transitionTimingFunction: "linear",
  }}
/>

Имена — из src/css/types/transition.ts: transitionProperty, transitionDuration, transitionTimingFunction, transitionDelay, есть и сокращение transition; длительность — число миллисекунд или строка вроде "300ms". Обычному View из react-native эти ключи по-прежнему ничего не говорят. И переход тянет ширину — то, чего не умел нативный драйвер: его список держал только свойства, которые не трогают раскладку. У переходов Reanimated список свой, в C++ (Common/cpp/reanimated/CSS/InterpolatorRegistry.cpp), и width с height в нём есть. Кадры такого перехода считает C++ Reanimated, а не ваш код: читается он так же, как описание нативного драйвера, — данные, отданные один раз.

Осталась сводка: три среды, в которых может оказаться строка подхода.

На телефоне иначе: колбэки жеста и функция стиля выполняются в UI-рантайме в главном потоке, и занятый JS-поток строку не останавливает. В веб-версии на Expo второго рантайма нет: жест, стиль и ваш код делят один поток. Плавность Reanimated проверяют только на телефоне.

// shared value из статьи «Reanimated и gesture-handler: как это читать».
// Хозяин значения живёт во втором потоке; отсюда видно только его имя,
// а запись и чтение — сообщения хозяину.
function putShared(key, value) {
  globalThis.hosts = globalThis.hosts || {};
  hosts[key] = value;
}
function takeShared(key) {
  return hosts[key];
}
function sharedValue(key, initial) {
  runOnWorker(putShared, key, initial);
  return { key: key };
}
// запись — сообщение хозяину, ответа не ждём
function writeShared(sv, value) {
  runOnWorker(putShared, sv.key, value);
}
// чтение отсюда — вопрос хозяину и ответ промисом
function readShared(sv) {
  return runOnWorker(takeShared, sv.key);
}