Секции, липкие шапки и пустое состояние

FlatList из прошлых статей показывает справочник одной лентой. Для ленты с группами у React Native есть SectionList — с тем же окном внутри и почти теми же пропами. Вместо data он берёт sections — массив секций. Секция — обычный объект, у которого обязательно одно поле, data, — строки группы; остальное ваше, у нас это title. renderItem рисует строку, как у FlatList, а renderSectionHeader — шапку группы и получает объект с полем section.

Секции собирает обычная функция: пройти справочник и разложить упражнения по группам. Прогноз: сколько шапок и сколько строк окажется в первой отрисовке — и какой index получит «Подтягивания широким хватом», первое упражнение «Спины» и шестнадцатое в справочнике?

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

function toSections(list: Exercise[]): Section[] {
  // Map помнит порядок вставки: группы идут так, как встретились в справочнике
  const byGroup = new Map<string, Exercise[]>();
  for (const exercise of list) {
    const rows = byGroup.get(exercise.group) ?? [];
    rows.push(exercise);
    byGroup.set(exercise.group, rows);
  }
  return [...byGroup].map(([title, data]) => ({ title, data }));
}

const sections = toSections(makeCatalog(120));
const headers = new Set<string>();
const indexOf = new Map<string, number>();

function Catalog() {
  // эффект родителя срабатывает, когда закоммичено всё дерево, список тоже
  React.useEffect(() => console.log("первая отрисовка: шапок", headers.size, "| строк", indexOf.size), []);
  return (
    <View style={{ height: 120 }}>
      <SectionList
        sections={sections}
        renderSectionHeader={({ section }) => {
          headers.add(section.title);
          return <Text style={{ height: 30, fontWeight: "bold" }}>{section.title}</Text>;
        }}
        renderItem={({ item, index }) => {
          indexOf.set(item.name, index);
          return <Text style={{ height: 30 }}>{item.name}</Text>;
        }}
      />
    </View>
  );
}

mount(<Catalog />);
setTimeout(() => console.log("«Подтягивания широким хватом»: index", indexOf.get("Подтягивания широким хватом")), 1500);

Шапка одна, строк девять — вместе десять. initialNumToRender считает не упражнения, а ячейки, и шапка группы — такая же ячейка, как строка. Первая порция — те же десять, что у FlatList: шапка «Грудь» и девять упражнений под ней.

А index — 0. В renderItem приходит номер строки внутри её секции, а не во всём справочнике. Рядом с item и index лежат section — сама секция со всеми вашими полями — и separators, как у FlatList. Сквозного номера в аргументе нет. Если он нужен — например, чтобы чередовать фон строк без сброса в начале каждой группы, — его считают сами.

Компилятор песочницы отметит здесь item и index: «Свойство "item" не существует в типе "SectionListRenderItemInfo<Exercise, Section>"». Тип аргумента renderItem собирается из ListRenderItemInfo пакета @react-native/virtualized-lists, которого в наборе типов песочницы нет, и от него остаётся одно поле section. В проекте item выводится из sections сам, и запись ({ item }) — обычная; пример выполняется и здесь.

С этой статьи toSections живёт в подложке и объявляется в примерах через declare, как makeCatalog. Там же новый помощник, seenAtTop, — он понадобится в следующем разделе.

Шапка группы полезна, пока её видно. Прокрутили «Грудь» до середины — и уже непонятно, чьи упражнения на экране. Поэтому шапку делают липкой: она стоит у верхнего края рамки, пока её не вытеснит шапка следующей группы. У SectionList за это отвечает проп stickySectionHeadersEnabled.

Проверять будем тем, что видит глаз у верхнего края. Помощник rowAtTop из прошлой статьи здесь не годится: он читает раскладку строк, а липкая шапка лежит поверх строки, и по раскладке у края оказываются обе. Поэтому seenAtTop спрашивает браузер, что нарисовано в этой точке. В разметку, как и прежде, заглядывает подложка, а не пример. Ниже два одинаковых справочника: у второго флаг включён, у первого не задан вовсе. Прогноз: что будет у верхнего края каждой рамки на смещениях 200 и 560 — и что напечатает Platform.OS?

