FlatList: та же идея, доведённая до конца

У нашего окна были data, renderRow, две высоты и запас. У FlatList набор почти тот же. data — массив упражнений. renderItem — функция, которая рисует одну строку. keyExtractor — функция, которая по элементу отдаёт ключ строки, строкой. key внутри renderItem писать не нужно: ключ FlatList ставит сам, на обёртку строки — ячейку. А высоту строки по умолчанию не спрашивает: меряет сам, когда строка уже нарисована.

Одно отличие от нашего renderRow: в renderItem приходит не сам элемент, а объект. Прогноз: сколько у него полей — и сколько строк нарисует первая отрисовка, если в справочнике тысяча упражнений, а в рамку влезает четыре?

const { FlatList, View, Text, StyleSheet } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

const catalog = makeCatalog(1000);
const rendered = new Set<number>();
let fields = "";

function renderExercise(info: { item: Exercise; index: number }) {
  if (!fields) fields = Object.keys(info).join(", ");
  rendered.add(info.index);
  return <Text style={styles.row}>{info.item.name}</Text>;
}

function Catalog() {
  // эффект родителя срабатывает, когда закоммичено всё дерево, список тоже
  React.useEffect(() => console.log("строк в первой отрисовке:", rendered.size, "| поля аргумента:", fields), []);
  return (
    // высоту списку отдаёт обёртка — на телефоне её так отдаёт экран
    <View style={styles.frame}>
      <FlatList data={catalog} keyExtractor={(exercise) => exercise.id} renderItem={renderExercise} />
    </View>
  );
}

const styles = StyleSheet.create({
  frame: { height: 120 },
  row: { height: 30, paddingHorizontal: 12 },
});

mount(<Catalog />);

Полей три. item — сам элемент data, index — его номер, separators — ручки для подсветки разделителей между строками, если они заданы через ItemSeparatorComponent. Отсюда привычная запись ({ item }) => …: из трёх полей обычно нужно одно.

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

Тип аргумента renderItem в примерах записан руками, а высоту списку даёт обёртка. В проекте тип выводится из data сам (ListRenderItemInfo), а style и testID ставят прямо на FlatList. Эти пропы и тип приходят из пакета @react-native/virtualized-lists, которого в наборе типов песочницы нет. Без записи руками компилятор песочницы скажет «Элемент привязки "item" имеет неявный тип "any"», а на style и testID у FlatList — «Ни одна перегрузка не соответствует этому вызову». Код при этом выполняется.

keyExtractor в примере выше можно было не писать. Без него FlatList берёт ключ сам — функцией keyExtractor из VirtualizeUtils.js, одинаковой в React Native 0.86 и react-native-web: поле key, если оно есть, иначе поле id, иначе номер строки, String(index). У упражнения «Подхода» есть id, и справочник получил бы те же ключи. Явный keyExtractor всё равно полезен: он говорит, какое поле — ключ, а не надеется на то, что поле называется id.

Прошлая статья вычитала в исходнике обещание: если нет ни key, ни id, FlatList возьмёт номер строки и напечатает предупреждение. Проверим. С сервера пришли одни названия, строками. Прогноз: появится ли в консоли что-нибудь раньше строки «список отрисован»?

const { FlatList, View, Text } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

// с сервера пришли одни названия: ни key, ни id
const names = makeCatalog(8).map((exercise) => exercise.name);

function renderName({ item }: { item: string }) {
  return <Text style={{ height: 30 }}>{item}</Text>;
}

mount(
  <View style={{ height: 120 }}>
    <FlatList data={names} renderItem={renderName} />
  </View>,
);
setTimeout(() => console.log("список отрисован"), 500);

Ничего. Список молча взял номера, и обещание прошлой статьи оказалось неверным. Текст предупреждения в исходниках есть — «VirtualizedList: missing keys for items…», — но печатает его VirtualizedList, и только когда номер вместо ключа выбрал его собственный _keyExtractor, то есть когда своего keyExtractor у списка нет. А FlatList всегда передаёт вниз свой: в FlatList.js стоит keyExtractor={this._keyExtractor}, и уже этот метод сам откатывается на key, id и номер. До флажка, который включает предупреждение, дело не доходит. Так и в React Native 0.86, и в копии внутри react-native-web: про номера FlatList молчит.

const { VirtualizedList, View, Text } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

