企业官网建设流程全解析

• UI组件
• 前端

ngx-bootstrap 的 Modal 模块同时提供BsModalService服务与bsModal指令两条使用路径。本文聚焦文档 modals.directive-examples.auto-shown-modal.md 所定义的Auto shown modal（自动显示模态框）用例：即模态框在初始化完成后立即自动弹出，并结合条件渲染指令实现“只在需要时把模态框挂进 DOM、关闭后彻底移除”的干净模式。读完本文，你将掌握show: true配置的底层触发原理、Demo 中的完整可运行代码、关闭流程与事件处理，以及它与静态模态框、手动控制模式的区别。

一、用例场景：什么是自动显示模态框

根据仓库中的规格文档 modals.directive-examples.auto-shown-modal.md，该用例的核心定义如下：

• Primary Actor（主要参与者）：User
• Scope（适用范围）：Ngx-bootstrap DEMO，兼容 Bootstrap 3 与 4
• Goal（目标）：向用户展示auto shown modal（自动显示模态框）功能——模态框不再依赖用户点击某个按钮调用show()来打开，而是在其自身初始化完成后立即显示。

这一模式最常见的业务价值在于延迟初始化：模态框的内容组件可以等到用户真正看到它时才执行耗时的初始化操作（例如“选择邮件收件人”模态框中的收件人列表加载）。同时，由于模态框模板本身由条件指令控制挂载，页面 DOM 始终保持干净，只有需要显示时模态框节点才会被创建。

二、Demo 中的操作路径（主成功场景与变体）

规格文档给出了完整的可复现操作流程，即“主成功场景”（Main success scenario）：

1. 用户打开Modals演示页面；
2. 用户点击Auto shown modal子菜单；
3. 用户点击Render auto-shown modal按钮后，模态框弹出；
4. 用户点击关闭按钮（×）关闭模态框后，模态框节点从 DOM 中移除。

规格文档同时记录了变体（Variations）：用户也可以不点击子菜单，而是直接滚动到 “Auto shown modal” 区块（2*. User scrolls to "Auto shown modal"），效果相同——只要点击按钮即可触发自动显示。

该 Demo 在文档站中的注册位置见 modal-section.list.ts，其中以title: 'Auto shown modal'、anchor: 'directive-auto-shown'注册在 “Directive examples” 分组下，并在 “Examples” 页签中以directive-auto-shown-ex锚点再次挂载，对应的组件为DemoAutoShownModalComponent（见 demos/index.ts）。

三、核心机制：show: true配置与初始化后自动打开

自动显示的关键在于ModalDirective的ngOnInit钩子。在 modal.directive.ts 中可以看到：

ngOnInit(): void { this._config = this._config || this.getConfig(); setTimeout(() => { if (this._config.show) { this.show(); } }, 0); }

当指令初始化时，它会读取合并后的配置；如果show为true，就在下一个宏任务（setTimeout(..., 0)）中调用show()方法完成打开。这里的延时是为了让 Angular 完成当前变更检测周期、模态框节点真正进入 DOM 后再执行显示逻辑，从而避免时序问题。

show配置项正是 modal-options.class.ts 中ModalOptions的一个字段，其注释为 “Shows the modal when initialized.”（初始化时即显示模态框）。同时该文件定义的默认配置modalConfigDefaults中show: false（modal-options.class.ts），即默认情况下模态框不会自动打开，只有显式传入{ show: true }才启用自动显示行为。

此外，指令的show()方法（modal.directive.ts）会依次完成：清空dismissReason、发出onShow事件、检测滚动条并锁定body滚动、创建 backdrop，最后显示模态框元素并发出onShown。

四、完整可运行示例：Demo 源码逐行解读

仓库中该用例的完整实现位于 auto-shown.ts 与 auto-shown.html。组件类如下：

