Настройки чтения

Кнопка настройки в шапке открывает боковую панель «Настройки» справа. Панель строит продуктовый Smart-компонент docara.preferences, а поведение модального окна, затемнение, фокус, закрытие по Escape и блокировку прокрутки предоставляет sf-modal SIMAI Framework.

В базовой поставке панель содержит три параметра: тему, размер шрифта и ширину страницы. Каждый параметр — это подпись и под ней сегментированный переключатель из группы кнопок SIMAI Framework. Внутри каждого сегмента находится обычная радиокнопка, поэтому группа доступна с клавиатуры как radiogroup: одна остановка по Tab, выбор стрелками. Изменение применяется сразу, отдельная кнопка сохранения не нужна. Шапка панели лежит на поверхности --sf-surface-1, параметры — на --sf-surface-0.

В шапке панели слева от кнопки закрытия находится кнопка «Сбросить настройки» (значок restart_alt): она возвращает все параметры к значениям сайта.

Тема поддерживает три значения:

• Как в системе — тема следует режиму устройства;
• Светлая — всегда используется светлая тема;
• Тёмная — всегда используется тёмная тема.

Размер шрифта

Мелкий, Обычный и Крупный меняют размер всего интерфейса документации: шапки, левого меню, содержания страницы, хлебных крошек и текста. Основной текст 16 px становится 14 px или 18 px, и вместе с ним меняются меню, отступы и элементы управления.

Docara меняет корневой размер шрифта на 87,5 % или 112,5 %. Типографика, отступы, элементы управления и ширины контейнеров SIMAI Framework заданы в rem, поэтому весь интерфейс масштабируется согласованно, как при изменении размера текста в браузере. Проценты сохраняют собственную базовую настройку браузера читателя. Примеры в изолированных фреймах получают корневой размер страницы при подготовке.

Ширина страницы

Обычная использует ширину сетки, которую автор задал через layout.container.max. Широкая берёт самый широкий шаг контейнера SIMAI Framework — тот же, что layout.container.max: 8 (112rem), — для шапки, сетки документации и футера и снимает ограничение длины строк у абзацев и списков. Ширина не растёт бесконечно: на большом экране или при уменьшенном масштабе браузера она останавливается на этом шаге. Если сайт уже использует max: 8, широкий формат меняет только длину строк.

Содержание и режим чтения

Справа от хлебных крошек находятся две кнопки: сначала «Режим чтения», затем кнопка содержания, ближайшая к колонке, которой она управляет.

• Скрыть содержание страницы (значок dock_to_left) убирает правую колонку «Содержание», и текст занимает освободившееся место. Повторное нажатие возвращает колонку. Кнопка видна только там, где колонка показывается: на узких экранах содержание открывается отдельной кнопкой над текстом.
• Режим чтения оставляет на экране только текст страницы: шапка, левое меню, содержание и футер скрываются. В правом верхнем углу окна появляется круглая кнопка выхода (radius-rounded Framework), и фокус переходит на неё; выйти можно и клавишей Escape, после чего фокус возвращается на кнопку режима чтения.

У обеих кнопок постоянная подпись и состояние aria-pressed. Состояние сохраняется для всего сайта и действует при переходе на другие страницы, после перезагрузки и в других вкладках.

Значение по умолчанию

Автор задаёт тему сайта через наследуемую ветку settings:

{
  "settings": {
    "theme": "system",
    "modal_blur": "none",
    "ui_radius": "default"
  }
}

Эти значения можно переопределять в section.json и <page>.page.json. Локальный выбор читателя имеет приоритет. Кнопка «Сбросить настройки» удаляет все пользовательские переопределения и снова применяет значения текущей страницы. Для размера шрифта и ширины значение сайта — «Обычный» и «Обычная».

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

Какие поля показывать

Состав панели задаётся только на уровне сайта в docara.json:

{
  "reader_preferences": {
    "enabled": true,
    "view": "side-panel",
    "groups": [
      {
        "id": "appearance",
        "fields": ["appearance.theme", "appearance.font_size", "appearance.content_width"]
      }
    ]
  }
}

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

{
  "reader_preferences": {
    "enabled": true,
    "view": "side-panel",
    "hidden_fields": ["appearance.content_width"],
    "groups": [{"id": "appearance", "fields": ["appearance.theme"]}]
  }
}

Поле нельзя одновременно перечислить в группе и в hidden_fields: такая конфигурация останавливает сборку.

enabled: false полностью убирает кнопку, Smart-компонент и его ассеты. Неизвестное поле, повтор, неверная группа или неподдерживаемое представление останавливают сборку. Исключение — снятые поля appearance.modal_blur и appearance.ui_radius: если они остались в старой конфигурации, Docara их пропускает. В section.json и page sidecar эта ветка запрещена: один сайт не должен менять состав пользовательских настроек от страницы к странице.

Новые настройки добавляются через реестр определений. Определение сообщает идентификатор, группу, допустимые значения, вид элемента управления, безопасный эффект, момент применения и ключи локализованного текста. docara.json только выбирает, какие зарегистрированные поля показать, и не содержит исполняемого кода.

Хранение и приватность

Docara сохраняет один версионированный JSON-документ в localStorage:

{
  "schema": 1,
  "values": {
    "appearance.theme": "dark",
    "appearance.font_size": "large",
    "appearance.content_width": "wide"
  }
}

Ключ изолирован по base_url сайта и имеет вид docara.preferences.<site-hash>.v1. Хранятся только отличия от авторских значений. Значения полей, которых сайт больше не предлагает, удаляются из документа при следующем открытии страницы. Состояние кнопок содержания и режима чтения хранится рядом, под ключом docara.reading.<site-hash>.v1. Аккаунт, сервер, аналитика и cookie не используются.

Тема, размер шрифта, ширина и состояние кнопок восстанавливаются скриптом в <head> до первого отображения страницы, поэтому страница не мигает неправильной раскладкой. Если постоянное хранилище недоступно, выбор работает до перезагрузки, а панель честно сообщает об этом. Изменение в другой вкладке синхронизируется через событие браузера storage.

См. также конфигурацию, макеты и навигацию и наследование настроек.