RTL-языки

Shepherd.js — библиотека для создания интерактивных пошаговых руководств в веб-приложениях, и она предусматривает гибкую работу с языками, использующими направление письма справа налево (Right-to-Left, RTL), такими как арабский, иврит и персидский. Управление RTL важно для корректного отображения подсказок, их позиционирования и навигационных кнопок.

Определение направления текста

В Shepherd.js направление текста зависит от контейнера, в котором отображается тур, а также от конфигурации body и целевых элементов. Для RTL необходимо правильно задавать CSS-свойство direction:

body {
  direction: rtl;
}

Если тур создается внутри отдельного контейнера:

<div id="tour-container" style="direction: rtl;"></div>

При такой настройке Shepherd корректно отобразит все подсказки, учитывая зеркальное положение стрелок и кнопок навигации.

Конфигурация шага для RTL

Каждый шаг Shepherd.js создается через объект конфигурации с ключевыми параметрами: title, text, attachTo, buttons, advanceOn и classes. Для RTL важно корректно настроить позиционирование с помощью свойства attachTo:

const tour = new Shepherd.Tour({
  useModalOverlay: true,
  defaultStepOptions: {
    scrollTo: { beh * avior: 'smooth', block: 'center' },
    classes: 'shepherd-theme-arrows'
  }
});

tour.addStep({
  id: 'step-1',
  text: 'Пример шага с поддержкой RTL',
  attachTo: {
    element: '#example-element',
    on: 'left' // для RTL 'left' становится справа визуально
  },
  buttons: [
    {
      text: 'Назад',
      action: tour.back
    },
    {
      text: 'Вперед',
      action: tour.next
    }
  ]
});

tour.start();

Важно учитывать, что свойства on: 'left' или 'right' в RTL инвертируются визуально, поэтому стрелка и подсказка будут корректно отображены по направлению текста.

Адаптация стрелок и тем

Shepherd.js использует темы для визуализации стрелок и контейнеров. Для RTL необходимо применять CSS, который отражает направление подсказки:

.shepherd-theme-arrows .shepherd-arrow {
  right: auto;
  left: 0;
}

Можно создавать отдельные темы для LTR и RTL и переключать их в зависимости от языка страницы. Например:

const theme = document.documentElement.dir === 'rtl'
  ? 'shepherd-theme-rtl'
  : 'shepherd-theme-arrows';

Настройка кнопок навигации

Кнопки “Назад” и “Вперед” нужно располагать с учётом RTL, чтобы пользовательский интерфейс был интуитивным:

buttons: [
  {
    text: 'Вперед',
    action: tour.next,
    classes: 'shepherd-button-primary'
  },
  {
    text: 'Назад',
    action: tour.back,
    classes: 'shepherd-button-secondary'
  }
]

Для RTL логично менять порядок кнопок визуально через CSS:

.shepherd-footer {
  display: flex;
  flex-direction: row-reverse;
  justify-content: flex-end;
}

Обработка событий и динамических изменений

При динамической смене языка на странице с RTL необходимо пересоздавать или обновлять тур. Shepherd.js предоставляет методы tour.steps.forEach(step => step.updateStepOptions({...})), что позволяет изменять направление, текст и кнопки без полной перезагрузки страницы.

tour.steps.forEach(step => {
  step.updateStepOptions({
    attachTo: { on: document.documentElement.dir === 'rtl' ? 'left' : 'right' },
    buttons: document.documentElement.dir === 'rtl'
      ? [{ text: 'Вперед', action: tour.next }, { text: 'Назад', action: tour.back }]
      : [{ text: 'Назад', action: tour.back }, { text: 'Вперед', action: tour.next }]
  });
});

Интеграция с библиотеками локализации

Для многоязычных приложений полезно интегрировать Shepherd.js с библиотеками локализации, такими как i18next. Это позволяет динамически подставлять текст, менять направление страницы и адаптировать все шаги тура:

tour.addStep({
  id: 'localized-step',
  text: i18next.t('tour.step1'),
  attachTo: { element: '#element', on: document.documentElement.dir === 'rtl' ? 'left' : 'right' },
  buttons: [
    { text: i18next.t('tour.back'), action: tour.back },
    { text: i18next.t('tour.next'), action: tour.next }
  ]
});

Особенности для сложных макетов

  • Модальные оверлеи: при включении useModalOverlay: true модальный слой корректно учитывает направление текста, но для RTL может потребоваться дополнительная настройка CSS, чтобы стрелки не пересекали элементы.
  • Прокрутка: свойство scrollTo работает одинаково для LTR и RTL, но ориентация относительно экрана изменяется, особенно при использовании block: 'center'.
  • Множественные шаги: при переходе между шагами в RTL важно проверять, что attachTo отражает правильное направление, иначе стрелки будут “смотреть” в неверную сторону.

Поддержка RTL в Shepherd.js достигается комбинацией корректного CSS, динамического управления шагами и внимательного обращения с кнопками и позиционированием подсказок. Это позволяет создавать удобные интерактивные туры для пользователей, использующих языки с письмом справа налево.

Оглавление