升级指南

本页面包含了一个详细的破坏性变动的列表，以及如何将你的应用升级到 Vuetify 3.0 所需的步骤。

DANGER

此页面中的许多问题，可以使用 eslint-plugin-vuetify 插件完成

INFO

在升级 Vuetify 3 之前，请参考确认官方的 Vue 3 升级指导升级指导。

WARNING

并非所有的 Vuetify 2 的组件在 Vuetify 3 中都可用；这些组件会在 Vuetify 实验室中开发并释出。

起步

Vuetify 类已删除, 现在使用的是 createVuetify 函数。

Vue.use(Vuetify)

const vuetify = new Vuetify({ ... })

const app = new Vue({
  vuetify,
  ...
})

const app = createApp()

const vuetify = createVuetify({ ... })

app.use(vuetify)

现在一般使用 import ... from 'vuetify' 单独导入所需的内容，为了导入全部内容，请导入 'vuetify/dist/vuetify.js' （不推荐）
'vuetify/lib' 不再被使用，请根据情况更改为使用 'vuetify' / 'vuetify/components' / 'vuetify/directives' 之一
仅组件样式会被导入，全局样式必须从 'vuetify/styles' 单独导入。
vuetify-loader 已更名为 webpack-plugin-vuetify, 我们还有一个新的 vite-plugin-vuetify 插件用于 vite 。

Features （特性）

Layout （布局）

不再包含以前作为 .v-application p 或 .v-application ul 包含的全局样式。如果您需要 p, 的 margin 或 ul 和 ol的 padding-left，请在根组件的 <style> 标记中手动设置。
已从 v-navigation-drawer、v-app-bar 和 v-system-bar 中移除 stateless, clipped, clipped-right 和 app 等 props。标记中的位置决定了外观。使用 order="number" prop 可手动影响其位置。
$vuetify.breakpoint 已更名为 $vuetify.display 并拓展了新的属性

Theme （主题）

现在支持多个主题，因此从组件中删除了 light / dark props 。使用 v-theme-provider 为特定组件树设置主题。
- 组件以前有一个 dark prop,如 v-app-bar，现在接受 theme="dark" prop 。
主题颜色会自动设置前景文字颜色，如果您正在使用 light / dark 来获得不同的文本颜色，您可能不再需要它。
变体命名方案略有变化，现在是一个单词而不是两个。例如，primary darken-1 现在是 primary-darken-1 。
- 要使用变量命名作为color props 的值，您打算使用的变量需要在 theme.variations.colors 下的主题中启用。例如:colors: ['primary']
颜色类已重命名：
- 背景有一个 bg- 前缀, 例如 .primary 现在是 .bg-primary.
- 文本颜色有一个 text- 前缀, 例如， .primary--text 现在是 .text-primary.
- 变量不再是一个单独的类，例如 .primary--text.text--darken-1 现在是 .text-primary-darken-1.
主题系统现在内部使用 CSS 变量，所以 customProperties 不再需要。
- 如果你想在 v2 里使用 customProperties , 命名方案已从 --v-primary-base 改为 --v-theme-primary.
- 自定义属性现在也是一个 rgb 列表，而不是十六进制，因此访问它们必须使用 rgb() 或 rgba(), 例如 color: rgb(var(--v-theme-primary)) 而不是 color: var(--v-primary-base).
主题配置中的主题颜色现在嵌套在 colors 属性内，例如： const myTheme = { theme: { themes: { light: { colors: { primary: '#ccc' } } } } }

SASS variables （变量）

$headings 与 $typography 合并: 通过 map-get($typography, 'subtitle-2', 'size') 访问 subtitle-2 的字体大小
如果您在 v2 版本中从 ~vuetify/src/styles/settings/_variables 导入了变量，现在则必须使用 vuetify/settings 替代。
以前存在于类似 ~/vuetify/src/components/VIcon/VIcon.sass 中的组件变量现在可以直接从 vuetify/settings 中导入了。
$display-breakpoints不再包括 {breakpoint}-only 变量 (例如. xs-only), 使用 @media #{map-get(v.$display-breakpoints, 'xs')} 代替。
$transition 映射已被删除, 请使用独立的 $standard-easing, $decelerated-easing, $accelerated-easing 变量替代。
$container-padding-x 在 v2 现在是 16px 而不是 12px。您可以将其替换为 $spacer * 3 t'以获得之前的外观。
重命名或删除的组件变量太多，无法列出。由于元素结构发生了重大变化，所以没有自动更新这些元素的方法，您需要手动更新这些元素以及任何自定义样式。

