Gogs e3d664bdc9 --		3 هفته پیش
..
README.md	e3d664bdc9 --	3 هفته پیش
index.coffee	d100bd6170 --	3 هفته پیش
index.pug	d100bd6170 --	3 هفته پیش
index.styl	d100bd6170 --	3 هفته پیش

Компонент SuccessModal - Полная документация

Назначение компонента

SuccessModal - компонент модального окна для отображения успешных операций, подтверждений и уведомлений. Предоставляет стандартизированный интерфейс для информирования пользователя о успешном выполнении действий с возможностью кастомизации контента и поведения.

git репозитарий

https://gogs.osvoj.ru/s5l.ru/borbad.s5l.ru/src/master/vue/app/shared/SuccessModal/

Импорт и регистрация

# В основном файле приложения (app/temp.coffee)
components:
    'success-modal': require 'app/shared/SuccessModal'

Базовое использование

1. Простое модальное окно

success-modal(
    :show="showSuccess"
    title="Операция выполнена"
    message="Данные успешно сохранены"
    @close="showSuccess = false"
)

2. Модальное окно с кастомными действиями

success-modal(
    :show="showSuccess"
    title="Заказ оформлен"
    message="Ваш заказ успешно создан и передан в обработку"
    @close="handleOrderSuccess"
)

Полный список props

`show` (обязательный)

Тип: Boolean
Описание: Управляет видимостью модального окна

Пример:

success-modal(:show="isModalVisible" @close="isModalVisible = false")

`title` (опциональный)

Тип: String
По умолчанию: 'Успешно!'
Описание: Заголовок модального окна

Пример:

success-modal(:show="showModal" title="Профиль обновлен")

`message` (опциональный)

Тип: String
По умолчанию: ''
Описание: Основное сообщение модального окна

Пример:

success-modal(
  :show="showModal"
  message="Изменения успешно сохранены и применены к вашему профилю"
)

`buttonText` (опциональный)

Тип: String
По умолчанию: 'Понятно'
Описание: Текст на кнопке подтверждения

Пример:

success-modal(:show="showModal" buttonText="Отлично!")

`icon` (опциональный)

Тип: String
По умолчанию: 'check-circle'
Описание: Название иконки для отображения
Допустимые значения: Любое название иконки из используемой иконной библиотеки

Пример:

success-modal(:show="showModal" icon="check")

`size` (опциональный)

Тип: String
По умолчанию: 'md'
Описание: Размер модального окна
Допустимые значения: 'sm', 'md', 'lg', 'xl'

Пример:

success-modal(:show="showModal" size="lg")

`closeOnBackdrop` (опциональный)

Тип: Boolean
По умолчанию: true
Описание: Закрывать ли модальное окно при клике на бэкдроп

Пример:

success-modal(:show="showModal" :closeOnBackdrop="false")

`showCloseButton` (опциональный)

Тип: Boolean
По умолчанию: true
Описание: Показывать ли кнопку закрытия в заголовке

Пример:

success-modal(:show="showModal" :showCloseButton="false")

`autoClose` (опциональный)

Тип: Boolean | Number
По умолчанию: false
Описание: Автоматическое закрытие модального окна. Если true - 3000ms, если число - указанное время в ms

Примеры:

success-modal(:show="showModal" :autoClose="true") // Закроется через 3 секунды
success-modal(:show="showModal" :autoClose="5000") // Закроется через 5 секунд

События (Events)

`@close`

Описание: Событие закрытия модального окна
Payload: null
Когда вызывается:
- Клик на кнопку закрытия
- Клик на бэкдроп (если closeOnBackdrop = true)
- Нажатие клавиши ESC
- Автоматическое закрытие (если autoClose включен)

Пример:

success-modal(:show="showModal" @close="handleModalClose")

`@confirm`

Описание: Событие подтверждения (клик на основную кнопку)
Payload: null

Пример:

success-modal(:show="showModal" @confirm="handleSuccessAction")

Слоты (Slots)

`[body]` (основной слот)

Описание: Кастомное содержимое модального окна вместо стандартного message

Примеры:

success-modal(:show="showModal" title="Заказ оформлен")
  div(class="space-y-4")
      p Ваш заказ №{{ orderId }} успешно создан
      div(class="bg-gray-50 p-4 rounded")
          h4(class="font-semibold") Детали заказа:
          p Сумма: {{ orderAmount }} TJS
          p Статус: В обработке

`[icon]` (опциональный)

