vue3 迁移指南

原文地址 v3.cn.vuejs.org

# 值得注意的新特性

Vue 3 中需要关注的一些新功能包括：

• 组合式 API
• Teleport
• 片段
• 触发组件选项
• 来自 @vue/runtime-core 的 createRenderer API(opens new window) 创建自定义渲染器
• 单文件组件组合式 API 语法糖 (<script setup>)(opens new window) 实验性
• 单文件组件状态驱动的 CSS 变量 (<style vars>)(opens new window) 实验性
• 单文件组件 <style scoped> 现在可以包含全局规则或只针对插槽内容的规则 (opens new window)

# 非兼容的变更

提示

我们仍在开发 Vue 3 的专用迁移版本，该版本的行为与 Vue 2 兼容，运行时警告不兼容。如果你计划迁移一个非常重要的 Vue 2 应用程序，我们强烈建议你等待迁移版本完成以获得更流畅的体验。

下面列出了从 2.x 开始的重大更改：

# 全局 API

• 全局 Vue API 已更改为使用应用程序实例

注释：全局 API，是指原来绑定在 vue 下的方法和属性，例如 vue.mixin。这种方式虽然便于全局修改每一个由该 vue 创建的实例，但是却污染了单元测试的环境

• 全局和内部 API 已经被重构为可 tree-shakable（树摇）

注释：全局API支持树摇，即在未使用时不会被打包工具打包

# 模板指令

• 组件上 v-model 用法已更改，替换 v-bind.sync

注释：v-model 修改了使用方法，用以替换 v-bind.sync 的实现

• <template v-for> 和非 v-for 节点上 key 用法已更改

注释：对于 v-if/v-else/v-else-if 的各分支项 key 将不再是必须的（过去似乎也不是必须的），<template v-for> 的 key 应该设置在 <template> 标签上，如果你手动提供 key，那么每个分支必须使用唯一的 key。你不能通过故意使用相同的 key 来强制重用分支。

• 在同一元素上使用的 v-if 和 v-for 优先级已更改

注释：vue2 中 v-for 的优先级高于 v-if

• v-bind="object" 现在排序敏感

注释：vue2 中对单个 property 的绑定会覆盖 v-bind:Object 的方式，vue3 中根据绑定顺序决定覆盖行为

• v-on:event.native 修饰符已移除

注释：新增的 emits 选项允许子组件定义会被组件触发的事件，未被定义为组件触发的所有事件监听器，Vue 现在将把它们作为原生事件监听器添加到子组件的根元素中 (除非在子组件的选项中设置了 inheritAttrs: false)。

• v-for 中的 ref 不再注册 ref 数组

注释：vue2 中，在模板语法中使用 v-for 和 ref 是，对同名 ref 会生成数组。在 render 函数中，需要手动传入 refInFor={true} 来实现。
注释：vue3 中，ref 允许绑定一个函数，接收每个绑定的 dom 作为参数

# 组件

• 只能使用普通函数创建功能组件
• functional 属性在单文件组件 (SFC) <template> 和 functional 组件选项被抛弃
• 异步组件现在需要 defineAsyncComponent 方法来创建
• 组件事件现在需要在 emits 选项中声明

# 渲染函数

• 渲染函数 API 改变
• $scopedSlots property 已删除，所有插槽都通过 $slots 作为函数暴露
• $listeners 被移除或整合到 $attrs
• $attrs 现在包含 class and style attribute

# 自定义元素

• 自定义元素白名单现在已经在编译时执行
• 对特殊的 is prop 的使用只严格限制在被保留的 <component> 标记中

# 其他小改变

• destroyed 生命周期选项被重命名为 unmounted
• beforeDestroy 生命周期选项被重命名为 beforeUnmount
• default prop 工厂函数不再可以访问 this 上下文
• 自定义指令 API 已更改为与组件生命周期一致
• data 选项应始终被声明为一个函数
• 来自 mixin 的 data 选项现在为浅合并
• Attribute 强制策略已更改
• 一些过渡 class 被重命名
• <TransitionGroup> 不再默认渲染包裹元素
• 当侦听一个数组时，只有当数组被替换时，回调才会触发，如果需要在变更时触发，则需要指定 deep 选项
• 没有特殊指令的标记 (v-if/else-if/else、v-for 或 v-slot) 的 <template> 现在被视为普通元素，并将生成原生的 <template> 元素，而不是渲染其内部内容。
• 在 Vue 2.x 中，应用根容器的 outerHTML 将替换为根组件模板 (如果根组件没有模板 / 渲染选项，则最终编译为模板)。Vue 3.x 现在使用应用容器的 innerHTML，这意味着容器本身不再被视为模板的一部分。

# 移除 API

• keyCode 支持作为 v-on 的修饰符
• $on，$off 和 $once 实例方法
• 过滤
• 内联模板 attribute
• $children 实例 property
• $destroy 实例方法。用户不应再手动管理单个 Vue 组件的生命周期。

# 官方支持的库

我们所有的官方库和工具现在都支持 Vue 3，但大多数仍然处于 beta 状态，并在 npm 的 next dist 标签下发布。我们正计划在 2020 年底前稳定所有项目，并将其转换为使用 latest 的 dist 标签。

# Vue CLI

从 v4.5.0 开始，vue-cli 现在提供了内置选项，可在创建新项目时选择 Vue 3。现在可以升级 vue-cli 并运行 vue create 来创建 Vue 3 项目。

• 文档 (opens new window)
• GitHub(opens new window)

# Vue Router

Vue Router 4.0 提供了 Vue 3 支持，并有许多突破性的变化，查看迁移指南 (opens new window) 获取完整的细节。

• 文档 (opens new window)
• Github(opens new window)
• RFCs(opens new window)

# Vuex

Vuex 4.0 提供了 Vue 3 支持，其 API 与 3.x 基本相同。唯一的突破性变化是插件的安装方式 (opens new window) 。

• 文档 (opens new window)
• Github(opens new window)

# Devtools Extension

我们正在开发一个新版本的 Devtools，它有一个新的 UI 和经过重构的内部结构，以支持多个 Vue 版本。新版本目前处于测试阶段，目前只支持 Vue 3。Vuex 和路由器的集成也在进行中。

• Chrome：从 Chrome web 商店中安装 (opens new window)

  • 提示：beta 版本可能与 devtools 的稳定版本冲突，因此你可能需要暂时禁用稳定版本，以便 beta 版本正常工作。

• Firefox：下载签名扩展 (opens new window) (assets 下的 .xpi 文件)

# IDE 支持

推荐使用 VSCode(opens new window) 和我们官方拓展 [(opens new window)](https://marketplace.visualstudio.com/items?item>Vetur<svg xmlns=) ，它为 Vue 3 提供了全面的 IDE 支持

# 其他项目

项目	npm	仓库
@vue/babel-plugin-jsx		[Github]
eslint-plugin-vue		[Github]
@vue/test-utils		[Github]
vue-class-component		[Github]
vue-loader		[Github]
rollup-plugin-vue		[Github]