vue-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vuejs/core

vue

Vue.js核心

vue

Version: 3.6.0-beta.6 (Feb 2026) Deps: @vue/shared@3.6.0-beta.6, @vue/runtime-dom@3.6.0-beta.6, @vue/runtime-vapor@3.6.0-beta.6, @vue/compiler-dom@3.6.0-beta.6, @vue/compiler-sfc@3.6.0-beta.6, @vue/server-renderer@3.6.0-beta.6 Tags: csp: 1.0.28-csp (Sep 2016), legacy: 2.7.16 (Dec 2023), v2-latest: 2.7.16 (Dec 2023), rc: 3.5.0-rc.1 (Aug 2024), alpha: 3.6.0-alpha.7 (Dec 2025), beta: 3.6.0-beta.6 (Feb 2026), latest: 3.5.28 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

版本： 3.6.0-beta.6（2026年2月） 依赖： @vue/shared@3.6.0-beta.6, @vue/runtime-dom@3.6.0-beta.6, @vue/runtime-vapor@3.6.0-beta.6, @vue/compiler-dom@3.6.0-beta.6, @vue/compiler-sfc@3.6.0-beta.6, @vue/server-renderer@3.6.0-beta.6 标签： csp: 1.0.28-csp（2016年9月）, legacy: 2.7.16（2023年12月）, v2-latest: 2.7.16（2023年12月）, rc: 3.5.0-rc.1（2024年8月）, alpha: 3.6.0-alpha.7（2025年12月）, beta: 3.6.0-beta.6（2026年2月）, latest: 3.5.28（2026年2月）

参考链接： 文档 — API参考、指南 • GitHub Issues — 问题、解决方案、边缘情况 • GitHub Discussions — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

NEW:
```
createVaporApp()
```
(experimental) — new in v3.6, creates a Vapor-mode app instance without pulling in the Virtual DOM runtime; use
```
createApp()
```
for standard VDOM apps source
NEW:
```
vaporInteropPlugin
```
(experimental) — new in v3.6, install into a VDOM
```
createApp()
```
instance to allow Vapor components inside VDOM trees; without it, Vapor SFCs cannot be used in VDOM apps source
NEW:
```
<script setup vapor>
```
attribute (experimental) — new in v3.6, opts an SFC into Vapor Mode compilation; only works with
```
<script setup>
```
; does not support Options API,
```
app.config.globalProperties
```
, or
```
getCurrentInstance()
```
source
NEW:
```
useTemplateRef(key)
```
— new in v3.5, preferred replacement for plain
```
ref
```
variable names matching
```
ref="key"
```
attributes; supports dynamic string IDs at runtime unlike the old static-only pattern source
NEW:
```
useId()
```
— new in v3.5, generates stable unique IDs per component instance guaranteed to match between SSR and client hydration; replaces manual ID management for form/accessibility attributes source
NEW:
```
onWatcherCleanup(fn)
```
— new in v3.5, registers a cleanup callback inside a
```
watch
```
or
```
watchEffect
```
callback; replaces the
```
onCleanup
```
parameter pattern and can be called from nested functions source

NEW:

hydrateOnVisible()

hydrateOnIdle()

hydrateOnInteraction()

hydrateOnMediaQuery()

— new in v3.5, lazy hydration strategies passed to

defineAsyncComponent({ hydrate: hydrateOnVisible() })

; without the

hydrate

option, async components hydrate immediately source