Описание: Кастомная иконка вместо стандартной

Пример:

success-modal(:show="showModal")
  template([icon])
      div(class="w-16 h-16 bg-green-100 rounded-full flex items-center justify-center")
          icon(name="trophy" class="w-8 h-8 text-green-600")

`[actions]` (опциональный)

Описание: Кастомные действия вместо стандартной кнопки

Пример:

success-modal(:show="showModal" title="Заказ создан")
  template([actions])
      div(class="flex space-x-3")
          button(
              @click="$emit('close')"
              class="px-4 py-2 border border-gray-300 rounded hover:bg-gray-50"
          ) Закрыть
          app-link(
              to="/orders"
              class="app-link--primary"
          ) Перейти к заказам
          app-link(
              to="/products"
              class="app-link--secondary"
          ) Продолжить покупки

Примеры использования в различных сценариях

1. Успешное создание заказа

success-modal(
    :show="orderSuccess"
    title="Заказ оформлен!"
    message="Ваш заказ успешно создан. Номер заказа: #12345"
    icon="shopping-bag"
    @close="handleOrderSuccessClose"
)

2. Успешная регистрация

success-modal(
    :show="registrationSuccess"
    title="Добро пожаловать!"
    message="Регистрация завершена успешно. На ваш email отправлено письмо с подтверждением."
    buttonText="Начать"
    @confirm="redirectToDashboard"
)

3. Успешное сохранение настроек

success-modal(
    :show="settingsSaved"
    title="Настройки сохранены"
    message="Изменения в настройках профиля успешно применены"
    autoClose="2000"
    @close="resetSettingsState"
)

4. Кастомное модальное окно с дополнительной информацией

success-modal(
    :show="showCustomSuccess"
    title="Билеты забронированы"
    size="lg"
)
    div(class="space-y-4")
        p(class="text-lg") Ваши билеты успешно забронированы!
        
        div(class="bg-blue-50 border border-blue-200 rounded-lg p-4")
            h4(class="font-semibold text-blue-900 mb-2") Важная информация:
            ul(class="list-disc list-inside space-y-1 text-blue-800")
                li Сохраните QR-код из письма
                li Приходите за 30 минут до начала
                li Иметь при себе документ, удостоверяющий личность
        
        p(class="text-sm text-gray-600") Подробности отправлены на ваш email

    template([actions])
        div(class="flex flex-col sm:flex-row gap-3")
            button(
                @click="$emit('close')"
                class="px-6 py-3 border border-gray-300 rounded-lg hover:bg-gray-50 flex-1"
            ) Закрыть
            app-link(
                to="/tickets"
                class="app-link--primary text-center flex-1"
            ) Мои билеты

5. Модальное окно с автоматическим закрытием

success-modal(
    :show="showAutoClose"
    title="Форма отправлена"
    message="Ваше сообщение успешно отправлено. Мы свяжемся с вами в ближайшее время."
    autoClose="4000"
    @close="resetContactForm"
)

6. Модальное окно без возможности закрытия

success-modal(
    :show="processingComplete"
    title="Обработка завершена"
    message="Все данные успешно обработаны и сохранены в системе."
    :closeOnBackdrop="false"
    :showCloseButton="false"
    @confirm="redirectToNextStep"
)

Интеграция с глобальным состоянием приложения

Использование через EventBus

# В компоненте
methods:
    showSuccessModal: (title, message) ->
        EventBus.emit('show_success_modal', { title, message })

# В основном приложении (app/temp.coffee)
EventBus.on 'show_success_modal', (data) ->
    _.openModal('success-modal', data)

Использование с глобальным modalState

success-modal(
    :show="_.modalState.isVisible && _.modalState.component === 'success-modal'"
    :title="_.modalState.props.title"
    :message="_.modalState.props.message"
    @close="_.closeModal()"
)

Стили и кастомизация

Размеры модального окна

//- Маленький (sm)
success-modal(:show="showModal" size="sm")

//- Средний (md) - по умолчанию
success-modal(:show="showModal" size="md")

//- Большой (lg)
success-modal(:show="showModal" size="lg")

//- Очень большой (xl)
success-modal(:show="showModal" size="xl")

Кастомные CSS классы

Компонент поддерживает стандартные классы Tailwind CSS для дополнительной стилизации:

success-modal(
    :show="showModal"
    class="success-modal-custom"
)

Особенности поведения

Управление фокусом

