---
title: "<NuxtAnnouncer>"
description: "<NuxtAnnouncer> 组件会添加一个隐藏元素，用于向辅助技术宣布动态内容变更。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-announcer"
---
# <NuxtAnnouncer>

> <NuxtAnnouncer> 组件会添加一个隐藏元素，用于向辅助技术宣布动态内容变更。

<important>

此组件适用于 Nuxt v4.4.2+。

</important>

## 使用方法

在 [`app.vue`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/app) 或 [`app/layouts/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/layouts) 中添加 `<NuxtAnnouncer/>`，即可启用向屏幕阅读器宣布动态内容变更的功能。这适用于表单验证、toast 通知、加载状态及其他页面内更新。

```vue [app/app.vue]
<template>
  <NuxtAnnouncer />
  <NuxtRouteAnnouncer />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

然后，在应用中的任意位置使用 [`useAnnouncer`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-announcer) 组合式函数来宣布消息：

```vue [app/pages/contact.vue]
<script setup lang="ts">
const { polite, assertive } = useAnnouncer()

async function submitForm () {
  try {
    await $fetch('/api/contact', { method: 'POST', body: formData })
    polite('消息发送成功')
  } catch (error) {
    assertive('错误：发送消息失败')
  }
}
</script>
```

## 插槽

你可以通过 announcer 的默认插槽传入自定义 HTML 或组件。

```vue
<template>
  <NuxtAnnouncer>
    <template #default="{ message }">
      <p>{{ message }}</p>
    </template>
  </NuxtAnnouncer>
</template>
```

## Props

- `atomic`：控制屏幕阅读器是只宣布变化部分还是整个内容。设置为 `true` 则更新时朗读全部内容，`false` 则只朗读变化部分。（默认 `true`）
- `politeness`：设置屏幕阅读器宣布的默认紧急程度：`off`（禁用宣布），`polite`（等待空闲时宣布），或 `assertive`（立即打断宣布）。默认值为 `polite`

## 与 `<NuxtRouteAnnouncer>` 的区别

<table>
<thead>
  <tr>
    <th>
      方面
    </th>
    
    <th>
      <code>
        <NuxtRouteAnnouncer>
      </code>
    </th>
    
    <th>
      <code>
        <NuxtAnnouncer>
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        用途
      </strong>
    </td>
    
    <td>
      宣布路由/页面变更
    </td>
    
    <td>
      宣布任何动态内容
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        触发方式
      </strong>
    </td>
    
    <td>
      导航自动触发
    </td>
    
    <td>
      通过 <code>
        polite()
      </code>
      
      /<code>
        assertive()
      </code>
      
       手动触发
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        消息来源
      </strong>
    </td>
    
    <td>
      页面 <code>
        <title>
      </code>
    </td>
    
    <td>
      开发者提供
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        atomic 默认值
      </strong>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout>

此组件是可选的。 <br />


如果需要完全自定义，你可以基于[其源码](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts)自行实现。

</callout>

<callout>

你可以使用[`useAnnouncer` 组合式函数](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-announcer)连接到底层的 announcer 实例，以设置自定义宣布消息。

</callout>

---

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


## Sitemap

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