Меня зовут Женя Тютюев, я iOS-разработчик в компании 2ГИС. Хочу поделиться, как адаптировал наше приложение под VoiceOver:
делюсь историей про сдвиг парадигмы и как перешёл из стадии «делать, потому что так Эпл советует» в совершенно новую — «делать для людей».
как разработал новый вид snapshot-тестирования, чтобы ничего не ломалось при добавлении новых неадаптированных элементов.
описал несколько нюансов, которые важно учесть в работе: escape, динамический расчёт accessibility, укрупнение элементов.
Надеюсь, мой опыт вдохновит принести неоценимую пользу и сделать собственные приложения доступными для большего числа пользователей.
Что такое VoiceOver
VoiceOver — функция, доступная на всех устройствах Apple, таких как iPhone, iPad, Mac, Apple Watch, TV и VisionPro. Она озвучивает элементы интерфейса, позволяя незрячим пользователям управлять устройством с помощью жестов. Например, тап по экрану фокусирует и озвучивает элемент, двойной тап активирует его, а прокрутка тремя пальцами используется для навигации по экрану. Список основных жестов можно глянуть на сайте Apple.
Вот, например, видео, как пользуются VoiceOver:
Как и многие разработчики, я впервые столкнулся с VO, когда начал писать тесты. По всему проекту расставлял accessibilityIdentifier, по которому в UI-тестах уже можно найти элемент на экране, узнать его состояние или взаимодействовать с этим элементом по этому id.
let app = XCUIApplication()
app.launch()
// Находим кнопку по AccessibilityID
let button = app.buttons["myButtonAccessibilityID"]
// Проверяем, что кнопка найдена
XCTAssertTrue(button.exists)
// Нажимаем на кнопку
button.tap()
// Пример проверки, что текст изменился после нажатия
XCTAssertEqual(button.label, "New Button Label")Шли годы, периодически приходилось тестировать всё более сложные штуки, и уже просто accessibilityIdentifier не хватало, пришлось закапываться в документацию. Тогда я рассматривал VO как утилитарную технологию для роботов и долгое время жил в этой парадигме. По мере просмотра лекций на WWDC начало появляться стойкое ощущение, что эта функция вообще-то разрабатывалась не для тестов, а для людей.
Посмотрев ещё парочку видео, я был вдохновлен, — можно разметить обычные стандартные контролы и дать им нормальные имена, и профит! Просто и быстро сделал, как советовал Apple. Заходил в их accessibility-inspector, инспектировал по инструкции из видео, проверял, что кнопочки нажимаются и проблем с вёрсткой нет. Ну, думал, теперь всё по-взрослому: срочно в релиз, доступность с пылу с жару! Ну как срочно… я размечал все элементы месяца два: никто не говорил, что будет легко. Всё ушло в релиз, и некоторое время работало. Моя совесть была чиста — я сделал всё, что мог, и даже больше.
И долгое время это была просто обезличенная работа: читал документацию, следовал ей, проверял результаты по ней же. А потом наткнулся на видео от Wylsacom, как незрячий пользуется iPhone, MacBook и Apple Watch. Тогда я понял, что на свете есть люди, которые по-настоящему пользуются VoiceOver. Это их связь с миром, их «глаза», и он существенно помогает им в повседневной жизни.
И на волне нахлынувшего энтузиазма я решил тёплыми вечерами причинить непоправимую пользу человечеству. Из стадии «делать, потому что Эпл советует» я перешёл в другую — «делать для людей». Это оказался совершенно другой подход. Решил делать всё по-честному.
VoiceOver, версия 1.0
У Apple есть все инструменты для адаптации, они как бы шепчут: бери да и делай. Но в основном информация поверхностная и мало «живых» примеров. Также всё здорово, если на проекте стандартный UIKit, стандартные системные кнопочки. Шаг влево, шаг вправо, и совсем нет понимания, как всё адаптировать, чтобы людям было удобно пользоваться.
Приложение 2ГИС тяжелое (189214 файлов и 29452584 строчек кода на момент написания статьи), относительно хорошо покрытое UI-тестами – 700+ честных UI-тестов (это которые через XCUIApplication) и 1000+ нечестных UI-тестов (поделка, которая трогает UI в рамках Unit-тестирования, без поднятия всего приложения). Потыкав во всё приложение, определил, какие сценарии нужно взять в работу, а какими для начала можно пренебречь. Без какого-либо опыта, включил интуицию.
То, без чего я не мог начать погружаться в эту тему, — разделение кода для пользователей и кода для роботов. В первой итерации адаптации я даже не думал об этом. Чем больше доступности, тем лучше, правда же? Спойлер: на самом деле, нет.
Для разделения в переменные окружения для тестов нужно написать специальный флаг:
extension XCUIApplication {
@discardableResult
/// Запустить приложение для тестов или как для обычного пользователя
func customLaunch(asUser: Bool = false) -> XCUIApplication {
if !asUser {
self.launchEnvironment["v4ios_uitests"] = "YES"
}
self.launch()
return self
}
}
extension ProcessInfo {
static var isUITests: Bool {
ProcessInfo.processInfo.environment["v4ios_uitests"] == "YES"
}
}В дальнейшем все сниппеты и примеры можно щупать на GitHub. Там полностью рабочий проект со всеми примерами, что я расписал ниже.
Раньше я думал, что покрыл 80% важных сценариев, и это хорошо. Однако реальным людям такая адаптация хоть и позволяла работать с приложением, но не была такой, к которой хотелось бы возвращаться снова и снова. Хотелось, чтобы человек с опытом использования адаптаций проинспектировал наше приложение и дал рекомендации.
На волне энтузиазма я связался с Анатолием, героем видео Wylsacom. Коллаборация с ним по неизвестным мне причинам не сложилась, но он посоветовал обратиться в другое сообщество. Также нам периодически писали пользователи с отзывами о приложении. Я создал чат в WhatsApp (да, именно WhatsApp, так как он оказался более доступным, чем Telegram на iOS) и приглашал туда всех, кого находил.
Потихоньку я добавлял в приложение функции, адаптированные по документации Apple, и просил пользователей оставлять обратную связь. Это помогало находить и исправлять ошибки. Процесс был итеративным: некоторые обновления сразу заливал в прод, а другие отправлял в виде TestFlight-сборок.
Спустя год у нас появилась версия приложения, которую условно можно было назвать адаптированной. Работало не идеально, но всё функционировало. Самое главное, что мы учли мнение реальных пользователей, которым новая адаптация стала удобнее и понятнее.
Но прошли годы, приложение пережило редизайны и переписывание на Swift, и вся адаптация постепенно превратилась в тыкву. Если честно, я тогда немного (на самом деле, прилично) выгорел. Люди не фидбэчили, и я думал: или всё работает нормально, или никто не пользуется. Чат постепенно умер.
VoiceOver, версия 2.0
В 2022 случились санкции, которые усугубили ситуацию для пользователей: Google ушёл с рынка в качестве провайдера данных для транспорта, а другие российские приложения были не особо доступными. У пользователей не осталось альтернатив, и нам массово (насколько это возможно для такой небольшой аудитории) начали писать, что всё работает плохо.
Примерно в это же время я смог связаться с экспертами по тестированию доступности из Сбера. Без их помощи и советов вряд ли бы получилось двигаться дальше. Ещё неожиданно написал неравнодушный тифлопедагог (я даже не знал, что такие существуют) и добавил мотивации продолжать начатое дело.
Также к тому же моменту появился титанический труд Михаила Рубанова — спасибо ему! Его работа помогала решать типовые задачи. Крайне советую начинать онбординг в VoiceOver с этой книги.
Благодаря всем этим факторам появились желание и силы сделать новый VoiceOver, более серьёзное и адаптированное приложение.
Важные вводные
С точки зрения продуктовой разработки, фича VoiceOver всегда проигрывает другим задачам по всем критериям. Для неё никогда не находится время на разработку и на тестирование. Если не подталкивать всех — дизайнеров, продактов, QA, разработчиков и даже конечных пользователей — энтропия делает своё беспощадное дело. Без регулярного регресса и контроля за новыми функциями, вероятность того, что случайный сценарий станет недоступен за 2-3 недели активной разработки, неуклонно стремится к 100%. И из этих вводных важно понимать, что никто не будет проводить этот регресс примерно никогда.
И ещё один диксклеймер.
2ГИС — настоящий Nero burning ROM (только диски уже писать не умеет: кто поймет, тот поймёт). У нас на экране десятки контролов, реализованы сотни пользовательских сценариев. Есть боевой код, написанный ещё в 2012 году. В таких условиях я честно понимал, что всё адаптировать невозможно. Адаптировать надо только то, чем точно пользуются люди: данные брал на основе обратной связи.
И дальше я буду описывать не идеальную адаптацию, а адаптацию, которую может сделать один человек за сторипоинты, которые выбиваются с потом и кровью. В гигантском проекте, который поддерживается множеством людей, каждый из которых может случайно сломать что-то (не со злости, а по незнанию). В проекте, где появляются новые экраны, о которых я могу не знать, и постоянно меняются уже существующие. И самое главное, чтобы этим могли пользоваться настоящие люди. И было бы неплохо, чтобы всё не сломалось на следующий день.
Поэтому во втором очередном подходе разработку я начал с тестирования. Пришло чёткое осознание — нужны бездушные тесты, чтобы руки разработчиков, не участвующих в разработке этой фичи или написании UI-тестов на уже существующий экран, ничего больше не сломали. И было стойкое желание, чтобы эти тесты не занимали вечность (то есть не были UI-тестами, которые гоняются десятки секунд). А еще хотелось, чтобы их было супер просто писать, ещё проще поддерживать, и чтобы при их падении сразу было понятно, что пошло не так. Типичный ИКР по ТРИЗу. Кажется, что так не бывает, но на самом деле бывает.
Snapshot-тестирование
К счастью, нам не нужно делать скриншоты экрана, ведь такие тесты не решают главной проблемы — быстро понять, что пошло не так.
Всё гораздо проще, достаточно лишь использовать простой советский...
снапшот букв, которые слышит пользователь.
Для этого пришлось придумать новый вид тестирования, который быстро интегрируется в нашу систему тестирования, заводится с полпинка на существующей инфраструктуре и легко попадёт на Jenkins.
Эти тесты создают текстовый слепок всего экрана, фиксируя текст, который услышит незрячий пользователь. Описание доступных элементов прибивается «гвоздями» в тестах для тестируемого экрана: если кто-то добавит недоступный элемент или удалит существующий, тест не пройдет и код не будет замёржен = профит.
Если вы хотите начать или уже ведёте серьёзную разработку на долгие годы, то советую начинать именно с этого. Для начала можно, как и мы, «поиграться» с первым подходом. Но затем сами поймете, что это ненадёжно.
Для такого снапшот-тестирования нужно построить дерево всех View, найти среди них доступные, вытащить из них необходимые данные (id, label, value, actions), схлопнуть всё до одного текстового значения и в конце сделать дерево плоским, получив массив текстов для каждого доступного элемента.
Сам я парсить всё не хотел и времени не было, но до меня всё это сделал вот этот замечательный «человек» — https://github.com/cashapp/AccessibilitySnapshot.
Уже неплохо, но тот вид данных, который отдаёт библиотека, неудобен для тестов, поэтому напишем свою обёртку, которая позволяет превратить UIView во что-то человекочитаемое. Для тестов мы используем Nimble, он симпатично выводит ошибки. Ещё одно «приседание», и готов «матчер», который позволяет тестировать в удобном виде любую View. Вывести любую иерархию в лог можно так: printAccessibilityHierarchySnapshot.
Результатом вызова будет такое сообщение в логе:
[
.label("Some text. Button."),
]Дальше нужно взять эти буквы и вставить в матчер haveAccessibilityHierarchyOfElements(...)
Так теперь у нас есть код, который за разработчиков пишет тесты и сравнивает иерархию. В итоговом варианте тест начинает выглядеть вот так:
func test_проверяем_иерахию_простого_контроллера() throws {
let vc = ViewController()
self.uiTester.showChild(vc)
expect(vc.view).to(haveAccessibilityHierarchyOfElements([
.label("Some text. Button."),
]))
}Если иерархия меняется, то тест падает с ошибкой:
Когда появились тесты, можно начинать адаптировать приложение.
Escape
В VoiceOver есть важный момент: вы можете запустить любой сценарий (открыть новый экран), но должна быть возможность выйти с этого экрана. Это то, о чём мало кто задумывается. Поэтому правило хорошего тона — если мы забыли или не успели адаптировать экран, лучшее, что мы можем сделать, — это дать пользователю возможность уйти с него.
Лучше всего для этого подходит метод accessibilityPerformEscape (а тут пример). В любой момент пользователь может сделать жест Z двумя пальцами по экрану, и iOS по responder chain найдёт первый элемент, который вернёт true. В этом методе настоятельно рекомендую реализовать способ сбежать с экрана. Очень желательно добавить реализацию этого метода в каждый ViewController, куда может попасть пользователь.
Высший пилотаж — сделать первым элементом иерархии кнопку, которая закрывает экран. Типичный пример — UINavigationController со своей кнопкой back.
Динамический расчёт accessibility
Мы хотим вручную управлять доступными элементами, чтобы доступным было только то, в чем мы уверены. Наша цель — собрать весь код по доступности в одном предсказуемом месте, а не распределять его по всему экрану. Это также поможет выиграть неравный бой с автоматизаторами, которые пишут доступность для роботов.
В iOS 17 появилась нативная ленивая динамическая доступность (например, вот):
/*
Block based setters take precedence over single line setters (i.e setAccessibilityLabel:(NSString *)) and property overrides (i.e. accessibilityLabel).
These methods require the block to have a specific return type that corresponds to the attribute's type.
Each of these block based setters have a corresponding accessibility property.
See the notes for the property for more specific information about that property.
*/Но это не наш случай, нам нужна поддержка для iOS 15. Кроме того, нам необходимы проверки на isHidden и alpha. Поэтому напишем специальный блок, который возвращает предсказуемую ленивую иерархию для ViewController.
self.customAccessibilityElementsBlock = { [weak self] in
guard let self else { return nil }
/// если мы хотим вручную задать порядок элементов доступности, с учётом их видимости
/// по дефолту читаем сверху-вниз слева-направо
/// но если по какой-то причине хотим, чтобы верхний элемент был в конце, можем перемешать дефолтный порядок
return [
self.carousel,
self.label2,
self.label,
]
}Нам это понадобилось по нескольким причинам:
Повышаем перформанс, избегая выполнения ненужной работы.
Не боимся изменение экрана — когда экран обновляется (например, зашли в интернет) или пользователь взаимодействует с ним, то могут добавляться новые элементы или что-то удалиться. Не придётся делать дополнительные действия, Accessibility-иерархия всегда в консистентном состоянии.
Делаем настройку удобной. Вся настройка Accessibility-иерархии сосредоточена в одном месте, что позволяет легко разделить код доступности для людей и роботов.
Теперь об accessibility самих элементов. Обычно нас интересуют динамические свойства (label, value, actions). Мы стараемся вычислять их лениво по необходимости, то есть в геттерах:
override var accessibilityLabel: String? {
get { "ячейка" }
set {}
}
override var accessibilityValue: String? {
get { self.label.text }
set {}
}
Если иерархия поменялась, можно дёрнуть метод:
UIAccessibility.post(notification: .layoutChanged, argument: nil)
И тогда iOS пересчитает всё дерево доступности. В аргумент можно передать любой доступный элемент, и фокус ставится на него. Если ничего не передать, то фокус останется на текущем элементе, если он остался.
Укрупнение элементов
Еще один столб доступности, который делает конструкцию более устойчивой к изменениям, — это объединение нескольких блоков текста или кнопок в одну смысловую конструкцию. Такой блок обычно удобнее в использовании, проще в поддержке и сложнее сломать.
Самый очевидный пример смыслового блока — это ячейка в таблице, которая может содержать несколько label’ов, кнопок, картинок и описаний.
Всю эту конструкцию можно превратить в один доступный элемент.
Для начала мы делаем всю ячейку доступной кнопкой, предназначенной исключительно для людей. Для UI-тестов необходимо, чтобы все элементы ячейки можно было идентифицировать по их id. После укрупнения элементов мы рискуем потерять доступ к ним. Конечно, Apple завезла нативный инструмент, который можно посмотреть тут, но он поддерживается только с iOS 17 и не соответствует требованиям наших текущих тестов. Поэтому мы используем старое доброе проверенное годами решение:
if !ProcessInfo.isUITests {
// если не тесты, то ячейка становится одной большой кнопкой
cell.isAccessibilityElement = true
cell.accessibilityTraits.formUnion(.button)
}В нашем проекте мы применяем MVVM, и каждая view имеет свою ViewModel. Для каждой ячейки существует соответствующая ViewModel, которая содержит все сырые данные. Мы собираем все данные для всех label в ячейке в одну ленивую конструкцию, представленную в виде текста в одной большой куче, используя метод accessibilityLabel().
var accessibilityLabel: String? {
[
self.title,
self.subtitle,
…
].accessibilityLabel()
}Также соберём все кнопки в ячейке (если такие имеются) в такую конструкцию:
override var accessibilityCustomActions: [UIAccessibilityCustomAction]? {
get {
guard let name = self.buttonContent?.accessibilityLabel else { return nil }
return [
UIAccessibilityCustomAction(name: name) { [weak self] _ in
guard let self else { return false }
return self.performCallToAction()
},
]
}
set { _ = newValue }
}В самой ячейке нужно переопределить методы:
override var accessibilityLabel: String? {
get { viewModel.accessibilityLabel }
set {}
}
override var accessibilityCustomActions: [UIAccessibilityCustomAction]? {
get { viewModel.accessibilityCustomActions }
set {}
}Возможно, использование одной большой ячейки не самый удобный способ взаимодействия для пользователя, но это очень простой и универсальный подход в разработке и тестировании. Такой код легко написать, ведь есть чёткое правило: одна ячейка — один доступный элемент. Всего четыре возможных способа доставить данные в ячейку — через label, value, accessibilityCustomActions и иногда hint. Ещё можно accessibilityCustomContent для самых странных сценариев, но в данной статье я не рассматривал.
На выходе получим такой сценарий:
Сториз
Ещё один сценарий, который после Snapchat стал актуальным для каждого нового приложения — это сториз. Как правило, это один из первых элементов на экране. 2ГИС не стал исключением:
Если адаптировать сториз в лоб, то пользователю нужно будет пролистать примерно X историй, где X сильно больше 10, прежде чем перейти к следующему доступному элементу.
В книге «Доступность для всех» приводится пример решения такой проблемы с хорошим описанием. Также есть рекомендации Apple.
В этих референсах для таких горизонтальных списков предлагается использовать компонент AccesibilityCarousel. Однако как уважающий себя разработчик я решил написать собственный велосипед, который больше подходит под наши потребности. Этот компонент можно легко интегрировать с любым UICollectionView, чтобы он заработал как карусель. Пример использования есть в демо-проекте.
В основном приложении это выглядит так:
Нюансы, которые о которых неплохо знать
Один важный момент, о котором упомянули специалисты из Сбера: пользователи часто отключают accessibilityHint. Поэтому не следует помещать в него важную актуальную информацию, а использовать его лишь для инструкций по онбордингу для конкретных элементов, которые могут вести себя неочевидным образом.
Для разметки заголовков лучше использовать хэдеры.
Это значительно структурирует большие списки и с помощью специальных механизмов роторов можно очень быстро навигироваться: https://support.apple.com/en-us/111796.
В действии это выглядит так:
К нам приходят новые модные разработчики на SwiftUI, и мне самому приходится становится более современным. В данной статье часть принципов для SwiftUI уже не так актуальна, однако общие принципы по-прежнему применимы. К счастью, SwiftUI пока что использует UIKit под капотом, поэтому создаваемые им иерархии также понимает Snapshot-тестирование, и новый тип тестов пока что изобретать не требуется.
Приложение с плохой разметкой, без укрупнения, но с подписанными кнопками, которые можно нажимать в режиме VoiceOver, а также с возможностью уйти с недоступного экрана, гораздо лучше, чем зацикливаться на идеальном доступном приложении, которое может никогда не наступить.
Accessibility Inspector очень плох, при работе с симулятором не стоит рассчитывать на него. На девайсе он работает намного лучше. Фактически, нет ничего лучше, чем лично тестировать сценарии с закрытыми глазами или выключенным экраном на реальном устройстве.
В результате
Мы адаптировали сценарии, которые решают реальные пользовательские задачи. Например, вот так VoiceOver озвучит пункты стартового экрана приложения и помогает с навигацией по нему:
Киллер-фича (на данный момент) — это адаптация экрана транспортной выдачи под VoiceOver. Он основан на визуальных знаках и символах, которые нужно озвучивать для незрячих пользователей. Мы добавили логику, позволяющую озвучивать сложные маршруты.
Например, подсказка "M (14) → 2" будет озвучена как: «Садитесь на остановке МЦК Площадь Гагарина, выходите на остановке МЦК Кутузовская в сторону станции Лужники, из вагона налево, выход номер 2».
Начало и конец сегмента маршрута озвучиваются как «Садитесь на остановке» и «Выходите на остановке» вместо просто названия остановок.
Напоследок
Apple проделала гигантскую работу — разработала технологии, фреймворки и инструменты, которые продолжают совершенствовать каждый год. Их труд впечатляет, снимаю шляпу. Любое приложение может стать доступным для любого пользователя, адаптация необходима не только для людей с нарушением зрения.
Но в реальной жизни процесс адаптации приложения часто сталкивается с дилеммой курицы и яйца:
если никто не использует доступность, зачем её делать;
но если её не делать, никто и не начнёт использовать.
Поэтому, повторюсь, в больших коммерческих организациях адаптация приложения обычно уступает приоритетом другим фичам. Но этот круг можно разомкнуть. И потребуется настоящая отвага, чтобы довести адаптацию до конца и продолжать её поддерживать.
От стадии непонимания, как взяться за VoiceOver, мы пришли наконец в момент, когда мы выпустили версию 6.34, и начали получать благодарности от пользователей за возможность находить компании, изучать информацию о них и строить маршруты.
Многолетняя работа над этой фичей даёт о себе знать: копится усталость и чувствуется выгорание. Вот буквально на днях переписали «Избранное», и как обычно забыли про доступность.
Но понимаю, что останавливаться нельзя. До сих пор остаются ряд недоступных сценариев. И по мере сил продолжаю работать дальше: делаю VoiceOver-навигатор, который меня просили сделать.
Если вы тоже решитесь адаптировать приложение, то приходите в комменты или личные сообщения. Давайте общаться и делиться опытом!
Команда инженеров ведёт тг-канал, можно краем глаза заглянуть, почитать. Если захотите работать в нашей команде — у нас открыта вакансия iOS-разработчика.