NEW:
```
defineModel()
```
stable — promoted from experimental in v3.3 to stable in v3.4; automatically declares a prop and returns a mutable ref; replaces the manual
```
defineProps
```
+
```
defineEmits('update:modelValue')
```
pattern source
NEW:
```
defineProps
```
destructure with defaults — stabilized in v3.5 (was experimental in v3.3);
```
const { count = 0 } = defineProps<{ count?: number }>()
```
replaces
```
withDefaults(defineProps<...>(), { count: 0 })
```
; destructured vars must be wrapped in getters to pass to
```
watch()
```
or composables source
BREAKING:
```
@vnodeXXX
```
event listeners — removed in v3.4, are now a compiler error; use
```
@vue:XXX
```
listeners instead (e.g.
```
@vue:mounted
```
) source
BREAKING: Reactivity Transform (
```
$ref
```
,
```
$computed
```
, etc.) — removed in v3.4 after being deprecated in v3.3; was experimental and distinct from the now-stable props destructure feature; use Vue Macros plugin to continue using it source
BREAKING: Global
```
JSX
```
namespace — no longer registered by default since v3.4; set
```
jsxImportSource: "vue"
```
in
```
tsconfig.json
```
or import
```
vue/jsx
```
to restore it; affects TSX users only source
BREAKING:
```
app.config.unwrapInjectedRef
```
— removed in v3.4; ref unwrapping in
```
inject()
```
is now always enabled and cannot be disabled source
NEW:
```
<Teleport defer>
```
prop — new in v3.5, mounts the teleport after the current render cycle so the target element can be rendered by Vue in the same component tree; requires explicit
```
defer
```
attribute for backwards compatibility source

Also changed:

defineSlots<{}>()

macro NEW v3.3 for typed slot declarations ·

defineOptions({})

macro NEW v3.3 to set component options without a separate

<script>

block ·

toRef(() => getter)

enhanced in v3.3 to accept plain values and getters ·

toValue()

NEW v3.3 normalizes values/getters/refs to values (inverse of

toRef

) ·

v-bind

same-name shorthand NEW v3.4 (

:id

shorthand for

:id="id"

) ·

data-allow-mismatch

attribute NEW v3.5 to suppress hydration mismatch warnings ·

useHost()

useShadowRoot()

NEW v3.5 for custom element host access ·

v-is

directive REMOVED v3.4 (use

is="vue:ComponentName"

instead) · reactivity system alien-signals refactor in v3.6 improves memory usage with no API changes

本节记录特定版本的API变更——优先关注近期的主版本/次版本更新。

新增：
```
createVaporApp()
```
（实验性）——v3.6版本新增，无需引入Virtual DOM运行时即可创建Vapor模式的应用实例；标准VDOM应用请使用
```
createApp()
```
来源
新增：
```
vaporInteropPlugin
```
（实验性）——v3.6版本新增，安装到基于VDOM的
```
createApp()
```
实例中，允许在VDOM树中使用Vapor组件；如果不安装该插件，Vapor SFC无法在VDOM应用中使用来源
新增：
```
<script setup vapor>
```
属性（实验性）——v3.6版本新增，将SFC设置为Vapor模式编译；仅适用于
```
<script setup>
```
；不支持Options API、
```
app.config.globalProperties
```
或
```
getCurrentInstance()
```
来源
新增：
```
useTemplateRef(key)
```
——v3.5版本新增，是与
```
ref="key"
```
属性匹配的普通
```
ref
```
变量名的推荐替代方案；与旧的仅静态模式不同，它在运行时支持动态字符串ID 来源
新增：
```
useId()
```
——v3.5版本新增，为每个组件实例生成稳定的唯一ID，确保SSR和客户端水合时ID一致；替代表单/无障碍属性的手动ID管理来源
新增：
```
onWatcherCleanup(fn)
```
——v3.5版本新增，在
```
watch
```
或
```
watchEffect
```
回调中注册清理回调；替代
```
onCleanup
```
参数模式，可从嵌套函数中调用来源

新增：

hydrateOnVisible()

、

hydrateOnIdle()

、

hydrateOnInteraction()

、

hydrateOnMediaQuery()

——v3.5版本新增，延迟水合策略，可传递给

defineAsyncComponent({ hydrate: hydrateOnVisible() })

；如果不设置

hydrate

选项，异步组件会立即水合来源