const names = makeCatalog(8).map((exercise) => exercise.name);

function renderName({ item }: { item: string }) {
  return <Text style={{ height: 30 }}>{item}</Text>;
}

mount(
  <View style={{ height: 120 }}>
    <VirtualizedList
      data={names}
      // data у VirtualizedList не обязан быть массивом, поэтому счёт и доступ к элементу задают явно
      getItemCount={(data: string[]) => data.length}
      getItem={(data: string[], index: number) => data[index]}
      renderItem={renderName}
    />
  </View>,
);
setTimeout(() => console.log("список отрисован"), 500);

Настоящее предупреждение про ключи, которое достаётся пользователю FlatList, приходит от самого React — и оно не про то, что ключа нет, а про то, что он повторился. К справочнику добавили своё упражнение, а номер ему выдали отдельно, и он совпал с номером из справочника. Прогноз: что будет в консоли?

const { FlatList, View, Text } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

// своё упражнение пронумеровали отдельно от справочника
const mine: Exercise = { id: "ex-1", name: "Жим штанги с паузой", group: "Грудь" };

function renderExercise({ item }: { item: Exercise }) {
  return <Text style={{ height: 30 }}>{item.name}</Text>;
}

mount(
  <View style={{ height: 120 }}>
    <FlatList data={[mine, ...makeCatalog(8)]} renderItem={renderExercise} />
  </View>,
);
setTimeout(() => console.log("список отрисован"), 500);

Это console.error отладочной сборки React — та же проверка, что у любого массива детей (часть IV, «Своя сверка: что на самом деле делает key»). FlatList отдал React две ячейки с ключом ex-1, и React предупреждает: при обновлениях одна из этих строк может задвоиться или пропасть. .$ex-1 — тот же ex-1, переписанный React.Children: ScrollView пропускает через него детей списка. В React Native 0.86 он делает это всегда, через toArray; в react-native-web — через map, потому что VirtualizedList всегда передаёт ему массив stickyHeaderIndices, пусть и пустой. Поэтому строка одна и та же в песочнице и на телефоне.

Отсутствия ключа FlatList не заметит, а повтор заметит React — и ловит он ровно ту беду, которая бывает на практике: ключи есть, но не уникальны. В «Подходе» номера будут рождаться в разных местах — справочник, свои упражнения, второе устройство, — и в главе 6 id станет «устройство + счётчик» как раз затем, чтобы номера не совпадали. А пока повтор лечится keyExtractor, — это вторая задача.

И последнее про ключ: keyExtractor обязан вернуть строку. Если сервер присылает id числом, запись keyExtractor={(w) => w.id} компилятор не пропустит. Сообщение длинное — «Ни одна перегрузка не соответствует этому вызову» с разбором обеих перегрузок, — а суть в последней его строке: «Тип "number" не может быть назначен для типа "string"». Этот тип компилятор песочницы знает: keyExtractor объявлен в самом FlatList.d.ts пакета react-native, а не в пакете списков. Лечится String(w.id).

Наше окно было обычным компонентом-функцией: перерисовался экран — перерисовалось и оно, и renderRow заново вызвалась для каждой строки. FlatList устроен иначе. Это классовый PureComponent, так он и объявлен в FlatList.js: он перерисовывается, только если какой-то его проп изменился при поверхностном сравнении через Object.is, — то же правило, что у memo в части IV («memo, useMemo и useCallback: что они делают»).

Пока renderItem — стрелка прямо в теле экрана, она новая на каждой перерисовке, и FlatList перерисовывается всегда. Но renderItem часто делают постоянной — выносят из компонента или оборачивают в useCallback: обычный шаг, когда список начинают ускорять. Что тогда станет со строками, которые читают не только data?

Проверим на отметках. Отметки «сделано» лежат не в data, а в отдельном множестве — так они будут жить в хранилище главы 6. Кнопка отмечает жим лёжа и перерисовывает экран. Под ней два списка с постоянными функциями строки: наше окно из прошлой статьи — с этой статьи оно в подложке, как WindowedList, — и FlatList. Прогноз: что покажет каждый после нажатия?

const { FlatList, View, Text, Pressable } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];
type WindowedListProps<T> = {
  testID: string;
  data: T[];
  height: number;
  rowHeight: number;
  overscan: number;
  renderRow: (item: T) => React.ReactNode;
};
declare function WindowedList<T extends { id: string }>(props: WindowedListProps<T>): React.ReactElement;

