Alt-screen и размеры окна

Опция tea.WithAltScreen() передаётся в tea.NewProgram, как мышь или скорость кадров: терминал переключается во второй буфер, и весь экран становится вашим холстом. При завершении программы терминал сам вернёт первый буфер — история команд, вывод прошлых запусков, приглашение оболочки, всё останется нетронутым. Механизм старше Bubble Tea на десятилетия: vim и less жили в нём всегда, и пользователь терминала ожидает именно такое поведение от полноэкранных программ. Переключаться можно и на ходу: команды tea.EnterAltScreen и tea.ExitAltScreen возвращаются из Update как обычные tea.Cmd — так делают виджеты, которые по клавише f разворачиваются на весь экран и сворачиваются обратно. Есть нюанс: во втором буфере нет истории прокрутки, потому что там и нечего прокручивать — вы перерисовываете весь кадр каждый раз. Отсюда правило: в alt-screen живут панели и дашборды, чей кадр помещается на экран целиком или прокручивается внутренним viewport, а всё, что должно остаться в терминальной истории — логи, результаты, вывод команд, — оставляйте инлайну. Смешивать можно: базовый вывод — инлайном, а по клавише f — разворот во второй буфер через tea.EnterAltScreen, рабочий компромисс для утилит с двумя режимами.

Сообщение tea.WindowSizeMsg — единственный честный способ узнать размеры терминала. У него два поля: Width и Height, оба в ячейках, оба — размер всего окна. Приходит оно дважды по смыслу: один раз при старте, до первых нажатий, и на каждое изменение размера окна — пользователь потянул край, развернул на полный экран, переехал в tmux-сплит. Важно, что измеряет фреймворк само: вы не вызываете функции из golang.org/x/term и не ловите SIGWINCH руками — цикл Bubble Tea делает это за вас и кладёт результат в очередь сообщений. Игнорировать сообщение можно, но недолго: раскладка с жёсткими константами будет жить в мёртвом прямоугольнике посреди изменившегося окна. Первый WindowSizeMsg — самое первое событие вашей программы, оно обрабатывается раньше любого нажатия клавиш. Храните размеры в модели как поля width и height и держите в голове: View не умеет спрашивать терминал, ему размеры обязана принести модель из Update. Раскладка — функция этих чисел, а не догадка на этапе компиляции. Полезная привычка на время разработки — печатать текущие размеры в отладочной строке футера: сразу видно, доходит ли сообщение и какие числа приходят в tmux-сплите и при сворачивании окна.

Ветка WindowSizeMsg — место, где живёт вся адаптивность. Схема механическая: сохранить msg.Width и msg.Height в модель, пересчитать размеры компонентов их сеттерами, вернуть модель. Компоненты bubbles перенастраиваются методами SetWidth и SetHeight — таблица из тринадцатого урока, textarea, viewport. Вычитаемые числа — резервы вашей раскладки: сколько колонок съедает сайдбар, сколько строк уходит заголовку и статус-бару. Держите их в именованных константах, а не в магических числах посреди Update: раскладка меняется часто, и разыскивать «а что тут за минус восемнадцать» вы будете у себя же. Если в модели есть производные от размеров поля — ширины колонок, лимиты переноса — пересчитывайте их в той же ветке: рассинхрон между полями модели и компонентами ловится хуже всего. Связь с предыдущим уроком прямая: там собирались фиксированные панели, здесь их размеры становятся вычисляемыми. Отдельно помните про первый запуск: пока WindowSizeMsg не обработан, размеры в модели нулевые, и View может отрисовать пустоту — либо обрабатывайте сообщение до первого кадра, либо задайте полям разумные дефолты в конструкторе.

В инлайн-режиме высоту терминала вы почти не чувствуете: строки дозаписываются и прокручиваются средствами самого терминала. В alt-screen высота становится равноценной ширине: экран высотой в тридцать строк — это тридцать строк под весь интерфейс, включая шапку и статус-бар. Формула простая: viewport.SetHeight(msg.Height) минус высота всех соседей по кадру. Высоту шапки и футера не обязательно считать руками — lipgloss.Height измеряет уже отрендеренную строку, и вызов его в ветке WindowSizeMsg экономит от расползания констант: поменяли шапку — пересчёт сам подхватился. Тело панели живёт в viewport и прокручивается клавишами и колесом мыши из урока про мышь. Держите бюджет строк в голове при каждой правке кадра: добавили разделитель — высота тела уменьшилась на единицу, забрали — появилась пустая строка. Если содержимого меньше высоты, viewport добьёт остаток пустотой — это нормально и лучше, чем прыгающий футер. Проверять высотную раскладку нужно вживую: только локальный запуск в настоящем терминале покажет, что на высоте в двадцать строк панель не срезала статус-бар — браузерные эмуляции resize терминала не передают.

