Доступность и мелочи, из-за которых приложение кажется чужим

Строка ленты собрана как в любом приложении: View, внутри три Text — упражнение, вес, повторы, — а справа крестик «удалить подход». Глазами это одна строка. Голосом — не одна: скринридер ходит не по тому, что нарисовано, а по узлам доступности, и каждый такой узел — отдельная остановка, на которой голос называет подпись, роль и состояние.

Правил, из которых складывается обход, три, и все они записаны в документации React Native и в типах. Первое: Text и всё нажимаемое — узлы доступности сами по себе, обычный View — нет. Второе: пропс accessible делает узлом сам View, и тогда обход внутрь не идёт вовсе — поддерево склеивается в одну остановку. Третье: если подписи нет, она собирается сама — обходом всех потомков со склейкой текста через пробел, как сказано про accessibilityLabel в ViewAccessibility.d.ts.

Соберём эти три правила в два десятка строк и прогоним через них три варианта одной и той же строки ленты: как она написана сейчас; вся строка одним доступным узлом с подписью; группа с текстом плюс кнопка снаружи. Прогноз: сколько остановок выйдет в каждом случае и что голос скажет на каждой?

const { View, Text, Pressable } = ReactNative;
type Node = React.ReactNode;
type A11y = { children?: Node; accessible?: boolean; accessibilityLabel?: string; accessibilityRole?: string };
const ROLE: Record<string, string> = { button: "кнопка", header: "заголовок", switch: "переключатель" };

// подпись по умолчанию — текст всех потомков подряд: так она описана в типах
function label(node: Node): string {
  if (Array.isArray(node)) return node.map(label).filter(Boolean).join(" ");
  if (React.isValidElement(node)) {
    const props = node.props as A11y;
    return props.accessibilityLabel ?? label(props.children);
  }
  return node == null || typeof node === "boolean" ? "" : String(node);
}

// остановки голоса: обход дерева, который упирается в доступный узел
function stops(node: Node, out: string[] = []): string[] {
  if (Array.isArray(node)) node.forEach((child) => stops(child, out));
  else if (React.isValidElement(node)) {
    const props = node.props as A11y;
    const type: unknown = node.type;
    const сам = props.accessible ?? (type === Text || type === Pressable);
    if (сам) out.push([label(node), ROLE[props.accessibilityRole ?? ""]].filter(Boolean).join(", "));
    else stops(props.children, out);
  } else if (node != null && typeof node !== "boolean") out.push(String(node));
  return out;
}

const SAY = "жим, 82,5 килограмма, 5 повторов";
const cells = [<Text key="e">жим</Text>, <Text key="w">82,5</Text>, <Text key="r">5</Text>];
const bare = <Pressable><Text>×</Text></Pressable>;
const cross = (
  <Pressable accessibilityRole="button" accessibilityLabel="Удалить подход">
    <Text>×</Text>
  </Pressable>
);

console.log("как есть:", stops(<View>{cells}{bare}</View>).join(" / "));
console.log("вся строка:", stops(<View accessible accessibilityLabel={SAY}>{cells}{cross}</View>).join(" / "));
console.log("группа и кнопка:", stops(<View><View accessible accessibilityLabel={SAY}>{cells}</View>{cross}</View>).join(" / "));

Первый вариант — четыре остановки, и ни одна не годится. «82,5» — чего? «5» — чего? Голос читает ячейки таблицы, из которой убрали шапку. А крестик он называет «×», потому что подписи нет, и собрать её не из чего: внутри тот же символ.

Второй вариант выглядит решением и им не является. Остановка одна, текст правильный — а кнопки «Удалить подход» в озвучке нет вовсе. Доступный узел заканчивает обход: всё, что внутри, для голоса перестаёт существовать, включая нажимаемое. На телефоне это значит ровно то, как звучит: удалить подход, не глядя на экран, станет нельзя.

Третий вариант — то, что нужно: две остановки, «жим, 82,5 килограмма, 5 повторов» и «Удалить подход, кнопка». Отсюда правило, к которому сводится почти вся работа над озвучкой списка: группируют текст, нажимаемое оставляют снаружи и подписывают отдельно. Подпись при этом пишется словами, которые человек говорит вслух: «82,5 килограмма», а не «82.5 kg» и не «вес двоеточие».

Это модель, а не голос. VoiceOver в песочницу не поставить, обход здесь наш собственный и по трём правилам из документации. Он годится, чтобы увидеть, где остановок слишком много, а где они пропали. Он не скажет, каково это — слушать ваш экран полчаса подряд; для такого есть телефон, и им статья заканчивается.

