---
title: "<ClientOnly>"
description: "使用 <ClientOnly> 组件仅在客户端渲染组件。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/components/client-only"
---
# <ClientOnly>

> 使用 <ClientOnly> 组件仅在客户端渲染组件。

`<ClientOnly>` 组件用于刻意仅在客户端渲染组件。

<note>

默认插槽的内容将会在服务端构建中被 tree-shake 掉。（这也意味着其中组件使用的任何 CSS 在渲染初始 HTML 时可能不会被内联。）

</note>

## 属性

- `placeholderTag` | `fallbackTag`：指定在服务端渲染时要输出的标签。
- `placeholder` | `fallback`：指定在服务端渲染时要显示的内容。

```vue [app/pages/example.vue]
<template>
  <div>
    <Sidebar />
    <!-- <Comment> 组件仅会在客户端渲染 -->
    <ClientOnly
      fallback-tag="span"
      fallback="正在加载评论..."
    >
      <Comment />
    </ClientOnly>
  </div>
</template>
```

## 插槽

- `#fallback`：指定在服务端渲染并在浏览器中 `<ClientOnly>` 挂载前显示的内容。

```vue [app/pages/example.vue]
<template>
  <div>
    <Sidebar />
    <!-- 这会在服务端渲染 "span" 元素 -->
    <ClientOnly fallback-tag="span">
      <!-- 这个组件只会在客户端渲染 -->
      <Comments />
      <template #fallback>
        <!-- 这会在服务端渲染 -->
        <p>加载评论中...</p>
      </template>
    </ClientOnly>
  </div>
</template>
```

## 示例

### 访问 HTML 元素

`<ClientOnly>` 内的组件仅在挂载后才会被渲染。要访问 DOM 中渲染出的元素，可以监听一个模板引用（template ref）：

```vue [app/pages/example.vue]
<script setup lang="ts">
const nuxtWelcomeRef = useTemplateRef('nuxtWelcomeRef')

// 当组件可用时，watch 将被触发
watch(nuxtWelcomeRef, () => {
  console.log('<NuxtWelcome /> 已挂载')
}, { once: true })
</script>

<template>
  <ClientOnly>
    <NuxtWelcome ref="nuxtWelcomeRef" />
  </ClientOnly>
</template>
```

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-only.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.