【Vue3 Props】【组件传参规范】从必传校验、默认值到类型标注彻底搞懂组件Props最佳写法避开undefined、类型混用、布尔值误传高频坑 文章目录一、前言为什么要重视 Props 设计二、Props 基础从对象写法到 TypeScript2.1 最简单的数组写法不推荐2.2 对象写法推荐作为起步2.3 完整对象写法日常开发推荐三、必传校验required3.1 什么时候用 required: true3.2 必传时不要写 default3.3 实际踩坑忘了传必传 prop四、默认值default4.1 什么时候需要 default4.2 对象/数组默认值必须用函数4.3 有默认值时的类型建议五、类型标注type5.1 支持的类型5.2 多类型用数组5.3 常见坑布尔 prop 的简化写法六、综合实战一个完整的按钮组件七、TypeScript 写法可选但推荐八、规范速查表九、小结 系列模块导航同学们好我是 Eugene尤金一名多年中后台前端开发工程师。Eugene 发音 /juːˈdʒiːn/大家怎么顺口怎么叫就好很多前端开发者都会遇到一个瓶颈代码能跑但不够规范功能能实现但维护起来特别痛苦一个人写没问题一到团队协作就各种混乱、踩坑、返工。想写出干净、优雅、可维护的专业代码靠的不是天赋而是体系化的规范 真实实战经验。这一系列《前端规范实战》我会用大白话 真实业务场景不讲玄学、不堆理论只分享能直接落地的规范、标准与避坑指南。帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。一、前言为什么要重视 Props 设计如果你已经会写 Vue 组件但经常出现下面这些情况子组件里props.xxx是undefined控制台一堆Cannot read property of undefined多人协作时不清楚某个 prop 是必传还是可选传true和true傻傻分不清导致判断逻辑异常本质问题往往是Props 设计不规范。本文从「必传校验、默认值、类型标注」三块入手给出日常写代码时该怎么选、为什么这么选、常见坑点目标是把 Props 写得清晰、可维护。⬆ 返回目录二、Props 基础从对象写法到 TypeScript2.1 最简单的数组写法不推荐// 只适合快速验证不推荐长期使用exportdefault{props:[title,count,isDisabled]}问题没有类型、没有默认值、没有必传说明别人很难知道该怎么传、传什么。⬆ 返回目录2.2 对象写法推荐作为起步exportdefault{props:{title:String,count:Number,isDisabled:Boolean}}这里只是给 Vue 提供了运行时类型检查但仍没有默认值和必传约束。⬆ 返回目录2.3 完整对象写法日常开发推荐exportdefault{props:{// 必传 类型title:{type:String,required:true},// 可选 类型 默认值count:{type:Number,default:0},// 布尔值建议显式 defaultisDisabled:{type:Boolean,default:false}}}这样别人一看就知道title必传count有默认 0isDisabled默认false。⬆ 返回目录三、必传校验required3.1 什么时候用 required: true当某个数据没有就失去意义时就设为必传。例如!-- 用户卡片没有 userId 就没法展示 --UserCard:user-idcurrentUser.id/!-- 分页器没有 total 就没法算页数 --Pagination:total100:page-size10/对应定义props:{userId:{type:[String,Number],// 兼容字符串和数字 idrequired:true},total:{type:Number,required:true}}⬆ 返回目录3.2 必传时不要写 default// ❌ 逻辑矛盾既必传又有默认值props:{userId:{type:String,required:true,default:// 多余且会掩盖漏传问题}}// ✅ 必传就只写 requiredprops:{userId:{type:String,required:true}}⬆ 返回目录3.3 实际踩坑忘了传必传 prop!-- 父组件 --templateUserCard/!-- 漏传 userId --/template控制台会看到类似[Vue warn]: Missing required prop: userId这是 Vue 的运行时校验能帮你尽早发现问题。⬆ 返回目录四、默认值default4.1 什么时候需要 default当某个 prop可以没有并且你希望有一个合理的兜底值时用default。props:{pageSize:{type:Number,default:10},placeholder:{type:String,default:请输入}}⬆ 返回目录4.2 对象/数组默认值必须用函数// ❌ 错误直接写对象所有组件实例会共享同一个引用props:{config:{type:Object,default:{}// 危险},list:{type:Array,default:[]// 危险}}// ✅ 正确用函数返回新对象props:{config:{type:Object,default:()({})},list:{type:Array,default:()[]}}原因对象和数组是引用类型多个实例如果共用同一个引用修改会互相影响。用函数每次返回新对象/新数组互不干扰。⬆ 返回目录4.3 有默认值时的类型建议// 如果 default 是 0type 就写 Numbercount:{type:Number,default:0}// 如果 default 是 type 就写 Stringkeyword:{type:String,default:}// 布尔值建议显式写 default避免被当成字符串 falsevisible:{type:Boolean,default:false}⬆ 返回目录五、类型标注type5.1 支持的类型Vue 3 的 props 支持String、Number、BooleanArray、ObjectDate、FunctionSymbol自定义构造函数⬆ 返回目录5.2 多类型用数组// id 可能是字符串或数字props:{id:{type:[String,Number],required:true}}⬆ 返回目录5.3 常见坑布尔 prop 的简化写法!-- 下面两种写法等价 --MyButtondisabled/MyButton:disabledtrue/如果写成MyButtondisabledfalse/此时disabled会收到字符串false在 JS 里它是 truthy所以if (props.disabled)仍然为真按钮还是会被禁用。正确做法需要传 false 时必须用绑定MyButton:disabledfalse/⬆ 返回目录六、综合实战一个完整的按钮组件需求支持type、size、loading、disabled并有合理默认值。!-- BaseButton.vue --templatebutton:classbuttonClass:disabledisDisabledclickhandleClickspanv-ifloadingclassloading-icon⏳/spanslot//button/templatescriptexportdefault{name:BaseButton,props:{// 必传按钮类型决定样式type:{type:String,required:true,validator:(value)[primary,default,danger].includes(value)},// 可选 默认值size:{type:String,default:medium,validator:(value)[small,medium,large].includes(value)},loading:{type:Boolean,default:false},disabled:{type:Boolean,default:false}},computed:{buttonClass(){return[btn,btn--${this.type},btn--${this.size},{btn--loading:this.loading,btn--disabled:this.isDisabled}]},isDisabled(){returnthis.disabled||this.loading}},methods:{handleClick(e){if(!this.isDisabled){this.$emit(click,e)}}}}/script使用示例!-- 最简只传必传 type --BaseButtontypeprimary确认/BaseButton!-- 完整传参 --BaseButtontypedangersizesmall:loadingisSubmitting:disabled!formValidclickhandleSubmit提交/BaseButton要点type必传并加上validator限制合法值size、loading、disabled有默认值可选传布尔类 prop 在需要传false时用:disabledfalse⬆ 返回目录七、TypeScript 写法可选但推荐使用script setup TypeScript 时可以用defineProps做类型标注scriptsetuplangtsinterfaceProps{title:string count?:number isDisabled?:boolean}constpropswithDefaults(definePropsProps(),{count:0,isDisabled:false})/scripttemplatediv{{ props.title }} - {{ props.count }}/div/templatetitle没有?相当于必传count、isDisabled有?可选并在withDefaults中给出默认值⬆ 返回目录八、规范速查表场景写法必传字符串{ type: String, required: true }可选字符串 默认值{ type: String, default: }可选数字 默认值{ type: Number, default: 0 }布尔值{ type: Boolean, default: false }传 false 时用:propfalse对象/数组默认值使用default: () ({})或default: () []多类型type: [String, Number]枚举值校验使用validator⬆ 返回目录九、小结必传校验核心数据用required: true且不写default默认值可选但有合理兜底时用default对象/数组用函数返回类型标注用type做运行时校验避免类型混用布尔 prop传false时一定要用:propfalse避免字符串false可选增强需要限制取值范围时用validator把这些规范用在日常组件设计中可以减少 undefined 报错、提高协作效率也让代码更易读、易维护。如果你有特定场景例如复杂表单、多级组件通信想进一步规范可以写在评论区我们可以继续细化。⬆ 返回目录 系列模块导航 编码语法规范这是前端规范实战系列中第二个模块当编码语法规范模块更新完成之后会附上此模块的跳转链接方便同学们阅读学习。更新中敬请期待~ 跟着系列慢慢学把技术功底扎扎实实地打牢 系列总览「前端规范实战系列」正在持续更新中后续会整理一篇《前端规范实战系列全系列目录导航》包含每篇文章简介 直达链接方便大家按顺序、体系化学习。更新中敬请期待⬆ 返回目录技术成长从来不是比谁写得快而是比谁写得稳、规范、可维护。哪怕每次只吃透一条规范长期下来差距会非常明显。后续我会持续更新前端规范、工程化、可维护代码相关实战干货帮你告别面条代码、维护噩梦在开发与面试中更有底气。觉得有用欢迎点赞 收藏 关注不错过每一篇实战内容。我是 Eugene与你一起写规范、写优质代码我们下篇干货见
Vue3 Props 传参实战规范：必传校验 + 默认值 + 类型标注，避开 undefined / 类型混用坑｜Vue 组件与模板规范篇
【Vue3 Props】【组件传参规范】从必传校验、默认值到类型标注彻底搞懂组件Props最佳写法避开undefined、类型混用、布尔值误传高频坑 文章目录一、前言为什么要重视 Props 设计二、Props 基础从对象写法到 TypeScript2.1 最简单的数组写法不推荐2.2 对象写法推荐作为起步2.3 完整对象写法日常开发推荐三、必传校验required3.1 什么时候用 required: true3.2 必传时不要写 default3.3 实际踩坑忘了传必传 prop四、默认值default4.1 什么时候需要 default4.2 对象/数组默认值必须用函数4.3 有默认值时的类型建议五、类型标注type5.1 支持的类型5.2 多类型用数组5.3 常见坑布尔 prop 的简化写法六、综合实战一个完整的按钮组件七、TypeScript 写法可选但推荐八、规范速查表九、小结 系列模块导航同学们好我是 Eugene尤金一名多年中后台前端开发工程师。Eugene 发音 /juːˈdʒiːn/大家怎么顺口怎么叫就好很多前端开发者都会遇到一个瓶颈代码能跑但不够规范功能能实现但维护起来特别痛苦一个人写没问题一到团队协作就各种混乱、踩坑、返工。想写出干净、优雅、可维护的专业代码靠的不是天赋而是体系化的规范 真实实战经验。这一系列《前端规范实战》我会用大白话 真实业务场景不讲玄学、不堆理论只分享能直接落地的规范、标准与避坑指南。帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。一、前言为什么要重视 Props 设计如果你已经会写 Vue 组件但经常出现下面这些情况子组件里props.xxx是undefined控制台一堆Cannot read property of undefined多人协作时不清楚某个 prop 是必传还是可选传true和true傻傻分不清导致判断逻辑异常本质问题往往是Props 设计不规范。本文从「必传校验、默认值、类型标注」三块入手给出日常写代码时该怎么选、为什么这么选、常见坑点目标是把 Props 写得清晰、可维护。⬆ 返回目录二、Props 基础从对象写法到 TypeScript2.1 最简单的数组写法不推荐// 只适合快速验证不推荐长期使用exportdefault{props:[title,count,isDisabled]}问题没有类型、没有默认值、没有必传说明别人很难知道该怎么传、传什么。⬆ 返回目录2.2 对象写法推荐作为起步exportdefault{props:{title:String,count:Number,isDisabled:Boolean}}这里只是给 Vue 提供了运行时类型检查但仍没有默认值和必传约束。⬆ 返回目录2.3 完整对象写法日常开发推荐exportdefault{props:{// 必传 类型title:{type:String,required:true},// 可选 类型 默认值count:{type:Number,default:0},// 布尔值建议显式 defaultisDisabled:{type:Boolean,default:false}}}这样别人一看就知道title必传count有默认 0isDisabled默认false。⬆ 返回目录三、必传校验required3.1 什么时候用 required: true当某个数据没有就失去意义时就设为必传。例如!-- 用户卡片没有 userId 就没法展示 --UserCard:user-idcurrentUser.id/!-- 分页器没有 total 就没法算页数 --Pagination:total100:page-size10/对应定义props:{userId:{type:[String,Number],// 兼容字符串和数字 idrequired:true},total:{type:Number,required:true}}⬆ 返回目录3.2 必传时不要写 default// ❌ 逻辑矛盾既必传又有默认值props:{userId:{type:String,required:true,default:// 多余且会掩盖漏传问题}}// ✅ 必传就只写 requiredprops:{userId:{type:String,required:true}}⬆ 返回目录3.3 实际踩坑忘了传必传 prop!-- 父组件 --templateUserCard/!-- 漏传 userId --/template控制台会看到类似[Vue warn]: Missing required prop: userId这是 Vue 的运行时校验能帮你尽早发现问题。⬆ 返回目录四、默认值default4.1 什么时候需要 default当某个 prop可以没有并且你希望有一个合理的兜底值时用default。props:{pageSize:{type:Number,default:10},placeholder:{type:String,default:请输入}}⬆ 返回目录4.2 对象/数组默认值必须用函数// ❌ 错误直接写对象所有组件实例会共享同一个引用props:{config:{type:Object,default:{}// 危险},list:{type:Array,default:[]// 危险}}// ✅ 正确用函数返回新对象props:{config:{type:Object,default:()({})},list:{type:Array,default:()[]}}原因对象和数组是引用类型多个实例如果共用同一个引用修改会互相影响。用函数每次返回新对象/新数组互不干扰。⬆ 返回目录4.3 有默认值时的类型建议// 如果 default 是 0type 就写 Numbercount:{type:Number,default:0}// 如果 default 是 type 就写 Stringkeyword:{type:String,default:}// 布尔值建议显式写 default避免被当成字符串 falsevisible:{type:Boolean,default:false}⬆ 返回目录五、类型标注type5.1 支持的类型Vue 3 的 props 支持String、Number、BooleanArray、ObjectDate、FunctionSymbol自定义构造函数⬆ 返回目录5.2 多类型用数组// id 可能是字符串或数字props:{id:{type:[String,Number],required:true}}⬆ 返回目录5.3 常见坑布尔 prop 的简化写法!-- 下面两种写法等价 --MyButtondisabled/MyButton:disabledtrue/如果写成MyButtondisabledfalse/此时disabled会收到字符串false在 JS 里它是 truthy所以if (props.disabled)仍然为真按钮还是会被禁用。正确做法需要传 false 时必须用绑定MyButton:disabledfalse/⬆ 返回目录六、综合实战一个完整的按钮组件需求支持type、size、loading、disabled并有合理默认值。!-- BaseButton.vue --templatebutton:classbuttonClass:disabledisDisabledclickhandleClickspanv-ifloadingclassloading-icon⏳/spanslot//button/templatescriptexportdefault{name:BaseButton,props:{// 必传按钮类型决定样式type:{type:String,required:true,validator:(value)[primary,default,danger].includes(value)},// 可选 默认值size:{type:String,default:medium,validator:(value)[small,medium,large].includes(value)},loading:{type:Boolean,default:false},disabled:{type:Boolean,default:false}},computed:{buttonClass(){return[btn,btn--${this.type},btn--${this.size},{btn--loading:this.loading,btn--disabled:this.isDisabled}]},isDisabled(){returnthis.disabled||this.loading}},methods:{handleClick(e){if(!this.isDisabled){this.$emit(click,e)}}}}/script使用示例!-- 最简只传必传 type --BaseButtontypeprimary确认/BaseButton!-- 完整传参 --BaseButtontypedangersizesmall:loadingisSubmitting:disabled!formValidclickhandleSubmit提交/BaseButton要点type必传并加上validator限制合法值size、loading、disabled有默认值可选传布尔类 prop 在需要传false时用:disabledfalse⬆ 返回目录七、TypeScript 写法可选但推荐使用script setup TypeScript 时可以用defineProps做类型标注scriptsetuplangtsinterfaceProps{title:string count?:number isDisabled?:boolean}constpropswithDefaults(definePropsProps(),{count:0,isDisabled:false})/scripttemplatediv{{ props.title }} - {{ props.count }}/div/templatetitle没有?相当于必传count、isDisabled有?可选并在withDefaults中给出默认值⬆ 返回目录八、规范速查表场景写法必传字符串{ type: String, required: true }可选字符串 默认值{ type: String, default: }可选数字 默认值{ type: Number, default: 0 }布尔值{ type: Boolean, default: false }传 false 时用:propfalse对象/数组默认值使用default: () ({})或default: () []多类型type: [String, Number]枚举值校验使用validator⬆ 返回目录九、小结必传校验核心数据用required: true且不写default默认值可选但有合理兜底时用default对象/数组用函数返回类型标注用type做运行时校验避免类型混用布尔 prop传false时一定要用:propfalse避免字符串false可选增强需要限制取值范围时用validator把这些规范用在日常组件设计中可以减少 undefined 报错、提高协作效率也让代码更易读、易维护。如果你有特定场景例如复杂表单、多级组件通信想进一步规范可以写在评论区我们可以继续细化。⬆ 返回目录 系列模块导航 编码语法规范这是前端规范实战系列中第二个模块当编码语法规范模块更新完成之后会附上此模块的跳转链接方便同学们阅读学习。更新中敬请期待~ 跟着系列慢慢学把技术功底扎扎实实地打牢 系列总览「前端规范实战系列」正在持续更新中后续会整理一篇《前端规范实战系列全系列目录导航》包含每篇文章简介 直达链接方便大家按顺序、体系化学习。更新中敬请期待⬆ 返回目录技术成长从来不是比谁写得快而是比谁写得稳、规范、可维护。哪怕每次只吃透一条规范长期下来差距会非常明显。后续我会持续更新前端规范、工程化、可维护代码相关实战干货帮你告别面条代码、维护噩梦在开发与面试中更有底气。觉得有用欢迎点赞 收藏 关注不错过每一篇实战内容。我是 Eugene与你一起写规范、写优质代码我们下篇干货见