Пользователь тянет край окна — терминал посылает процессу сигнал SIGWINCH, «окно изменилось». Цикл Bubble Tea ловит его, заново измеряет терминал и кладёт в очередь WindowSizeMsg с новыми числами; дальше работает обычный механизм: Update, пересчёт, перерисовка. Что стоит сделать в этой ветке кроме пересчёта размеров. Первое — поджать позицию прокрутки: если viewport показывал конец лога, после уменьшения высоты окно могло оказаться больше содержимого или наоборот — часть программ переходит к концу списка принудительно, вычитая из высоты контента новую высоту окна. Второе — деградация раскладки: на ширину меньше минимальной сайдбар лучше убрать вовсе, а не сжимать панели до нечитаемости; порог — тоже константа рядом с резервами, и решение об убранной панели — ветка if в той же обработке. Третье — не доверять кратковременным размерам: перетаскивание края порождает целую серию сообщений, и тяжёлые вычисления в ветке resize лучше делать по последнему значению, а не на каждое промежуточное. И проверка после правок: несколько растяжений-сжатий подряд не должны оставлять после себя мусор — кадр рисуется с нуля каждый раз.

Выбор режима — это ответ на вопрос, что должно остаться в терминале после выхода. Инлайн оставляет след: последний кадр дозаписан в историю, вывод можно листать, копировать и встречать в CI-логах — идеально для прогресса, однолинейных виджетов и утилит, которые вызывают в пайплайнах. Alt-screen следа не оставляет: после выхода терминал выглядит нетронутым — это режим панелей, дашбордов и редакторов, интерфейс-приложений, а не интерфейс-вывода. Отдельная опция tea.WithOutput расширяет выбор: программа рисует в переданный io.Writer, а не в stdout — так тестируют рендер в буфер строк и встраивают интерфейсы в нестандартные окружения вроде SSH-сессий, где терминал находится на стороне клиента. Опции комбинируются: WithAltScreen с WithMouseCellMotion даёт полноэкранную кликабельную панель, а WithOutput чаще нужен для тестов — о них ближе к уроку про тестирование TUI. Решение не навсегда: маленькая утилита может начать с инлайна и переехать в alt-screen по мере роста, смена — одна строка в main. Переехать обратно тоже можно, но пользователи будут удивлены, если утилита вдруг начнёт съедать экран целиком — режим вывода — часть контракта с тем, кто вызывает программу из скриптов. Сводка различий — в таблице ниже.

Полноэкранную раскладку удобно собрать из трёх приватных методов: headerView, bodyView и footerView, каждый возвращает строку, а View склеивает их JoinVertical из прошлого урока. Такой разрез даёт две выгоды. Первая — измерение: lipgloss.Height от шапки и футера в ветке WindowSizeMsg считается именно по этим методам, и формула высоты тела всегда согласована с реальным рисунком. Вторая — изоляция: шапку с титулом и часами правите вы отдельно, тело с viewport — отдельно, и правка одного куска не задевает другой. Футер — самое практичное место: справа подсказки клавиш, слева состояние — эта строка тянется на всю ширину через вычитание ширин. Проверенный порядок сборки: сначала методы возвращают содержимое без ширины, затем View обёртывает каждый в стиль с Width из модели — так один и тот же headerView работает и в полноэкранной панели, и в узком инлайн-виджете. Порядок строк в JoinVertical задаёт и порядок чтения: шапка, тело, футер — на нём же строится представление пользователя о том, что где искать. Если методы начинают тянуть в себя десяток полей модели — это сигнал, что экрану пора в отдельный файл, но об этом дальше по курсу.

Полноэкранная геометрия — фундамент для остального. Клики по зонам, которые должны следовать за resize, разбирает урок про мышь — вместе эти два урока дают живую панель. Часы, тикающие в углу полноэкранного дашборда, — дело урока про таймеры и tea.Tick. Когда панелей и экранов станет несколько, раскладка с константами переберётся в отдельные файлы — этому учит урок про структуру крупного проекта. Обзор остальных тем — на странице курса Bubble Tea. Практика: запустите панель в alt-screen, растяните и сожмите окно от сорока до ста двадцати колонок и проверьте, что статус-бар тянется, а viewport не съедает футер.