Vue.js中如何在strictTemplates: true下使用fallthrough attributes？

关键解决步骤 #

要在开启strictTemplates的同时正常使用属性透传，需要结合组件类型声明和正确的配置项——单独开启fallthroughAttributes不足以让TypeScript通过类型检查：

1. 为自定义组件声明允许的透传属性
   如果你的组件需要接收HTML通用属性（比如class、style、data-*等），可以在defineProps中合并对应类型：

   <script setup lang="ts">
   import type { HTMLAttributes } from 'vue'
   
   // 组件自身的Props定义
   interface ComponentProps {
     label: string
   }
   
   // 合并自身Props与HTML通用属性，允许透传
   const props = defineProps<ComponentProps & HTMLAttributes>()
   </script>
   
   <template>
     <button>{{ label }}</button>
   </template>
   

   这样TypeScript会把所有合法的HTML属性视为组件的有效属性，不会再标记为错误。如果只需要特定的透传属性，也可以直接在Props接口中声明，比如interface ComponentProps { label: string; disabled?: boolean }。

2. 确保配置文件的正确设置

   • 在tsconfig.json中同时启用strictTemplates和fallthroughAttributes：

     {
       "compilerOptions": {
         "strict": true
       },
       "vueCompilerOptions": {
         "strictTemplates": true,
         "fallthroughAttributes": true
       }
     }
     

   • 若使用Vite，需在vite.config.ts中把编译器选项传递给Vue插件：

     import { defineConfig } from 'vite'
     import vue from '@vitejs/plugin-vue'
     
     export default defineConfig({
       plugins: [
         vue({
           template: {
             compilerOptions: {
               fallthroughAttributes: true
             }
           }
         })
       ]
     })
     

为什么单独开启fallthroughAttributes无效？ #

fallthroughAttributes是控制Vue模板编译器是否允许属性透传的运行时开关，但TypeScript的严格模板检查依赖组件的props类型定义。如果组件没有明确声明允许额外属性，TS会把未在Props中定义的属性判定为错误，和编译器的运行时配置无关。

相关官方文档参考 #

• 严格模板类型检查：Vue官方TypeScript指南中关于strictTemplates的章节，详细说明了该选项的作用和配置细节
• 属性透传：Vue组件基础文档的「透传Attributes」部分，讲解了透传的行为逻辑，以及如何结合TypeScript进行类型适配

内容的提问来源于stack exchange，提问作者cdauth