---
title: "门面组件"
description: "门面组件是占位 UI 元素，会在第三方脚本加载后被替换。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/docs/guides/facade-components"
last_updated: "2026-08-11T09:33:00.521Z"
---

门面会渲染轻量级的占位 UI，直到其第三方脚本和组件准备就绪。

## 什么是外观组件？

视频嵌入、支付模态框或聊天小部件可能会在启动期间获取多个资源。延迟这些工作有助于提升页面的初始加载效果，但稍后再插入真实 UI 可能会导致[累积布局偏移（CLS）](https://web.dev/articles/optimize-cls)。外观组件可以预留空间，并在供应商代码加载时显示加载状态。

## 权衡

Facade 组件可能会带来用户体验方面的权衡：

- **内容不匹配的闪现**：占位符的外观可能与最终 UI 不一致。你可能需要调整默认样式，使其与应用的设计相匹配。
- **无法进行交互**：真实元素需要脚本加载后才能使用。如果加载失败，请保留可用的替代方案。
- **无障碍访问问题**：清晰地告知加载状态和失败状态。

## 可用的 facade

由脚本支持的 facade 组件封装了相关的 `useScript<Provider>()` 可组合函数，并公开 props、插槽和事件，以控制其占位内容。某些组件提供了带有最简样式的默认占位内容。请查看每个组件的注册表页面，了解其确切的 API。

## 使用指南

### 提供错误回退

告知用户发生了什么错误，并提供另一种访问内容的方式。

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

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

`ScriptLoadingIndicator` 提供可见的加载状态和可访问的状态标签。

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

### 选择触发事件

Facade 组件具有默认触发器，你可以根据周围的 UI 对其进行覆盖。

优先选择需要用户明确交互的触发器，例如点击。悬停时加载可能会导致后续事件（例如点击）在组件被替换时丢失。

## 门面组件 API

由脚本支持的门面组件共享相似的 API，但具体的 props、插槽、事件和事件负载会因组件而异。

### 属性

- `trigger`：对于受支持的门面组件，用于触发脚本加载的事件。更多信息请参阅[元素事件触发器](/docs/guides/script-triggers#element-event-triggers)。PayPal 门面组件目前会公开此 prop，但不会使用它来进行加载或管理门面状态。请改为配置 PayPal 注册表中的 `trigger`。

### 插槽

下面示例中使用的 `ScriptYouTubePlayer` 提供了最小化的默认 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>
```

Crisp 和 Intercom 组件目前会先检查加载分支，再检查错误分支。它们的 `error` 事件仍会触发，但在修复该顺序之前，其命名插槽 `#error` 无法渲染。暂时请在这两个组件外部处理 `@error`。

### 事件

- `ready`：脚本或组件准备就绪时触发。负载取决于组件。
- `error`：脚本或组件加载失败时触发。负载取决于组件。