const { SectionList, View, Text, Platform, StyleSheet } = ReactNative;
type Exercise = { id: string; name: string; group: string };
type Section = { title: string; data: Exercise[] };
declare function makeCatalog(count: number): Exercise[];
declare function toSections(list: Exercise[]): Section[];
declare function seenAtTop(testID: string): string;

const sections = toSections(makeCatalog(120));

function Catalog({ testID, sticky }: { testID: string; sticky?: boolean }) {
  return (
    <View style={{ height: 60 }}>
      <SectionList
        testID={testID}
        sections={sections}
        stickySectionHeadersEnabled={sticky}
        renderSectionHeader={({ section }) => <Text style={styles.header}>{section.title}</Text>}
        renderItem={({ item }) => <Text style={styles.row}>{item.name}</Text>}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  header: { height: 30, fontWeight: "bold", backgroundColor: "#eef" },
  row: { height: 30 },
});

mount(
  <View>
    <Catalog testID="plain" />
    <Catalog testID="sticky" sticky />
  </View>,
);
console.log("Platform.OS:", Platform.OS);
function look(y: number) {
  fireEvent.scroll("plain", y);
  fireEvent.scroll("sticky", y);
  setTimeout(() => console.log("y =", y, "| без флага:", seenAtTop("plain"), "| с флагом:", seenAtTop("sticky")), 300);
}
setTimeout(() => look(200), 800);
setTimeout(() => look(560), 1400);

Без флага шапки уехали вместе со строками: у края упражнения, «Разводка гантелей лёжа» и «Подтягивания обратным хватом». С флагом у края «Грудь», а на 560 — уже «Спина»: шапка «Спины» дошла до верха и вытеснила «Грудь».

Главное — первая строка вывода. Значение флага по умолчанию в SectionList.js — одно выражение: stickySectionHeadersEnabled ?? Platform.OS === 'ios'. Оно одинаковое в React Native 0.86 и в react-native-web. На iPhone шапки липнут сами, на Android — нет, а в песочнице Platform.OS — "web", и она ведёт себя как Android. Выходит, один и тот же экран без флага на двух телефонах выглядит по-разному. Поэтому флаг пишут всегда, явно: true или false — как решил дизайн, а не платформа.

Устроена липкость на платформах по-разному, хотя видно одно и то же. react-native-web оборачивает шапку во View со стилем position: "sticky" — стиль stickyHeader в ScrollView/index.js, — и шапку держит браузер. React Native заворачивает её в ScrollViewStickyHeader — Animated.View, который сдвигается через transform: translateY вслед за значением прокрутки. Значение привязано к нативному событию прокрутки через attachNativeEvent, поэтому шапка едет, не дожидаясь JS на каждом кадре. Из чего сделано такое значение, соберёт глава 8.

В шапке VirtualizedSectionList.js прямо сказано: пока что всё просто сплющивается в один список и отдаётся VirtualizedList. То есть SectionList — это то же окно, что у FlatList, а шапки групп — такие же строки плоской ленты. Липкость — проп stickyHeaderIndices у ScrollView: номера строк, которые должны липнуть. Соберём это сами: сплющим секции в одну ленту, запомним места шапок и отдадим FlatList. Рядом — настоящий SectionList с включённым флагом. Прогноз: сколько строк в ленте, на каких местах шапки и что будет у края обеих рамок на 560?

const { FlatList, SectionList, View, Text, StyleSheet } = ReactNative;
type Exercise = { id: string; name: string; group: string };
type Section = { title: string; data: Exercise[] };
type Row = { kind: "header"; key: string; title: string } | { kind: "item"; key: string; exercise: Exercise };
declare function makeCatalog(count: number): Exercise[];
declare function toSections(list: Exercise[]): Section[];
declare function seenAtTop(testID: string): string;

// секции в одну ленту: шапка — такая же строка, запоминаем только её место
function flatten(sections: Section[]) {
  const rows: Row[] = [];
  const headerIndices: number[] = [];
  for (const section of sections) {
    headerIndices.push(rows.length);
    rows.push({ kind: "header", key: section.title + ":header", title: section.title });
    for (const exercise of section.data) rows.push({ kind: "item", key: section.title + ":" + exercise.id, exercise });
  }
  return { rows, headerIndices };
}