样式和实用类

.hidden-{breakpoint}-only 已重命名为 .hidden-{breakpoint}
.text-xs-{alignment} 已重命名为 .text-{alignment} 以反映它适用于所有断点的事实。
为了保持一致性，排版类已经重命名，并且都以text-, 作为前缀，例如 .display-4现在是 .text-h1
转换缓和类已被删除。

INFO

不会提供类更改的完整列表，请使用eslint-plugin-vuetify 自动修复它们。

Components （组件）

常规更改

在支持 v-model 使用的组件上，value prop 已被 model-value 所取代。(v3 需要此更改)。
- 注意，一些作为 selection value 使用的值不适用于 value ，例如v-btn-toggle中的v-btn。
在支持v-model使用的组件上，@input event 已被@update:model-value取代。(v3 需要此更改)
Left和right分别被start和end取代。这也适用于实用程序类，例如.round -r现在是.round-e。
尺寸 props small /medium/ large 等已合并为一个 size prop。
absolute 和 fixed props 已合并为一个 position prop。
top / bottom /left/ right props 已合并为一个 location prop。
background-color prop 已更名为 bg-color。
在诸如 v-select、v-btn-toggle、v-alert、v-text-field、v-list 和 v-list-item 等组件上，dense prop 已更改为 density prop，其可选值有 default、comfortable、compact。
激活器插槽的工作方式略有不同。将#activator={attrs, on}替换为#activator={props}，然后删除v-on="on"并将v-bind="attrs"替换为v-bind="props" 。
一些组件的标记有结构上的变化。这意味着您可能必须更改在测试中查询和断言它们的方式。例如，V-switch现在在底层使用<input type="checkbox" />，这就是为什么aria-checked和aria-role="switch"属性被删除的原因。

Input 组件

词缀槽现在是一致的
- prepend 和 prepend-inner 是一样的。
- append 已经重命名为 append-inner。
- append-outer 已经重命名为 append。
变量 props filled/outlined/solo 已经合并成一个 variant prop。
- 可用的值有 'underlined', 'outlined', 'filled', 'solo', 或 'plain'。
success 和 success-messages props 已被删除。
validate-on-blur prop 已经重命名为 validate-on="blur"。

v-alert

border属性值left和right已被重命名为start和end。
colored-border 属性已更名为 border-color。
dismissable 属性已更名为 closable。
outlined 和 text 属性已合并为 variant 属性。
- 允许的值有 'elevated', 'flat', 'tonal', 'outlined', 'text', 和 'plain'。
text 属性有新的用途。它用于代表警告的文字内容，如果保持默认则其不起作用。

v-badge

overlap 重叠已经被移除，现在是默认样式，使用floating来恢复 v2 的默认样式。
翻译 props 的 mode 和 origin 已被移除。
avatar prop 不再需要，并已被移除。

actions slot 不再提供解散函数。
shaped prop 已被移除。
icon-color 已被移除。
Single-line已被lines="one"取代。
color 现在适用于图标和动作文本。使用bg-color更改背景颜色。

v-btn/v-btn-toggle

