Discourse 3.1.0.beta6 提供了一个全新的基于组件的 <DModal> API。DModal 是 UI 套件 的一部分,从 discourse/ui-kit/d-modal 导入。
此 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}}
这里使用了
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 上建议更改。