const sections = toSections(makeCatalog(120));
const { rows, headerIndices } = flatten(sections);
const own = React.createRef<import("react-native").FlatList<Row>>();

function renderRow({ item }: { item: Row }) {
  return item.kind === "header"
    ? <Text style={styles.header}>{item.title}</Text>
    : <Text style={styles.row}>{item.exercise.name}</Text>;
}

const styles = StyleSheet.create({
  header: { height: 30, fontWeight: "bold", backgroundColor: "#eef" },
  row: { height: 30 },
});

mount(
  <View>
    <View testID="own" style={{ height: 60 }}>
      <FlatList ref={own} data={rows} keyExtractor={(row) => row.key} renderItem={renderRow} stickyHeaderIndices={headerIndices} />
    </View>
    <View style={{ height: 60 }}>
      <SectionList
        testID="real"
        sections={sections}
        stickySectionHeadersEnabled
        renderSectionHeader={({ section }) => <Text style={styles.header}>{section.title}</Text>}
        renderItem={({ item }) => <Text style={styles.row}>{item.name}</Text>}
      />
    </View>
  </View>,
);
console.log("строк в ленте:", rows.length, "| шапки на местах:", headerIndices.join(", "));
setTimeout(() => {
  own.current?.scrollToOffset({ offset: 560, animated: false });
  fireEvent.scroll("real", 560);
}, 800);
setTimeout(() => console.log("вверху своей:", seenAtTop("own"), "| вверху SectionList:", seenAtTop("real")), 1400);

128 строк: 120 упражнений и 8 шапок. Шапки стоят через 16 — шапка и пятнадцать упражнений группы. У края обеих рамок «Спина»: для липких групп хватило плоской ленты и номеров шапок. Компилятор песочницы отметит stickyHeaderIndices у FlatList: проп приходит из @react-native/virtualized-lists, как и testID, поэтому свою ленту мы прокручиваем её же методом. В проекте это обычные пропы, а пример выполняется и здесь.

От нашей миниатюры настоящий SectionList отличается двумя вещами. Первая — подвал. На каждую секцию VirtualizedSectionList кладёт в ленту шапку, строки и ещё ячейку подвала — даже если renderSectionFooter не задан: в его render число ячеек так и считается, по две на секцию сверх строк. У справочника их 8 × 17 = 136, а не 128. Пустой подвал ничего не рисует, но ячейка у него есть, — это всплывёт в разделе про пустоту.

Вторая — ключ. Ключ ячейки собирает метод _subExtractor: ключ секции, двоеточие, ключ строки. Ключ строки — ваш keyExtractor, а без него поле key, id или номер, как у FlatList. Ключ секции — её поле key, а если его нет — её номер, String(i). Номер секции — такой же ключ по месту, как индекс в обычном списке (часть IV, «Своя сверка: что на самом деле делает key»). Пока секции не меняются, этого не видно. Но фильтр убирает целые группы.

Ниже два справочника с одним фильтром «Только тяги». У обоих keyExtractor — id упражнения, у второго у каждой секции ещё и key — её название. Прогноз: сколько строк смонтируется заново в каждом после нажатия?

const { SectionList, View, Text, Pressable } = ReactNative;
type Exercise = { id: string; name: string; group: string };
type Section = { title: string; data: Exercise[]; key?: string };
declare function makeCatalog(count: number): Exercise[];
declare function toSections(list: Exercise[]): Section[];

const catalog = makeCatalog(120);
const mounts = { byIndex: 0, byTitle: 0 };

function Row({ exercise, counter }: { exercise: Exercise; counter: keyof typeof mounts }) {
  // счётчик монтирований: перерисовка той же строки сюда не попадает
  React.useEffect(() => { mounts[counter] += 1; }, []);
  return <Text style={{ height: 30 }}>{exercise.name}</Text>;
}

