useAnnouncer
向屏幕阅读器通告消息的组合式函数。
此组合式函数在 Nuxt v3.17+ 中可用。
描述
用于向屏幕阅读器通告动态内容更改的组合式函数。与自动通告路由更改的 useRouteAnnouncer`` 不同，useAnnouncer` 让您可以手动控制通告的内容和时间。
将其用于页面内更新，如表单验证、异步操作、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('Message sent successfully')
} catch (error) {
assertive('Error: Failed to send message')
}
}
</script>
使用场景
表单验证
app/components/LoginForm.vue
<script setup lang="ts">
const { assertive } = useAnnouncer()
function validateForm () {
const errors = []
if (!email.value) { errors.push('Email is required') }
if (!password.value) { errors.push('Password is required') }
if (errors.length) {
assertive(`Form has ${errors.length} errors: ${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('Loading data...')
} else if (newStatus === 'success') {
polite('Data loaded successfully')
}
})
</script>
搜索结果
app/components/Search.vue
<script setup lang="ts">
const { polite } = useAnnouncer()
const results = ref([])
watch(results, (newResults) => {
polite(`Found ${newResults.length} results`)
})
</script>
您需要将
<NuxtAnnouncer> 组件添加到您的应用中，以便在 DOM 中呈现通告。对于路由/页面更改的自动通告，请改用带有
<NuxtRouteAnnouncer> 组件的 useRouteAnnouncer。