使用 DModal API 在 Discourse 中渲染模态窗口(即弹出框/对话框)

Discourse 3.1.0.beta6 提供了一个全新的基于组件的 <DModal> API。DModal 是 UI 套件 的一部分,从 discourse/ui-kit/d-modal 导入。

:information_source: 此 API 取代了旧的基于控制器的 API,后者现已弃用。如果你有使用旧 API 的现有模态框,请查阅 迁移指南。

渲染模态框

模态框通过在 Handlebars 模板中包含 <DModal> 组件来渲染。如果你还没有合适的模板,请查看 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 中设置值的一种纯模板方式。你也可以使用任何其他标准的 Ember 方法来设置 modalIsVisible。

此示例将创建一个简单的模态框,如下所示:

包装在组件中

在引入更多复杂性之前,通常最好将新的模态框包装在它自己的组件定义中。让我们把 <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}}

添加页脚

许多模态框都有某种行动号召(Call to Action)。在 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()` 返回一个 promise,因此你可以等待它被关闭
// 它将解析为传递给 `@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 当设置了 @closeModal 时默认为 true。禁用 Esc / 背景点击 / X。
@autofocus 默认为 true。通过 dTrapTab 自动聚焦第一个可聚焦元素。
@submitOnEnter 默认为 true。除非焦点在表单 / 文本域 / select-kit 中,否则 Enter 键会点击 .d-modal__footer .btn-primary。
@beforeClose async ({ initiatedBy }) => boolean。返回 false 以取消关闭(例如脏表单确认)。
@hidden 暂停键盘处理;用于当嵌套模态框位于顶部时。
@tagName "div"(默认)或 "form"。对表单使用 "form" 以启用原生提交。

块

块 位置 何时使用
默认 / :body 主要内容区域 默认区域
:aboveHeader 最顶部,在标题之前 很少需要;用于必须位于标题栏之上的内容(例如横幅)。
:headerAboveTitle 在标题内部,在标题之前 存在但未使用。很少需要。
:belowModalTitle 在 .d-modal__title 内部,在 <h1> 之后 补充元信息的极佳位置。
:headerBelowTitle 在标题内部,在标题块之后 属于标题部分的选项卡、子导航或搜索输入。
:headerPrimaryAction 仅移动端 标题右侧 用一个主要操作(例如“保存”)替换 X 关闭按钮。还会在左侧自动渲染一个“取消”按钮,并向标题添加 .--has-primary-action。
:belowHeader 在标题和正文之间 持久化的子标题内容(例如搜索栏),位于可滚动正文之外,因此可粘性显示。
:aboveFooter 在正文和页脚之间 设置 @hideFooter 时被抑制。用于与页脚绑定但在页脚之外的内容。也很少见。
:footer 底部操作栏 主要 + 次要按钮。Enter 键触发的是这里的第一个 .btn-primary。
:belowFooter 在页脚之后 很少需要;忽略 @hideFooter。用于位于带边框页脚区域之外的状态文本。

来源:关于参数,参见 交互式风格指南,关于命名块,参见 d-modal 模板实现。

CSS

使用 .d-modal 类作为锚点来覆盖核心样式,并避免使用旧版的 .modal 选择器。

有 4 个可用的修饰符:

  • .--large 将最大宽度设置为 800px(仅限桌面端)
  • .--max 将最大宽度设置为 90vw(仅限桌面端)
  • .has-search 设置固定高度(80vh):旨在用于具有搜索/过滤系统的模态框,以避免因结果长度不同而改变高度(仅限桌面端)
  • .--stacked 将页脚按钮设置为堆叠布局(仅限移动端)

此文档受版本控制 - 请在 github 上建议更改。

17 个赞

帖子已拆分为新主题:Can I show a modal from head_tag