新增：
```
defineModel()
```
稳定版——从v3.3的实验性特性升级为v3.4的稳定特性；自动声明一个prop并返回一个可变的ref；替代手动的
```
defineProps
```
+
```
defineEmits('update:modelValue')
```
模式来源
新增：带默认值的
```
defineProps
```
解构——v3.5版本稳定（v3.3为实验性）；
```
const { count = 0 } = defineProps<{ count?: number }>()
```
替代
```
withDefaults(defineProps<...>(), { count: 0 })
```
；传递给组合式函数或
```
watch
```
时，需用getter包裹：
```
watch(() => count, ...)
```
来源
破坏性变更：
```
@vnodeXXX
```
事件监听器——v3.4版本移除，现在会触发编译器错误；请改用
```
@vue:XXX
```
监听器（例如
```
@vue:mounted
```
）来源
破坏性变更：响应式转换（
```
$ref
```
、
```
$computed
```
等）——在v3.3版本弃用后，v3.4版本移除；属于实验性特性，与现在稳定的props解构功能不同；如需继续使用，请安装Vue Macros插件来源
破坏性变更：全局
```
JSX
```
命名空间——v3.4版本起不再默认注册；可在
```
tsconfig.json
```
中设置
```
jsxImportSource: "vue"
```
或导入
```
vue/jsx
```
来恢复；仅影响TSX用户来源
破坏性变更：
```
app.config.unwrapInjectedRef
```
——v3.4版本移除；
```
inject()
```
中的ref自动解包现在始终启用，无法禁用来源
新增：
```
<Teleport defer>
```
属性——v3.5版本新增，在当前渲染周期后挂载Teleport，以便目标元素可由Vue在同一组件树中渲染；为了向后兼容，需要显式添加
```
defer
```
属性来源

其他变更：

defineSlots<{}>

宏 v3.3新增，用于类型化插槽声明 ·

defineOptions({})

宏 v3.3新增，无需单独的

<script>

块即可设置组件选项 ·

toRef(() => getter)

v3.3增强，支持接受普通值和getter ·

toValue()

v3.3新增，将值/getter/refs归一化为值（

toRef

的逆操作） ·

v-bind

同名简写 v3.4新增（

:id

是

:id="id"

的简写） ·

data-allow-mismatch

属性 v3.5新增，用于抑制水合不匹配警告 ·

useHost()

useShadowRoot()

v3.5新增，用于自定义元素宿主访问 ·

v-is

指令 v3.4移除（请改用

is="vue:ComponentName"

） · v3.6版本响应式系统alien-signals重构，在不改变API的情况下提升了内存使用效率

Best Practices

最佳实践

Use reactive props destructure (3.5+) with native default value syntax instead of
```
withDefaults()
```
— destructured variables are reactive and the compiler rewrites accesses to
```
props.x
```
automatically. When passing to composables or
```
watch
```
, wrap in a getter:
```
watch(() => count, ...)
```
source
Use
```
toValue()
```
in composables to normalize
```
MaybeRefOrGetter<T>
```
arguments — handles plain values, refs, and getter functions uniformly so callers can pass any form without the composable caring source
Use
```
onWatcherCleanup()
```
(3.5+) instead of the
```
onCleanup
```
callback parameter in
```
watch
```
and
```
watchEffect
```
— it can be called from any helper function in the sync execution stack, not just the top-level callback, making cleanup logic easier to extract source
Use
```
useTemplateRef()
```
(3.5+) instead of a plain
```
ref
```
with a matching variable name for template refs — supports dynamic ref IDs and provides better IDE auto-completion and type checking via
```
@vue/language-tools
```
2.1 source
Use
```
useId()
```
(3.5+) for form element and accessibility IDs in SSR apps — generated IDs are stable across server and client renders, preventing hydration mismatches. Avoid calling inside
```
computed()
```
as it can cause instance conflicts source
Use
```
shallowRef()
```
/
```
shallowReactive()
```
for large immutable data structures — deep reactivity tracks every property access via proxy traps; shallow variants avoid this overhead while still reacting to root
```
.value
```
replacement source
Pass computed values directly as
```
active
```
props rather than IDs for comparison — child components re-render when any received prop changes, so passing a stable boolean avoids re-rendering every list item when only one item's active state changes source
When a computed returns a new object on every evaluation, accept
```
oldValue
```
and return it unchanged when data is equivalent — avoids unnecessary downstream effect triggers since Vue 3.4+ only triggers effects when the computed value reference changes source
Use
```
defineAsyncComponent
```
with a lazy hydration strategy (3.5+) for SSR —
```
hydrateOnVisible()
```
,
```
hydrateOnIdle()
```
,
```
hydrateOnInteraction()
```
, and
```
hydrateOnMediaQuery()
```
are tree-shakable and defer hydration until the component is actually needed