Миниатюра показала, что должно произойти. Теперь — что происходит на самом деле, в той среде, где выполняются примеры. Это не только про предпросмотр: react-native-web и есть веб-версия «Подхода», то самое второе устройство из главы 7, и разметка ниже — ровно та, которую на компьютере получит настоящий скринридер.

Пять узлов, и все написаны так, как советуют их писать: заголовок экрана с ролью header; крестик с подписью, подсказкой и запасом hitSlop; переключатель единиц с ролью switch и состоянием через accessibilityState; он же, но с aria-checked; и декоративная иконка, спрятанная от голоса через importantForAccessibility. Прогноз: что из этого доедет до разметки, а что исчезнет по дороге?

declare function hostTag(testID: string): string | null;
declare function hostAttr(testID: string, name: string): string | null;
const { View, Text, Pressable } = ReactNative;

function Screen() {
  return (
    <View>
      <Text testID="title" accessibilityRole="header">Тренировка</Text>
      <Pressable
        testID="del"
        accessibilityRole="button"
        accessibilityLabel="Удалить подход"
        accessibilityHint="подход исчезнет из ленты"
        hitSlop={10}
      >
        <Text>×</Text>
      </Pressable>
      {/* один переключатель единиц, написанный двумя способами */}
      <Pressable testID="units" accessibilityRole="switch" accessibilityLabel="Фунты" accessibilityState={{ checked: true }}>
        <Text>lb</Text>
      </Pressable>
      <Pressable testID="units-aria" accessibilityRole="switch" accessibilityLabel="Фунты" aria-checked>
        <Text>lb</Text>
      </Pressable>
      <View testID="decor" importantForAccessibility="no-hide-descendants">
        <Text>🏋</Text>
      </View>
    </View>
  );
}

mount(<Screen />);
setTimeout(() => {
  const show = (id: string, names: string[]) =>
    console.log(id, "→", hostTag(id), "|", names.map((name) => name + ": " + hostAttr(id, name)).join(" | "));
  show("title", ["role"]);
  show("del", ["role", "aria-label", "aria-describedby"]);
  show("units", ["role", "aria-label", "aria-checked"]);
  show("units-aria", ["role", "aria-checked"]);
  show("decor", ["aria-hidden"]);
}, 150);

Роль доехала, и даже щедрее, чем просили: Text с ролью header стал настоящим <h1>, а Pressable с ролью button — <button>, который сам попадает в обход с клавиатуры. Подпись доехала тоже. А подсказка, состояние, запас нажатия и «спрятать от голоса» не доехали никак: в разметке их нет ни в каком виде. Диагностик при этом ноль — все пять узлов написаны по настоящим типам react-native 0.86.

Причина не в ошибке, а в списке. У react-native-web есть перечень пропсов, которые он пропускает в разметку (modules/forwardedProps): там все aria-* и role, там старые accessibilityLabel и accessibilityLiveRegion — и нет ни accessibilityState, ни accessibilityHint, ни accessibilityValue. А hitSlop и importantForAccessibility веб-сборка не разбирает вовсе: первый — потому что зону касания в вебе никто не считает («Нажатие — это автомат, а не onClick»), второй — потому что это пропс Android.

Отсюда правило для проекта, который живёт на трёх платформах: подпись и роль пишутся одним пропсом, состояние — двумя. Подпись с ролью работают везде; состояние на вебе понимают только aria-*, а на телефоне aria-checked — псевдоним accessibilityState, и react-native сворачивает его в состояние сам. Написать оба всё равно дешевле, чем однажды выпустить переключатель, который молчит о себе. Строка ленты после этого выглядит так:

// app/components/set-row/set-row.tsx — строка ленты «Подхода»
import { Pressable, Text, View } from "react-native";
import { styles } from "./set-row.styles";
import type { SetRowProps } from "./set-row.types";

export function SetRow({ set, onDelete }: SetRowProps) {
  const say = set.exercise + ", " + formatWeight(set.weightKg) + ", " + set.reps + " повторов";
  return (
    <View style={styles.row}>
      {/* группа: весь текст строки — одна остановка голоса. Роль нужна вебу:
          имя у безролевого узла ARIA не разрешает */}
      <View accessible accessibilityLabel={say} role="group" style={styles.cells}>
        <Text style={styles.exercise} numberOfLines={1}>{set.exercise}</Text>
        <Text style={styles.numbers}>{formatWeight(set.weightKg)} · {set.reps}</Text>
      </View>
      {/* кнопка — снаружи группы, иначе голос до неё не дойдёт */}
      <Pressable
        accessibilityRole="button"
        accessibilityLabel="Удалить подход"
        accessibilityHint="подход исчезнет из ленты"
        hitSlop={10}
        onPress={onDelete}
        style={styles.cross}
      >
        <Text style={styles.crossText}>×</Text>
      </Pressable>
    </View>
  );
}

