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 は EOL です（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 以降ではポリフィルが必要です。デザインの最小幅は 320px です（README.md:159）。
• デフォルトのフォントは Roboto です。@fontsource/roboto などを自分で追加する必要があります（https://vuetifyjs.com/getting-started/installation/）。

セットアップ

自動ツリーシェイキングを利用できる 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
})

ローダープラグインを使わない場合は、手動で登録してください。ワイルドカードインポートはすべての内容を含むため、開発ビルドが遅くなります。

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 を設定してください（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 よりも vuetify/components/<Group> からのインポートを優先してください。
• 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> はローダープラグインから認識されません。これらのコンポーネントは手動でインポートしてください（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/）。
• 表示：v4 ではブレークポイントが変更されました。デフォルト値は sm 600, md 840, lg 1145, xl 1545, xxl 2138 です（lib/composables/display.js:10）。
• アイコン：デフォルトのセットは mdi で、@mdi/font のスタイルシートが必要です。または、バンドルされた SVG アイコンには mdi-svg を使用してください（https://vuetifyjs.com/features/icon-fonts/）。
• 日付：デフォルトのアダプターはネイティブの Date をラップします。任意の date-io アダプターに置き換えられます（https://vuetifyjs.com/features/dates/）。
• ブループリント：createVuetify({ blueprint: md3 }) はデザインシステムのプリセットを適用します。明示的に指定したオプションはブループリントより優先されます（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。
• エレベーションはレベル 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 — 公開 Composables API
• references/styling.md — CSS と SASS のエントリーポイント、変数、レイヤー
• references/migration-v4.md — v3 から v4 への破壊的変更と互換性対応のスニペット

公式ドキュメント：https://vuetifyjs.com。URL ごとのリリースノート：https://vuetifyjs.com/getting-started/release-notes/。