vuetify-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vuetify@4.0.1

Material Design component framework for Vue 3. Source citations like

lib/framework.js:15

refer to the prepared

vuetify@4.0.1

package (

package.json:4

基于 Vue 3 的 Material Design 组件框架。类似

lib/framework.js:15

的源码引用指向已准备好的

vuetify@4.0.1

包（

package.json:4

）。

Environment limits

环境限制

Vue
```
^3.5.0
```
peer dependency (
```
package.json:208
```
). No Vue 2 support; Vuetify 2 is EOL (
```
README.md:274
```
).
ESM only:
```
"type": "module"
```
(
```
package.json:32
```
).

Optional peers:

vite-plugin-vuetify >=2.1.0

webpack-plugin-vuetify >=3.1.0

typescript >=4.7

(

package.json:205

Modern browsers, Safari 13+ with polyfills, minimum design width 320px (
```
README.md:159
```
).
Default font is Roboto; you must add it yourself, e.g.
```
@fontsource/roboto
```
(https://vuetifyjs.com/getting-started/installation/).

Vue
```
^3.5.0
```
peer dependency（
```
package.json:208
```
）。不支持 Vue 2；Vuetify 2 已进入 EOL（
```
README.md:274
```
）。
仅支持 ESM：
```
"type": "module"
```
（
```
package.json:32
```
）。

可选 peer dependencies：

vite-plugin-vuetify >=2.1.0

、

webpack-plugin-vuetify >=3.1.0

、

typescript >=4.7

（

package.json:205

）。

支持现代浏览器；Safari 13+ 需使用 polyfill；最小设计宽度为 320px（
```
README.md:159
```
）。
默认字体为 Roboto；需要自行添加，例如
```
@fontsource/roboto
```
（https://vuetifyjs.com/getting-started/installation/）。

Setup

设置

Vite with automatic treeshaking (preferred). The vuetify plugin must come after the vue plugin:

// vite.config.js
import vue from '@vitejs/plugin-vue'
import vuetify from 'vite-plugin-vuetify'
export default defineConfig({ plugins: [vue(), vuetify()] })

// src/plugins/vuetify.js
import 'vuetify/styles'
import { createVuetify } from 'vuetify'
export default createVuetify({
  // components, directives not needed with the loader plugin
})

Without a loader plugin, register manually; wildcard imports include everything and slow development builds:

import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'
createVuetify({ components, directives })

createVuetify

accepts

aliases

blueprint

components

date

defaults

directives

display

goTo

icons

locale

ssr

theme

and returns

{ install, unmount, defaults, display, theme, icons, locale, date, goTo }

(

lib/framework.js:15

). Install with

app.use(vuetify)

; wrap the app in a single

<v-app>

root.

For SSR frameworks (Nuxt, vite-ssr) set

ssr: true

so display values render correctly (https://vuetifyjs.com/getting-started/installation/).

Scaffolding:

pnpm create vuetify

npm create vuetify@latest

(

README.md:44

CDN bundle with everything included:

vuetify/dist/vuetify.js

(

package.json:35

使用 Vite 并自动进行 treeshaking（推荐）。vuetify 插件必须位于 vue 插件之后：

// vite.config.js
import vue from '@vitejs/plugin-vue'
import vuetify from 'vite-plugin-vuetify'
export default defineConfig({ plugins: [vue(), vuetify()] })

// src/plugins/vuetify.js
import 'vuetify/styles'
import { createVuetify } from 'vuetify'
export default createVuetify({
  // components, directives not needed with the loader plugin
})

不使用 loader plugin 时，需要手动注册；通配符导入会包含所有内容，并降低开发构建速度：

import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'
createVuetify({ components, directives })

createVuetify

接受

aliases

、

blueprint

、

components

、

date

、

defaults

、

directives

、

display

、

goTo

、

icons

、

locale

、

ssr

、

theme

，并返回

{ install, unmount, defaults, display, theme, icons, locale, date, goTo }

（

lib/framework.js:15

）。通过

app.use(vuetify)

安装；将应用包裹在一个

<v-app>

根元素中。

对于 SSR 框架（Nuxt、vite-ssr），设置

ssr: true

，以确保 display 值能够正确渲染（https://vuetifyjs.com/getting-started/installation/）。

项目脚手架：

pnpm create vuetify

npm create vuetify@latest

（

README.md:44

）。

包含全部内容的 CDN bundle：

vuetify/dist/vuetify.js

（

package.json:35

）。

Components

组件

Prefer imports from
```
vuetify/components/<Group>
```
over
```
vuetify/components
```
(loads only needed styles in dev).
Labs components are NOT production ready; import from
```
vuetify/labs/<Name>
```
or
```
vuetify/labs/components
```
. In 4.0.1 labs holds: VAvatarGroup, VColorInput, VCommandPalette, VDateInput, VFileUpload, VIconBtn, VMaskInput, VPicker, VPie, VStepperVertical, VPullToRefresh, VVideo (
```
lib/labs/components.js:1
```
).
Dynamic
```
<component :is>
```
is invisible to the loader plugin; import those components manually (https://vuetifyjs.com/features/treeshaking/).
Full inventory and export paths: references/exports.md

优先从
```
vuetify/components/<Group>
```
导入，而不是从
```
vuetify/components
```
导入，这样在开发环境中只会加载所需样式。
Labs 组件尚不适用于生产环境；从
```
vuetify/labs/<Name>
```
或
```
vuetify/labs/components
```
导入。4.0.1 中的 labs 包含：VAvatarGroup、VColorInput、VCommandPalette、VDateInput、VFileUpload、VIconBtn、VMaskInput、VPicker、VPie、VStepperVertical、VPullToRefresh、VVideo（
```
lib/labs/components.js:1
```
）。
loader plugin 无法识别动态
```
<component :is>
```
；需要手动导入这些组件（https://vuetifyjs.com/features/treeshaking/）。
完整清单和导出路径：references/exports.md

Configuration

配置

Theme: the v4 default is

system

(follows

prefers-color-scheme

), not

light

(

lib/composables/theme.js:10

). Pin it with

theme: { defaultTheme: 'light' }

if system switching is unwanted.

Defaults: set prop defaults per component with
```
createVuetify({ defaults: { VBtn: { ... } } })
```
.
```
class
```
and
```
style
```
work only on component keys, never in the
```
global
```
key (https://vuetifyjs.com/features/global-configuration/).

Display: v4 breakpoints changed; defaults are

sm 600, md 840, lg 1145, xl 1545, xxl 2138

(

lib/composables/display.js:10

Icons: default set is
```
mdi
```
and expects the
```
@mdi/font
```
stylesheet, or use
```
mdi-svg
```
for bundled SVG icons (https://vuetifyjs.com/features/icon-fonts/).
Dates: default adapter wraps native
```
Date
```
; swap with any date-io adapter (https://vuetifyjs.com/features/dates/).
Blueprints:
```
createVuetify({ blueprint: md3 })
```
applies a design-system preset; explicit options override the blueprint (
```
lib/framework.js:15
```
,
```
lib/blueprints/index.js:1
```
).
Details and examples: references/configuration.md

主题：v4 的默认主题是
```
system
```
（遵循
```
prefers-color-scheme
```
），而不是
```
light
```
（
```
lib/composables/theme.js:10
```
）。如果不需要跟随系统切换，请使用
```
theme: { defaultTheme: 'light' }
```
固定主题。
Defaults：通过
```
createVuetify({ defaults: { VBtn: { ... } } })
```
按组件设置 prop 默认值。
```
class
```
和
```
style
```
仅适用于组件键，绝不能放在
```
global
```
键中（https://vuetifyjs.com/features/global-configuration/）。

Display：v4 的断点发生了变化；默认值为

sm 600, md 840, lg 1145, xl 1545, xxl 2138

（

lib/composables/display.js:10

）。

图标：默认图标集为
```
mdi
```
，需要引入
```
@mdi/font
```
样式表；也可以使用
```
mdi-svg
```
获取内置的 SVG 图标（https://vuetifyjs.com/features/icon-fonts/）。
日期：默认适配器封装原生
```
Date
```
；也可以替换为任意 date-io 适配器（https://vuetifyjs.com/features/dates/）。
Blueprints：
```
createVuetify({ blueprint: md3 })
```
会应用设计系统预设；显式设置的选项优先于 blueprint（
```
lib/framework.js:15
```
、
```
lib/blueprints/index.js:1
```
）。
详细信息和示例：references/configuration.md

Composables

All exported from the

vuetify

entry point (

lib/composables/index.js:1

useDate

useDefaults

useDisplay

useGoTo

useLayout

useLocale

useRtl

useTheme

useHotkey

useMask

vue

<script setup>
import { useTheme } from 'vuetify'
const theme = useTheme()
theme.toggle() // light <-> dark
</script>

For hotkeys prefer the

cmd

modifier (

useHotkey('cmd+s', save)

); it resolves to Command on Mac and Control elsewhere (

lib/composables/hotkey/key-aliases.js:10

Full API per composable: references/composables.md

所有 composables 均从

vuetify

入口点导出（

lib/composables/index.js:1

）：

useDate

、

useDefaults

、

useDisplay

、

useGoTo

、

useLayout

、

useLocale

、

useRtl

、

useTheme

、

useHotkey

、

useMask

。

vue

<script setup>
import { useTheme } from 'vuetify'
const theme = useTheme()
theme.toggle() // light <-> dark
</script>

快捷键应优先使用

cmd

修饰符（

useHotkey('cmd+s', save)

）；在 Mac 上会解析为 Command，在其他平台上会解析为 Control（

lib/composables/hotkey/key-aliases.js:10

）。

每个 composable 的完整 API：references/composables.md

Styles

样式

import 'vuetify/styles'

is the all-in-one precompiled CSS; modular entries are

vuetify/styles/core

(must be first),

vuetify/styles/colors

vuetify/styles/utilities

(

package.json:61

SASS variable overrides require the sass preprocessor and

vuetify({ styles: { configFile: 'src/styles/settings.scss' } })

in the loader plugin; use

@use 'vuetify/settings' with (...)

v4 styles ship in cascade layers (
```
vuetify-core
```
,
```
vuetify-components
```
,
```
vuetify-overrides
```
,
```
vuetify-utilities
```
,
```
vuetify-final
```
); unlayered user CSS now always wins over Vuetify.
Entry points, variables, layers, Tailwind interop, legacy grid restore: references/styling.md

import 'vuetify/styles'

是包含所有内容的预编译 CSS；模块化入口包括

vuetify/styles/core

（必须最先引入）、

vuetify/styles/colors

和

vuetify/styles/utilities

（

package.json:61

）。

覆盖 SASS 变量需要使用 sass 预处理器，并在 loader plugin 中配置

vuetify({ styles: { configFile: 'src/styles/settings.scss' } })

；使用

@use 'vuetify/settings' with (...)

。

v4 样式使用 cascade layers（
```
vuetify-core
```
、
```
vuetify-components
```
、
```
vuetify-overrides
```
、
```
vuetify-utilities
```
、
```
vuetify-final
```
）；未分层的用户 CSS 现在始终优先于 Vuetify。
入口点、变量、图层、Tailwind 互操作和 legacy grid 恢复：references/styling.md

Migrating from v3

从 v3 迁移

v4 is a breaking MD3 release. Highest-impact changes:

Grid uses CSS

gap

;

dense

is now

density="compact"

align

justify

order

align-self

props replaced by utility classes. VRow gains a

gap

prop (

lib/components/VGrid/VRow.js:154

Typography variants renamed:

h1

h3

display-*

h4

h6

headline-*

subtitle-1

body-1

body-large

caption

body-small

button

subtitle-2

label-large

Elevation reduced from levels 0-24 to 0-5 (
```
lib/styles/settings/_elevations.scss:6
```
).

VSelect

VCombobox

VAutocomplete

slot

item

renamed to

internalItem

;

item

is now an alias for

internalItem.raw

```
VForm
```
slot values (
```
isValid
```
,
```
errors
```
, ...) are unwrapped, no longer refs.
Defaults merging skips
```
undefined
```
; use
```
null
```
to override a global default.

Full change list with compat snippets: references/migration-v4.md

v4 是采用 MD3 的破坏性升级。影响最大的变更包括：

Grid 使用 CSS
```
gap
```
；
```
dense
```
现在改为
```
density="compact"
```
，
```
align
```
/
```
justify
```
/
```
order
```
/
```
align-self
```
props 被工具类取代。VRow 新增了
```
gap
```
prop（
```
lib/components/VGrid/VRow.js:154
```
）。

Typography variants 已重命名：

h1

h3

display-*

，

h4

h6

headline-*

，

subtitle-1

body-1

body-large

，

caption

body-small

，

button

subtitle-2

label-large

。

Elevation 从 0-24 级减少为 0-5 级（
```
lib/styles/settings/_elevations.scss:6
```
）。

VSelect

VCombobox

VAutocomplete

的

item

slot 已重命名为

internalItem

；

item

现在是

internalItem.raw

的别名。

```
VForm
```
的 slot 值（
```
isValid
```
、
```
errors
```
等）已解包，不再是 refs。
Defaults 合并时会跳过
```
undefined
```
；如需覆盖全局默认值，请使用
```
null
```
。

包含完整变更列表和兼容代码片段：references/migration-v4.md

Common pitfalls

常见问题

Missing icon font: components render blank icons until
```
@mdi/font
```
CSS (or an SVG set) is installed.
Missing Roboto font: text renders with fallback font (
```
README.md:159
```
).
Styles broken after adding custom CSS: check layer order; place overrides inside
```
@layer vuetify-overrides
```
or declare your layer order explicitly.
```
VNumberInput
```
uses
```
toFixed()
```
internally; for arbitrary-precision decimals use
```
v-text-field
```
with decimal.js (
```
lib/components/VNumberInput/VNumberInput.js:81
```
, https://vuetifyjs.com/components/number-inputs/).
Do not use
```
vuetify/styles
```
inside SASS files; it resolves to precompiled CSS. Use
```
vuetify
```
or
```
vuetify/settings
```
(https://vuetifyjs.com/features/sass-variables/).

缺少图标字体：安装
```
@mdi/font
```
CSS 或 SVG 图标集之前，组件中的图标会显示为空白。
缺少 Roboto 字体：文本会使用回退字体渲染（
```
README.md:159
```
）。
添加自定义 CSS 后样式损坏：检查图层顺序；将覆盖样式放在
```
@layer vuetify-overrides
```
中，或显式声明图层顺序。
```
VNumberInput
```
内部使用
```
toFixed()
```
；如需任意精度的小数，请使用搭配 decimal.js 的
```
v-text-field
```
（
```
lib/components/VNumberInput/VNumberInput.js:81
```
，https://vuetifyjs.com/components/number-inputs/）。
不要在 SASS 文件中使用
```
vuetify/styles
```
；它会解析为预编译 CSS。请使用
```
vuetify
```
或
```
vuetify/settings
```
（https://vuetifyjs.com/features/sass-variables/）。

References

参考

references/exports.md — entry points, component inventory, directives, iconsets, locale
references/configuration.md — every
```
createVuetify
```
option with examples
references/composables.md — public composables API
references/styling.md — CSS and SASS entry points, variables, layers
references/migration-v4.md — v3 to v4 breaking changes and compat snippets

Official documentation: https://vuetifyjs.com. Release notes by URL: https://vuetifyjs.com/getting-started/release-notes/.

references/exports.md——入口点、组件清单、directives、图标集和 locale
references/configuration.md——所有
```
createVuetify
```
选项及示例
references/composables.md——公共 composables API
references/styling.md——CSS 和 SASS 入口点、变量与图层
references/migration-v4.md——v3 到 v4 的破坏性变更和兼容代码片段

官方文档：https://vuetifyjs.com。Release notes（按 URL 访问）：https://vuetifyjs.com/getting-started/release-notes/。