Спиннеры: индикаторы загрузки

bubbles — официальный набор компонентов Charm, и спиннер — самый маленький его жилец: пакет github.com/charmbracelet/bubbles/spinner. Идея та же, что у всей библиотеки: компонент — это модель со своими Update и View, которую вы встраиваете в свою модель полем и кормите сообщениями. Встраивание — не наследование: переопределять ничего не нужно, вы храните значение и сами решаете, какие сообщения ему достанутся — этот подход целиком разберёт восьмой урок. spinner.New() возвращает начальный спиннер с пресетом Line; чтобы выбрать другой, присвойте поле Spinner — s.Spinner = spinner.Dot. У модели есть и поле Style для цвета, но о цвете поговорим на уроке про Lip Gloss, пока достаточно и без стилей. Если вы уже трогали другие bubbles-компоненты, схема узнается с первого взгляда — и наоборот, спиннер станет образцом для всего набора. Дальше по плану: рассмотреть пресеты, разобрать команду Tick, которая запускает анимацию, и главный практический навык урока — как спиннер останавливать, потому что вечно крутящийся индикатор врёт пользователю ровно так же, как молчащий экран.

Анимация спиннера — это цепочка асинхронных команд из прошлого урока. В модели spinner есть поле Tick — готовая команда первого тика: Init возвращает её, фреймворк запускает, и через промежуток FPS в Update прилетает spinner.TickMsg. Дальше ваша очередь: переслать сообщение вложенной модели — m.spinner, cmd = m.spinner.Update(msg) — и вернуть полученную команду наружу. Внутри она планирует следующий тик, тот снова приходит TickMsg, цепочка замыкается: спиннер крутится, пока Update исправно возвращает команды. Это тот же приём самозапланированной команды, что вы поймали в predict прошлого урока, только закрытый в компоненте. Заметьте, что тик — обычное сообщение: он проходит через ваш switch наравне с клавишами, поэтому вы всегда можете вмешаться — замедлить, пропустить или не вернуть команду вовсе. Схема одинакова для всех тикающих компонентов — часов, таймеров, прогресс-баров: учась на спиннере, вы учитесь всему классу. Заметьте деталь: пересылка сообщения и возврат команды — два отдельных действия, и оба нужны. Забудете вернуть — анимация умрёт; забудете переслать — кадр перестанет меняться, хотя тики продолжат приходить. О том, как цепочку разрывать, — чуть ниже, это главный навык урока.

Пресет — это просто значение типа spinner.Spinner с двумя полями: Frames — срез строк-кадров и FPS — частота. Никакой магии, поэтому свой спиннер собирается одной переменной: var slowRing = spinner.Spinner{Frames: []string{"◐", "◓", "◑", "◒"}, FPS: time.Second / 2} — и присваивается модели как обычный пресет. Частота подбирается по характеру ожидания: десять кадров в секунду — живое вращение, три-четыре — степенное, «мы работаем, не торопимся». Пара грабель. Брайль-кадры требуют шрифта с поддержкой брайля: на дежурной моноширинной машине вы получите квадратики вместо точек. Эмодзи-кадры вроде глобуса занимают двойную ширину и рвут вёрстку строк. Я по умолчанию беру Line: скучно, зато предсказуемо в любом терминале; выразительные пресеты оставляю для случаев, когда точно знаю аудиторию. Полный список пресетов с их FPS живёт в исходнике пакета — spinner.go, он короткий.

Загрузка — это машина состояний, и спиннер — только её видимая часть. Минимальный набор: idle — работы нет, экран спокойный; loading — идёт, индикатор крутится; done — результат показан; error — ошибка видна и повтор доступен. Пара полей модели покрывает всё: loading bool и err error, как в прошлом уроке. Ошибки проектирования начинаются, когда состояния смешивают: спиннер крутится поверх уже показанных данных, «Готово» рисуется рядом с ошибкой, повторная загрузка не сбрасывает старый результат. Проверяйте себя простым правилом: каждая ветка View отвечает ровно одному состоянию, а переходы делаются только в Update при приходе сообщений — workDoneMsg, tasksLoadedMsg, errMsg. Если один и тот же переход случается в двух местах, вы уже потеряли контроль. И помните: повторная операция обязана снова включить loading и обнулить прошлый результат — забытый сброс даёт интерфейс, который показывает старое поверх нового.

