Tour

Запуск обзора

Обычный обзор показывается при каждом запуске. Одноразовый — только пока не завершён: отметка лежит в localStorage под ключом c3-tour-playground-tour-once. Прерванный через «Пропустить» отметку не ставит.

Цель третьего шага

Элемент цели последнего шага: подсветка обводит его, даже когда он обычный текст.

События

Запустите обзор — здесь появятся переходы между шагами и результат.

Входные параметры

Компонент C3Tour не имеет пропов: он рендерит обзор, который запустили программно. Все параметры задаются в вызове start(options) из useC3Tour().

Параметры `start(options)`

Имя	Тип	По умолчанию	Описание
`steps`	`TourStep[]`	—	Обязательный список шагов. Пустой список не запускает обзор.
`name`	`string`	`undefined`	Имя обзора: попадает в ключ `localStorage` как `c3-tour-<name>`. Обязательно при `persist`.
`persist`	`boolean`	`false`	Не показывать обзор повторно, если он уже завершён в этом браузере.
`labels`	`TourLabels`	русские подписи	Переопределение подписей кнопок: `next`, `prev`, `done`, `skip`.
`onFinish`	`() => void`	—	Обзор дошёл до последнего шага и нажата кнопка «Готово».
`onSkip`	`() => void`	—	Обзор прерван: «Пропустить», крестик или Escape. Отметка о завершении не пишется.
`onStepChange`	`(index, step) => void`	—	Показан новый шаг: его индекс и сам шаг.

Тип `TourStep`

Поле	Тип	По умолчанию	Описание
`target`	`string`	—	Обязательный CSS-селектор элемента. Шаг, чей элемент не найден, пропускается; если не нашлось ни одного — обзор завершается.
`title`	`string`	`undefined`	Заголовок шага. Попадает в `aria-label` подсказки.
`content`	`string`	`undefined`	Текст шага.
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Сторона подсказки относительно элемента. При нехватке места сторона меняется автоматически.
`padding`	`number`	`6`	Отступ подсветки от элемента в пикселях.
`beforeShow`	`() => void \| Promise<void>`	—	Выполняется до показа шага. Нужен, чтобы раскрыть панель или дождаться загрузки: прямоугольник считается уже после этого.

Методы `useC3Tour()`

Имя	Возвращает	Описание
`start(options)`	`Promise<void>`	Запустить обзор.
`next()`	`Promise<void>`	Следующий шаг: на последнем завершает обзор.
`prev()`	`Promise<void>`	Предыдущий шаг.
`goTo(index)`	`Promise<void>`	Перейти к шагу. Индекс за пределами списка завершает обзор, отрицательный игнорируется.
`finish()`	—	Завершить обзор и записать отметку о завершении.
`skip()`	—	Прервать обзор без отметки о завершении.
`isRunning`	`Ref<boolean>`	Идёт ли обзор.
`currentIndex`	`Ref<number>`	Индекс текущего шага.
`total`	`ComputedRef<number>`	Всего шагов.
`labels`	`ComputedRef<TourLabels>`	Подписи кнопок запущенного обзора.
`currentStep`	`ComputedRef<TourStep \| null>`	Текущий шаг.
`isLastStep`	`ComputedRef<boolean>`	Последний ли шаг.
`hasPrev`	`ComputedRef<boolean>`	Есть ли куда вернуться.
`resetC3TourCompletion(name?)`	—	Сбросить отметку о завершении: один обзор или все сразу.

Описание

Обзор интерфейса проводит пользователя по ключевым элементам экрана: затемняет страницу, подсвечивает нужный элемент и показывает рядом подсказку с кнопками. Это способ показать новую функциональность без длинной статьи.

Состояние общее для приложения, поэтому start() можно вызвать из composable, стора или обработчика — достаточно поставить хост C3Tour один раз в корневом макете.

Цели задаются CSS-селекторами, поэтому обзор не привязан к конкретной вёрстке: шаг указывает на элемент по id или классу. Если элемент на странице отсутствует (например, панель свёрнута и шаг запустился не вовремя), шаг пропускается, а не показывается поверх произвольного места. Если не нашлось ни одного шага, обзор просто завершается.

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

Дополнительная информация

Затемнение делается тенью подсвеченного элемента: окно вокруг цели остаётся чистым, а перекрытие страницы работает без отдельного слоя.
Скругление подсветки берётся из border-radius цели, поэтому круглые кнопки подсвечиваются круглыми.
Перед показом элемент прокручивается в центр: иначе шаг мог бы оказаться за пределами экрана.
Положение подсказки пересчитывается при прокрутке и изменении размеров окна; сторона меняется автоматически, если элемент у края экрана (computePopoverPosition).
Клавиатура: → и Enter — следующий шаг, ← — предыдущий, Escape — прервать обзор.
Доступность: подсказка — role="dialog" с aria-modal="true", заголовок шага попадает в aria-label, фокус переносится на подсказку. Подсветка помечена aria-hidden: это декорация, смысл несут текст и позиция.
Прогресс показывается как «2 / 5», а кнопка «Назад» появляется только со второго шага; на последнем «Далее» превращается в «Готово».
Отметка о завершении пишется в localStorage только при finish(): прерывание через «Пропустить» позволяет показать обзор снова.
Все обращения к localStorage обёрнуты в try/catch: в приватном режиме хранилище недоступно, но обзор продолжит работать.
Состояние читается и пишется только на клиенте, поэтому SSR не расходится с гидрацией.
Телепорт рендерится только на клиенте, поэтому SSR-разметка не расходится при нескольких таких компонентах.
Слой не перехватывает клики: элемент под подсветкой остаётся доступным, чтобы пользователь мог сразу попробовать действие.

Пример использования

const { start } = useC3Tour()

start({ name: 'dashboard-intro', persist: true, steps: [{ target: '#kpi', title: 'Показатели', content: 'Здесь собираются ключевые числа', placement: 'bottom' }, { target: '#chart', content: 'График за последние 30 дней', placement: 'right' }], onFinish: () => track('tour-finished') })