function Catalog({ query, counter }: { query: string; counter: keyof typeof mounts }) {
  const found = toSections(catalog.filter((exercise) => exercise.name.toLowerCase().includes(query)));
  const sections = counter === "byTitle" ? found.map((section) => ({ ...section, key: section.title })) : found;
  return (
    <View style={{ height: 120 }}>
      <SectionList
        sections={sections}
        keyExtractor={(exercise) => exercise.id}
        renderSectionHeader={({ section }) => <Text style={{ height: 30, fontWeight: "bold" }}>{section.title}</Text>}
        renderItem={({ item }) => <Row exercise={item} counter={counter} />}
      />
    </View>
  );
}

function Screen() {
  const [query, setQuery] = React.useState("");
  return (
    <View>
      <Pressable testID="pulls" onPress={() => setQuery("тяг")}>
        <Text>Только тяги</Text>
      </Pressable>
      <Catalog query={query} counter="byIndex" />
      <Catalog query={query} counter="byTitle" />
    </View>
  );
}

mount(<Screen />);
let before = { ...mounts };
// жмём, когда оба списка дорисовали запас
setTimeout(() => { before = { ...mounts }; fireEvent.press("pulls"); }, 1500);
setTimeout(() => console.log("смонтировано заново: без key у секций", mounts.byIndex - before.byIndex, "| с key", mounts.byTitle - before.byTitle), 3000);

После фильтра строк пятнадцать, и без key у секций заново смонтированы все пятнадцать. В «Груди» тяг нет, группа исчезла, и «Спина» из секции 1 стала секцией 0: ключ 1:ex-16 превратился в 0:ex-16 — и так у каждой строки каждой следующей группы. Для React это другие строки: старые размонтированы вместе с состоянием, новые смонтированы. С key: title ключ Спина:ex-16 остался прежним, и заново смонтированы только три строки — те, которых до фильтра в окне не было: две тяги из «Плеч» и одна из «Ягодиц». keyExtractor здесь не помогает ничем: он задаёт только часть ключа после двоеточия.

Отсюда правило: секциям, которые могут пропадать и переставляться, — свой key, уникальный, потому что из него строятся ключи всех ячеек секции. В «Подходе» это название группы. Во что обходится забытый key, когда у строки есть своё состояние, — первая задача.

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

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

mount(
  <View style={{ height: 120 }}>
    <SectionList
      sections={[{ title: "Мои", data: mine }, { title: "Справочник", data: makeCatalog(4) }]}
      keyExtractor={(exercise) => exercise.id}
      renderSectionHeader={({ section }) => <Text style={{ fontWeight: "bold" }}>{section.title}</Text>}
      renderItem={({ item }) => <Text style={{ height: 30 }}>{item.name}</Text>}
    />
  </View>,
);
setTimeout(() => console.log("список отрисован"), 500);

Справочник, в котором поиск ничего не нашёл, — самое частое пустое место приложения. Список без строк не рисует ничего: на телефоне это белое поле, и человек не знает, сломалось что-то, грузится или правда пусто. Для этого у SectionList, как и у FlatList, есть проп ListEmptyComponent — компонент или готовый элемент, который список рисует вместо строк. Условие в render у VirtualizedList одно: ячеек ноль.

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

const { SectionList, View, Text } = ReactNative;
type Exercise = { id: string; name: string; group: string };
type Section = { title: string; data: Exercise[] };
declare function makeCatalog(count: number): Exercise[];
declare function toSections(list: Exercise[]): Section[];
declare function countNodes(testID: string): number;

const query = "скакалка с утяжелением";
const matches = (exercise: Exercise) => exercise.name.toLowerCase().includes(query);
// путь первый: разложить по группам, потом фильтровать внутри каждой
const kept = toSections(makeCatalog(120)).map((section) => ({ ...section, data: section.data.filter(matches) }));
// путь второй: сначала фильтр, потом группировка
const dropped = toSections(makeCatalog(120).filter(matches));
const shown = { kept: { headers: 0, empty: 0 }, dropped: { headers: 0, empty: 0 } };

