UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本篇技术指南以 ng-zorro-antd 官方组件文档 components/color-picker/doc/index.zh-CN.md 为核心骨架围绕 Angular 版 Ant Design 的颜色选择器nz-color-picker展开。你将系统掌握该组件的全部输入输出 API、nz-color-block色彩块用法、NzColor颜色对象的六种转换方法以及如何在响应式表单与模板驱动表单中集成颜色选择。文中所有参数默认值与行为描述均对照仓库源码 color-picker.component.ts 与类型定义 typings.ts 逐一印证并附带可复制的实战示例代码。何时使用当用户需要自定义颜色选择的时候使用。典型场景包括主题定制页面中让用户挑选品牌主色、背景色、文字色设计工具、画板类应用中选取填充色与描边色表单中录入带透明度的颜色值如告警配置、图表配色。组件自 16.2.0 版本文档 front-matter 中的tag: 16.2.0随 ng-zorro-antd 提供其中nzPresets预设颜色能力在 21.0.0 版本中新增。快速开始引入模块与最小示例使用颜色选择器前需要在应用或独立组件中导入NzColorPickerModule。以最简单的用法为例摘自 demo/basic.tsimport { Component } from angular/core; import { NzColorPickerModule } from ng-zorro-antd/color-picker; Component({ selector: nz-demo-color-picker-basic, imports: [NzColorPickerModule], template: nz-color-picker / }) export class NzDemoColorPickerBasicComponent {}渲染后得到一个默认的触发块默认色#1677ff点击弹出完整颜色面板面板底部带 HEX / HSB / RGB 三种格式的输入区与透明度滑杆。nz-color-picker 完整 API 详解组件对外暴露的完整参数与事件如下表与原文档 API 表格一一对应并结合源码补充说明。参数说明类型默认值版本[nzFormat]颜色格式rgb \| hex \| hsbhex[nzValue]颜色的值string \| NzColor-[nzSize]设置触发器大小large \| small \| defaultdefault[nzDefaultValue]颜色默认的值string \| NzColor-[nzAllowClear]允许清除选择的颜色booleanfalse[nzTrigger]颜色选择器的触发模式hover \| clickclick[nzShowText]显示颜色文本booleanfalse[nzOpen]是否显示弹出窗口booleanfalse[nzDisabled]禁用颜色选择器booleanfalse[nzDisabledAlpha]禁用透明度booleanfalse[nzTitle]设置颜色选择器的标题TemplateRefvoid \| string-[nzPresets]预设的颜色NzColorPickerPresetsItem[]-21.0.0(nzOnChange)颜色变化的回调EventEmitter{ color: NzColor; format: string }-(nzOnClear)清除的回调EventEmitterboolean-(nzOnFormatChange)颜色格式变化的回调EventEmitterrgb \| hex \| hsb-(nzOnOpenChange)打开颜色面板的回调EventEmitterboolean-颜色格式 nzFormat 与 nzValue / nzDefaultValuenzFormat决定组件对外输出的颜色字符串格式类型NzColorPickerFormatType定义在 typings.ts取值为rgb | hex | hsb默认hex。在源码 color-picker.component.ts 中每当内部表单值变化时会按当前格式将颜色归一化为对应字符串hex透明度小于 1 时输出 8 位十六进制如#1677ff80否则输出 6 位十六进制如#1677ffhsb输出hsb(215, 91%, 100%)风格字符串rgb输出rgb(22, 119, 255)风格字符串。nzValue是受控颜色值nzDefaultValue是初始默认值。两者的取值顺序在getBlockColor()color-picker.component.ts中体现优先使用nzValue其次使用nzDefaultValue都不传时回退到默认色#1677ff。注意nzValue与nzDefaultValue的类型既可以是颜色字符串也可以是NzColor实例。传入任意合法输入如#1677ff、rgb(22, 119, 255)、{ r: 22, g: 119, b: 255 }都会先经过generateColor()归一化再统一转为 RGB 字符串用于触发块展示。触发模式 nzTrigger 与开关控制nzTrigger支持click默认与hover两种弹出方式底层通过NzPopoverDirective实现见 color-picker.component.ts弹层方位会在bottomLeft / bottomRight / topLeft / topRight四个位置间自动适配。nzOpen用于受控管理面板开关切换时通过nzOnOpenChange事件通知外部。展示与交互细节nzShowText / nzTitle / nzAllowClear / nzDisabledAlphanzShowText为true时在触发块右侧显示当前颜色的文本值默认显示格式由nzFormat决定例如 HEX 格式下显示#1677ff初始值见 color-picker.component.tsnzTitle面板顶部标题可传字符串或TemplateRefvoid模板引用。当nzTitle或nzAllowClear任意一个开启时面板头部区域ant-color-picker-title才会渲染见 color-picker.component.tsnzAllowClear为true时面板标题右侧出现清除按钮点击后触发nzOnClear事件并将透明度归零内部逻辑见clearColorHandle()color-picker.component.tsnzDisabledAlpha为true时隐藏透明度滑杆与透明度输入框颜色将不再包含 alpha 通道nzDisabled禁用整个选择器禁用后弹层不再响应点击或悬停模板中[nzPopoverTrigger]!nzDisabled ? nzTrigger : null。尺寸 nzSizenzSize支持large | small | default三种尺寸。组件还会通过NZ_FORM_SIZE令牌感知所处表单环境inject(NZ_FORM_SIZE, { optional: true })当表单统一设置了尺寸时优先跟随表单尺寸见finalSize计算逻辑color-picker.component.ts。预设颜色 nzPresets21.0.0nzPresets允许为面板提供预设色块分组类型NzPresetColor定义如下typings.tsexport interface NzPresetColor { label: TemplateRefvoid | string; colors: Arraystring | NzColor; defaultOpen?: boolean; key?: string | number; }字段含义label分组标题支持字符串或模板colors该组的颜色数组每一项为颜色字符串或NzColor实例defaultOpen分组是否默认展开未显式指定时默认展开key分组的唯一标识。一个包含多分组与折叠状态控制的完整示例摘自 demo/presets.tsimport { Component } from angular/core; import { NzColorPickerModule, NzPresetColor } from ng-zorro-antd/color-picker; Component({ selector: nz-demo-color-picker-presets, imports: [NzColorPickerModule], template: nz-color-picker [nzPresets]customPresets nzValue#722ed1 / }) export class NzDemoColorPickerPresetsComponent { 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 } ]; }事件回调nzOnChange面板内颜色变化时触发载荷为{ color: NzColor; format: string }其中color是NzColor实例format为当前格式未显式设置nzFormat时按hex输出见 color-picker.component.tsnzOnClear点击清除按钮时触发载荷为truenzOnFormatChange用户切换 HEX / HSB / RGB 格式时触发载荷为新格式值在 color-format.component.ts 中随格式下拉框的valueChanges发出nzOnOpenChange面板打开或关闭时触发载荷为开关状态布尔值。nz-color-block 色彩块独立使用的色彩展示块组件不依赖弹层面板。API 如下参数说明类型默认值[nzColor]模块的颜色string#1677ff[nzSize]色彩块的大小large \| small \| defaultdefault[nzOnClick]点击色彩块的回调EventEmittervoid-源码实现非常轻量color-block.component.ts内部直接渲染ng-antd-color-block点击时向外冒泡nzOnClick事件尺寸通过宿主类ant-color-picker-inline-sm / ant-color-picker-inline-lg控制。典型用途是作为只读的色值预览块例如在列表中展示每个条目的标识色。NzColor统一颜色对象与六种转换方法NzColor是组件内部与回调中统一使用的颜色对象类型由Color类实例化见 color.ts。Color继承自ctrl/tinycolor的TinyColor并在构造时把 HSB 输入自动转换为 HSV 后再解析因此能同时接受 HEX 字符串、RGB/HSB 对象等多种输入ColorGenInput类型见 type.ts。NzColor暴露的方法及其返回格式参数说明类型toHex转换成hex格式字符返回格式如1677ff() stringtoHexString转换成hex格式颜色字符串返回格式如#1677ff() stringtoHsb转换成hsb对象() ({ h, s, b, a })toHsbString转换成hsb格式颜色字符串返回格式如hsb(215, 91%, 100%)() stringtoRgb转换成rgb对象() ({ r, g, b, a })toRgbString转换成rgb格式颜色字符串返回格式如rgb(22, 119, 255)() string几点源码级细节toHsb()在Color中被重写color.ts当原始输入本身就是 HSB 对象时直接沿用输入值否则由 HSV 转换得到toHsbString()会对 h、s、b 做四舍五入取整getRoundNumber并且当 alpha 不为 1 时输出hsba(h, s%, b%, a)形式透明度以a字段参与上述所有对象型方法范围 01对外推荐统一通过generateColor(input)工厂函数创建NzColor实例util.ts该函数对已存在的Color实例直接复用避免重复解析。实际使用示例import { generateColor } from ng-zorro-antd/color-picker; // 视导出路径而定可在组件内使用 const color generateColor(#1677ff); color.toHexString(); // #1677ff color.toRgbString(); // rgb(22, 119, 255) color.toHsbString(); // hsb(215, 91%, 100%) color.toHsb(); // { h: 215, s: 0.91, b: 1, a: 1 }表单集成响应式表单与 ngModelnz-color-picker实现了ControlValueAccessorcolor-picker.component.ts 提供NG_VALUE_ACCESSOR因此可以直接配合 Angular 表单体系使用。模板驱动表单ngModel摘自 demo/format.ts三种格式可分别绑定import { Component, signal } from angular/core; import { FormsModule } from angular/forms; import { NzColorPickerModule } from ng-zorro-antd/color-picker; Component({ selector: nz-demo-color-picker-format, imports: [FormsModule, NzColorPickerModule], template: div classformatnz-color-picker nzFormathex [(ngModel)]hex / HEX: {{ hex() }}/div div classformatnz-color-picker nzFormathsb [(ngModel)]hsb / HSB: {{ hsb() }}/div div classformatnz-color-picker nzFormatrgb [(ngModel)]rgb / RGB: {{ rgb() }}/div }) export class NzDemoColorPickerFormatComponent { readonly hex signal(#1677ff); readonly hsb signal(hsb(215, 91%, 100%)); readonly rgb signal(rgb(22, 119, 255)); }响应式表单FormGroup摘自 demo/use.ts颜色字段与其他字段同属一个FormGroup提交时一并取值import { Component, inject } from angular/core; import { FormBuilder, ReactiveFormsModule, Validators } from angular/forms; import { NzButtonModule } from ng-zorro-antd/button; import { NzColorPickerModule } from ng-zorro-antd/color-picker; import { NzFormModule } from ng-zorro-antd/form; Component({ selector: nz-demo-color-picker-use, imports: [ReactiveFormsModule, NzButtonModule, NzColorPickerModule, NzFormModule], template: form nz-form [formGroup]validateForm (ngSubmit)submitForm() nz-form-item nz-form-label nzSpan4color/nz-form-label nz-form-control nzSpan16 nz-color-picker formControlNamecolorPicker nzShowText / /nz-form-control /nz-form-item nz-form-item nz-form-control button nz-button nzTypeprimarysubmit/button /nz-form-control /nz-form-item /form }) export class NzDemoColorPickerUseComponent { private formBuilder inject(FormBuilder); validateForm this.formBuilder.group({ colorPicker: [#1677ff] }); submitForm(): void { console.log(this.validateForm.value); } }表单双向同步的内部机制组件通过writeValue()接收外部写入的值并刷新触发块颜色color-picker.component.ts通过setDisabledState()同步表单禁用状态nzDisabled与表单禁用取并集见 color-picker.component.ts颜色变化时经onChange回调把按nzFormat格式化的字符串写回表单控件。面板底部格式区HEX / HSB / RGB 手动输入弹出面板底部由nz-color-format组件color-format.component.ts提供精确输入能力这也是“既有色盘拖拽、又能手输精确值”的关键补充格式下拉框提供HEX / HSB / RGB三种选项切换即触发nzOnFormatChangeHEX 模式下是带#前缀的输入框输入校验正则^[0-9a-fA-F]{6}$hexValidator见 color-format.component.ts非法输入不生效HSB 模式下分别是色相0360、饱和度0100%、明度0100%三个数字输入框RGB 模式下是 R / G / B 三个 0255 的数字输入框未禁用透明度nzDisabledAlpha为false时底部追加 0100% 的透明度输入框所有输入经 200ms 防抖、去重后向外发出formatChange组件再转写回nzValue并同步表单color-picker.component.ts。FAQ滚动时浮层元素没有跟随滚动位置默认情况下浮层元素使用body作为滚动容器。如果项目中使用的是自定义滚动容器例如某个带overflow: auto的布局盒子浮层将无法跟随该容器的滚动而移动位置。解决办法在自定义滚动容器元素上添加CdkScrollable指令需从angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块使 CDK Overlay 能够感知该容器并同步浮层位置。这也与组件底层使用NzPopoverDirective基于 CDK Overlay 实现的机制一致。源码结构与延伸阅读如果希望深入理解组件实现可以在当前仓库中按以下路径继续探索组件门面与表单逻辑color-picker.component.ts、color-block.component.ts类型定义typings.ts颜色引擎HSB/HSV 换算、格式化输出color.ts、util.ts面板内部实现色盘、滑杆、预设渲染picker.component.ts、slider.component.ts、gradient.directive.ts样式入口index.less测试用例color-picker.component.spec.ts、color-block.component.spec.ts组件对外导出public-api.ts赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐MCP协议深度解析使用Teams SDK将Teams聊天转化为AI代理交互平台MCP协议深度解析使用Teams SDK将Teams聊天转化为AI代理交互平台 Teams SDK是专注于为Microsoft Teams和其他Bot FraUI组件前端ng-zorro-antd ColorPicker 颜色编码格式HEX / HSB / RGB实战指南ng zorro antd ColorPicker 颜色编码格式HEX / HSB / RGB实战指南 nz color picker 是 ng zorroUI组件前端ng-zorro-antd Checkbox 组件完全指南API、源码原理与全选/半选实战ng zorro antd Checkbox 组件完全指南API、源码原理与全选/半选实战 ng zorro antd 是基于 Ant Design 设计体系UI组件前端上一篇Hearthstone-Script终极指南如何用开源炉石脚本实现智能自动对战下一篇如何3分钟完成Windows和Office智能激活KMS_VL_ALL_AIO使用详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考