import { defineAsyncComponent, hydrateOnVisible } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnVisible()
})

source

(experimental) Opt in to Vapor Mode per-component with
```
<script setup vapor>
```
when targeting performance-sensitive UI — Vapor avoids Virtual DOM diffing entirely and achieves Solid/Svelte 5 benchmark parity, but does not support Options API,
```
app.config.globalProperties
```
, or
```
getCurrentInstance()
```
. Use
```
vaporInteropPlugin
```
to mix Vapor and VDOM components in an existing app source

在3.5+版本中，使用带原生默认值语法的响应式props解构替代
```
withDefaults()
```
——解构后的变量是响应式的，编译器会自动将访问重写为
```
props.x
```
。传递给组合式函数或
```
watch
```
时，需用getter包裹：
```
watch(() => count, ...)
```
来源
在组合式函数中使用
```
toValue()
```
来归一化
```
MaybeRefOrGetter<T>
```
参数——统一处理普通值、refs和getter函数，调用者可以传递任意形式的值，组合式函数无需关心来源
使用
```
onWatcherCleanup()
```
（3.5+）替代
```
watch
```
和
```
watchEffect
```
中的
```
onCleanup
```
回调参数——它可以在同步执行栈中的任何辅助函数中调用，而不仅仅是顶层回调，使清理逻辑更易于提取来源
使用
```
useTemplateRef()
```
（3.5+）替代与模板ref匹配的普通
```
ref
```
变量名——支持动态ref ID，并通过
```
@vue/language-tools
```
2.1提供更好的IDE自动补全和类型检查来源
在SSR应用中，使用
```
useId()
```
（3.5+）生成表单元素和无障碍属性的ID——生成的ID在服务器和客户端渲染中保持稳定，避免水合不匹配。避免在
```
computed()
```
中调用，否则可能导致实例冲突来源
对于大型不可变数据结构，使用
```
shallowRef()
```
/
```
shallowReactive()
```
——深度响应式会通过代理陷阱跟踪每个属性的访问；浅响应式变体可避免此开销，同时仍会对根
```
.value
```
的变更做出响应来源
直接传递计算值作为
```
active
```
props，而非用于比较的ID——子组件在接收到的props变更时会重新渲染，传递稳定的布尔值可避免仅单个项的激活状态变更时，所有列表项都重新渲染来源
当计算属性每次求值都返回新对象时，接受
```
oldValue
```
并在数据等价时返回旧值——Vue 3.4+仅在计算属性值引用变更时触发副作用，这样可避免不必要的下游副作用触发来源
对于SSR，使用带延迟水合策略的
```
defineAsyncComponent
```
（3.5+）——
```
hydrateOnVisible()
```
、
```
hydrateOnIdle()
```
、
```
hydrateOnInteraction()
```
和
```
hydrateOnMediaQuery()
```
支持摇树优化，会延迟水合直到组件真正需要时才执行

import { defineAsyncComponent, hydrateOnVisible } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnVisible()
})

来源

（实验性）针对性能敏感的UI，通过
```
<script setup vapor>
```
为单个组件启用Vapor模式——Vapor完全避免了Virtual DOM diffing，性能达到Solid/Svelte 5的基准水平，但不支持Options API、
```
app.config.globalProperties
```
或
```
getCurrentInstance()
```
。在现有应用中混合使用Vapor和VDOM组件时，请使用
```
vaporInteropPlugin
```
来源