Vuetify v-dialog模态框打开后如何让屏幕阅读器聚焦到其内部内容？

失效原因说明 #

你遇到的聚焦失效和role="document"属性无关，该属性是无障碍标准标注，作用是告知屏幕阅读器当前区域为可浏览的文档内容，不会拦截聚焦行为。之前的方案失效主要有两个核心原因：

• Vuetify的v-dialog默认自带打开过渡动画，调用聚焦方法时模态框DOM还未完成挂载渲染
• v-dialog默认采用懒加载机制，未打开时内部DOM不会插入到页面中，此时调用focus()自然无响应

适配步骤 #

1. 给目标聚焦元素添加可聚焦标识 #

如果需要聚焦的是标题、提示文本等非交互元素，需要给元素添加tabindex="-1"属性，该配置可以让元素被编程式聚焦，但不会被键盘的Tab键误触发；如果是按钮、输入框等原生可聚焦元素不需要额外加属性。
给目标元素绑定ref属性，示例代码如下：

<template>
  <v-dialog 
    v-model="dialogVisible"
    <!-- 监听模态框完全打开事件 -->
    @opened="handleDialogOpened"
  >
    <!-- 给要聚焦的标题添加属性和ref -->
    <h2 ref="dialogTitle" tabindex="-1">操作确认</h2>
    <p>是否确认提交当前填写的内容？</p>
    <v-btn ref="confirmBtn">确认提交</v-btn>
  </v-dialog>
</template>

2. 在模态框完全打开后执行聚焦 #

使用v-dialog内置的opened事件触发聚焦，该事件会在模态框过渡动画结束、DOM完全挂载后才执行，配合$nextTick确保DOM渲染完成：

<script>
export default {
  data() {
    return {
      dialogVisible: false
    }
  },
  methods: {
    handleDialogOpened() {
      this.$nextTick(() => {
        // 聚焦标题，适合屏幕阅读器优先播报模态框核心主题
        this.$refs.dialogTitle.focus()
        // 如果需要优先聚焦交互按钮，替换为对应ref即可
        // this.$refs.confirmBtn.focus()
      })
    }
  }
}
</script>

补充说明 #

Vuetify 2.x及以上版本的v-dialog默认开启retain-focus属性，会自动将键盘焦点限制在模态框内部，完成上述配置后即可符合仅键盘导航的无障碍要求。如果仍出现聚焦失败的情况，检查目标元素是否存在disabled、display: none、visibility: hidden等无法被聚焦的状态。

内容的提问来源于stack exchange，提问作者Éder Sousa