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="Show Modal"
@action={{fn (mut this.modalIsVisible) true}}
/>
{{#if this.modalIsVisible}}
<DModal @title="My Modal" @closeModal={{fn (mut this.modalIsVisible) false}}>
Hello world, this is some content in a modal
</DModal>
{{/if}}
mut辅助函数 作为仅在 hbs 中设置值的方法。您也可以使用任何其他标准的 Ember 方法来设置modalIsVisible。
此示例将创建一个简单的模态框，如下所示：
封装为组件
在引入更多复杂性之前，通常最好将您的新模态框封装在独立的组件定义中。让我们将 <DModal> 部分移动到一个新的 <MyModal /> 组件中
// components/my-modal.gjs
<template>
<DModal @title="My Modal" @closeModal={{@closeModal}}>
Hello world, this is some content in a modal
</DModal>
</template>
将此 .gjs 文件升级为基于类的组件，将允许您引入更复杂的逻辑和状态。
要使用新组件，请更新调用站点以引用它，并确保传入 @closeModal 参数。
<DButton
@translatedLabel="Show Modal"
@action={{fn (mut this.modalIsVisible) true}}
/>
{{#if this.modalIsVisible}}
<MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}
添加页脚
许多模态框都有某种形式的操作按钮（Call-to-Action）。在 Discourse 中，这些通常位于模态框的底部。为了实现这一点，DModal 拥有多个“命名块”（named blocks），可以在其中渲染内容。以下是更新后的示例，在页脚中包含两个按钮，其中一个是标准的 DModalCancel 按钮
<DModal @title="My Modal" @closeModal={{@closeModal}}>
<:body>
Hello world, this is some content in a modal
</:body>
<:footer>
<DButton class="btn-primary" @translatedLabel="Submit" />
<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" 以使原生提交功能正常工作。 |
块
| 块 | 位置 | 何时使用 |
|---|---|---|
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 上建议更改。