declare function hostTag(testID: string): string | null;
declare function hostAttr(testID: string, name: string): string | null;
const { View, Text } = ReactNative;

const SAY = "жим, 82,5 килограмма, 5 повторов";

function Row() {
  return (
    <View>
      <View testID="plain" accessible accessibilityLabel={SAY}>
        <Text>жим</Text>
      </View>
      <View testID="grouped" accessible accessibilityLabel={SAY} role="group">
        <Text>жим</Text>
      </View>
    </View>
  );
}

mount(<Row />);
setTimeout(() => {
  for (const id of ["plain", "grouped"]) {
    console.log(id, "→", hostTag(id), "| role:", hostAttr(id, "role"), "| aria-label:", hostAttr(id, "aria-label"));
  }
}, 150);

Состояние «недоступно» — единственное, о котором не надо рассказывать дважды: disabled у Pressable сам доезжает и до разметки (aria-disabled, tabindex="-1"), и до телефона. Это та же кнопка из «Первого экрана», у которой выключенность и нажатие живут в одном пропсе.

В приложении на запросах экран меняется после нажатия: нажали — подождали — увидели. В local-first половина изменений приходит сама: sync() запускается при возврате из фона, чужая правка приезжает с курсора, индикатор из «Цикла синхронизации» переходит из «ждут отправки: 2» в «сохранено». Глазами это мигнувшая строка. Голосом — ничего: скринридер читает то, на чём стоит фокус, а фокус никуда не двигался.

Способов рассказать два, и они не взаимозаменяемы. Живая область — accessibilityLiveRegion (пропс Android, в вебе это aria-live): система сама зачитывает изменившийся текст. Прямое объявление — AccessibilityInfo.announceForAccessibility(строка): приложение произносит фразу, никак не связанную с фокусом. Прогноз: что покажет разметка индикатора до и после нажатия на «Синхронизировать» и что вернёт объявление?

declare function hostAttr(testID: string, name: string): string | null;
declare function hostText(testID: string): string | null;
interface Journal { newId(): string; change(rowId: string, fields: Record<string, string | number>): void }
interface Client { journal: Journal; queue(): { opId: string }[]; sync(): void }
interface Server { net: { offline: boolean } }
declare function createServer(): Server;
declare function createClient(device: string, server: Server): Client;
const { View, Text, Pressable, AccessibilityInfo } = ReactNative;

const server = createServer();
const phone = createClient("A", server);
const set = phone.journal.newId();
phone.journal.change(set, { exercise: "жим", weightKg: 82.5, reps: 5 });

function Status() {
  const [, redraw] = React.useState(0);
  const waiting = phone.queue().length;
  const text = waiting === 0 ? "сохранено" : "ждут отправки: " + waiting;
  return (
    <View>
      {/* живая область: об изменении, которого никто не нажимал, рассказывает система */}
      <Text testID="status" accessibilityLiveRegion="polite">{text}</Text>
      <Pressable
        testID="sync"
        accessibilityRole="button"
        accessibilityLabel="Синхронизировать"
        onPress={() => {
          phone.sync();
          AccessibilityInfo.announceForAccessibility("дневник отправлен");
          redraw((n) => n + 1);
        }}
      >
        <Text>↑</Text>
      </Pressable>
    </View>
  );
}

mount(<Status />);
setTimeout(() => {
  console.log("до нажатия:", hostText("status"), "| aria-live:", hostAttr("status", "aria-live"));
  fireEvent.press("sync");
  setTimeout(() => console.log("после нажатия:", hostText("status"), "| aria-live:", hostAttr("status", "aria-live")), 50);
}, 150);

Текст индикатора сменился, aria-live стоит на месте: в вебе живая область работает по-настоящему, и это тот редкий случай, когда предпросмотр делает ровно то же, что будет у веб-версии. А вот объявление здесь не сделало ничего: announceForAccessibility в react-native-web — пустой метод, как Alert.alert из главы 4. На телефоне всё наоборот: объявление работает на обеих платформах, а живая область — только на Android.

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