Автоматически фокусируется на кнопке подтверждения при открытии
Захватывает фокус внутри модального окна (accessibility)
Возвращает фокус предыдущему элементу при закрытии

Обработка клавиатуры

ESC - закрывает модальное окно
Enter - активирует основную кнопку
Tab - циклическое перемещение по фокусируемым элементам внутри модального окна

Анимации

Плавное появление и исчезновение
Анимация масштабирования
Затемнение фона с переходом

Best Practices

1. Всегда обрабатывайте событие закрытия

//- Правильно
success-modal(:show="showModal" @close="showModal = false")

//- Опасно (модальное окно не сможет закрыться)
success-modal(:show="showModal")

2. Используйте autoClose для временных уведомлений

//- Для кратковременных сообщений
success-modal(
    :show="showTempMessage"
    message="Настройки сохранены"
    autoClose="2000"
    @close="showTempMessage = false"
)

3. Предоставляйте понятные заголовки и сообщения

//- Хорошо
success-modal(
    :show="showSuccess"
    title="Профиль обновлен"
    message="Изменения в вашем профиле успешно сохранены и применены"
)

//- Плохо
success-modal(:show="showSuccess" message="Успешно")

4. Используйте слоты для сложного контента

//- Вместо длинного message
success-modal(:show="showComplex" title="Отчет готов")
    div(class="space-y-3")
        p Отчет успешно сгенерирован и содержит:
        ul(class="list-disc list-inside")
            li 25 записей о мероприятиях
            li Статистику посещаемости
            li Финансовые показатели
        p(class="text-sm text-gray-600") Файл доступен для скачивания в вашем кабинете

5. Соответствуйте контексту действия

//- Для финансовых операций
success-modal(
    :show="paymentSuccess"
    title="Платеж выполнен"
    icon="credit-card"
    buttonText="Перейти к заказу"
)

//- Для создания контента
success-modal(
    :show="contentCreated"
    title="Материал опубликован"
    icon="edit"
    buttonText="Посмотреть"
)

Отладка и разработка

Проверка состояния модального окна

# В методах компонента
checkModalState: ->
    debug.log "Modal visible: "+@show
    debug.log "Modal title: "+@title
    debug.log "Modal message: "+@message

Отслеживание событий

# В основном приложении
EventBus.on 'success_modal_closed', (data) ->
    debug.log "Success modal closed"

EventBus.on 'success_modal_confirmed', (data) ->
    debug.log "Success modal confirmed"

Компонент SuccessModal предоставляет унифицированный и гибкий способ отображения успешных операций в приложении, обеспечивая согласованный пользовательский опыт и широкие возможности для кастомизации под конкретные сценарии использования.

README.md

Компонент SuccessModal - Полная документация

Назначение компонента

git репозитарий

Импорт и регистрация

Базовое использование

1. Простое модальное окно

2. Модальное окно с кастомными действиями

Полный список props

show (обязательный)

title (опциональный)

message (опциональный)

buttonText (опциональный)

icon (опциональный)

size (опциональный)

closeOnBackdrop (опциональный)

showCloseButton (опциональный)

autoClose (опциональный)

События (Events)

@close

@confirm

Слоты (Slots)

[body] (основной слот)

[icon] (опциональный)

[actions] (опциональный)

Примеры использования в различных сценариях

1. Успешное создание заказа

2. Успешная регистрация

3. Успешное сохранение настроек

4. Кастомное модальное окно с дополнительной информацией

5. Модальное окно с автоматическим закрытием

6. Модальное окно без возможности закрытия

Интеграция с глобальным состоянием приложения

Использование через EventBus

Использование с глобальным modalState

Стили и кастомизация

Размеры модального окна

Кастомные CSS классы

Особенности поведения

Управление фокусом

Обработка клавиатуры

Анимации

Best Practices

1. Всегда обрабатывайте событие закрытия

2. Используйте autoClose для временных уведомлений

3. Предоставляйте понятные заголовки и сообщения

4. Используйте слоты для сложного контента

5. Соответствуйте контексту действия

Отладка и разработка

Проверка состояния модального окна

Отслеживание событий

`show` (обязательный)

`title` (опциональный)

`message` (опциональный)

`buttonText` (опциональный)

`icon` (опциональный)

`size` (опциональный)

`closeOnBackdrop` (опциональный)

`showCloseButton` (опциональный)

`autoClose` (опциональный)

`@close`

`@confirm`

`[body]` (основной слот)

`[icon]` (опциональный)

`[actions]` (опциональный)