const catalog = makeCatalog(5);
// отметки не в data, а рядом — так они будут жить в хранилище главы 6
const done = new Set<string>();
const shown = { own: "", flat: "" };
const markOf = (item: Exercise) => (done.has(item.id) ? "✓" : "без отметки");

// обе функции строки объявлены вне экрана и между перерисовками не меняются
function renderOwn(item: Exercise) {
  if (item.id === "ex-1") shown.own = markOf(item);
  return <Text>{done.has(item.id) ? "✓ " : ""}{item.name}</Text>;
}
function renderFlat({ item }: { item: Exercise }) {
  if (item.id === "ex-1") shown.flat = markOf(item);
  return <Text style={{ height: 30 }}>{done.has(item.id) ? "✓ " : ""}{item.name}</Text>;
}

function Screen() {
  const [version, setVersion] = React.useState(0);
  return (
    <View>
      <Pressable testID="done" onPress={() => { done.add("ex-1"); setVersion(version + 1); }}>
        <Text>Сделано: жим лёжа</Text>
      </Pressable>
      <WindowedList testID="own" data={catalog} height={90} rowHeight={30} overscan={2} renderRow={renderOwn} />
      <View style={{ height: 90 }}>
        <FlatList data={catalog} renderItem={renderFlat} />
      </View>
    </View>
  );
}

mount(<Screen />);
const report = () => console.log("своё окно:", shown.own, "| FlatList:", shown.flat);
// нажимаем после секунды тишины, когда оба списка закончили первые отрисовки
setTimeout(report, 1000);
setTimeout(() => fireEvent.press("done"), 1100);
setTimeout(report, 1600);

Своё окно отметку показало, FlatList — нет. Экран перерисовался, но пропсы FlatList — тот же массив data, та же функция renderFlat — не изменились, и PureComponent пропустил перерисовку целиком: renderFlat даже не вызывалась. Отметка в множестве есть, а на экране её не будет, пока список не перерисуется по другой причине.

Для этого у FlatList есть проп extraData: в описании пропа в FlatList.js он назван меткой, которая говорит списку перерисоваться, раз он PureComponent. Передайте туда номер версии — extraData={version} — и после нажатия FlatList покажет отметку. Сменившийся проп заставит перерисоваться сам список, а тот соберёт для ячеек новую функцию строки, и ячейки перерисуются вслед за ним. Отсюда и правило из того же описания: extraData должен меняться по ===. Номер версии годится. Множество, в которое добавили элемент, — нет, это тот же объект; об этом третья задача.

const { FlatList, View, Text, Pressable } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

const catalog = makeCatalog(5);
let shown = "";

function Screen() {
  // отметки в состоянии экрана, а renderItem — стрелка прямо в его теле
  const [done, setDone] = React.useState<ReadonlySet<string>>(() => new Set());
  return (
    <View>
      <Pressable testID="done" onPress={() => setDone(new Set(done).add("ex-1"))}>
        <Text>Сделано: жим лёжа</Text>
      </Pressable>
      <View style={{ height: 90 }}>
        <FlatList
          data={catalog}
          renderItem={({ item }: { item: Exercise }) => {
            if (item.id === "ex-1") shown = done.has(item.id) ? "✓" : "без отметки";
            return <Text style={{ height: 30 }}>{done.has(item.id) ? "✓ " : ""}{item.name}</Text>;
          }}
        />
      </View>
    </View>
  );
}

mount(<Screen />);
setTimeout(() => console.log("до нажатия:", shown), 1000);
setTimeout(() => fireEvent.press("done"), 1100);
setTimeout(() => console.log("после:", shown), 1600);

const { FlatList, View, Text, Pressable } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

const catalog = makeCatalog(1000);
const done = new Set<string>();
const list = React.createRef<import("react-native").FlatList<Exercise>>();
let shown = "";

// та же постоянная функция строки, что в первом опыте раздела, и extraData по-прежнему нет
function renderExercise({ item }: { item: Exercise }) {
  if (item.id === "ex-1") shown = done.has(item.id) ? "✓" : "без отметки";
  return <Text style={{ height: 30 }}>{done.has(item.id) ? "✓ " : ""}{item.name}</Text>;
}

