Carbon Design System 的 Sass 网格体系carbon/grid 的 CSS Grid 与 Flexbox 网格完整使用指南【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncarbon/grid是 IBM Carbon Design System 中负责布局体系的核心 Sass 包它同时提供基于 CSS Grid 与 Flexbox 的两种网格实现以及配套的栅格工具类。本文以 packages/grid/docs/sass.md 为主线结合包内源码与测试系统讲解如何在你的 Sass 工程中引入网格、使用css-gridmixin 生成全套响应式列类、掌握sm/md/lg/xlg/max五档断点下的列宽、列起始、列结束、子网格与悬挂hang等能力并深入剖析每个 API 参数与底层实现原理帮助你快速搭建符合 IBM Design Language 规范的响应式布局。一、快速上手安装与引入在开始使用网格之前需要先将carbon/grid安装为项目依赖。根据 packages/grid/README.md 的说明可以使用 npm 或 Yarn 安装npm install -S carbon/grid或使用 Yarnyarn add carbon/grid安装完成后在你的 Sass 文件中通过 Dart Sass 推荐的use语法引入use carbon/grid; // Emit all the CSS for the CSS Grid include grid.css-grid();carbon/grid的包入口 packages/grid/index.scss 通过forward依次转发了四份内部模块这也是你在外部可以访问的全部公共 APIforward scss/config; forward scss/breakpoint; forward scss/css-grid; forward scss/flex-grid;即config配置变量、breakpoint断点函数与媒体查询 mixin、css-gridCSS Grid 网格与flex-gridFlexbox 网格四个模块会整体合并到carbon/grid这一个命名空间下因此文档中的grid.css-grid()、grid.breakpoint-up()、grid.$prefix等写法才能成立。二、Usage用 css-grid mixin 生成整套网格 CSS2.1 基本用法调用grid.css-grid()会一次性输出 CSS Grid 所需的基础样式。根据 packages/grid/docs/sass.md 的示例生成后即可在 HTML 中直接使用网格类div classcds--css-grid div classcds--css-grid-column cds--col-span-4Span 4 columns/div div classcds--css-grid-column cds--col-span-2Span 2 columns/div /div其中cds--css-grid是网格容器类cds--css-grid-column是列类cds--col-span-4表示该列无条件横跨 4 列默认 16 列栅格。2.2 响应式能力css-gridmixin 生成的响应式类允许你针对每个断点做三件事改变列跨度根据断点调整内容横跨的列数如cds--lg:col-span-8隐藏或显示内容跨度设为 0如cds--col-span-0时对应列会被display: none隐藏改变列起始/结束位置通过cds--lg:col-start-3、cds--lg:col-end-9精确控制列落位。2.3 css-grid mixin 的源码结构从源码 packages/grid/scss/_css-grid.scss 可以看清这套类的生成逻辑。css-gridmixin 被设计为以最少 CSS 输出实现全部能力整体分三个阶段最小断点无媒体查询输出最小的sm断点样式直接裸输出其他断点才包裹在媒体查询内每个非最小断点用媒体查询包裹仅在该断点命中时才生效按需输出无条件选择器例如cds--col-span-4这种不依赖断点、始终生效的类。mixin 首先在:root选择器上通过 CSS 自定义属性Custom Properties暴露网格的全局配置包括--cds-grid-gutter栅格间距、--cds-grid-columns列数与--cds-grid-margin网格外边距。值得注意的是--cds-grid-columns与--cds-grid-margin只有在与上一断点不同时才会在新的断点内重新输出见 _css-grid.scss这是最少 CSS策略的关键实现。基础容器类的核心声明如下_css-grid.scss.#{$prefix}--css-grid { --cds-grid-gutter-start: calc(var(--cds-grid-gutter) / 2); --cds-grid-gutter-end: calc(var(--cds-grid-gutter) / 2); display: grid; grid-template-columns: repeat(var(--cds-grid-columns), minmax(0, 1fr)); inline-size: 100%; margin-inline: auto; max-inline-size: get-grid-width($breakpoints, largest-breakpoint-name($breakpoints)); padding-inline: var(--cds-grid-margin); }max-inline-size取最大断点max的宽度即网格容器默认最宽为max断点对应的 1584px。三、ClassesCSS Grid 可用类一览下表来自 packages/grid/docs/sass.md 的 Classes 章节完整列出css-grid()输出后可供 HTML 使用的全部类名NameDescriptioncds--css-gridGrid class namecds--css-grid-columnColumn class namecds--col-span-{0,16}Unconditional column spancds--{sm,md,lg,xlg,max}:col-span-{0,16}Responsive column spancds--col-span-{25,50,75,100}Percent column span across breakpointscds--col-start-{1,16}Unconditional column startcds--{sm,md,lg,xlg,max}:col-start-{1,16}Responsive column startcds--col-end-{2,17}Unconditional column endcds--{sm,md,lg,xlg,max}:col-end-{2,17}Responsive column endcds--grid-column-hangHang content on a grid columncds--subgridSpecify an element as a subgridcds--subgrid--{wide,narrow,condensed}Specify the gutter mode of subgrid3.1 列跨度Column Span与百分比跨度无条件列跨度由 _css-grid.scss 中的for循环生成范围 0 到最大列数默认 16for $i from 0 through get-grid-columns($breakpoints) { .#{$prefix}--col-span-#{$i} { include -column-span($i); } }内部-column-spanmixin_css-grid.scss定义了关键行为span 0时输出display: none隐藏列否则设置--cds-grid-columns自定义属性并输出grid-column: span $i / span $i。百分比跨度类cds--col-span-{25,50,75,100}会跨所有断点按比例计算实际跨度内部由-percent-column-spanmixin_css-grid.scss实现它遍历每个断点取该断点的列数乘以百分比得到span当相邻断点计算结果不同时才在对应媒体查询中输出再次体现只输出变化的优化策略。例如在 16 列断点上cds--col-span-50即相当于跨 8 列。3.2 列起始与列结束无条件类与断点规则的取值区间不同原因在于CSS Grid 的网格线从 1 开始计数cds--col-start-{1,16}grid-column-start从 1 到 16不取 17 是因为让列从网格末尾开始会导致其没有任何可用宽度_css-grid.scsscds--col-end-{2,17}grid-column-end从 2 到 17列数 1不取 1 是因为结束于第 1 条线意味着列宽为 0_css-grid.scss。两类都额外提供了auto变体cds--col-start-auto、cds--col-end-auto用于在响应式场景下重置为默认自动定位。3.3 子网格Subgrid与悬挂Hangcds--subgrid让一个元素成为嵌套网格并复用父网格的列定义_css-grid.scss.#{$prefix}--subgrid { display: grid; grid-template-columns: repeat(var(--cds-grid-columns), minmax(0, 1fr)); margin-inline: calc(var(--cds-grid-mode-start) * -1) calc(var(--cds-grid-mode-end) * -1); }子网格通过负外边距抵消父网格的 padding使其能严丝合缝地嵌入父网格。--cds-grid-mode-start/end这两个自定义属性由列类捕获父网格的栅格设置_css-grid.scss从而让子网格正确回退外层间距。子网格支持三种 gutter 模式每种模式同时覆盖了起始/结束边距与 column-hang子网格类起始 gutter结束 guttercolumn-hangcds--subgrid--wide$grid-gutter / 216px$grid-gutter / 216px0cds--subgrid--narrow0$grid-gutter / 216px$grid-gutter / 216pxcds--subgrid--condensed$grid-gutter-condensed / 20.5px同上$grid-gutter / 2 - $grid-gutter-condensed / 2cds--grid-column-hang则用于文字对齐补偿当列处于narrow起始 gutter 为 0或condensedgutter 缩小模式时文本会贴着网格边缘该工具类通过margin-inline-start: var(--cds-grid-column-hang)将内容悬挂回正常的排版起点_css-grid.scss。3.4 其他修饰类cds--css-grid--full-width容器宽度设为 100%突破最大宽度限制cds--css-grid--narrow/cds--css-grid--condensed切换窄版起始 gutter 为 0与紧凑版gutter 缩为 1pxgutter 模式cds--css-grid--with-row-gap为行之间添加等于$grid-gutter的row-gapnarrow 模式下为$grid-gutter / 2cds--css-grid--start/cds--css-grid--end将容器左对齐或右对齐对应margin-inline-start: 0/margin-inline-end: 0。以上所有修饰类在子网格上也有对应版本cds--subgrid--with-row-gap等见 _css-grid.scss。四、API配置变量、函数与 mixin 速查下表完整继承自 packages/grid/docs/sass.md 的 API 章节NameDescriptionTypeDefaultcss-gridGenerate the CSS for using the CSS Gridmixin$prefixSpecify the prefix used for CSS selectorsStringcds$flex-grid-columnsSpecify the number of columns for the flex gridNumber16$grid-gutterSpecify the gutter of the gridNumber32px (2rem)$grid-gutter-condensedSpecify the gutter of the condensed gridNumber1px$grid-breakpointsSpecify the breakpoints for the gridMapbreakpoint-nextGet the value of the next breakpointfunctionbreakpoint-prevGet the value of the previous breakpointfunctionis-smallest-breakpointCheck to see if the given breakpoint is the smallest breakpointfunctionbreakpoint-upGenerate a media query from the width of the given breakpoint to infinitymixinbreakpoint-downGenerate a media query that applies below the maximum width of the given breakpointmixinbreakpoint-betweenGenerate a media query for the range between the lower and upper breakpointsmixinlargest-breakpointGenerate a media query for the largest breakpointmixinbreakpointGenerate a media query for a given breakpoint, alias ofbreakpoint-upmixin4.1 配置变量的默认值来源这些默认值定义在 packages/grid/scss/_config.scss 中全部使用!default声明意味着你可以在任何引入前用自己的值覆盖它们。注意自定义属性变量与上述配置变量名相同如--cds-grid-gutter与$grid-gutter它们分别服务于运行时CSS与编译时Sass。4.2 断点映射的默认结构$grid-breakpoints默认包含五档断点每档包含columns列数、margin网格外边距与width断点宽度三个字段_config.scss断点columnsmarginwidthsm40320pxmd816px672pxlg1616px1056pxxlg1616px1312pxmax1624px1584px这些宽度值由carbon/layout/scss/convert的to-rem转换为 rem 单位。此外_config.scss还有一个隐藏逻辑当$flex-grid-columns被设为 12 时lg/xlg/max三档断点的列数会自动同步改为 12_config.scss保证 CSS Grid 与 12 列 Flexbox 网格在列数上保持一致。4.3 断点函数与媒体查询 mixin 的实现要点断点工具集中在 packages/grid/scss/_breakpoint.scss掌握其行为对自定义布局至关重要breakpoint-next($name)/breakpoint-prev($name)基于map.keys($breakpoints)的顺序索引返回相邻断点名越界时返回nullis-smallest-breakpoint($name)判断是否为 map 中的第一个断点即sm源码通过list.index(...) 1实现_breakpoint.scssbreakpoint-up($name)生成min-width媒体查询。特例对最小断点直接裸输出内容而不产生媒体查询_breakpoint.scss这也解释了为什么sm相关的响应式类无需包裹在media中若传入的断点名不存在会以error报错并列出合法断点名breakpoint-down($name)生成max-width媒体查询上限取断点宽度减去 0.02px。源码注释说明这是借鉴 Bootstrap 的做法用 0.02 而非 0.01 是为了规避 Safari 的舍入问题_breakpoint.scssbreakpoint-between($lower, $upper)生成min-width与max-width组合的范围查询且对$lower为最小断点或$upper为最大断点的情况自动退化为breakpoint-up/breakpoint-down_breakpoint.scsslargest-breakpoint($breakpoints)等价于对最大断点调用breakpoint常用于输出仅在大屏生效的样式如--full-width修饰类breakpoint($name)breakpoint-up的别名在包内被大量用于生成响应式类。五、Flexbox 网格与 CSS Grid 的取舍除 CSS Grid 外carbon/grid还保留了基于 Flexbox 的经典网格通过grid.flex-grid()输出。README 中给出了最小示例packages/grid/README.mduse carbon/grid; // Emit the flex-grid styles include grid.flex-grid();Flexbox 网格提供三种原语类cds--grid网格容器负责宽度与边距cds--row一行内容cds--col列单元。配合断点前缀可精确控制每档断点下的列数例如 4 列等分布局div classcds--grid div classcds--row div classcds--col-sm-11/4/div div classcds--col-sm-11/4/div div classcds--col-sm-11/4/div div classcds--col-sm-11/4/div /div /divflex-gridmixinpackages/grid/scss/_flex-grid.scss内部复用了一组私有 mixin-make-col-ready初始化列宽为 100% 与 gutter padding-make-col通过flex: 0 0 百分比设置列宽并在span 0时隐藏列-make-col-offset以百分比 margin 实现cds--offset-{bp}-{n}偏移类-make-container计算容器内边距gutter 一半 断点 margin。-make-grid-columns会为每个断点生成从 0 到该断点列数的全部cds--col{bp}-{n}类。此外还支持cds--no-gutter及--start/--end、cds--hang--start/cds--hang--end、cds--row-padding、cds--grid--with-row-gap等工具类。与 CSS Grid 版本相比Flexbox 版更偏向经典的行列流式布局且通过$flex-grid-columns支持 12 列与 16 列两种体系而 CSS Grid 版则提供了子网格、显式行列定位等更现代的布局能力。两者共享同一套$grid-breakpoints断点配置可按需选择或混用。六、工程实践在真实项目中验证与定制6.1 验证公共 API测试即文档carbon/grid通过 packages/grid/tests/scss-test.js 使用carbon/test-utils/scss的SassRenderer编译../index.scss并断言meta.module-variables(grid)导出的变量与快照snapshot一致meta.mixin-exists(css-grid, grid)与meta.mixin-exists(flex-grid, grid)均为true。这个测试确认了包入口index.scss的forward结构是完整的css-grid与flex-grid两个 mixin 以及全部配置变量都是通过use carbon/grid可用的公共 API。如果你在集成时遇到mixin not found之类的错误应优先检查 Sass 版本是否支持use/forward模块语法。6.2 定制示例修改前缀与栅格参数结合!default语义你可以通过先定义变量再use的方式定制网格。例如将类前缀改为ibm、将 gutter 改为 24pxuse carbon/grid with ( $prefix: ibm, $grid-gutter: 24px ); include grid.css-grid();编译后生成的就是ibm--css-grid、ibm--col-span-4等类名gutter 相关的自定义属性也会相应变化。断点映射同样可整体替换但需保证每档都包含columns、margin、width三个键且键的顺序决定断点的大小关系breakpoint-next/prev/is-smallest-breakpoint都依赖 map 顺序。6.3 实战示例目录仓库在 packages/grid/examples/css-grid 提供了一个完整的 CSS Grid 示例基于 Next.js包含可运行的styles.scss与页面代码是观察css-gridmixin 输出类在实际页面中排布效果的最佳参考packages/grid/examples/preview 则提供了网格预览示例。建议在接入自己的设计系统前先运行这些示例直观对比sm/md/lg/xlg/max各断点下的列数、margin 与 gutter 变化。结语carbon/grid把 IBM Design Language 的栅格规范封装成了一组体积可控、职责清晰的 Sass APIcss-grid与flex-grid两大 mixin 分别输出现代与经典的网格体系$grid-breakpoints五档断点配合breakpoint-*系列函数与 mixin 提供了完整的媒体查询能力所有配置变量均可通过!default机制按项目定制。理解其最小断点裸输出、其余断点按需包裹、仅输出变化值的编译策略能帮助你在享受开箱即用的响应式网格的同时精确掌控最终 CSS 体积与行为。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考