---
title: "门面组件"
description: "门面组件是虚假的 UI 元素，在第三方脚本加载完成后会被替换。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/facade-components"
last_updated: "2026-05-22T14:11:53.684Z"
---

## 什么是门面组件？

为了渲染诸如视频嵌入、支付弹窗或聊天插件等第三方脚本所依赖的复杂组件，我们需要加载许多资源。<br />


在 Nuxt 启动时加载它们会降低你的应用性能。

然而，如果我们延迟加载脚本直到 Nuxt 启动完成，会导致有害的内容布局偏移（CLS）和视觉噪点，<br />


进而造成较差的用户体验。

门面组件的目标是通过渲染一个“假”的 UI 元素来解决这个问题，这个“假”元素会在第三方脚本加载后被替换。

通过钩住合适的 DOM 事件并提供用户反馈，我们可以使用这些假元素，同时仍然保障良好的用户体验。

## 使用门面组件的利弊是什么？

虽然性能上的提升非常明显，但在用户体验上可能存在权衡。

- **内容不匹配的闪烁**：假 UI 元素可能与最终的 UI 元素外观不同，导致内容闪烁错位。Nuxt Scripts 只提供了最小化的样式，你可能需要调整以匹配你的应用设计。
- **交互性可能中断**：元素的交互性依赖于脚本的加载，如果脚本未加载，你需要提供降级处理。
- **无障碍性问题**：需要在脚本加载或加载失败时，向用户提供明确的无障碍（a11y）反馈。

## Nuxt Scripts 门面组件

所有门面组件都是无样式组件，包装对应的 `useScript<provider>` 组合式函数。文档中仅提供最小化样式，作为起点。

## 使用门面组件的最佳实践

### 提供错误降级处理

如果脚本加载失败，提供一个降级方案，告知用户加载失败并提供访问内容的替代方式。

```vue
<ScriptYouTubePlayer>
  <template #error>
    <UAlert color="red" title="YouTube 播放器加载失败" description="请刷新页面重试。" />
  </template>
</ScriptYouTubePlayer>
```

### 提供可访问的加载状态反馈

脚本加载期间，提供加载状态，告知用户内容正在加载中。

Nuxt Scripts 提供了 `ScriptLoadingIndicator` 组件，帮助实现加载状态展示并提供无障碍反馈。

```vue
<ScriptYouTubePlayer>
  <template #loading>
    <ScriptLoadingIndicator />
  </template>
</ScriptYouTubePlayer>
```

### 明智地选择触发事件

门面组件预设了最佳的通用性能事件触发，但你可以自定义触发事件，使其更契合你的应用需求。

最佳触发事件是需要明确用户交互的事件，如点击。<br />


鼠标悬停加载可能导致用户体验问题，比如丢失后续点击事件。

## 门面组件 API

所有门面组件共享相似的 API。

### Props

- `trigger` - 触发脚本加载的事件。详情请参见 [元素事件触发器](/docs/guides/script-triggers#element-event-triggers)。

### 插槽

该组件默认只提供最小化 UI，保证功能和可访问性。你可通过多个插槽按需自定义组件。

- `default` - 组件始终显示的内容。

```vue
<template>
  <ScriptYouTubePlayer>
    <div class="bg-blue-500 text-white p-5">
      YouTube！
    </div>
  </ScriptYouTubePlayer>
</template>
```

- `loading` - 仅在脚本加载中显示的内容。

```vue
<template>
  <ScriptYouTubePlayer>
    <template #loading>
      <ScriptLoadingIndicator />
    </template>
  </ScriptYouTubePlayer>
</template>
```

- `awaitingLoad` - 脚本等待加载时显示的内容。

```vue
<template>
  <ScriptYouTubePlayer>
    <template #awaitingLoad>
      <div class="bg-blue-500 text-white p-5">
        点击播放！
      </div>
    </template>
  </ScriptYouTubePlayer>
</template>
```

- `error` - 当脚本加载失败时显示的内容。

```vue
<template>
  <ScriptYouTubePlayer>
    <template #error>
      <UAlert color="red" title="YouTube 播放器加载失败" description="请刷新页面重试。" />
    </template>
  </ScriptYouTubePlayer>
</template>
```

### 事件

- `ready` - 脚本加载完成时触发，提供底层脚本 API 的访问权限。
- `error` - 脚本加载失败时触发。