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 中。如需自动发布路由/页面更改公告，请改用
useRouteAnnouncer 配合 <NuxtRouteAnnouncer> 组件。