本文介绍如何在 Svelte 3 中构建一个挂载于 document.body 的全局模态框组件，支持从任意嵌套组件调用、渲染动态内容（含子组件、props、binds 及父级上下文），并解决 overflow 截断与事件冒泡等常见问题。

本文介绍如何在 svelte 3 中构建一个挂载于 `document.body` 的全局模态框组件，支持从任意嵌套组件调用、渲染动态内容（含子组件、props、binds 及父级上下文），并解决 overflow 截断与事件冒泡等常见问题。

在 Svelte 应用中实现一个真正“全局可用”的模态框（Modal），远不止是加个 display: block 样式那么简单。核心挑战在于：既要脱离 DOM 层级限制（避免被父组件 overflow: hidden 或 transform 等 CSS 属性截断），又要无缝继承应用上下文与响应式能力。以下是经过实践验证的 Svelte 3 原生解决方案。

✅ 正确挂载至 document.body：Portal 模式

Svelte 不内置 Portal，但可通过 onMount 手动将模态框节点附加到 document.body，确保其脱离组件树布局约束：

<!-- Modal.svelte -->
<script>
  import { onMount, onDestroy } from 'svelte';

  let modalEl;
  let isOpen = false;

  // 关键：挂载时追加到 body，销毁时移除
  onMount(() => {
    if (typeof document !== 'undefined') {
      document.body.appendChild(modalEl);
    }
  });

  onDestroy(() => {
    if (modalEl && modalEl.parentNode === document.body) {
      document.body.removeChild(modalEl);
    }
  });
</script><div class="modal" class:hidden="{!isOpen}" bind:this="{modalEl}">
  <div class="modal-overlay" on:click="{()"> isOpen = false} />
  <div class="modal-content">
    <slot></slot>
</div>
</div>

<style>
  .modal {
    position: fixed;
    top: 0; left: 0; right: 0; bottom: 0;
    z-index: 1000;
  }
  .modal-overlay {
    position: absolute;
    width: 100%; height: 100%;
    background: rgba(0,0,0,0.5);
  }
  .modal-content {
    position: absolute;
    top: 50%; left: 50%;
    transform: translate(-50%, -50%);
    background: white;
    padding: 1rem;
    border-radius: 4px;
    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
  }
  .modal.hidden {
    display: none;
  }
</style>
<blockquote><p>⚠️ 注意：此方式下原生事件（如 <code>click</code>）<strong>不会向上冒泡至 <code><app></app></code> 或其他祖先组件</strong>（因 DOM 节点已脱离组件树）。若需全局事件通信，推荐使用 <code>dispatch</code> + <code>createEventDispatcher</code> 或 store（如 <code>writable</code>）驱动状态。</p></blockquote>
<h3>✅ 动态内容注入：基于 Slot + Context 透传</h3>
<p>Svelte 的 <code><slot></slot></code> 天然支持任意合法内容——HTML 片段、带 props 的组件、双向绑定（<code>bind:</code>）、甚至 <code>#if</code>/<code>#each</code> 块。关键在于<strong>确保父级 <code>Context</code> 在模态框内仍可访问</strong>。</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill1462" title="MoltOverflow"><img
														src="https://img.php.cn/upload/skill/000/000/081/178823887742941.jpg" alt="MoltOverflow" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill1462" title="MoltOverflow" class="overflowclass">MoltOverflow</a>
													<p class="overflowclass">Moltbots问答社区 - 提问编程问题，分享解决方案</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill1462" title="MoltOverflow" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>
<p>Svelte 的 <code>setContext</code>/<code>getContext</code> API <strong>基于组件实例生命周期，而非 DOM 位置</strong>，因此只要模态框组件本身在 <code>App.svelte</code> 中声明（即使其 DOM 被移至 <code>body</code>），其子 slot 内容仍能正确继承上层 context：</p>
<pre class="brush:php;toolbar:false;"><!-- App.svelte -->
<script>
  import { setContext } from 'svelte';
  import Modal from './Modal.svelte';

  // 设置全局 context（例如主题、API client）
  setContext('theme', 'dark');
  setContext('api', { fetchUser: () => fetch('/user') });
</script><modal let:open let:close><!-- 此处 slot 内容可正常使用 getContext --><userprofile></userprofile><button on:click="{close}">关闭</button>
</modal>

<!-- UserProfile.svelte -->
<script>
  import { getContext } from 'svelte';
  export let userId;

  const api = getContext('api'); // ✅ 正常获取
  $: user = $api.fetchUser(userId); // 示例逻辑
</script><div>用户：{user?.name}</div>

✅ 全局调用：暴露 show() 方法 + Store 驱动

为支持“从任意深层子组件触发”，推荐采用 writable store + 统一 Modal 实例 方案，避免层层透传 show() 函数：

<!-- stores.js -->
import { writable } from 'svelte/store';

export const modalStore = writable({
  isOpen: false,
  content: null,
  props: {},
  onClose: () => {}
});

export function showModal(Component, props = {}, onClose = () => {}) {
  modalStore.set({
    isOpen: true,
    content: Component,
    props,
    onClose
  });
}

export function hideModal() {
  modalStore.update(s => ({ ...s, isOpen: false }));
}

<!-- Modal.svelte（增强版） -->
<script>
  import { onMount, onDestroy, afterUpdate } from 'svelte';
  import { modalStore, hideModal } from './stores.js';

  let modalEl;
  $: ({ isOpen, content: Content, props, onClose }) = $modalStore;

  onMount(() => {
    if (typeof document !== 'undefined') {
      document.body.appendChild(modalEl);
    }
  });

  onDestroy(() => {
    if (modalEl?.parentNode === document.body) {
      document.body.removeChild(modalEl);
    }
  });

  // 自动聚焦首个可聚焦元素（无障碍优化）
  afterUpdate(() => {
    if (isOpen && modalEl) {
      const focusable = modalEl.querySelector('button, [href], input, select, textarea, [tabindex]');
      focusable?.focus();
    }
  });
</script><div class="modal" class:hidden="{!isOpen}" bind:this="{modalEl}">
  <div class="modal-overlay" on:click="{hideModal}"></div>
  <div class="modal-content" role="dialog" aria-modal="true">
    {#if Content}
      <component this="{Content}" on:close="{hideModal}"></component>
    {/if}
  </div>
</div>

<!-- AnyChildComponent.svelte -->
<script>
  import { showModal } from './stores.js';
  import ConfirmDialog from './ConfirmDialog.svelte';
</script><button on:click="{()"> 
  showModal(ConfirmDialog, { 
    title: "确认删除？", 
    onConfirm: () => alert("已删除") 
  })
}>
  删除项目
</button>

✅ 总结与最佳实践

• 挂载时机：务必在 onMount 中操作 document.body，服务端渲染（SSR）时需 typeof document !== 'undefined' 守卫；
• 上下文安全：Svelte Context 100% 兼容 Portal 模式，无需额外桥接；
• 动态渲染：<component></component> 是渲染运行时组件的唯一标准方式，配合 spread operator（{...props}）完美支持 props/binds；
• 无障碍（a11y）：添加 role="dialog"、aria-modal="true"、焦点管理及 Esc 键关闭（可监听 keydown 事件）；
• 性能提示：避免在 slot 中直接写复杂逻辑；重度交互组件建议提取为独立 .svelte 文件并通过 showModal() 加载。

此方案已在多个生产级 Svelte 3 应用中稳定运行，兼顾灵活性、可维护性与可访问性，是构建企业级模态系统的核心范式。