import { Component, ViewChild } from '@angular/core'; import { ModalDirective } from 'ngx-bootstrap/modal'; @Component({ // eslint-disable-next-line @angular-eslint/component-selector selector: 'demo-modal-auto-shown', templateUrl: './auto-shown.html', standalone: false }) export class DemoAutoShownModalComponent { @ViewChild('autoShownModal', { static: false }) autoShownModal?: ModalDirective; isModalShown = false; showModal(): void { this.isModalShown = true; } hideModal(): void { this.autoShownModal?.hide(); } onHidden(): void { this.isModalShown = false; } }

模板如下：

<button type="button" class="btn btn-primary" (click)="showModal()">Render auto-shown modal</button> @if (isModalShown) { <div [config]="{ show: true }" (onHidden)="onHidden()" bsModal #autoShownModal="bs-modal" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="dialog-auto-name"> <div class="modal-dialog modal-sm"> <div class="modal-content"> <div class="modal-header"> <h4 id="dialog-auto-name" class="modal-title pull-left">Auto shown modal</h4> <button type="button" class="btn-close close pull-right" aria-label="Close" (click)="hideModal()"> <span aria-hidden="true" class="visually-hidden">&times;</span> </button> </div> <div class="modal-body"> <p>I am a modal that is shown right after initialization!</p> <p>I wasn't present in DOM until you clicked the button</p> <p>When you close me, I'll be removed from the DOM</p> </div> </div> </div> </div> }

代码的关键点：

1. 状态驱动挂载：isModalShown初始为false，点击 “Render auto-shown modal” 按钮后showModal()将其置为true，模板中的@if (isModalShown)（Angular 新控制流语法）才渲染出模态框节点；
2. 自动打开：模态框节点一旦创建，bsModal指令（selector: '[bsModal]'，exportAs: 'bs-modal'，见 modal.directive.ts）的ngOnInit检测到[config]="{ show: true }"便自动调用show()，无需再写任何打开代码；
3. 模板引用：#autoShownModal="bs-modal"将指令实例暴露给组件，供hideModal()通过autoShownModal?.hide()手动关闭；
4. 关闭后移除 DOM：关闭按钮点击hideModal()→hide()；模态框隐藏动画完成后指令发出onHidden事件，模板上绑定的(onHidden)="onHidden()"把isModalShown复位为false，@if随即移除模态框节点——这正是规格文档第 4 步“modal popup is removed from the DOM”的实现路径。

五、关闭流程与事件回调的底层原理

理解“关闭后从 DOM 移除”需要结合ModalDirective的关闭链路（modal.directive.ts）：

hide(event?: Event): void { if (!this._isShown) { return; } // ... this._hide(); }

_hide()会先发出onHide事件，随后：

• 移除show样式类；
• 若启用了动画（animated，默认true），等待 300ms 过渡（TRANSITION_DURATION）后再执行hideModal()；
• hideModal()内部将元素设置为display: none、aria-hidden="true"，还原body的滚动与 padding，最后发出onHidden事件（modal.directive.ts）。

因此 Demo 中(onHidden)="onHidden()"的语义是“等到隐藏动画完成、指令完成清理之后”再把isModalShown置为false，保证 DOM 移除时机与动画结束一致，不会出现闪烁或布局跳动。

另外，ModalDirective还暴露了 4 个事件：onShow、onShown、onHide、onHidden（modal.directive.ts），以及dismissReason字段记录关闭原因。在 events.ts 的示例中可以看到如何通过$event.dismissReason判断用户是以哪种方式关闭的（backdrop-click、esc，或直接调用hide()时为空）。

六、相关配置项速查（ModalOptions）

自动显示模式用到的配置来自ModalOptions（完整定义见 modal-options.class.ts），与本文主题相关的常用项如下：

全局默认配置定义在modalConfigDefaults中（modal-options.class.ts），且可通过MODAL_CONFIG_DEFAULT_OVERRIDE注入令牌整体覆盖，相关测试见 modal.default-setting.spec.ts。

七、与相邻模式的对比：Static modal 与手动控制

将 Auto shown modal 放在 “Directive examples” 分组中对比，可以更清晰地理解它的定位：

• Static modal（静态模态框）：同样使用bsModal指令，但模板始终存在于 DOM 中，点击按钮直接调用staticModal.show()打开，并通过[config]="{backdrop: 'static'}"禁止 backdrop 点击关闭，见 static.ts 与 static.html；
• Auto shown modal（自动显示模态框）：模板受@if条件控制，仅在需要时挂载；挂载即自动打开，关闭后节点被移除；
• 手动控制模式（如 Child modal）：通过@ViewChild拿到ModalDirective引用后调用show()/hide()，打开时机完全由业务代码决定。

Auto shown modal 的独特价值在于：它把“创建节点”和“打开弹窗”合并为一个动作——节点出现即弹窗出现，因此特别适合把模态框内容（如列表加载）延迟到真正展示时再初始化，同时避免页面长期驻留无用的 DOM 节点。

八、源码索引与延伸阅读

• 用例规格文档：modals.directive-examples.auto-shown-modal.md
• Demo 组件与模板：auto-shown.ts、auto-shown.html
• 指令核心实现（自动打开、显示/关闭、滚动条与 backdrop 管理）：modal.directive.ts
• 配置定义与默认值：modal-options.class.ts
• 模块导出（ModalModule同时导出ModalBackdropComponent与ModalDirective）：modal.module.ts
• 文档站注册信息：modal-section.list.ts
• 同组对比示例：static.html、events.ts
• 安装与模块导入方式（Standalone / NgModule 两种用法）：usage.md

在集成到自己的项目时，只需引入ModalModule，按上文的组件类与模板结构复制即可；若使用 Standalone 组件，直接在imports中加入ModalModule（模块内指令均声明为standalone: true）即可。需要注意，自动显示依赖show: true与条件渲染指令的配合，两者缺一不可：缺少show: true模态框不会自动弹出，缺少条件渲染则关闭后节点仍残留在 DOM 中，也就失去了该模式“按需挂载、关后即焚”的意义。

• UI组件
• 前端