Одинокая палочка малоинформативна, поэтому спиннер склеивают с надписью: m.spinner.View() + " Загружаю задачи..." — View возвращает текущий кадр строкой, дальше обычная конкатенация. Рядом уместно писать, что именно происходит: «Проверяю токен», «Скачиваю пакет 2 из 9» — чем конкретнее строка, тем спокойнее пользователь. Цвет и отступы добавит поле Style, когда дойдём до Lip Gloss. Отдельный вопрос — куда влезает спиннер: в инлайн-режиме кадр перерисовывается на месте, и постоянное вращение дёргает вывод, если интерфейс длиннее пары строк; полноэкранным программам с альтернативным экраном это не грозит. И не забывайте про честность: спиннер без слова «отмена» — это спиннер, который нельзя отменить; кнопку Esc по контексту из прошлого урока стоит держать в голове с первого дня. Практика из жизни: строчку статуса полезно менять на этапах — «Подключаюсь», «Разбираю ответ», «Сохраняю» — пользователь читает её как прогресс, даже без процентов.

Спиннер — инструмент для неопределённого ожидания: вы не знаете, сколько продлится операция. Когда доля выполненного известна — копирование файла по байтам, загрузка девяти пакетов, — честнее показать полосу прогресса: проценты снимают тревогу лучше любого вращения. Когда операция короче полсекунды, индикатор вообще вреден: он успевает мигнуть и создаёт ощущение дёрганья; классическое правило интерфейсов — показывать ожидание не сразу, а после задержки в 300–500 миллисекунд, и терминал здесь не исключение. Наконец, когда пользователь ждёт осмысленно — установка пакета на пять минут, — спиннер плюс этапы информативнее одного процента: люди предпочитают понимать, где они в процессе. Выбирайте индикатор по природе ожидания, а не по красоте пресета — и интерфейс станет честнее без единой новой зависимости.

Десять кадров в секунду звучит дорого, и для спиннера это неправда: рендерер Bubble Tea сравнивает новый кадр со старым и обновляет только изменившиеся строки — одна строка с палочкой почти ничего не стоит. Но View целиком пересчитывается при каждом сообщении, включая тики: если View строит гигантскую строку на тысячи позиций — таблицу, лог — вы будете пересобирать её десять раз в секунду только ради палочки. Симптом знакомый: спиннер тормозит интерфейс, хотя «ничего не делает». Лечение простое: держите View дешёвым — тяжёлые куски собирайте один раз в полях модели при изменении данных, а на каждый кадр только склеивайте готовое. Второй рычаг — FPS: для медленных операций степенный Ellipsis на трёх кадрах информативен не хуже быстрого Dot. Замеряйте на своём железе: у теории дешёвых перерисовок, как и у всего, есть предел применимости.

Спиннер закрыл вопрос «как показать ожидание», но в примере выше работу запускало нажатие клавиши — потому что Init умеет возвращать лишь одну команду. Как запустить тики и загрузку одновременно, объединяя команды в пачки, — тема седьмого урока про tea.Batch и tea.Sequence. Когда ожидание измеримо в процентах, вращение меняется на полосу: прогресс-бары bubbles покажут долю сделанного. А вернуть былую механику можно перечитав пятый урок про tea.Cmd — вся анимация спиннера построена на нём. Программа курса целиком — на странице курса Bubble Tea. Домашнее задание сделайте в терминале: замените Dot на свой пресет из трёх кадров и подберите FPS так, чтобы вращение не раздражало за десять секунд.