active-class prop 已重命名为 selected-class
不再支持fab。如果你只需要一个圆形按钮，使用icon prop 或应用一个.rounded-circleclass。
flat / outlined / text / plain props 已合并为一个 variant prop.
depressed 已更名为 variant="flat"
retain-focus-on-click 已被移除，使用 :focus-visible 代替。
v-btn-toggle 需要 mandatory="force" prop 来实现与 V2 中的 mandatory prop 相同的行为。
禁用的按钮会使用指定 color 的褪色变体而不是灰色 (#15147)
- 将 sass 变量 $button-colored-disabled 设置为 false 以使用灰色。

v-checkbox/v-radio/v-switch

input-value prop 已重命名为 model-value。 (v3 需要这个更改)
on-icon 和 off-icon props 已更名为 true-icon 和 false-icon.
on-value 和 off-value props 已更名为 true-value 和 false-value.
v-checkbox的 slot 标签不应该再包含一个 <label> ，因为它已经包装了一个了。

v-date-picker

使用 Date 使用 Date 对象而不是字符串。包括一些实用程序函数来帮助在两者之间进行转换，请参阅 dates.
locale, locale-first-day-of-year, first-day-of-week, day-format, weekday-format, month-format, year-format, header-date-format, 和 title-date-format 现在是日期适配器的一部分，并使用全局配置的 locale 而不是被当作 props 传递。
active-picker 已重命名为 view-mode.
picker-date 已被单独取代 month 和 year props.
range 目前尚未实现，将来将作为单独的组件添加。

v-form

validate() 现在返回一个 Promise<FormValidationResult> 而不是 boolean。等待承诺，然后检查result.valid 以确定表单状态有效。

v-list

two-line 和 three-line props 已经合并成一个的 lines prop 允许值为“2”或“3”。
v-list-item-group 已被删除，只需为列表项添加value以使其可选，并在 v-list 上绑定v-model:selected以获得所选值。
v-list-item-icon 和 v-list-item-avatar 被去除, 使用 v-list-item 和 icon 或 avatar props, 或在附加或前置插槽中的角色。
v-list-item-content 已被删除，列表现在使用 CSS 网格进行布局。
v-list-group 现在可以任意深度嵌套， sub-group prop 应当去除。
v-list-item input-value prop 已经被替换为 active.
v-list-item inactive prop 已经被替换为 :active="false" :link="false".
v-subheader 已重命名为 v-list-subheader.
v-list-item的 active scoped slot prop 已重命名为 isActive

stateless prop 已被删除，手动控制状态使用 model-value 或 v-model 代替。

v-rating

color 已重命名为 active-color.
background-color 已重命名为 color.

v-select/v-combobox/v-autocomplete

不存在于items中的 V-model 值现在将被渲染而不是被忽略。
cache-items prop 已经删除，缓存应该在外部处理。
item-text 已重命名为 item-title, 默认情况下查找 item 对象上的title属性。value 没有变化。
item-disabled 已被删除, 并且关于项目对象的 disabled, header, divider, 和 avatar 属性被忽略。
- 传递给v-list-item的其他道具可以使用item-props prop 来指定。 item-props 可以是一个函数，它接受 item 对象并返回一个 props 对象，或者设置为 booleantrue以将 item 对象直接作为 props 传播。
插槽中的item项目对象现在是一个ListItem 对象，原始的项目对象可以通过item.raw获得。
item插槽将不再自动生成一个v-list-item组件, 取而代之的是一个props对象，它提供了所需的事件侦听器和 props:

html

<template #item="{ props }">
  <v-list-item v-bind="props"></v-list-item>
</template>

如果设置了chipsprop，应该使用chip slot 而不是 selection , 这将自动为芯片提供一些默认值。
Non-multiple 非多重组合框现在将更新它的模型，因为你输入(像一个文本字段)，而不是只在模糊。

v-simple-table

v-simple-table 已重命名为 v-table

v-stepper (vertical)

v-stepper-step 已重命名为 v-stepper-vertical-item. 将内容移动到 title slot.
v-stepper-content 已被移除。将内容移动到v-stepper-vertical-item的默认槽位。

v-data-table

头对象:
- text property 已重命名为 title.
- data-table-select 和 data-table-expand 必须定义为 key 而不是 value.
- class 已经被替换为 headerProps.
- cellClass 已经被替换为 cellProps 并且现在可以接受一个函数或一个对象。
- filter 功能需要使用 search 才能被触发。
表需要使用 search prop 才能触发过滤， items 项数组可以预先过滤和计算。
使用Server -items-length的服务器端表必须替换为 <v-data-table-server items-length />。
@click:* 时间的参数顺序现在一致为 (event, data).
- onRowClick (item, data, event) 应该改为 onRowClick (event, { item }).
item-class 和 item-style 都被合并成 row-props, 并且新添加了 cell-props 。
sort-desc and group-desc 都被合并成 sort-by 和 group-by. 这些属性现在接受 { key: string, order: 'asc' | 'desc' } 对象数组而不是字符串。
current-items event 已重命名为 update:current-items.
现在可以使用 headers 对象中的sort key 或使用custom-key-sort prop 来完成自定义排序。

v-slider/v-range-slider

ticks 已重命名为 show-ticks.
tick-labels 已重命名为 ticks.
vertical 已重命名为 direction="vertical".
step 步骤的默认值现在是 0 而不是 1。

v-tabs

v-tab-item 已被移除，请使用 v-window-item替代。

v-img

contain 已被移除，现在是默认行为。用cover填满整个容器。

rounded prop 已被移除。对菜单内容元素应用一个圆角 css 类代替效果。例如 .rounded-te
internal-activator prop 已被移除，请使用 ref 唯一选择器代替。
absolute, offset-y 和 offset-x props 已被移除.手动定位现在通过向target prop 传递一个[x, y]数组来完成。
nudge-* props 已被移除。没有直接替代，但可以使用offset来达到类似的结果。

v-snackbar

action 插槽已重命名为 actions

v-expansion-panel

v-expansion-panel-header 已重命名为 v-expansion-panel-title.
v-expansion-panel-content 已重命名为 v-expansion-panel-text.
v-expansion-panel 现在提供 text 和title props 以替代 subcomponents。

v-card

v-card 现在不允许内容溢出元素或是使用更大的 z-index 值来使元素显示在它的外面。要禁止这个行为，可以使用 <v-card style="overflow: initial; z-index: initial"> (#17593, #17628)

v-sparkline

value 现在是model-value

Directives

v-intersect

处理程序参数顺序已从 entries, observer, isIntersecting 改为 isIntersecting, entries, observer

升级指南

起步

Features （特性）

Layout （布局）

Theme （主题）

SASS variables （变量）

样式和实用类

Components （组件）

常规更改

Input 组件

v-alert

v-badge

v-banner

v-btn/v-btn-toggle

v-checkbox/v-radio/v-switch

v-date-picker

v-form

v-list

v-navigation-drawer

v-rating

v-select/v-combobox/v-autocomplete

v-simple-table

v-stepper (vertical)

v-data-table

v-slider/v-range-slider

v-tabs

v-img

v-menu

v-snackbar

v-expansion-panel

v-card

v-sparkline

Directives

v-intersect

升级指南 ​

起步 ​

Features （特性） ​

Layout （布局） ​

Theme （主题） ​

SASS variables （变量） ​

样式和实用类 ​

Components （组件） ​

常规更改 ​

Input 组件 ​

v-alert ​

v-badge ​

v-banner ​

v-btn/v-btn-toggle ​

v-checkbox/v-radio/v-switch ​

v-date-picker ​

v-form ​

v-list ​

v-navigation-drawer ​

v-rating ​

v-select/v-combobox/v-autocomplete ​

v-simple-table ​

v-stepper (vertical) ​

v-data-table ​

v-slider/v-range-slider ​

v-tabs ​

v-img ​

v-menu ​

v-snackbar ​

v-expansion-panel ​

v-card ​

v-sparkline ​

Directives ​

v-intersect ​

升级指南

起步

Features （特性）

Layout （布局）

Theme （主题）

SASS variables （变量）

样式和实用类

Components （组件）

常规更改

Input 组件

v-alert

v-badge

v-banner

v-btn/v-btn-toggle

v-checkbox/v-radio/v-switch

v-date-picker

v-form

v-list

v-navigation-drawer

v-rating

v-select/v-combobox/v-autocomplete

v-simple-table

v-stepper (vertical)

v-data-table

v-slider/v-range-slider

v-tabs

v-img

v-menu

v-snackbar

v-expansion-panel

v-card

v-sparkline

Directives

v-intersect