function Catalog({ id, sections }: { id: keyof typeof shown; sections: Section[] }) {
  return (
    <View testID={id} style={{ height: 60 }}>
      <SectionList
        sections={sections}
        ListEmptyComponent={() => { shown[id].empty += 1; return <Text>Ничего не нашлось</Text>; }}
        renderSectionHeader={({ section }) => { shown[id].headers += 1; return <Text style={{ fontWeight: "bold" }}>{section.title}</Text>; }}
        renderItem={({ item }) => <Text>{item.name}</Text>}
      />
    </View>
  );
}

mount(
  <View>
    <Catalog id="kept" sections={kept} />
    <Catalog id="dropped" sections={dropped} />
  </View>,
);
setTimeout(() => {
  for (const id of ["kept", "dropped"] as const) {
    console.log(id === "kept" ? "группы оставлены" : "группы убраны", "| шапок нарисовано:", shown[id].headers > 0, "| пустота показана:", shown[id].empty > 0, "| узлов:", countNodes(id));
  }
}, 1000);

У первого пустоты нет, зато нарисованы шапки — все восемь групп, и ни одной строки под ними. Секция с пустым data всё равно даёт две ячейки, шапку и подвал, так что для VirtualizedList список не пуст: ячеек шестнадцать. Узлов 26 — это они и есть: восемь шапок по два узла (ячейка и Text), восемь пустых подвалов по одному и два узла ScrollView, рамка и внутренняя коробка. Второй справочник пуст по-настоящему: ноль ячеек, и на месте строк — Text пустоты, три узла вместе с рамкой и коробкой.

Правило: пустых групп в sections не бывает. Проще всего, как во втором справочнике, сначала фильтровать и потом группировать, а готовые секции — отсеивать по data.length. Это же лечит шапки без строк, которые обманывают и без всякого поиска: «Руки» в заголовке, а под ним пусто. И это же сдвигает номера секций — вот зачем нужен key из прошлого раздела.

Что писать в пустоте. Осмысленная пустота отвечает на три вопроса: что пусто, почему и что делать дальше. «По запросу „скакалка с утяжелением“ ничего нет» и кнопка «Сбросить поиск» — осмысленная пустота. «Нет данных» — нет. Разные причины — разные слова: пустой поиск и ещё не заведённые свои упражнения — это третья задача. А «ещё грузится» — отдельное состояние экрана, его разбирала часть IV («use() и Suspense: ожидание как часть разметки»). Показать «ничего не нашлось», пока данные в пути, — неправда.

const { SectionList, View, Text, StyleSheet } = ReactNative;
type Exercise = { id: string; name: string; group: string };
type Section = { title: string; data: Exercise[] };

const heights: Record<string, number> = {};
const nothing: Section[] = [];

function Empty({ label }: { label: string }) {
  return (
    <View style={styles.empty} onLayout={(e) => { heights[label] = e.nativeEvent.layout.height; }}>
      <Text>Ничего не нашлось</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  // пустота хочет встать посередине: растягивается и центрирует текст
  empty: { flex: 1, alignItems: "center", justifyContent: "center" },
  grow: { flexGrow: 1 },
});

mount(
  <View>
    <View style={{ height: 120 }}>
      <SectionList sections={nothing} renderItem={() => null} ListEmptyComponent={<Empty label="as is" />} />
    </View>
    <View style={{ height: 120 }}>
      <SectionList sections={nothing} renderItem={() => null} contentContainerStyle={styles.grow} ListEmptyComponent={<Empty label="flexGrow" />} />
    </View>
  </View>,
);
setTimeout(() => console.log("пустота в рамке 120: как есть ниже рамки —", heights["as is"] < 120, "| с flexGrow равна рамке —", heights["flexGrow"] === 120), 800);

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

Правило то же, что в прошлых статьях: код пишется так, чтобы быть верным в обеих колонках. Флаг липкости — явный. Пустых секций нет, у секций — key. Пустота растянута через flexGrow и говорит, что пусто и почему. Прыжки к группам — с getItemLayout, где шапка и подвал тоже ячейки; это вторая задача. Последняя статья главы — лента, которая подгружает страницы по onEndReached.