vuetify-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vuetifyjs/vuetify

vuetify

vuetifyjs/vuetify

vuetify

Version: 4.0.0-beta.2 (Feb 2026) Tags: v1-stable: 1.5.24 (Mar 2020), v2-stable: 2.7.2 (Feb 2024), dev: 3.11.0 (Nov 2025), latest: 3.11.8 (Jan 2026), next: 4.0.0-beta.2 (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

版本： 4.0.0-beta.2（2026年2月） 标签： v1-stable: 1.5.24（2020年3月）, v2-stable: 2.7.2（2024年2月）, dev: 3.11.0（2025年11月）, latest: 3.11.8（2026年1月）, next: 4.0.0-beta.2（2026年2月）

参考链接： 文档 — API参考、指南 • GitHub Issues — 问题、解决方案、边缘案例 • GitHub 讨论 — 问答、模式、实践方案 • 版本发布 — 更新日志、重大变更、新API

API Changes

API 变更

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

BREAKING:
```
VRow
```
/
```
VCol
```
Grid — complete overhaul using CSS
```
gap
```
instead of negative margins.
```
dense
```
prop removed (use
```
density="compact"
```
),
```
align
```
/
```
justify
```
on
```
VRow
```
and
```
order
```
/
```
align-self
```
on
```
VCol
```
removed in favor of utility classes source
BREAKING: MD3 Typography — variant names renamed for Material Design 3 compliance:
```
h1
```
-
```
h3
```
->
```
display-*
```
,
```
h4
```
-
```
h6
```
->
```
headline-*
```
,
```
subtitle-1
```
/
```
body-1
```
->
```
body-large
```
,
```
button
```
/
```
subtitle-2
```
->
```
label-large
```
source
BREAKING: MD3 Elevation — elevation levels reduced from 25 (0-24) to 6 (0-5) to align with MD3 density-independent pixel levels source

BREAKING:

VBtn

Defaults —

text-transform: uppercase

removed by default.

$button-stacked-icon-margin

Sass variable replaced by

$button-stacked-gap

source

BREAKING:
```
VSelect
```
/
```
VAutocomplete
```
/
```
VCombobox
```
—
```
item
```
slot prop renamed to
```
internalItem
```
. The
```
item
```
prop is now an alias for
```
internalItem.raw
```
source
BREAKING:
```
VForm
```
Slot —
```
isValid
```
,
```
errors
```
, and
```
isDisabled
```
slot variables are now unwrapped values instead of
```
Ref
```
objects source
NEW:
```
VSnackbarQueue
```
— rewritten in v4 to support showing multiple snackbars simultaneously;
```
default
```
slot renamed to
```
item
```
source
NEW:
```
VRow
```
```
gap
```
prop — provides fine-grained control over grid spacing, accepting numbers, strings, or
```
[x, y]
```
arrays source
NEW:
```
VAvatarGroup
```
(experimental) — new labs component for grouping multiple avatars with overlapping support source
NEW:
```
VCommandPalette
```
(experimental) — new labs component providing a search and action interface for application commands source

Also changed:

VCalendar

promoted from labs ·

VHotkey

promoted from labs ·

VToolbar

location

prop new ·

VAvatar

badge

prop new ·

VProgressCircular

reveal

prop new ·

VTreeview

indent-lines

props new ·

vuetify/styles/core

new entry point ·

system

default theme ·

VSnackbar

multi-line

removed ·

VContainer

fill-height

behavior changed

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

重大变更：
```
VRow
```
/
```
VCol
```
网格系统 — 完全重构，使用CSS
```
gap
```
替代负边距。移除
```
dense
```
属性（改用
```
density="compact"
```
），移除
```
VRow
```
上的
```
align
```
/
```
justify
```
属性以及
```
VCol
```
上的
```
order
```
/
```
align-self
```
属性，改用工具类来源
重大变更：MD3 排版 — 为了符合Material Design 3规范，变体名称已重命名：
```
h1
```
-
```
h3
```
->
```
display-*
```
，
```
h4
```
-
```
h6
```
->
```
headline-*
```
，
```
subtitle-1
```
/
```
body-1
```
->
```
body-large
```
，
```
button
```
/
```
subtitle-2
```
->
```
label-large
```
来源
重大变更：MD3 阴影层级 — 阴影层级从25级（0-24）减少到6级（0-5），以匹配MD3的密度无关像素层级来源

重大变更：

VBtn

默认值 — 默认移除

text-transform: uppercase

。Sass变量

$button-stacked-icon-margin

替换为

$button-stacked-gap

来源

重大变更：
```
VSelect
```
/
```
VAutocomplete
```
/
```
VCombobox
```
—
```
item
```
插槽属性重命名为
```
internalItem
```
。现在
```
item
```
属性是
```
internalItem.raw
```
的别名来源
重大变更：
```
VForm
```
插槽 —
```
isValid
```
、
```
errors
```
和
```
isDisabled
```
插槽变量现在是解包后的值，而非
```
Ref
```
对象来源
新增：
```
VSnackbarQueue
```
— 在v4版本中重写，支持同时显示多个通知栏；
```
default
```
插槽重命名为
```
item
```
来源
新增：
```
VRow
```
```
gap
```
属性 — 提供对网格间距的精细控制，支持数字、字符串或
```
[x, y]
```
数组来源
新增：
```
VAvatarGroup
```
（实验性） — 新的实验室组件，用于将多个头像分组并支持重叠显示来源
新增：
```
VCommandPalette
```
（实验性） — 新的实验室组件，为应用命令提供搜索和操作界面来源

其他变更：

VCalendar

从实验室组件转正 ·

VHotkey

从实验室组件转正 ·

VToolbar

新增

location

属性 ·

VAvatar

新增

badge

属性 ·

VProgressCircular

新增

reveal

属性 ·

VTreeview

新增

indent-lines

属性 ·

vuetify/styles/core

新增入口 · 默认主题改为

system

· 移除

VSnackbar

的

multi-line

VContainer

的

fill-height

行为变更

Best Practices

最佳实践

Use the
```
cmd
```
modifier in the
```
useHotkey
```
composable for cross-platform compatibility — automatically resolves to Command on Mac and Control on PC source

// Preferred: works on both Mac and PC
useHotkey('cmd+s', (e) => saveDocument(e))

// Avoid: hardcoding 'ctrl' may cause conflicts or feel non-idiomatic on Mac
useHotkey('ctrl+s', (e) => saveDocument(e))

Apply
```
class
```
and
```
style
```
to specific component keys in the
```
defaults
```
configuration — these are not supported in the
```
global
```
defaults key source

// Preferred
createVuetify({
  defaults: {
    VBtn: {
      class: 'text-none',
      style: { textTransform: 'none' }
    }
  }
})

// Avoid: class and style are ignored in global
createVuetify({
  defaults: {
    global: { class: 'text-none' }
  }
})

Resolve style conflicts between Vuetify and TailwindCSS by redefining CSS layer order — place Vuetify's styles in a dedicated layer with lower precedence than Tailwind's base layer source

css

/* main.css */
@layer theme, base, vuetify, components, utilities;
@import 'vuetify/styles' layer(vuetify);
@import 'tailwindcss';

Use
```
v-text-field
```
with
```
decimal.js
```
for high-precision decimal arithmetic —
```
VNumberInput
```
uses
```
toFixed()
```
internally and may suffer from standard JavaScript floating-point inaccuracies source
Centralize snackbar messages using global state (e.g., Pinia) with
```
v-snackbar-queue
```
— allows triggering notifications from any part of the application by pushing to a shared array source

vue


<template>
  <v-app>
    <v-snackbar-queue v-model="messages.queue" />
  </v-app>
</template>

Use the
```
order
```
prop to explicitly control layout component priority — overrides the default behavior where priority is determined solely by markup order source

vue


<v-navigation-drawer />
<v-app-bar :order="-1" />

Utilize
```
useDate()
```
's
```
parseISO
```
and
```
toISO
```
methods for standardizing date strings —
```
VDateInput
```
and other date components internally expect and return native JS
```
Date
```
objects source
Use
```
v-command-palette
```
(experimental) for keyboard-driven power-user workflows — provides a pre-configured, accessible, and searchable dialog interface that implements ARIA best practices automatically source
Restore previous negative-margin/padding grid behavior during Vuetify 4 migration using the
```
@layer vuetify-overrides
```
block — necessary when existing layouts rely on the legacy system instead of the new CSS
```
gap
```
property source

scss

@layer vuetify-overrides {
  .v-row {
    gap: unset;
    margin: calc(var(--v-col-gap-y) * -.5) calc(var(--v-col-gap-x) * -.5);
  }
}

在
```
useHotkey
```
组合式函数中使用
```
cmd
```
修饰符以实现跨平台兼容性 — 会自动在Mac上解析为Command键，在PC上解析为Control键来源

// 推荐：在Mac和PC上均可正常工作
useHotkey('cmd+s', (e) => saveDocument(e))

// 避免：硬编码'ctrl'可能在Mac上引发冲突或不符合使用习惯
useHotkey('ctrl+s', (e) => saveDocument(e))

在
```
defaults
```
配置中，将
```
class
```
和
```
style
```
应用于特定组件的键 — 这些在
```
global
```
默认键中不受支持来源

// 推荐
createVuetify({
  defaults: {
    VBtn: {
      class: 'text-none',
      style: { textTransform: 'none' }
    }
  }
})

// 避免：global中的class和style会被忽略
createVuetify({
  defaults: {
    global: { class: 'text-none' }
  }
})

通过重新定义CSS层顺序解决Vuetify与TailwindCSS之间的样式冲突 — 将Vuetify的样式放在专用层中，优先级低于Tailwind的基础层来源

css

/* main.css */
@layer theme, base, vuetify, components, utilities;
@import 'vuetify/styles' layer(vuetify);
@import 'tailwindcss';

结合
```
v-text-field
```
与
```
decimal.js
```
进行高精度小数运算 —
```
VNumberInput
```
内部使用
```
toFixed()
```
，可能会受到JavaScript标准浮点数精度问题的影响来源
使用全局状态（如Pinia）结合
```
v-snackbar-queue
```
集中管理通知消息 — 允许通过向共享数组推送消息，从应用的任何部分触发通知来源

vue


<template>
  <v-app>
    <v-snackbar-queue v-model="messages.queue" />
  </v-app>
</template>

使用
```
order
```
属性显式控制布局组件的优先级 — 覆盖默认仅由标记顺序决定优先级的行为来源

vue


<v-navigation-drawer />
<v-app-bar :order="-1" />

利用
```
useDate()
```
的
```
parseISO
```
和
```
toISO
```
方法标准化日期字符串 —
```
VDateInput
```
和其他日期组件内部期望并返回原生JS
```
Date
```
对象来源
使用
```
v-command-palette
```
（实验性）实现键盘驱动的高级用户工作流 — 提供预配置、可访问且支持搜索的对话框界面，自动遵循ARIA最佳实践来源
在Vuetify 4迁移期间，使用
```
@layer vuetify-overrides
```
块恢复之前的负边距/内边距网格行为 — 当现有布局依赖旧系统而非新的CSS
```
gap
```
属性时，这一步是必要的来源

scss

@layer vuetify-overrides {
  .v-row {
    gap: unset;
    margin: calc(var(--v-col-gap-y) * -.5) calc(var(--v-col-gap-x) * -.5);
  }
}

vuetify-skilld

Original

Translation

vuetifyjs/vuetify
`vuetify`

vuetifyjs/vuetify
`vuetify`

API Changes

API 变更

Best Practices

最佳实践