Vue2 vs Vue3 的 h 函数：渲染函数完整迁移指南

Vue2 vs Vue3 的 h 函数渲染函数完整迁移指南概述h()是hyperscript超脚本的缩写用来以编程方式创建VNode虚拟节点。它是 Vue 渲染函数Render Function的核心 API模板和 JSX 最终都会编译成h()/createElement()调用。Vue 2叫createElement由render函数的参数传入Vue 3叫h需要从vue中显式import 本文对照Vue 官方最新文档2026-07-09逐条校验文末附官方强调的避坑清单。━━━一、为什么需要 h()模板写大部分 UI 很香但遇到高度动态的结构递归树、虚拟列表、动态组件组合时渲染函数的 JS 表达力更强。核心心智模型始终不变h(type, props, children)// 类型 属性 子节点 三件套变的是属性对象的组织方式以及事件/插槽的传递约定。━━━二、Vue 2 的 createElement基本形态exportdefault{render(createElement){returncreateElement(div,{class:box},Hello)}}data 对象字段重点createElement(div,{class:{active:true}, style:{color:red}, attrs:{id:foo}, // 普通 HTML 属性 props:{myProp:value}, // 组件 props domProps:{innerHTML:spanx/span}, // DOM 属性 on:{click: this.handleClick}, // 事件组件 原生 nativeOn:{click: this.handleNativeClick}, // ⚠️ 仅组件监听根元素原生事件 directives:[{name:show, value:true}], scopedSlots:{// 作用域插槽 default:(props)createElement(span, props.text)}, slot:header, // 普通插槽 key:unique-key, ref:myRef, refInFor:true})⚠️ 子节点限制// Vue2❌ 数字会被忽略 createElement(div,[1,2])━━━三、Vue 3 的 h()基本形态import{h}fromvueexportdefault{render(){returnh(div,{class:box},Hello)}}与 Vue 2 的关键区别能力Vue 2Vue 3children 类型字符串 / VNode / 数组 数字 / 布尔 / 函数attrs/props/domProps分字段统一平铺事件 on / nativeOn分开合并为 onXxx插槽data.scopedSlots第三个参数 children 对象多根节点❌✅ Fragmentprops 平铺 官方修饰符前缀import{h}fromvueh(div,{class:{active:true}, style:{color:red}, id:foo, // 普通属性 myProp:value, // 组件 props onClick:(){}, // 事件统一 onXxx innerHTML:spanx/span// DOM 属性})官方细节Vue 会自动判断该用setAttribute还是赋值 DOM property。也可手动指定.name→ 作为 DOM property 赋值^width→ 作为 HTML attribute 赋值h(div,{.name:some-name,^width:100})━━━四、事件处理的变化迁移最容易踩坑Vue 3移除了nativeOn和.native// Vue2createElement(MyComponent,{on:{close: fn}, nativeOn:{click: fn}// 监听根元素原生 click})// Vue3h(MyComponent,{onClose: fn, // 组件 emits 的 close onClick: fn // 未声明 emits 时透传到根元素})事件修饰符两种写法①.passive/.capture/.once—— camelCase 拼接h(input,{onClickCapture(){},onKeyupOnce(){}})② 其余修饰符—— 用withModifiersimport{h, withModifiers}fromvueh(div,{onClick: withModifiers((){},[self,prevent])})⚠️ Vue 2 用前缀符号!clickcapture、~keyuponce、~!mouseover。迁移时要改写━━━五、作用域插槽Vue 2写在 data 里createElement(MyComponent,{scopedSlots:{default:(props)createElement(span, props.text)}})Vue 3写在第三个参数import{h}fromvueh(MyComponent, null,{// ⚠️ 无 props 时传 null避免被当 props default:(props)h(span, props.text), header:()h(h1,标题)})子组件调用// 子组件内 setup(props,{slots}){return()h(div, null, slots.default({text:hi}))}━━━六、函数式组件Vue 2exportdefault{functional: true, render(createElement, context){returncreateElement(div, context.children)}}// context 含: props / children / slots / scopedSlots / data / parent / listeners / injectionsVue 3取消 functional: trueimport{h}fromvueconst FunctionalComp(props,{slots, attrs, emit}){returnh(div, attrs, slots.default?.())}FunctionalComp.props[msg] Vue 3 的 context只含attrs/emit/slots无this、无状态、无生命周期渲染成本更低。━━━七、Fragment / Teleport / 自定义指令Fragment 多根节点import{h, Fragment}fromvueh(Fragment,[h(div,a), h(div,b)])Teleportimport{h, Teleport}fromvueh(Teleport,{to:#modal},()h(div,弹窗))自定义指令 withDirectivesimport{h, withDirectives}fromvueconst pin{mounted(){},updated(){}}const vnodewithDirectives(h(div),[[pin,200,top,{animate:true}]])v-model 手动展开h(SomeComponent,{modelValue: props.modelValue,onUpdate:modelValue:(v)emit(update:modelValue,v)})━━━八、template ref 版本差异// Vue3.5 推荐 useTemplateRefimport{h, useTemplateRef}fromvuesetup(){const divEluseTemplateRef(my-div)return()h(div,{ref:my-div})}// Vue3.5之前直接传 ref()对象 const divElref()return()h(div,{ref: divEl})━━━九、VNode 必须唯一官方强调约束// ❌ 同一个 vnode 对象不能复用 const ph(p,hi)returnh(div,[p, p])// ✅ 用工厂函数returnh(div, Array.from({length:20}).map(()h(p,hi)))━━━十、完整差异速查表概念Vue 2Vue 3名称createElementhcreateVNode引入参数传入显式importdata 结构attrs/props/domProps/on/nativeOn 分字段统一平铺插槽scopedSlotschildren 对象函数式组件functional: true普通函数多根❌✅ Fragment性能优化无 patchFlagpatchFlag / shapeFlag━━━总结渲染函数迁移的核心就是三件事data 拆字段 → props 平铺on/nativeOn → onXxxscopedSlots → 第三个参数 children 对象记住h(type, props, children)三件套剩下的只是约定变化。 Vue 3.4 起不再隐式注册全局 JSX 命名空间用 TSX 需在 tsconfig 配jsxImportSource: vue且 Vue 的 JSX ≠ React 的 JSX。本文对照 Vue 官方文档校验如有疏漏欢迎评论指正。如果对你有帮助点赞 收藏 ⭐ 关注 后续继续分享 Vue3 进阶内容。