Vuetify 4 网格系统 Legacy 模式用 CSS 覆盖还原旧版负边距布局【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify导读Vuetify 4 对VRow/VCol网格系统进行了重构从「行使用负外边距negative margins、列使用内边距padding撑开间距」的经典 Bootstrap 方案切换为现代 CSSgap属性统一管理列间距。本指南以官方 Grid legacy mode 文档为基础先讲清新旧两代网格的差异与类名变更再逐行剖析官方提供的 CSS 覆盖方案并结合仓库内VGrid组件的 Sass 源码、TypeScript 实现与浏览器级测试说明这套覆盖方案背后的变量体系与尺寸计算原理帮助你在大版本升级后无损还原旧的布局行为。为什么需要 Legacy 模式Vuetify 4 对网格系统的改动不是单纯改类名而是从根本上改变了间距与列宽的实现机制旧版Vuetify 3新版Vuetify 4VRow通过负外边距negative margins抵消列的内边距使用 CSSgap属性列之间依靠 padding 撑开间距列无 padding由 gap 处理间距简单的百分比宽度如flex: 0 0 75%考虑 gap 后的计算宽度flex-basis通过 calc 计算新旧实现带来的直接后果是同样一行cols9的列在两种模式下的实际渲染宽度并不相同。新模式下列宽公式需要把间隙计算进去因此如果你有大量基于旧版行为做像素级对齐的页面例如与绝对定位元素、图片裁切或第三方样式混排升级后可能出现细微的错位这时就需要恢复 Legacy 行为。除了机制差异内部类名也发生了变化旧类名新类名.v-row--dense.v-row--density-compact.v-col-{n}.v-col--cols-{n}.v-col-{breakpoint}-{n}.v-col--cols-{breakpoint}-{n}.offset-{n}.v-col--offset-{n}注意这些新类名并非「随手改的命名」而是组件源码中由 props 实时生成的。在 VCol.ts 的parseBreakpoint中cols、sm/md/lg/xl等断点 props 会被转换为v-col--cols-{bp}-{n}offset/offsetSm等会被转换为v-col--offset-{bp}-{n}若在 VCol.spec.ts 中可以看到对应的断言例如VCol cols6 sm5 /渲染为v-col v-col--cols-sm-5 v-col--cols-6。新网格系统的实现原理源码级拆解在动手写覆盖样式之前先理解新版网格是怎么工作的这样你才能判断覆盖方案是否适合自己。1. gap 与 CSS 变量体系新版网格的核心在 VGrid.sass.v-row --v-row-columns: #{settings.$grid-columns} display: flex flex-wrap: wrap flex: 1 1 auto gap: var(--v-col-gap-y) var(--v-col-gap-x) .v-row margin-top: var(--v-col-gap-y)行内间距不再由 margin/padding 控制而是通过一组 CSS 自定义属性custom properties贯穿整棵网格树--v-col-gap-x/--v-col-gap-y横向 / 纵向列间距由密度density修饰符决定--v-col-gap-x: #{$grid-gutter $modifier * 2}--v-row-columns行内总列数默认取$grid-columns即 12--v-col-size/--v-col-size-columns列当前占用的列数与总列数用于计算flex-basis--v-col-offset/--v-col-offset-columns列偏移量与总列数用于计算margin-inline-start。默认间距与密度配置在 _variables.scss$grid-gutter: $spacer * 6 !default; $grid-density: (default: 0, comfortable: -1, compact: -2) !default; $grid-columns: 12 !default;也就是说默认 gutter 基于$spacer基准放大 6 倍仓库浏览器测试 VCol.spec.browser.tsx 中以const defaultGap 24作为默认值densitycomfortable与densitycompact会逐级缩小间距。另外 VGrid.sass 中的.v-row--no-gutters会把两个 gap 变量直接置 0。2. VRow把 props 变成 CSS 变量VRow.ts 渲染时会把用户传入的gap、size写入行内样式style: [ { --v-col-gap-x: horizontalGap.value, --v-col-gap-y: verticalGap.value, --v-row-columns: props.size, }, props.style, ],其中gapprop 支持数字、字符串或数组[横向, 纵向]三种形式见 VRow.ts这解释了为什么你的自定义覆盖样式要基于--v-col-gap-x/y变量而不是写死数值——它能自动兼容应用层自定义的 gap。同时注意 VRow.ts 中的弃用逻辑if (props.dense) { deprecate(dense, densitycompact) }denseprop 在 Vuetify 4 中已被标记为弃用直接映射到densitycompact即旧类名.v-row--dense→ 新类名.v-row--density-compact。3. VColflex-basis 的「含 gap」宽度计算新版列的尺寸公式VGrid.sassflex-basis: var(--v-col-is-size, calc(($size * (100% $gap)) / $cols - $gap)) var(--v-col-is-auto, auto) var(--v-col-is-grow, 0)即flex-basis (列数 * (100% gap)) / 总列数 - gap这是旧版flex: 0 0 75%的「含 gap」升级版目的是让 N 列并排时加上 N-1 个 gap 恰好铺满整行。偏移量同理margin-inline-start: calc($offset * (100% $gap) / $offsetCols)。仓库的浏览器测试 VCol.spec.browser.tsx 用几何公式验证了这套计算function expectedSize (cols: number, rowSize: number) { return cols * (rowSize - 11 * defaultGap) / 12 (cols - 1) * defaultGap } function expectedShift (offset: number, rowSize: number) { return offset * (rowSize - 11 * defaultGap) / 12 offset * defaultGap }测试断言cols4的列宽等于expectedSize(4, 1000)、偏移列左边缘等于expectedShift(...)这从测试层面证实了「新版列宽已把 gap 计入」这一关键行为差异。CSS 覆盖恢复 Legacy 网格行为官方文档给出的解决方案是不修改组件代码也不逐个改写模板而是在你的应用中追加一段 CSS把间距机制从gap换回负边距 padding同时把列宽公式换回简单的百分比。在应用入口如全局样式文件中加入以下覆盖layer vuetify-overrides { .v-row { gap: unset; margin: calc(var(--v-col-gap-y) * -.5) calc(var(--v-col-gap-x) * -.5); } .v-row .v-row { margin-top: calc(var(--v-col-gap-y) * .5); } .v-col { padding: calc(var(--v-col-gap-y) * .5) calc(var(--v-col-gap-x) * .5); flex-basis: var(--v-col-is-size, calc(100% * var(--v-col-size) / var(--v-col-size-columns))) var(--v-col-is-auto, auto) var(--v-col-is-grow, 0); } .v-col:where([class*v-col--offset-]) { margin-inline-start: calc(100% * var(--v-col-offset) / var(--v-col-size-columns)) } }逐段解释这条覆盖做了什么.v-row部分gap: unset关闭新版间距行负外边距取 gap 变量的一半calc(var(--v-col-gap-y) * -.5)用于抵消列的外扩 padding恢复「行与容器边缘对齐」的经典行为。.v-row .v-row部分连续行之间的纵向间距恢复为半个 gap替代新版 .v-row { margin-top: var(--v-col-gap-y) }的整 gap 行为见 VGrid.sass。.v-col部分列重新获得左右/上下各半个 gap 的 paddingflex-basis退回简单百分比100% * var(--v-col-size) / var(--v-col-size-columns)等价于旧版flex: 0 0 75%这类写法同时通过var(--v-col-is-auto, auto)与var(--v-col-is-grow, 0)保留新版auto与 grow 列的行为开关。.v-col--offset-*部分偏移量改回纯百分比100% * var(--v-col-offset) / var(--v-col-size-columns)对应旧版.offset-{n}的偏移语义。为什么是layer vuetify-overrides覆盖样式必须包在layer vuetify-overrides中这不是随意取的层名。Vuetify 4 的样式系统基于 CSSlayer组织优先级层序声明位于 _layers.scsslayer vuetify-core { layer reset, base; } layer vuetify-components; // Contextual styles for nested components layer vuetify-overrides; layer vuetify-utilities { ... } layer vuetify-final { layer transitions, trumps; }vuetify-overrides是官方预留的「上下文覆盖」层排在vuetify-components之后、vuetify-utilities之前。组件样式通过 _layer.scss 中的layermixin 统一写入layer vuetify-componentsmixin layer ($name) { if ($name transitions or $name trumps) { $name: final. $name; } at-root (without: layer) { layer vuetify-#{$name} { content; } } }由于 CSS 层规则是「后声明的层优先级更高」把覆盖规则放进vuetify-overrides层即可稳定压过组件层样式而无需依赖!important。如果你的项目构建环境不支持layer如较老的后处理工具链可以把layer vuetify-overrides { ... }的外壳去掉直接用选择器书写并确保引入顺序靠后但更推荐保持原样以适配 Vuetify 4 的样式架构。覆盖方案的边界与注意事项官方覆盖方案是「行为级」还原但它并不能 100% 复刻旧版所有细节使用前请确认以下几点自定义 gap 仍生效覆盖规则完全基于--v-col-gap-x/y变量换算 margin/padding因此VRow的gapprop、no-guttersgap 变量置 0以及density密度系统都能继续工作无需额外处理。size自定义列数仍生效flex-basis与偏移公式中的var(--v-col-size-columns)会回退到--v-row-columns由VRow的sizeprop 写入所以自定义 12 之外的分栏数如size10同样被覆盖方案支持。自动宽度 / 等分列行为保留flex-basis中保留的--v-col-is-auto与--v-col-is-grow开关使colsauto和无cols的 grow 列在新旧模式下都维持原语义grow 分支的行为可在 VCol.spec.browser.tsx 的grow测试组中看到验证。嵌套与响应式断点类v-col--cols-sm-*、v-col--offset-md-*等由组件源码生成覆盖方案不依赖具体断点数值因此响应式布局完整保留。间隙观感差异Legacy 模式下列间距来自 padding视觉上「间隙」其实是列背景之外的空间若你的列带有背景色或边框两种模式的视觉呈现会有细微差异建议在关键页面上逐屏回归。升级到 Vuetify 4 的网格迁移清单结合本指南从 Vuetify 3 升级时建议按以下顺序处理网格相关代码先替换已弃用的 APIVRow dense→VRow densitycompact源码会在运行时输出 deprecation 提示见 VRow.ts若你的样式文件里直接使用了旧类名.v-row--dense、.v-col-*、.offset-*对照上文的类名映射表更新。评估是否启用 Legacy 覆盖若项目存在大量依赖旧宽度公式的像素级布局直接在全局样式引入上文「CSS 覆盖」一节的代码否则保持新版gap行为以获得更简洁的 DOM 与更好的响应式表现。逐页回归重点检查多行堆叠行间距、带背景色/边框的列、以及结合offset的对齐场景必要时微调--v-col-gap-x/y变量而非改回硬编码数值。延伸阅读VGrid.sass新版网格的完整 Sass 实现gap 变量体系与列宽公式均在此定义VRow.tsgap、size、density、noGutters等 props 到 CSS 变量的映射VCol.ts断点 / 偏移类名与--v-col-size-base、--v-col-offset-base变量的生成逻辑VCol.spec.browser.tsx浏览器级测试验证含 gap 的列宽与偏移计算_variables.scss$grid-gutter、$grid-density、$grid-columns等网格设计令牌_layers.scssvuetify-overrides层的声明与整体层序升级指南从 Vuetify 3 迁移到 Vuetify 4 的完整升级说明。【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vuetify 4 网格系统 Legacy 模式用 CSS 覆盖还原旧版负边距布局【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify导读Vuetify 4 对VRow/VCol网格系统进行了重构从「行使用负外边距negative margins、列使用内边距padding撑开间距」的经典 Bootstrap 方案切换为现代 CSSgap属性统一管理列间距。本指南以官方 Grid legacy mode 文档为基础先讲清新旧两代网格的差异与类名变更再逐行剖析官方提供的 CSS 覆盖方案并结合仓库内VGrid组件的 Sass 源码、TypeScript 实现与浏览器级测试说明这套覆盖方案背后的变量体系与尺寸计算原理帮助你在大版本升级后无损还原旧的布局行为。为什么需要 Legacy 模式Vuetify 4 对网格系统的改动不是单纯改类名而是从根本上改变了间距与列宽的实现机制旧版Vuetify 3新版Vuetify 4VRow通过负外边距negative margins抵消列的内边距使用 CSSgap属性列之间依靠 padding 撑开间距列无 padding由 gap 处理间距简单的百分比宽度如flex: 0 0 75%考虑 gap 后的计算宽度flex-basis通过 calc 计算新旧实现带来的直接后果是同样一行cols9的列在两种模式下的实际渲染宽度并不相同。新模式下列宽公式需要把间隙计算进去因此如果你有大量基于旧版行为做像素级对齐的页面例如与绝对定位元素、图片裁切或第三方样式混排升级后可能出现细微的错位这时就需要恢复 Legacy 行为。除了机制差异内部类名也发生了变化旧类名新类名.v-row--dense.v-row--density-compact.v-col-{n}.v-col--cols-{n}.v-col-{breakpoint}-{n}.v-col--cols-{breakpoint}-{n}.offset-{n}.v-col--offset-{n}注意这些新类名并非「随手改的命名」而是组件源码中由 props 实时生成的。在 VCol.ts 的parseBreakpoint中cols、sm/md/lg/xl等断点 props 会被转换为v-col--cols-{bp}-{n}offset/offsetSm等会被转换为v-col--offset-{bp}-{n}若在 VCol.spec.ts 中可以看到对应的断言例如VCol cols6 sm5 /渲染为v-col v-col--cols-sm-5 v-col--cols-6。新网格系统的实现原理源码级拆解在动手写覆盖样式之前先理解新版网格是怎么工作的这样你才能判断覆盖方案是否适合自己。1. gap 与 CSS 变量体系新版网格的核心在 VGrid.sass.v-row --v-row-columns: #{settings.$grid-columns} display: flex flex-wrap: wrap flex: 1 1 auto gap: var(--v-col-gap-y) var(--v-col-gap-x) .v-row margin-top: var(--v-col-gap-y)行内间距不再由 margin/padding 控制而是通过一组 CSS 自定义属性custom properties贯穿整棵网格树--v-col-gap-x/--v-col-gap-y横向 / 纵向列间距由密度density修饰符决定--v-col-gap-x: #{$grid-gutter $modifier * 2}--v-row-columns行内总列数默认取$grid-columns即 12--v-col-size/--v-col-size-columns列当前占用的列数与总列数用于计算flex-basis--v-col-offset/--v-col-offset-columns列偏移量与总列数用于计算margin-inline-start。默认间距与密度配置在 _variables.scss$grid-gutter: $spacer * 6 !default; $grid-density: (default: 0, comfortable: -1, compact: -2) !default; $grid-columns: 12 !default;也就是说默认 gutter 基于$spacer基准放大 6 倍仓库浏览器测试 VCol.spec.browser.tsx 中以const defaultGap 24作为默认值densitycomfortable与densitycompact会逐级缩小间距。另外 VGrid.sass 中的.v-row--no-gutters会把两个 gap 变量直接置 0。2. VRow把 props 变成 CSS 变量VRow.ts 渲染时会把用户传入的gap、size写入行内样式style: [ { --v-col-gap-x: horizontalGap.value, --v-col-gap-y: verticalGap.value, --v-row-columns: props.size, }, props.style, ],其中gapprop 支持数字、字符串或数组[横向, 纵向]三种形式见 VRow.ts这解释了为什么你的自定义覆盖样式要基于--v-col-gap-x/y变量而不是写死数值——它能自动兼容应用层自定义的 gap。同时注意 VRow.ts 中的弃用逻辑if (props.dense) { deprecate(dense, densitycompact) }denseprop 在 Vuetify 4 中已被标记为弃用直接映射到densitycompact即旧类名.v-row--dense→ 新类名.v-row--density-compact。3. VColflex-basis 的「含 gap」宽度计算新版列的尺寸公式VGrid.sassflex-basis: var(--v-col-is-size, calc(($size * (100% $gap)) / $cols - $gap)) var(--v-col-is-auto, auto) var(--v-col-is-grow, 0)即flex-basis (列数 * (100% gap)) / 总列数 - gap这是旧版flex: 0 0 75%的「含 gap」升级版目的是让 N 列并排时加上 N-1 个 gap 恰好铺满整行。偏移量同理margin-inline-start: calc($offset * (100% $gap) / $offsetCols)。仓库的浏览器测试 VCol.spec.browser.tsx 用几何公式验证了这套计算function expectedSize (cols: number, rowSize: number) { return cols * (rowSize - 11 * defaultGap) / 12 (cols - 1) * defaultGap } function expectedShift (offset: number, rowSize: number) { return offset * (rowSize - 11 * defaultGap) / 12 offset * defaultGap }测试断言cols4的列宽等于expectedSize(4, 1000)、偏移列左边缘等于expectedShift(...)这从测试层面证实了「新版列宽已把 gap 计入」这一关键行为差异。CSS 覆盖恢复 Legacy 网格行为官方文档给出的解决方案是不修改组件代码也不逐个改写模板而是在你的应用中追加一段 CSS把间距机制从gap换回负边距 padding同时把列宽公式换回简单的百分比。在应用入口如全局样式文件中加入以下覆盖layer vuetify-overrides { .v-row { gap: unset; margin: calc(var(--v-col-gap-y) * -.5) calc(var(--v-col-gap-x) * -.5); } .v-row .v-row { margin-top: calc(var(--v-col-gap-y) * .5); } .v-col { padding: calc(var(--v-col-gap-y) * .5) calc(var(--v-col-gap-x) * .5); flex-basis: var(--v-col-is-size, calc(100% * var(--v-col-size) / var(--v-col-size-columns))) var(--v-col-is-auto, auto) var(--v-col-is-grow, 0); } .v-col:where([class*v-col--offset-]) { margin-inline-start: calc(100% * var(--v-col-offset) / var(--v-col-size-columns)) } }逐段解释这条覆盖做了什么.v-row部分gap: unset关闭新版间距行负外边距取 gap 变量的一半calc(var(--v-col-gap-y) * -.5)用于抵消列的外扩 padding恢复「行与容器边缘对齐」的经典行为。.v-row .v-row部分连续行之间的纵向间距恢复为半个 gap替代新版 .v-row { margin-top: var(--v-col-gap-y) }的整 gap 行为见 VGrid.sass。.v-col部分列重新获得左右/上下各半个 gap 的 paddingflex-basis退回简单百分比100% * var(--v-col-size) / var(--v-col-size-columns)等价于旧版flex: 0 0 75%这类写法同时通过var(--v-col-is-auto, auto)与var(--v-col-is-grow, 0)保留新版auto与 grow 列的行为开关。.v-col--offset-*部分偏移量改回纯百分比100% * var(--v-col-offset) / var(--v-col-size-columns)对应旧版.offset-{n}的偏移语义。为什么是layer vuetify-overrides覆盖样式必须包在layer vuetify-overrides中这不是随意取的层名。Vuetify 4 的样式系统基于 CSSlayer组织优先级层序声明位于 _layers.scsslayer vuetify-core { layer reset, base; } layer vuetify-components; // Contextual styles for nested components layer vuetify-overrides; layer vuetify-utilities { ... } layer vuetify-final { layer transitions, trumps; }vuetify-overrides是官方预留的「上下文覆盖」层排在vuetify-components之后、vuetify-utilities之前。组件样式通过 _layer.scss 中的layermixin 统一写入layer vuetify-componentsmixin layer ($name) { if ($name transitions or $name trumps) { $name: final. $name; } at-root (without: layer) { layer vuetify-#{$name} { content; } } }由于 CSS 层规则是「后声明的层优先级更高」把覆盖规则放进vuetify-overrides层即可稳定压过组件层样式而无需依赖!important。如果你的项目构建环境不支持layer如较老的后处理工具链可以把layer vuetify-overrides { ... }的外壳去掉直接用选择器书写并确保引入顺序靠后但更推荐保持原样以适配 Vuetify 4 的样式架构。覆盖方案的边界与注意事项官方覆盖方案是「行为级」还原但它并不能 100% 复刻旧版所有细节使用前请确认以下几点自定义 gap 仍生效覆盖规则完全基于--v-col-gap-x/y变量换算 margin/padding因此VRow的gapprop、no-guttersgap 变量置 0以及density密度系统都能继续工作无需额外处理。size自定义列数仍生效flex-basis与偏移公式中的var(--v-col-size-columns)会回退到--v-row-columns由VRow的sizeprop 写入所以自定义 12 之外的分栏数如size10同样被覆盖方案支持。自动宽度 / 等分列行为保留flex-basis中保留的--v-col-is-auto与--v-col-is-grow开关使colsauto和无cols的 grow 列在新旧模式下都维持原语义grow 分支的行为可在 VCol.spec.browser.tsx 的grow测试组中看到验证。嵌套与响应式断点类v-col--cols-sm-*、v-col--offset-md-*等由组件源码生成覆盖方案不依赖具体断点数值因此响应式布局完整保留。间隙观感差异Legacy 模式下列间距来自 padding视觉上「间隙」其实是列背景之外的空间若你的列带有背景色或边框两种模式的视觉呈现会有细微差异建议在关键页面上逐屏回归。升级到 Vuetify 4 的网格迁移清单结合本指南从 Vuetify 3 升级时建议按以下顺序处理网格相关代码先替换已弃用的 APIVRow dense→VRow densitycompact源码会在运行时输出 deprecation 提示见 VRow.ts若你的样式文件里直接使用了旧类名.v-row--dense、.v-col-*、.offset-*对照上文的类名映射表更新。评估是否启用 Legacy 覆盖若项目存在大量依赖旧宽度公式的像素级布局直接在全局样式引入上文「CSS 覆盖」一节的代码否则保持新版gap行为以获得更简洁的 DOM 与更好的响应式表现。逐页回归重点检查多行堆叠行间距、带背景色/边框的列、以及结合offset的对齐场景必要时微调--v-col-gap-x/y变量而非改回硬编码数值。延伸阅读VGrid.sass新版网格的完整 Sass 实现gap 变量体系与列宽公式均在此定义VRow.tsgap、size、density、noGutters等 props 到 CSS 变量的映射VCol.ts断点 / 偏移类名与--v-col-size-base、--v-col-offset-base变量的生成逻辑VCol.spec.browser.tsx浏览器级测试验证含 gap 的列宽与偏移计算_variables.scss$grid-gutter、$grid-density、$grid-columns等网格设计令牌_layers.scssvuetify-overrides层的声明与整体层序升级指南从 Vuetify 3 迁移到 Vuetify 4 的完整升级说明。【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
