Компонент Guide в WordPress представляет собой всплывающее модальное окно, которое можно использовать для пошагового руководства для пользователей. Компонент позволяет добавлять несколько страниц, через которые пользователь может последовательно переходить, пока не завершит руководство. Завершение происходит либо при закрытии модального окна, либо при нажатии кнопки «Finish» на последней странице.
Основное использование
Для начала рассмотрим, как добавить компонент Guide в ваш React-компонент. В примере ниже создается руководство с двумя страницами.
import { useState } from 'react';
import { Guide } from '@wordpress/components';
function MyTutorial() {
const [ isOpen, setIsOpen ] = useState(true);
if ( !isOpen ) {
return null;
}
return (
<Guide
onFinish={ () => setIsOpen(false) }
contentLabel="Tutorial Guide"
pages={[
{
content: <p>Добро пожаловать в нашу платформу!</p>,
},
{
image: <img src="https://example.com/how-to-start.png" alt="How to start"/>,
content: <p>Нажмите кнопку <i>Начать</i>, чтобы продолжить.</p>,
},
]}
/>
);
}
Описание параметров компонента
Компонент Guide поддерживает несколько параметров, которые позволяют настроить внешний вид и функциональность модального окна. Рассмотрим каждый параметр подробно.
1. className
- Тип:
string - Описание: Позволяет добавить пользовательский CSS-класс к модальному окну для стилизации.
- Обязательный: Нет
<Guide
className="custom-guide-modal"
contentLabel="Custom Guide"
onFinish={ () => console.log("Guide finished") }
pages={[
{ content: <p>Шаг 1</p> },
{ content: <p>Шаг 2</p> },
]}
/>
2. contentLabel
- Тип:
string - Описание: Метка, используемая для доступности (например, для screen reader’ов). Обязательна для повышения доступности компонента.
- Обязательный: Да
<Guide
contentLabel="User Onboarding Guide"
onFinish={ () => console.log("Guide completed") }
pages={[
{ content: <p>Добро пожаловать в приложение!</p> },
]}
/>
3. finishButtonText
- Тип:
string - Описание: Позволяет настроить текст кнопки, завершающей руководство. По умолчанию кнопка отображает текст «Finish».
- Обязательный: Нет
- Значение по умолчанию:
'Finish'
<Guide
contentLabel="Setup Guide"
finishButtonText="Complete Setup"
onFinish={ () => console.log("Setup completed") }
pages={[
{ content: <p>Это первый шаг установки.</p> },
]}
/>
4. onFinish
- Тип:
( event?: KeyboardEvent< HTMLDivElement > | SyntheticEvent ) => void - Описание: Функция, которая вызывается при завершении руководства (при закрытии модального окна или нажатии на кнопку «Finish»).
- Обязательный: Да
<Guide
contentLabel="Welcome Guide"
onFinish={ () => alert("Спасибо за завершение руководства!") }
pages={[
{ content: <p>Поздравляем, вы начали использовать наш продукт!</p> },
]}
/>
5. pages
- Тип:
{ content: ReactNode; image?: ReactNode; }[] - Описание: Массив объектов, описывающий каждую страницу в руководстве. Объекты должны содержать обязательное свойство
contentи могут дополнительно включатьimage. - Обязательный: Нет
- Значение по умолчанию:
[]
<Guide
contentLabel="Product Tour"
onFinish={ () => console.log("Tour completed") }
pages={[
{
content: <p>Добро пожаловать в тур по продукту!</p>,
image: <img src="https://example.com/welcome-image.png" alt="Welcome" />,
},
{
content: <p>Узнайте, как использовать основные функции.</p>,
image: <img src="https://example.com/features.png" alt="Features" />,
},
]}
/>
Полный пример использования всех параметров
Теперь создадим пример, в котором будут задействованы все параметры компонента Guide:
import { useState } from 'react';
import { Guide } from '@wordpress/components';
function ProductGuide() {
const [isOpen, setIsOpen] = useState(true);
if (!isOpen) {
return null;
}
return (
<Guide
className="product-tour-guide"
contentLabel="Product Tour Guide"
finishButtonText="Got it!"
onFinish={() => {
setIsOpen(false);
console.log("User finished the product tour.");
}}
pages={[
{
content: <p>Приветствуем вас в туре по продукту!</p>,
image: <img src="https://example.com/intro.png" alt="Introduction" />,
},
{
content: (
<p>
Здесь вы можете найти наши самые популярные товары. Нажмите на продукт, чтобы увидеть подробности.
</p>
),
image: <img src="https://example.com/popular-items.png" alt="Popular Items" />,
},
{
content: <p>Спасибо, что прошли тур! Теперь вы готовы начать.</p>,
},
]}
/>
);
}
В этом примере используется весь функционал Guide: добавлены класс для стилизации, метка для доступности, кастомный текст для кнопки завершения, а также массив страниц с текстом и изображениями. Когда пользователь завершит тур, окно закроется, и в консоль будет выведено сообщение.
Заключение
Компонент Guide — это полезный инструмент для создания пошагового обучения, туров и других модальных руководств для пользователей. Он предлагает гибкие параметры для настройки, от оформления текста и изображений на каждой странице до задания текстов для кнопок и стилей. Используйте Guide, чтобы сделать ваше приложение более дружелюбным и легким для освоения.