vuetify-skilld

[email protected]

适用于 Vue 3 的 Material Design 组件框架。像 lib/framework.js:15 这样的源代码引用指向已准备好的 [email protected] 软件包（package.json:4）。

环境限制

• Vue ^3.5.0 对等依赖（package.json:208）。不支持 Vue 2；Vuetify 2 已结束生命周期（README.md:274）。
• 仅支持 ESM："type": "module"（package.json:32）。
• 可选对等依赖：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/）。

设置

推荐使用带自动 treeshaking 的 Vite。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 插件时，请手动注册；通配符导入会包含所有内容，并拖慢开发构建：

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 包：vuetify/dist/vuetify.js（package.json:35）。

组件

• 优先从 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）。
• 动态 <component :is> 对 loader 插件不可见；请手动导入这些组件（https://vuetifyjs.com/features/treeshaking/）。
• 完整清单和导出路径：references/exports.md

配置

• 主题：v4 默认值为 system（遵循 prefers-color-scheme），而非 light（lib/composables/theme.js:10）。如果不希望系统自动切换，请将其固定为 theme: { defaultTheme: 'light' }。
• 默认值：使用 createVuetify({ defaults: { VBtn: { ... } } }) 为各组件设置属性默认值。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

组合式函数

均从 vuetify 入口导出（lib/composables/index.js:1）：useDate、useDefaults、useDisplay、useGoTo、useLayout、useLocale、useRtl、useTheme、useHotkey、useMask。

<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）。

各组合式函数的完整 API：references/composables.md

样式

• import 'vuetify/styles' 是一体化预编译 CSS；模块化入口包括 vuetify/styles/core（必须放在首位）、vuetify/styles/colors、vuetify/styles/utilities（package.json:61）。
• 覆盖 SASS 变量需要 SASS 预处理器，并在加载器插件中使用 vuetify({ styles: { configFile: 'src/styles/settings.scss' } })；使用 @use 'vuetify/settings' with (...)。
• v4 样式采用级联层（vuetify-core、vuetify-components、vuetify-overrides、vuetify-utilities、vuetify-final）；未分层的用户 CSS 现在始终优先于 Vuetify。
• 入口、变量、级联层、Tailwind 互操作、旧版网格还原：references/styling.md

从 v3 迁移

v4 是一个包含破坏性更改的 MD3 版本。影响最大的更改：

• 网格使用 CSS gap；dense 现在改为 density="compact"，align/justify/order/align-self 属性替换为工具类。VRow 新增 gap 属性（lib/components/VGrid/VRow.js:154）。
• 排版变体重命名：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 重命名为 internalItem；item 现在是 internalItem.raw 的别名。
• VForm 插槽值（isValid、errors 等）不再是 ref，而是已解包的值。
• 合并默认值时会跳过 undefined；使用 null 覆盖全局默认值。

完整更改列表及兼容性代码片段：references/migration-v4.md

常见问题

• 缺少图标字体：安装 @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/exports.md — 入口、组件清单、指令、图标集、本地化
• references/configuration.md — 所有 createVuetify 选项及示例
• references/composables.md — 公共组合式 API
• references/styling.md — CSS 和 SASS 入口、变量、级联层
• references/migration-v4.md — 从 v3 到 v4 的破坏性更改及兼容性代码片段

官方文档：https://vuetifyjs.com。发布说明网址：https://vuetifyjs.com/getting-started/release-notes/。