function Screen() {
  const [version, setVersion] = React.useState(0);
  return (
    <View>
      <Pressable testID="done" onPress={() => { done.add("ex-1"); setVersion(version + 1); }}>
        <Text>Сделано: жим лёжа</Text>
      </Pressable>
      <View style={{ height: 120 }}>
        <FlatList ref={list} data={catalog} renderItem={renderExercise} />
      </View>
    </View>
  );
}

mount(<Screen />);
setTimeout(() => fireEvent.press("done"), 1000);
setTimeout(() => console.log("после нажатия:", shown), 1300);
// листаем справочник дальше, к сотой строке
setTimeout(() => list.current?.scrollToOffset({ offset: 3000, animated: false }), 1400);
setTimeout(() => console.log("после прокрутки:", shown), 1900);

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

Прокручиваем методом самого списка. В ref у FlatList лежит не ScrollView, а список, и у него свои методы прокрутки: scrollToOffset({ offset }) — к смещению, scrollToIndex({ index }) — к строке. Прогноз: какие из двух строк уйдут из дерева и что останется от отметок?

const { FlatList, View, Text, Pressable } = ReactNative;
type Exercise = { id: string; name: string; group: string };
declare function makeCatalog(count: number): Exercise[];

const catalog = makeCatalog(1000);
// в ref у FlatList — сам список, и прокручивают его его же методом
const list = React.createRef<import("react-native").FlatList<Exercise>>();
const shown: Record<string, string> = {};

function Row({ exercise }: { exercise: Exercise }) {
  const [done, setDone] = React.useState(false);
  shown[exercise.id] = done ? "отмечено" : "не отмечено";
  React.useEffect(() => () => {
    if (exercise.id === "ex-1" || exercise.id === "ex-16") console.log("ушла из дерева:", exercise.name);
  }, [exercise]);
  return (
    <Pressable testID={exercise.id} style={{ height: 30 }} onPress={() => setDone(!done)}>
      <Text>{done ? "✓ " : ""}{exercise.name}</Text>
    </Pressable>
  );
}

const renderRow = ({ item }: { item: Exercise }) => <Row exercise={item} />;
const scrollTo = (offset: number) => list.current?.scrollToOffset({ offset, animated: false });

mount(
  <View style={{ height: 120 }}>
    <FlatList ref={list} data={catalog} renderItem={renderRow} />
  </View>,
);
setTimeout(() => fireEvent.press("ex-1"), 300);
setTimeout(() => scrollTo(450), 400);
setTimeout(() => fireEvent.press("ex-16"), 900);
// далеко вниз — шагами, как ведёт палец: список дорисовывает строки по пути
[1500, 3000, 4500, 6000].forEach((offset, step) => setTimeout(() => scrollTo(offset), 1000 + step * 300));
setTimeout(() => scrollTo(0), 2400);
setTimeout(() => scrollTo(450), 2800);
setTimeout(() => console.log("ex-1:", shown["ex-1"], "| ex-16:", shown["ex-16"]), 3300);

Шестнадцатое упражнение, «Подтягивания широким хватом», ушло из дерева и вернулось без отметки — ровно как в нашем окне. А первое не уходило вовсе и отметку сохранило. Это не случайность. Строки первой порции, те самые initialNumToRender, VirtualizedList не размонтирует никогда: так записано в описании пропа в VirtualizedListProps.js, ради мгновенного возврата к началу списка. У нашего окна такого исключения не было.

Полагаться на него не стоит: оно касается только первых десяти строк, а проп initialScrollIndex, с которым список открывается сразу на нужной строке, выключает его совсем. Состояние, которое должно пережить прокрутку, держат выше строки, как в первой задаче прошлой статьи.

Остальные строки таблицы прошлой статьи — распорки $spacer-…, запас windowSize, ячейка CellRenderer — в этом опыте тоже работают, но разглядеть их можно только счётом: сколько строк держит список и во что обходится его перерисовка, считает следующая статья. Сверх окна у FlatList есть то, что к окну не относится: колонки numColumns (ключ строки тогда — ключи её элементов через двоеточие), разделители ItemSeparatorComponent, шапка и подвал ListHeaderComponent и ListFooterComponent.

Сведём в одно место, чем FlatList в песочнице отличается от FlatList на телефоне. Каждая строка сверена с исходниками, левая колонка — ещё и запуском выше.

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