Индикатор показывает состояние дневника, а не состояние запроса, — это решено ещё в «Цикле синхронизации». Озвучивать его надо теми же словами: не «загрузка завершена», а «дневник отправлен»; не «ошибка 503», а «нет сети, подход сохранён на телефоне». Человеку важно, где лежит его запись, а не что ответил сервер.

Вторая вещь, которой не видно в предпросмотре, — размер мишени. Мышь попадает в пиксель, палец накрывает пятно около сантиметра, и целится он хуже, чем кажется его хозяину. Отсюда требования платформ: Apple просит мишень не меньше 44 точек, Google — 48 dp, а типы react-native в описании hitSlop называют 30–40. Крестик «удалить подход» в строке ленты — 24 на 24.

Проверить это нажатием здесь нечем: fireEvent.press — это click по узлу, он попадает всегда, а hitSlop веб-сборка Pressable не разбирает вовсе — это выяснено в «Нажатие — это автомат, а не onClick». Остаётся то, что от среды не зависит: геометрия. Зона касания — прямоугольник кнопки, расширенный запасом, но не выходящий за границы родителя: так hitSlop описан в типах.

Прогноз: крестику 24 на 24 в строке высотой 32 дали hitSlop 10. Какая мишень получится, куда попадут пять нажатий и что изменится, если строку поднять до 44?

type Rect = { x: number; y: number; width: number; height: number };
type Point = { x: number; y: number };

const grow = (rect: Rect, slop: number): Rect => ({
  x: rect.x - slop,
  y: rect.y - slop,
  width: rect.width + slop * 2,
  height: rect.height + slop * 2,
});
// зона касания не выходит за границы родителя — так hitSlop описан в типах
const clip = (rect: Rect, parent: Rect): Rect => {
  const x = Math.max(rect.x, parent.x);
  const y = Math.max(rect.y, parent.y);
  return {
    x,
    y,
    width: Math.min(rect.x + rect.width, parent.x + parent.width) - x,
    height: Math.min(rect.y + rect.height, parent.y + parent.height) - y,
  };
};
const inside = (rect: Rect, p: Point): boolean =>
  p.x >= rect.x && p.x <= rect.x + rect.width && p.y >= rect.y && p.y <= rect.y + rect.height;
const size = (rect: Rect): string => rect.width + "×" + rect.height;

// строка ленты и крестик «удалить подход» внутри неё
const row: Rect = { x: 0, y: 0, width: 360, height: 32 };
const cross: Rect = { x: 320, y: 4, width: 24, height: 24 };
const zone = clip(grow(cross, 10), row);
console.log("крестик:", size(cross), "| просили с hitSlop 10:", size(grow(cross, 10)), "| получилось:", size(zone));

// куда попадает палец, метящий в крестик
const taps: Point[] = [
  { x: 332, y: 16 },
  { x: 315, y: 20 },
  { x: 332, y: 30 },
  { x: 332, y: 36 },
  { x: 306, y: 16 },
];
for (const tap of taps) {
  console.log("палец", tap.x + "," + tap.y, "→ по рисунку:", inside(cross, tap), "| по зоне:", inside(zone, tap));
}

// та же кнопка в строке высотой 44
const tall: Rect = { x: 0, y: 0, width: 360, height: 44 };
console.log("строка 44:", size(clip(grow({ ...cross, y: 10 }, 10), tall)));

Просили 44 на 44, получили 44 на 32: по горизонтали запас лёг целиком, а по вертикали его съела строка — зона не может быть выше родителя. Из пяти нажатий одно попало бы и без запаса, ещё два спас hitSlop, а последние два — промах. И промах снизу (332,36) — тот самый случай, ради которого запас и ставили: он не сработал.

Отсюда вывод, который экономит часы: hitSlop не заменяет размер строки. Пока у строки height: 32, любой запас упирается в её край. Строка с minHeight: 44 — и та же кнопка получает полную мишень (последняя строка вывода). Заодно решается и вторая беда, о которой следующий раздел: minHeight вместо height переживает крупный системный шрифт.

Запас есть и у второго края нажатия: pressRetentionOffset — насколько далеко палец может уехать, не погасив кнопку («Нажатие — это автомат»), и hitSlop прибавляется к нему тоже. А если по строке ещё и свайп («Жест как разговор»), зоны кнопки и жеста стоит разводить руками: спор за касание выигрывает не тот, кто ближе, а тот, кто первым стал ответчиком.

