Текстовое содержимое

Текстовое содержимое — ключевой элемент каждого шага тура в библиотеке Shepherd.js. Оно отвечает за передачу информации пользователю: пояснения интерфейса, инструкции, подсказки и предупреждения. Гибкость настройки текста позволяет создавать как простые подсказки, так и сложные интерактивные сценарии обучения.

Свойство text

Основной способ задания содержимого — использование свойства text в конфигурации шага.

Пример:

tour.addStep({
  id: 'step-1',
  text: 'Это описание элемента интерфейса',
  attachTo: {
    element: '.button-start',
    on: 'bottom'
  }
});

Свойство text поддерживает несколько форматов:

1. Строка

Наиболее простой вариант:

text: 'Нажмите на кнопку, чтобы продолжить'

2. HTML-разметка

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

text: '<strong>Важно:</strong> сохраните изменения перед выходом'

Поддерживаются любые допустимые HTML-теги, включая списки, ссылки и изображения.

3. Массив строк

Каждый элемент массива будет обернут в отдельный <p>:

text: [
  'Первое сообщение',
  'Второе сообщение'
]

Это удобно для логического разделения информации.

4. Функция

Позволяет динамически формировать содержимое:

text: () => {
  return `Текущее время: ${new Date().toLocaleTimeString()}`;
}

Функция вызывается в момент отображения шага, что даёт доступ к актуальным данным.

Использование сложной HTML-структуры

Shepherd.js не ограничивает структуру содержимого. Можно создавать сложные блоки:

text: `
  <div class="tour-content">
    <h3>Добро пожаловать</h3>
    <p>Это начало работы с системой.</p>
    <ul>
      <li>Шаг 1: регистрация</li>
      <li>Шаг 2: настройка профиля</li>
    </ul>
  </div>
`

Важно учитывать:

  • корректность HTML
  • отсутствие конфликтов с CSS
  • безопасность (избегать небезопасного ввода)

Динамическое содержимое и контекст

Функция в text позволяет учитывать состояние приложения:

text: () => {
  const userName = document.querySelector('#user-name').textContent;
  return `Здравствуйте, ${userName}`;
}

Подход полезен при:

  • персонализации туров
  • изменении данных в реальном времени
  • адаптации под разные роли пользователей

Использование DOM-элементов

Вместо строки можно вернуть DOM-узел:

text: () => {
  const container = document.createElement('div');
  container.innerHTML = '<strong>Динамический контент</strong>';
  return container;
}

Это даёт больше контроля над структурой и обработчиками событий.

Стилизация текстового содержимого

Текст наследует стили Shepherd.js, но может быть дополнительно кастомизирован:

.shepherd-text {
  font-size: 16px;
  line-height: 1.5;
}

.tour-content h3 {
  margin-bottom: 8px;
}

Также можно использовать пользовательские классы:

classes: 'custom-step'

Локализация

Для многоязычных интерфейсов текст часто выносится в отдельные ресурсы:

text: i18n.t('tour.step1.description')

Или:

text: () => translations[currentLang].step1

Это позволяет централизованно управлять содержимым.

Работа с пользовательским вводом

Внутри текста можно размещать формы:

text: `
  <label>Введите имя:</label>
  <input type="text" id="tour-name" />
`

Однако обработка событий должна выполняться отдельно:

when: {
  show: () => {
    document.querySelector('#tour-name').addEventListener('input', e => {
      console.log(e.target.value);
    });
  }
}

Ограничения и рекомендации

Безопасность:

  • избегать вставки непроверенных данных в HTML
  • использовать экранирование при необходимости

Читаемость:

  • избегать перегруженных текстов
  • разбивать длинные сообщения на части

Производительность:

  • не выполнять тяжёлые вычисления в функции text
  • кэшировать данные при необходимости

Единый стиль:

  • соблюдать одинаковый тон и формат
  • использовать шаблоны для повторяющихся шагов

Связь с другими параметрами шага

Текст тесно взаимодействует с другими свойствами:

  • title — заголовок шага
  • buttons — действия пользователя
  • attachTo — позиционирование
  • when — жизненный цикл

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

tour.addStep({
  id: 'step-2',
  title: 'Настройки',
  text: [
    'Здесь можно изменить параметры.',
    'Не забудьте сохранить изменения.'
  ],
  attachTo: {
    element: '#settings',
    on: 'right'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Повторное использование текстовых блоков

Часто используемые тексты можно выносить:

const messages = {
  welcome: 'Добро пожаловать в приложение',
  saveReminder: 'Не забудьте сохранить изменения'
};

И применять:

text: messages.welcome

Асинхронное получение текста

Для загрузки данных с сервера:

text: async () => {
  const response = await fetch('/api/tour-text');
  const data = await response.json();
  return data.message;
}

Важно учитывать, что Shepherd ожидает синхронный результат, поэтому асинхронные операции требуют предварительной загрузки данных.

Интеграция с фреймворками

В React, Vue или Angular текст может формироваться через состояние:

text: () => {
  return store.getState().tourMessage;
}

Или через рендер компонентов (с обёртками):

text: () => {
  const el = document.createElement('div');
  ReactDOM.render(<MyComponent />, el);
  return el;
}

Практика структурирования

Эффективная структура текста:

  • короткие абзацы
  • логическое деление
  • акценты через <strong> и <em>
  • списки вместо длинных предложений

Пример:

text: `
  <p><strong>Шаг 1:</strong> Откройте меню</p>
  <p><strong>Шаг 2:</strong> Выберите пункт "Настройки"</p>
`

Типичные ошибки

  • вставка слишком длинных текстов
  • отсутствие форматирования
  • использование небезопасного HTML
  • игнорирование адаптивности (переполнение блока)
  • отсутствие локализации

Расширенные техники

Условное содержимое:

text: () => {
  return isAdmin
    ? 'Доступны расширенные настройки'
    : 'Ограниченный доступ';
}

Генерация шаблонов:

function createStepText(title, description) {
  return `<h3>${title}</h3><p>${description}</p>`;
}

Интеграция с Markdown (через парсеры):

text: marked('# Заголовок\n\nОписание шага')

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

Оглавление