NG-ZORRO ColorPicker 预设颜色（nzPresets）实战指南：分组标签、默认展开与唯一键全解析

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载nzPresets是 NG-ZORRO ColorPicker颜色选择器组件提供的预设色板能力允许开发者预先为使用者准备好一组或多组常用颜色点击即可快速选中免去在色相盘与滑杆上反复拖拽调色的过程。本指南围绕官方预设颜色示例展开完整讲解NzPresetColor数据结构、单组/多组预设的配置写法、defaultOpen与key的语义并结合仓库源码剖析预设色板的渲染链路与交互原理读完即可在自己的 Angular 表单或设计工具类页面中落地一套可折叠、可复用的快捷取色面板。预设颜色能解决什么问题颜色选择器的默认形态是自由取色用户需要在面板上通过色相渐变、饱和度/明度滑杆以及透明度滑杆来拼出目标颜色操作链路较长对非设计背景的用户不友好。预设颜色的核心价值在于快速选择把高频使用的品牌色、语义色成功/警告/错误、中性灰阶等直接铺成色块一次点击即完成选择分组管理支持把颜色按主题或场景划分成多个预设组每组拥有独立的标题、颜色清单、默认展开状态和唯一键值适合需要维护大型色板的应用视觉反馈当前选中的颜色会在预设块上自动高亮checked 状态浅色块还会有明度标识交互反馈直观。在 NG-ZORRO 中这一切通过nz-color-picker的[nzPresets]输入属性一步到位官方说明位于 预设颜色示例文档配套的可运行示例见 presets.ts。NzPresetColor 数据结构详解预设颜色的类型定义位于 typings.ts是理解整个特性的第一手资料export interface NzPresetColor { label: TemplateRefvoid | string; colors: Arraystring | NzColor; defaultOpen?: boolean; key?: string | number; }字段类型必填说明labelTemplateRefvoid \| string是预设组的标题可以是纯字符串也可以传入模板引用实现自定义标题渲染colorsArraystring \| NzColor是该组包含的颜色清单每个元素既可以是#1677ff这样的十六进制字符串也可以是NzColor实例由组件内部generateColor统一转换处理defaultOpenboolean否该预设组是否默认展开。缺省时不展开需用户点击标题打开keystring \| number否预设组的唯一键值用于 Angular 渲染时的 track 标识同一列表中建议保持唯一对应的组件输入定义在 color-picker.component.tsInput() nzPresets: NzPresetColor[] | null null;默认值为null即不传入时色板区域完全不渲染。快速上手第一组预设色从 presets.ts 中的basicPresets可以看到最基础的用法——两组预设一组给推荐色黑色系透明度阶梯一组给最近使用Ant Design 品牌色环import { Component } from angular/core; import { NzColorPickerModule, NzPresetColor } from ng-zorro-antd/color-picker; Component({ selector: nz-demo-color-picker-presets, imports: [NzColorPickerModule], template: div styledisplay: flex; flex-direction: column; gap: 16px; div h4Basic Presets/h4 nz-color-picker [nzPresets]basicPresets nzValue#1677ff / /div /div }) export class NzDemoColorPickerPresetsComponent { basicPresets: NzPresetColor[] [ { label: Recommended, colors: [ #000000, #000000E0, #000000A6, #00000073, #00000040, #00000026, #0000001A, #00000012, #0000000A, #00000005 ] }, { label: Recent, colors: [ #F5222D, #FA8C16, #FADB14, #8BBB11, #52C41A, #13A8A8, #1677FF, #2F54EB, #722ED1, #EB2F96 ] } ]; }要点模板中使用[nzPresets]basicPresets绑定即可无需额外模块NzColorPickerModule已包含全部依赖颜色字符串支持 8 位十六进制如#000000E0最后两位表示透明度面板会原样解析并渲染这也是 Ant Design 设计规范中黑色遮罩层的标准色阶写法点击任意色块后组件会把该颜色作为当前值触发(nzOnChange)回调并同步到表单值。多分组预设用 key 保证渲染稳定当预设组数量较多时建议为每组设置key。示例中的multiplePresets把颜色按主色、次色、中性色拆成三个独立分组multiplePresets: NzPresetColor[] [ { label: Primary Colors, colors: [#1677ff, #52c41a, #faad14, #f5222d, #722ed1], key: primary }, { label: Secondary Colors, colors: [#13c2c2, #eb2f96, #fa541c, #a0d911, #2f54eb], key: secondary }, { label: Neutral Colors, colors: [#000000, #434343, #666666, #999999, #cccccc], key: neutral } ];key的底层作用体现在渲染层。在 ng-antd-color-preset.component.ts 中每个分组对应的折叠面板使用track preset.key || $index作为 track 表达式for (preset of presets; track preset.key || $index) { nz-collapse-panel [nzActive]openPresets.has($index) (nzActiveChange)onPanelActiveChange($index, $event) [nzHeader]preset.label 这意味着提供了key时以 key 追踪分组未提供时退化为数组下标。如果运行期间预设列表会发生增删、排序等动态变化显式给出稳定的key可以避免 Angular 因下标错位导致的面板展开状态错乱与不必要的 DOM 重建。从实现上看openPresets集合存的是面板索引Setstring | number索引与 key 的绑定关系越稳定展开状态的还原就越可靠。控制默认折叠defaultOpen 的三种形态defaultOpen决定面板初次渲染时的展开状态。示例中的customPresets演示了同一列表内混用展开与折叠的写法customPresets: NzPresetColor[] [ { label: Brand Colors, colors: [#1677ff, #69c0ff, #bae7ff, #e6f7ff], defaultOpen: true, key: brand }, { label: Success Colors, colors: [#52c41a, #95de64, #b7eb8f, #d9f7be], defaultOpen: false, key: success }, { label: Warning Colors, colors: [#faad14, #ffc53d, #ffd666, #ffe58f], defaultOpen: false, key: warning }, { label: Error Colors, colors: [#f5222d, #ff4d4f, #ff7875, #ffa39e], defaultOpen: false, key: error } ];实现机制在 ng-antd-color-preset.component.ts 的ngOnInit中一目了然ngOnInit(): void { this.presets.forEach((preset, index) { if (preset.defaultOpen) { this.openPresets.add(index); } }); }组件初始化时扫描所有预设组把defaultOpen true的组索引写入openPresets进而驱动nz-collapse-panel的nzActive。此后用户点击标题展开/收起面板时onPanelActiveChange会增删对应索引并触发变更检测。这种声明式初始状态 交互式增量维护的设计让品牌色默认展示、其余语义色默认收起的体验可以零成本实现。源码透视预设色板的完整渲染链路与交互从输入到渲染预设色板走了一条清晰的组件调用链以下内容均可从仓库源码逐一印证第一步外层转发。NzColorPickerComponent的模板中[presets]nzPresets被传给内部取色组件 ng-antd-color-picker.component.tsif (presets presets.length 0) { nz-divider nzSizesmall / ng-antd-color-preset [value]colorValue [presets]presets (presetSelect)handleChange($event) / }注意这里的守卫条件只有nzPresets非空且长度大于 0 时分隔线和预设区才会出现否则整个区域不渲染对应的单元测试 should not render presets when null 也验证了这一行为见 color-picker.component.spec.ts。第二步分组渲染。ng-antd-color-preset.component.ts 复用NzCollapseModulenz-collapse nzGhost把每个预设组渲染为一个可折叠面板组内每个颜色渲染为一个ng-antd-color-block色块for (color of preset.colors; track $index) { ng-antd-color-block [value]value [color]getColorString(color) (nzOnClick)selectPresetColor(color) / /divgetColorString对NzColor实例调用toRgbString()归一化后作为背景色字符串则原样透传。第三步点击取色。点击色块触发selectPresetColorselectPresetColor(color: string | NzColor): void { const colorInstance typeof color string ? generateColor(color) : color; this.presetSelect.emit(colorInstance); }字符串颜色在这里被generateColor统一转换为NzColor实例后向外发射父级收到presetSelect后调用handleChange完成当前值的更新与nzOnChange事件触发。也就是说预设色块与面板主色区最终走的是同一条取值通道。第四步选中态与明度反馈。色块的选中高亮和浅色标识由 ng-antd-color-block.component.ts 计算get isChecked(): boolean { if (!this.value) { return false; } const current generateColor(this.value).toHexString(); const colorPreset generateColor(this.color).toHexString(); return current colorPreset; } get isBright(): boolean { const { r, g, b, a } generateColor(this.color).toRgb(); if (a ! undefined a 0.5) return true; const brightness r * 0.299 g * 0.587 b * 0.114; return brightness 192; }isChecked把当前值与该色块颜色都归一化为 HEX 后比较选中即挂上ant-color-picker-presets-color-checked类此逻辑同样有单元测试覆盖见 ng-antd-color-preset.component.spec.tsisBright半透明色alpha ≤ 0.5或按 Rec.601 亮度公式r*0.299 g*0.587 b*0.114计算后亮度大于 192 的颜色会被判定为浅色挂上ant-color-picker-presets-color-bright类便于主题在浅色块上绘制可辨识的边框或对勾。测试佐证。预设特性的行为约束集中在两组测试里NgAntdColorPresetComponent的单元测试覆盖了面板与色块按预设渲染defaultOpen 生效点击标题切换展开点击色块发射 NzColor 实例浅色块增加 bright 类等场景ng-antd-color-preset.component.spec.ts组件级测试则验证了传入 presets 时渲染 2 个折叠面板传入 null 时不渲染预设区点击预设色块触发 nzOnChange面板可展开收起等集成行为color-picker.component.spec.ts。与事件回调及表单的联动预设取色不会绕过组件的标准事件与表单协议事件选中预设色后nzOnChange会以{ color: NzColor; format: string }结构向外发射见 color-picker.component.tsformat取当前nzFormat的值缺省为hex。你可以借此把选中的预设色同步到业务状态、上报埋点或联动其他控件表单NzColorPickerComponent实现了ControlValueAccessor见 color-picker.component.ts因此nz-color-picker可以直接配合formControlName使用预设取色与手动画板取色都会写入同一个表单控件值校验、重置、禁用等表单语义完整保留。API 速查与最佳实践建议[nzPresets]的官方 API 说明见 ColorPicker 组件文档自 21.0.0 版本起可用类型为预设颜色项数组配合NzPresetColor的四个字段即可覆盖绝大多数场景。配置推荐做法单组少量色只提供labelcolors其余省略多组大色板每组显式提供key保证动态增删时的渲染稳定高频色优先展示给最常用的一组设置defaultOpen: true其余保持收起控制面板整体高度字符串 vs NzColor日常直接写十六进制字符串即可需要程序化构造颜色如基于主题变量时可传NzColor实例长颜色清单控制每组色块数量示例多在 410 个避免色板过长遮挡取色面板主体结合源码可以确认预设区渲染在取色面板主体下方并以分隔线隔开面板展开时色块组以折叠面板形式呈现用户可自由展开/收起各组。这套能力完全基于组件自身输入实现无需额外配置服务或全局状态是 NG-ZORRO ColorPicker 中成本最低、见效最快的常用色速选方案。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd ColorPicker 颜色编码格式HEX / HSB / RGB实战指南ng zorro antd ColorPicker 颜色编码格式HEX / HSB / RGB实战指南 nz color picker 是 ng zorroUI组件前端如何用 Chatterbox 多说话人语音合成快速完成零样本声音克隆如何用 Chatterbox 多说话人语音合成快速完成零样本声音克隆 Chatterbox 是 Resemble AI 开源的文本转语音TTS模型家族。这篇UI组件前端如何快速获取安全APK安卓应用下载的终极指南如何快速获取安全APK安卓应用下载的终极指南 还在为安卓应用下载的烦恼而头疼吗找不到官方版本、担心病毒捆绑、想要特定历史版本却无处可寻今天我要为你推荐一个UI组件前端上一篇使用 WideWorldImporters 演示 SQL Server 实时运营分析非聚集列存储索引Nonclustered Columnstore Index性能验证下一篇如何用 Laravel-5-Generators-Extended 在5分钟内创建完整数据库迁移创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考