Использование API DModal для отрисовки модальных окон (всплывающих окон/диалогов) в Discourse

Discourse 3.1.0.beta6 поставляется с совершенно новым API, основанным на компоненте <DModal>. DModal является частью UI kit и импортируется из discourse/ui-kit/d-modal.

:information_source: Это заменяет старый API, основанный на контроллерах, который теперь устарел. Если у вас есть существующие модальные окна, использующие старые API, ознакомьтесь с руководством по миграции здесь.

Отрисовка модального окна

Модальные окна отрисовываются путем включения компонента <DModal> в шаблон handlebars. Если у вас еще нет подходящего шаблона, ознакомьтесь с Using Plugin Outlet Connectors from a Theme or Plugin.

Простое модальное окно будет выглядеть примерно так:

<DButton
  @translatedLabel="Показать модальное окно"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <DModal @title="Мое модальное окно" @closeModal={{fn (mut this.modalIsVisible) false}}>
    Привет, мир, это контент внутри модального окна
  </DModal>
{{/if}}

:information_source: Здесь используется хелпер mut как способ установки значения только в hbs. Вы также можете установить modalIsVisible, используя любой другой стандартный метод Ember.

Этот пример создаст простое модальное окно, такое как это:

Оборачивание в компонент

Прежде чем добавлять больше сложности, обычно лучше обернуть новое модальное окно в собственное определение компонента. Давайте перенесем код <DModal> внутрь нового компонента <MyModal />

// components/my-modal.gjs
<template>
  <DModal @title="Мое модальное окно" @closeModal={{@closeModal}}>
    Привет, мир, это контент внутри модального окна
  </DModal>
</template>

Обновление этого .gjs файла до класса-компонента позволит вам внедрять более сложную логику и состояние.

Чтобы использовать новый компонент, обновите место вызова, чтобы ссылаться на него, убедившись, что передается аргумент @closeModal.

<DButton
  @translatedLabel="Показать модальное окно"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}

Добавление нижнего колонтитула

У многих модальных окон есть призыв к действию. В Discourse они обычно расположены в нижней части модального окна. Чтобы сделать это возможным, DModal имеет несколько «именованных блоков», внутри которых может отображаться контент. Вот пример, обновленный для включения двух кнопок в нижнем колонтитуле, одна из которых — наша стандартная кнопка DModalCancel

<DModal @title="Мое модальное окно" @closeModal={{@closeModal}}>
  <:body>
    Привет, мир, это контент внутри модального окна
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Отправить" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

Отрисовка модального окна из контекста, отличного от hbs

В идеале экземпляры <DModal> должны отрисовываться из шаблона Ember, используя декларативный метод, показанный выше. Если это невозможно для вашего случая использования, это можно сделать, внедрив сервис modal и вызвав modal.show().

Убедитесь, что вы обернули свое модальное окно в собственный компонент, как описано выше. Затем откройте модальное окно, передав ссылку на класс вашего компонента в showModal:

import MyModal from "discourse/components/my-modal";

// (внедрите сервис modal в нужном месте)

// Добавьте этот вызов всякий раз, когда вы хотите открыть модальное окно.
// Аргумент `@closeModal` будет автоматически передан вашему компоненту.
this.modal.show(MyModal);

// Необязательно передайте параметр `'model'`. Он передается как `@model` вашему компоненту.
// Он может включать данные, а также действия/колбэки, которые будет использовать ваше модальное окно.
this.modal.show(MyModal, {
  model: { topic: this.topic, someAction: this.someAction },
});

// `modal.show()` возвращает промис, поэтому вы можете дождаться его закрытия
// Он разрешится с данными, переданными в действие `@closeModal`
const result = await this.modal.show(MyModal);

Больше возможностей для кастомизации!

У <DModal> есть множество именованных блоков и аргументов.

Аргументы

Аргумент Назначение
@closeModal Обязательно для появления UI закрытия.
@title Отображает <h1 id="discourse-modal-title">; связывает aria-labelledby.
@subtitle Небольшой текст под заголовком.
@flash / @flashType Встроенное уведомление вверху модального окна (DFlashMessage).
@hideHeader, @hideFooter Скрыть целые области.
@headerClass, @bodyClass Дополнительный класс для оберток заголовка/тела.
@dismissable По умолчанию true, если установлен @closeModal. Отключает Esc / клик по фону / X.
@autofocus По умолчанию true. Автоматически фокусирует первый фокусируемый элемент через dTrapTab.
@submitOnEnter По умолчанию true. Enter нажимает .d-modal__footer .btn-primary, если фокус не находится в форме/текстовой области/select-kit.
@beforeClose async ({ initiatedBy }) => boolean. Верните false, чтобы отменить закрытие (например, подтверждение для «грязной» формы).
@hidden Приостанавливает обработку клавиатуры; используется, когда поверх находится вложенное модальное окно.
@tagName "div" (по умолчанию) или "form". Используйте "form" для форм, чтобы работал нативный submit.

Блоки

Блок Позиция Когда использовать
default / :body Основная область контента Область по умолчанию
:aboveHeader Самый верх, перед заголовком Редко требуется; для контента, который должен находиться над строкой заголовка (например, баннер).
:headerAboveTitle Внутри заголовка, перед заголовком Присутствует, но не используется. Редко требуется.
:belowModalTitle Внутри .d-modal__title, после <h1> Отличная позиция для дополнительной мета-информации.
:headerBelowTitle Внутри заголовка, после блока заголовка Вкладки, поднавигация или поле поиска, которые являются частью заголовка.
:headerPrimaryAction Правая сторона заголовка только на мобильных Заменяет кнопку закрытия X основным действием (например, «Сохранить»). Также автоматически отображает кнопку «Отмена» слева и добавляет .--has-primary-action к заголовку.
:belowHeader Между заголовком и телом Постоянный подзаголовочный контент (например, поиск), который находится вне прокручиваемого тела, поэтому отображается как «прилипший».
:aboveFooter Между телом и нижним колонтитулом Подавляется при установленном @hideFooter. Используйте для контента, связанного с нижним колонтитулом, но находящегося вне его. Также редко требуется.
:footer Нижняя панель действий Основные и вторичные кнопки. Первая .btn-primary здесь — то, что срабатывает при нажатии Enter.
:belowFooter После нижнего колонтитула Редко требуется; игнорирует @hideFooter. Полезно для текстового статуса вне области нижнего колонтитула с рамкой.

Источники: интерактивный гид по стилям для аргументов и реализация шаблона d-modal для именованных блоков.

CSS

Используйте классы .d-modal как якорь для переопределения ядра и избегайте устаревшего селектора .modal.

Доступны 4 модификатора:

  • .--large устанавливает максимальную ширину в 800px (только для настольных ПК)
  • .--max устанавливает максимальную ширину в 90vw (только для настольных ПК)
  • .has-search устанавливает фиксированную высоту (80vh): предназначено для модальных окон с системой поиска/фильтрации, чтобы избежать изменения высоты в зависимости от длины результатов (только для настольных ПК)
  • .--stacked устанавливает кнопок нижнего колонтитула в столбик (только для мобильных)

Этот документ контролируется версиями — предлагайте изменения на github.

17 лайков

Пост был разделён на новую тему: Могу ли я показать модальное окно из head_tag