Третья вещь приходит из системных настроек: человек ставит крупный шрифт — и весь текст в приложении растёт вместе с ним, потому что React Native масштабирует его сам, пока у Text не выключен allowFontScaling. Насколько именно — сообщает PixelRatio.getFontScale(). Прогноз: что он ответит в предпросмотре и что станет со строкой ленты, у которой в стилях height: 60?

const { PixelRatio, Dimensions } = ReactNative;
console.log("getFontScale():", PixelRatio.getFontScale(), "| fontScale окна:", Dimensions.get("window").fontScale);

// строка ленты: название упражнения и подпись «82,5 кг · 5 повторов»
const LINES = [17, 13];
const PADDING = 16;
// высота строки при системном масштабе; maxFontSizeMultiplier его ограничивает
function rowHeight(scale: number, max = 0): number {
  const applied = max > 0 ? Math.min(scale, max) : scale;
  return LINES.reduce((sum, fontSize) => sum + Math.round(fontSize * applied * 1.3), 0) + PADDING;
}

for (const scale of [1, 1.3, 2, 3.1]) {
  const need = rowHeight(scale);
  console.log(
    "шрифт ×" + scale,
    "→ строке нужно",
    need,
    "| в height: 60 влезло:",
    need <= 60,
    "| с ограничением 1.5:",
    rowHeight(scale, 1.5),
  );
}

Единица — и так будет всегда: в Dimensions react-native-web поле fontScale записано единицей, а getFontScale() читает именно его. Значит, крупный шрифт в предпросмотре не проверяется в принципе, и это ровно та подмена, которую «Размеры без пикселей» называли поимённо: здесь fontScale всегда 1.

Зато цену видно по модели. При обычном размере строке нужно 55 точек — в height: 60 она помещается с запасом, и в этот момент код выглядит правильным. При множителе 1,3 нужно уже 67, при двух — 94, а на самых крупных системных размерах iOS — 137. Всё, что не влезло, будет обрезано: не «поедет вниз», а именно обрезано, потому что высота задана числом.

Правил отсюда три, и все дешёвые. Первое: minHeight вместо height везде, где внутри текст, — тогда строка растёт, а мишень из прошлого раздела только выигрывает. Второе: allowFontScaling не выключать; если раскладка ломается на огромных размерах, ограничивают maxFontSizeMultiplier — в прогоне 1,5 удержал строку на 74 вместо 137. Третье: там, где строка обязана остаться одной, ставится numberOfLines с многоточием («Каскада нет, наследования нет»), а не надежда, что текст поместится.

Крупный шрифт ставят не только слабовидящие. Его ставят все, кто читает телефон на вытянутой руке, в движении и в зале, где очки лежат в сумке. Это самая частая настройка доступности вообще — и самая дешёвая в поддержке, если height в стилях с самого начала не было.

Остался вопрос из названия главы: как убедиться, что экран читается голосом. У React Native для этого есть AccessibilityInfo — вопросы к системе и команда «сказать вслух». Прогноз: что он ответит здесь, в предпросмотре?

const { AccessibilityInfo, Platform } = ReactNative;

console.log("платформа:", Platform.OS);
console.log("announceForAccessibility вернул:", String(AccessibilityInfo.announceForAccessibility("подход записан")));
AccessibilityInfo.isScreenReaderEnabled().then((on) => console.log("скринридер включён:", on));
AccessibilityInfo.isReduceMotionEnabled().then((less) => console.log("меньше движения — ответ браузера, тип:", typeof less));

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

# Android: системный шрифт крупнее — то же, что человек делает в настройках
adb shell settings put system font_scale 1.30
# iOS: то же на симуляторе, категорией размера контента
xcrun simctl ui booted content_size accessibility-extra-large
# вернуть как было
adb shell settings put system font_scale 1.00
xcrun simctl ui booted content_size large

Второй опыт — голос. TalkBack на Android включается быстрым нажатием обеих кнопок громкости, VoiceOver на iPhone — тройным нажатием боковой кнопки, если это назначено в «Быстрой команде». Дальше приложение проходится свайпами, а не пальцем по кнопкам: свайп вправо — следующая остановка. Пройдите ленту, удалите подход, откройте настройки, переключите фунты — и слушайте не интонацию, а содержание: сколько остановок на строку, названа ли роль, говорит ли переключатель о своём состоянии, узнали ли вы о том, что дневник отправился.

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

И напоследок — те мелочи, из-за которых приложение кажется чужим, даже когда всё работает. Каждая разобрана в своей статье, здесь они собраны списком, чтобы перед выпуском пройти по нему за один вечер.

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