跳到主要内容

useAnnouncer

一个用于向屏幕阅读器播报消息的组合式函数。

该组合式函数在 Nuxt v4.4.2+ 中可用。 :

描述

一个用于向屏幕阅读器播报动态内容变化的组合式函数。不同于会自动播报路由变化的 useRouteAnnounceruseAnnouncer 让你可以手动控制播报什么以及何时播报。

将其用于表单校验、异步操作、toast 通知和实时内容变化等页内更新。

参数

  • politeness:设置屏幕阅读器播报的默认紧急程度:off(禁用播报)、polite(等待静默)、或 assertive(立即打断)。(默认 polite

属性

message

  • 类型Ref<string>
  • 描述:要播报的当前消息

politeness

  • 类型Ref<'polite' | 'assertive' | 'off'>
  • 描述:屏幕阅读器播报的紧急程度

方法

set(message, politeness = "polite")

设置要播报的消息及其紧急程度。

polite(message)

politeness = "polite" 设置消息。用于可以等待屏幕阅读器完成当前任务的非紧急更新。

assertive(message)

politeness = "assertive" 设置消息。用于应该立即打断屏幕阅读器的紧急更新。

示例

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>

使用场景

表单校验

app/components/LoginForm.vue
<script setup lang="ts">
const { assertive } = useAnnouncer()

function validateForm () {
  const errors = []
  if (!email.value) { errors.push('邮箱为必填项') }
  if (!password.value) { errors.push('密码为必填项') }

  if (errors.length) {
    assertive(`表单有 ${errors.length} 个错误:${errors.join(', ')}`)
    return false
  }
  return true
}
</script>

加载状态

app/pages/dashboard.vue
<script setup lang="ts">
const { polite } = useAnnouncer()

const { data, status } = await useFetch('/api/data')

watch(status, (newStatus) => {
  if (newStatus === 'pending') {
    polite('正在加载数据...')
  } else if (newStatus === 'success') {
    polite('数据加载成功')
  }
})
</script>

搜索结果

app/components/Search.vue
<script setup lang="ts">
const { polite } = useAnnouncer()

const results = ref([])

watch(results, (newResults) => {
  polite(`找到 ${newResults.length} 条结果`)
})
</script>

你需要将 <NuxtAnnouncer> 组件添加到你的应用中,播报内容才会被渲染到 DOM 中。 :

对于路由/页面变化的自动播报,请改用 useRouteAnnouncer 配合 <NuxtRouteAnnouncer> 组件。 :