
UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读在 NG-ZORROAngular UI 组件库中nz-checkbox-group除了支持通过nzOptions数组批量生成选项外还允许在标签内自由投影自定义内容——这就为布局提供了极大的灵活性。本篇指南以官方 Demo components/checkbox/demo/layout.md 为骨架完整解析「nz-checkbox-group内嵌nz-checkbox并与 Grid 组件协同」的经典写法从最小可运行模板、栅格排布规则到组件底层的内容投影与值同步原理再到基于源码与测试的可验证进阶方案。读完本文你将掌握用 24 栅格系统、响应式断点与nzGutter间距控制任意复杂 Checkbox 布局的完整实战能力。一、核心场景为什么需要自定义 Checkbox 布局官方文档对「布局」场景的定位非常明确nz-checkbox-group内嵌nz-checkbox并与 Grid 组件一起使用可以实现灵活的布局。zh-CNWe can usenz-checkboxand Grid innz-checkbox-group, to implement complex layout.en-US默认情况下nz-checkbox-group通过nzOptions输入一个数组string[] | number[] | NzCheckboxOption[]组件内部会自动渲染一排等宽选项见 components/checkbox/demo/group.ts。但当选项需要分栏、多行、错落排布、与其它控件混合时数组渲染的单一模式就不够用了。此时可以放弃nzOptions改为在nz-checkbox-group的标签体内直接书写label[nz-checkbox]再利用 Grid 的nz-row/nz-col组织排布。值得注意的是nz-checkbox-group本身仍然是数据聚合的容器它通过NG_VALUE_ACCESSOR实现ControlValueAccessor源码见 components/checkbox/checkbox-group.component.ts所以无论标签内内容如何摆放最终仍能以[(ngModel)]形式整体双向绑定一个string[] | number[]值表单校验、禁用联动等能力都完整保留。二、最小可运行模板nz-checkbox-group Grid官方「布局」Demo 的完整实现位于 components/checkbox/demo/layout.ts核心代码如下import { Component } from angular/core; import { FormsModule } from angular/forms; import { NzCheckboxModule } from ng-zorro-antd/checkbox; import { NzGridModule } from ng-zorro-antd/grid; Component({ selector: nz-demo-checkbox-layout, imports: [FormsModule, NzCheckboxModule, NzGridModule], template: nz-checkbox-group ngModelA [style.width.%]100 nz-row nz-col nzSpan8 label nz-checkbox nzValueAA/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueBB/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueCC/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueDD/label /nz-col nz-col nzSpan8 label nz-checkbox nzValueEE/label /nz-col /nz-row /nz-checkbox-group }) export class NzDemoCheckboxLayoutComponent {}逐行拆解其中的关键点要素写法作用分组容器nz-checkbox-group承接双向绑定、聚合选中值标签内内容通过ng-content投影渲染初值绑定ngModelA默认选中值为A的选项完整用法建议使用[(ngModel)]双向绑定宽度约束[style.width.%]100让分组占满整行宽度避免栅格换行异常栅格行nz-row建立 24 等分栅格的横向容器Flex 布局栅格列nz-col nzSpan8每个选项占据 8/24 宽度即一行三列选项本体label nz-checkbox nzValueAA/label选项标签nzValue作为该选项在组内的唯一标识值由于 5 个选项各占nzSpan8第一行 3 个A、B、C正好铺满 24 格剩余 2 个D、E自动换行到第二行——这正是 24 栅格系统「列宽之和超过 24 自动换行」规则的直接体现。三、底层原理内容投影与值同步机制这个看似简单的模板背后是 NG-ZORRO 精心设计的两层协作机制理解了它们才能放心地把任意内容放进nz-checkbox-group。3.1 内容投影ng-content 条件渲染nz-checkbox-group的模板components/checkbox/checkbox-group.component.ts同时保留了两条渲染路径ng-content for (option of normalizedOptions(); track option.value) { label nz-checkbox [nzValue]option.value ... {{ option.label }} /label } /ng-contentng-content投影通道当开发者像布局 Demo 那样在标签内书写内容时外部内容原样投影nzOptions为空数组for不渲染任何默认选项nzOptions数组通道当没有外部内容而传入nzOptions时组件自动生成一组label[nz-checkbox]。两条路径互不冲突因此你既可以完全自定义布局也可以在自定义布局中混入少量由数组生成的选项。3.2 父子通信依赖注入 Token 而非 DOM 层级查询外部自定义的label[nz-checkbox]之所以能被分组容器“识别”靠的是注入令牌NZ_CHECKBOX_GROUP定义见 components/checkbox/tokens.ts。分组组件将其自身以useExisting的方式注册到该令牌上checkbox-group.component.ts而每个nz-checkbox在构造时通过inject(NZ_CHECKBOX_GROUP, { optional: true })获取最近的组实例checkbox.component.ts。由此形成的协作关系可从源码确认选中状态同步组内维护一个value信号子选项在构造函数里用effect监听它——values.includes(this.nzValue)为真即勾选checkbox.component.ts选中事件上报用户勾选时子选项调用checkboxGroupComponent?.onCheckedChange(this.nzValue, checked)checkbox.component.ts组实例据此增删数组元素并触发onChange最终把新的string[] | number[]写回ngModelcheckbox-group.component.ts禁用与 name 联动组级nzDisabled、nzName会通过finalDisabled()、nzName()传导到每个子选项checkbox.component.ts。这意味着只要把带nzValue的label[nz-checkbox]放在nz-checkbox-group内任意 DOM 位置无论嵌套多深、被什么布局容器包裹值绑定与禁用联动都会自动生效——这正是与 Grid 自由组合的底气所在。四、Grid 栅格基础24 等分与响应式断点要让 Checkbox 布局真正“灵活”还需要掌握 NG-ZORROW Grid 的基础用法完整 API 见 components/grid/doc/index.zh-CN.md24 等分原则整个设计区域按 24 等分划分nz-col的nzSpan取值范围为 1–24表示跨越的栅格数例如三个等宽列可用nzSpan8实现行内规则内容必须放在nz-col内且只有nz-col可作为nz-row的直接子元素同一nz-row内所有列 span 之和超过 24 时超出的列整体换行布局 Demo 的 D、E 即是如此Flex 对齐栅格基于 Flex 布局nz-row支持nzJustifystart | end | center | space-around | space-between | space-evenly与nzAligntop | middle | bottom | stretch源码见 components/grid/row.directive.ts列属性nz-col还支持nzOffset、nzOrder、nzPush、nzPull等栅格位移属性以及nzFlex弹性属性components/grid/col.directive.ts。五、进阶间距与响应式布局5.1 用 nzGutter 控制选项间距栅格行支持nzGutter设置列间距传入数字表示水平间距单位 pxnz-row以负 margin、nz-col以 padding 实现见 row.directive.ts 与 col.directive.ts传入数组[水平, 垂直]可分别控制横纵间距nz-checkbox-group ngModelA [style.width.%]100 nz-row [nzGutter][16, 8] nz-col nzSpan8label nz-checkbox nzValueAA/label/nz-col nz-col nzSpan8label nz-checkbox nzValueBB/label/nz-col nz-col nzSpan8label nz-checkbox nzValueCC/label/nz-col /nz-row /nz-checkbox-group5.2 响应式断点按屏幕宽度重新排布nz-col提供nzXs、nzSm、nzMd、nzLg、nzXl、nzXXl、nzXXXl七档响应式输入col.directive.ts可针对不同视口给出不同 span实现“手机上一列、桌面三列”的自适应nz-checkbox-group ngModelA [style.width.%]100 nz-row [nzGutter][16, 8] nz-col nzXs24 nzMd8label nz-checkbox nzValueAA/label/nz-col nz-col nzXs24 nzMd8label nz-checkbox nzValueBB/label/nz-col nz-col nzXs24 nzMd8label nz-checkbox nzValueCC/label/nz-col /nz-row /nz-checkbox-group当视口为超小屏xs时每列占满 24 格选项纵向排列达到 md 断点后变为每列 8 格一行三列。栅格断点同样作用于nzJustify/nzAlign/nzGutter它们接受PartialResponsiveLikeT对象形式row.directive.ts。5.3 更自由的组合混入说明文本与其它控件既然内容是投影进来的理论上你可以在任意nz-col中放入任意 Angular 模板比如把部分选项换成带说明的分组标题、链接甚至其它组件nz-checkbox-group [style.width.%]100 nz-row [nzGutter]16 nz-col nzSpan8label nz-checkbox nzValueAA基础/label/nz-col nz-col nzSpan8label nz-checkbox nzValueBB高级/label/nz-col nz-col nzSpan8span classant-form-text更多选项见下方/span/nz-col /nz-row /nz-checkbox-group六、源码级验证测试如何覆盖自定义布局仓库测试 components/checkbox/checkbox-group.spec.ts 专门为「自定义布局」场景编写了checkbox group with custom layout测试套件L98-L164其测试组件模板与布局 Demo 同构nz-checkbox-group [nzDisabled]disabled() [(ngModel)]value label nz-checkbox nzValueAA/label label nz-checkbox nzValueBB/label label nz-checkbox nzValueCC/label /nz-checkbox-group测试验证的关键行为包括外部勾选可写回 ngModel依次点击 A、Bcomponent.value()依次变为[A]、[A, B]再次点击 A 后变为[B]L146-L159——证明投影的自定义选项与组值完全同步组级禁用生效disabled.set(true)后所有选项均带上ant-checkbox-wrapper-disabled样式类L110-L116初值可回显勾选状态value.set([A])后仅 A 选项带ant-checkbox-wrapper-checked类L118-L144。可见「自定义布局 双向绑定」是官方明确支持并持续测试保障的正式能力而非巧合可用。七、两种形态对比与选型建议维度nzOptions 数组形态自定义内容投影形态代码量极简一行nz-checkbox-group [nzOptions]options /模板稍长但布局自由度极高布局能力固定单排/自动换行无栅格控制可结合 Grid 任意分栏、响应式、错落排布值绑定同[(ngModel)]绑定string[] | number[]同[(ngModel)]绑定string[] | number[]禁用/name同组级nzDisabled/nzName统一生效同组级nzDisabled/nzName统一生效适用场景选项简单、无需特殊排布的表单选项需要分栏/分组/混排、或要求响应式布局的复杂表单八、实操注意事项务必设置宽度布局 Demo 在nz-checkbox-group上使用[style.width.%]100否则栅格行在分组容器内可能因宽度不足出现意外换行同样的思路也可改用style.width.px等其它单位每个选项都要有唯一的nzValue值同步依赖nzValue与组内value数组的includes比对重复或缺失都会造成勾选状态错乱组值类型保持一致nz-checkbox-group的ngModel类型为string[] | number[]默认[]自定义布局中所有nzValue建议统一为字符串或统一为数字嵌套任意深度皆可NZ_CHECKBOX_GROUP基于依赖注入定位组实例nz-checkbox被包裹在nz-col、nz-row乃至自定义组件中都不影响联动前提是这些容器不自行提供同名的NZ_CHECKBOX_GROUP覆盖令牌与响应式栅格配合时优先使用nzXs/nzMd等断点输入而非手写媒体查询保持与 Ant Design 断点体系一致。延伸阅读Checkbox 组件完整 API[nzChecked]、[nzIndeterminate]、nzOptions、NzCheckboxOption接口等components/checkbox/doc/index.zh-CN.md分组组件源码值聚合、CVA 实现components/checkbox/checkbox-group.component.ts选项组件源码注入令牌、effect 同步components/checkbox/checkbox.component.ts栅格行/列指令源码components/grid/row.directive.ts、components/grid/col.directive.ts自定义布局的官方测试保障components/checkbox/checkbox-group.spec.ts赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Ant Design Checkbox 布局指南Checkbox.Group 与 Grid 栅格组合实现灵活多选布局Ant Design Checkbox 布局指南Checkbox.Group 与 Grid 栅格组合实现灵活多选布局 导读 在 Ant Design 中默认前端UI组件设计系统ng-zorro-antd Checkbox Group 实战从数组生成 Checkbox 组ng zorro antd Checkbox Group 实战从数组生成 Checkbox 组 nz checkbox group 是 ng zorro anUI组件前端antd Checkbox 布局实战Checkbox.Group 与 Grid 组合实现多列勾选布局antd Checkbox 布局实战Checkbox.Group 与 Grid 组合实现多列勾选布局 导读 在 ant design 中 Checkbox.前端UI组件设计系统上一篇AirSim终极部署指南3大平台快速搭建方法下一篇Tambo AI完全指南构建智能生成式UI的React开发神器创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考