前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载ColorPicker 是 TDesign 针对 UniApp 生态提供的一体化颜色选择组件支持 base系统预设色与 multiple色板 系统预设色两种形态内置 HEX、RGB、HSL、HSV、CMYK、CSS 等十种色值格式的自由切换并可通过usePopup快速切换为底部弹窗模式。本文以 ColorPicker 官方文档 为主线结合tdesign/uniapp的源码实现从引入方式、属性/事件/插槽 API、scroll-view 场景适配到底层色值运算原理进行系统讲解帮助开发者在表单、主题定制、绘图工具等场景中直接落地使用。一、组件引入easycom 与手动注册两种方式官方推荐使用easycom 模式引入组件配置完成后无需手动 import即可直接在模板中使用t-color-picker /标签。该模式是 UniApp 内置的组件自动注册机制可减少每个页面重复 import 的样板代码。若项目未开启 easycom或需要在特定页面局部使用可采用手动引入方式import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue;并在页面/组件的components字段中注册后使用script import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue; export default { components: { TColorPicker, }, }; /script说明tdesign/uniapp是仓库中 UniApp 组件包的 npm 包名组件源码位于 packages/uniapp-components/color-picker/入口组件为 color-picker.vue类型定义统一收敛在 type.ts。二、组件类型base 与 multiple 两种形态基础颜色选择器base默认type为base仅展示系统预设色块区域用户点击预设色即可完成选择template view t-color-picker changeonChange / /view /template script import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue; export default { components: { TColorPicker, }, methods: { onChange(e) { console.log(change:, e); }, }, }; /script该示例对应仓库演示代码 packages/uniapp-components/color-picker/_example/base/index.vue。带色板的颜色选择器multiple将type指定为multiple后组件会额外渲染 HSB 饱和度面板saturation panel、色相滑动条hue slider与可选的不透明度滑动条alpha slider配合系统预设色一起使用是完整的自由取色形态template view t-color-picker enable-alpha typemultiple changeonChange palette-bar-changeonPaletteBarChange / /view /template script import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue; export default { components: { TColorPicker, }, methods: { onChange(e) { console.log(change, e); }, onPaletteBarChange(e) { console.log(onPaletteBarChange, e); }, }, }; /script对应演示代码见 packages/uniapp-components/color-picker/_example/multiple/index.vue。从 template.vue 的渲染逻辑可以看到组件内部通过isMultiple控制饱和度面板、色相/透明度滑动条、格式输入区、系统预设色区域的显隐并且isMultiple与type属性通过 watch 实时联动见 color-picker.vue 中的typewatcher。三、组件状态色值格式format自由切换format属性用于控制组件对外输出的色值格式默认值为RGB。可选项共 10 种| 格式 | 示例输出 | 说明 | | -- | -- | -- | | HEX |#0052D9| 6 位十六进制色值 | | HEX8 |#0052D9FF| 8 位十六进制色值含透明度 | | RGB |rgb(0, 82, 217)| 红绿蓝三通道 | | RGBA |rgba(0, 82, 217, 1)| 红绿蓝 透明度 | | HSL |hsl(217, 100%, 43%)| 色相/饱和度/明度 | | HSLA |hsla(217, 100%, 43%, 1)| HSL 透明度 | | HSV |hsv(217, 100%, 85%)| 色相/饱和度/明度色彩模型 | | HSVA |hsva(217, 100%, 85%, 1)| HSV 透明度 | | CMYK |cmyk(100, 61, 0, 15)| 印刷四分色 | | CSS |rgba(...)或linear-gradient(...)| CSS 原生色值 / 渐变色 |官方文档特别说明当enableAlpha为真时HEX8 / RGBA / HSLA / HSVA四种带透明通道的格式才真正有效。format属于组件状态维度通常与受控的value搭配使用。仓库示例 packages/uniapp-components/color-picker/_example/format/index.vue 展示了如何通过点击切换格式template view view v-for(list, index) in formatList :keyindex classformat-line view v-for(item, index1) in list :keyindex1 :classformat-item (curFormat item ? active : ) :data-formatitem click.stop.preventclickFormat t-icon v-ifcurFormat item namecheck size14 / {{ item }} /view /view t-color-picker enable-alpha typemultiple :formatcurFormat :valuecolor changeonChange palette-bar-changeonPaletteBarChange / /view /template script import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue; import TIcon from tdesign/uniapp/icon/icon.vue; export default { components: { TColorPicker, TIcon, }, data() { return { curFormat: CSS, color: #7bd60b, formatList: [ [CSS, HEX, RGB], [HSL, HSV, CMYK], ], }; }, methods: { onChange(e) { console.log(change, e); }, onPaletteBarChange(e) { console.log(onPaletteBarChange, e); }, clickFormat(e) { this.curFormat e.target.dataset.format; }, }, }; /script值得说明的是format不仅决定对外输出格式也决定组件输入区format-list展示的分量数值。在 color-picker.vue 的getFormatList()中各格式被映射到 HSV/HSL/RGB/CMYK 分量数组并把透明度单独以百分比呈现formatValue()则通过Color.getFormatsColorMap()[this.format]取对应格式字符串返回给change事件。四、弹窗模式usePopup visible 受控显隐默认情况下 ColorPicker 以内嵌面板形式渲染。设置use-popup即usePopup为true后组件会使用底部弹出的 Popup 层包裹整个选择面板适合在设置页、表单页等空间受限的场景中使用。此时需配合visible属性受控控制显隐template view t-color-picker :visiblevisible use-popup enable-alpha typemultiple update:visible(e) (visible e) changeonChange palette-bar-changeonPaletteBarChange / t-button block sizelarge variantoutline themeprimary clickhandlePopup 弹窗形式的颜色选择器 /t-button /view /template script import TButton from tdesign/uniapp/button/button.vue; import TColorPicker from tdesign/uniapp/color-picker/color-picker.vue; export default { components: { TColorPicker, TButton, }, data() { return { visible: false, }; }, methods: { onChange(e) { console.log(change, e); }, handlePopup() { this.visible true; }, onPaletteBarChange(e) { console.log(onPaletteBarChange, e); }, }, }; /script对应演示代码见 packages/uniapp-components/color-picker/_example/use-popup/index.vue。从 color-picker.vue 的实现细节可以补充两点弹窗模式下组件会透传popup-props给底部 Popup内置默认值包括show-overlay为true、z-index为11500、placementbottomPopup 的全部属性closeOnOverlayClick、duration、overlayProps、usingCustomNavbar等均可通过popup-props覆盖完整类型定义见 packages/uniapp-components/popup/type.ts。弹窗打开时会延迟约 350ms 再执行元素位置测量onWatchPopupVisible这是因为 Popup 的过渡动画时长为 300ms需等面板真正渲染完成后再计算饱和度面板与滑动条的区域尺寸从而保证拖拽坐标换算准确。另外visible与dataVisible通过 watch 双向联动点击遮罩层后组件会同步派发update:visible事件因此示例中通过update:visible回写visible即可形成闭环的受控状态。五、FAQscroll-view 场景下的定位适配官方文档专门提示了一个高频坑当 ColorPicker 的使用场景位于scroll-view中时除了需要显式指定fixed属性为true还必须手动调用组件实例的debouncedUpdateEleRect()方法否则面板拖拽坐标会随滚动偏移产生错位。原文档给出的小程序侧示例同为tdesign/uniapp组件体系的用法scroll-view typelist scroll-y bind:scrollonScroll t-color-picker idColorPicker fixed / /scroll-viewonScroll(e) { if (!this.colorPicker) this.colorPicker this.selectComponent(#ColorPicker); this.colorPicker.debouncedUpdateEleRect(e); }在 UniApp 组合式/选项式 API 中可以通过uni.createSelectorQuery()或$refs拿到组件实例后调用同名方法template scroll-view scroll-y typelist scrollonScroll t-color-picker refColorPicker fixed / /scroll-view /template script export default { methods: { onScroll(e) { this.$nextTick(() { this.$refs.ColorPicker.debouncedUpdateEleRect(e); }); }, }, }; /script之所以需要这一步骤可以从源码中找到依据color-picker.vue 在mounted中创建了防抖函数this.debouncedUpdateEleRect debounce((e) this.updateEleRect(e), 150);updateEleRect()会读取scroll-view滚动事件中的e.detail.scrollTop并以初始面板顶部位置initTop减去当前滚动距离来更新panelRect.top。而饱和度拖拽与滑动条拖拽的坐标换算getCoordinate()正是依赖panelRect/sliderRect的top/left值滚动不更新这些值就会导致取色位置与实际手指位置不一致。防抖时长 150ms 与mounted中 33ms 的初始化延迟均可在 common/utils.js 的debounce实现与组件挂载逻辑中查证。fixed属性则对应坐标计算中的分支当fixed或弹窗模式usePopup为真时getCoordinate()使用事件中的clientY与已测量的rect.top计算 Y 坐标而非依赖offsetTop以此规避position:fixed容器内的定位偏差。六、ColorPicker Props 完整 API以下属性表完整继承自官方文档含默认值与类型说明| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式 | N | | auto-close | Boolean | true | 自动关闭。在点击遮罩层时自动关闭不需要手动设置 visible | N | | enable-alpha | Boolean | false | 是否开启透明通道 | N | | fixed | Boolean | false | 如果 color-picker 是在一个position:fixed的区域需要显式指定属性 fixed 为 true | N | | format | String | RGB | 格式化色值。enableAlpha为真时HEX8/RGBA/HSLA/HSVA有效。可选项HEX/HEX8/RGB/RGBA/HSL/HSLA/HSV/HSVA/CMYK/CSS | N | | popup-props | Object | {} | 透传 Popup 组件全部属性TS 类型为PopupProps见 packages/uniapp-components/popup/type.ts | N | | swatch-colors | Array | undefined | 系统预设的颜色样例值为null或[]则不显示系统色值为undefined会显示组件内置的系统默认色。TS 类型Arraystring \| null \| undefined| N | | type | String | base | 颜色选择器类型base仅展示系统预设内容/ multiple展示色板和系统预设内容。TS 类型TypeEnum base \| multiple| N | | use-popup | Boolean | false | 是否使用弹出层包裹颜色选择器 | N | | value | String | - | 色值。支持语法糖v-model:value| N | | default-value | String | - | 色值。非受控属性 | N | | visible | Boolean | false | 是否显示颜色选择器。usePopup为 true 时有效 | N |属性实现与校验细节以上属性的运行时定义含默认值与枚举校验位于 props.tsformat与type均内置validator只接受文档列出的枚举值传入非法值会被拦截value与defaultValue的默认值均为空字符串组件在created阶段使用defaultValue || value || DEFAULT_COLOR初始化Color实例swatchColors的默认值为null而组件内置的系统预设色定义在 constants.ts 中DEFAULT_SYSTEM_SWATCH_COLORS为 10 个 TDesign 品牌蓝紫色系色值。从genSwatchList()的逻辑可以看到三者取值差异传undefined→ 使用内置默认色传null或[]→ 隐藏系统色区域传颜色数组 → 完全自定义预设色组件默认色DEFAULT_COLOR #001F97色相最大值HUE_MAX 360、透明度最大值ALPHA_MAX 100等常量同样定义在 constants.ts。受控与非受控用法受控模式使用value支持v-model:value语法糖配合change事件更新外部状态非受控模式只设置default-value组件内部维护色值适合无需外部回读的简单取色场景。七、ColorPicker Events 事件说明| 名称 | 参数 | 描述 | | -- | -- | -- | | change |(context: { value: string, context: { color: ColorObject; trigger: ColorPickerChangeTrigger }})| 选中的色值发生变化时触发第一个参数value表示新色值context.color表示当前调色板控制器的色值context.trigger表示触发颜色变化的来源。type ColorPickerChangeTrigger palette-hue-bar \| palette-alpha-bar \| preset| | close |(context: { trigger: ColorPickerTrigger })| 关闭按钮时触发。type ColorPickerTrigger overlay| | palette-bar-change |(context: { color: ColorObject })| 调色板控制器的值变化时触发context.color指调色板控制器的值。interface ColorObject { alpha: number; css: string; hex: string; hex8: string; hsl: string; hsla: string; hsv: string; hsva: string; rgb: string; rgba: string; value: number; }|事件触发来源trigger解析从 color-picker.vue 的方法实现可以梳理出trigger的完整取值路径palette-hue-bar拖动色相滑动条时触发onChangeSlider({ value, isAlpha: false })palette-alpha-bar拖动透明度滑动条时触发onChangeSlider({ value, isAlpha: true })preset点击系统预设色块时触发clickSwatch()。此外饱和度面板拖拽会先派发palette-bar-change再按实际变化的维度派发change内部区分palette-saturation/palette-brightness/palette-saturation-brightness三种细分来源方便需要实时预览的场景消费。ColorObject是组件对外输出的统一色值对象包含alpha、css、hex、hex8、hsl、hsla、hsv、hsva、rgb、rgba、value等字段其构造逻辑见 common/shared/color-picker/color.js 中的getColorObject()。八、ColorPicker Slots 插槽| 名称 | 描述 | | -- | -- | | footer | 底部插槽仅在usePopup为true时有效 | | header | 顶部插槽仅在usePopup为true时有效 |从 color-picker.vue 的模板结构可以看到header/footer插槽只渲染在t-popup分支内且分别位于面板模板template-vue的上方与下方适合放置自定义标题栏、确认/取消按钮等弹窗配套元素。九、CSS Variables 自定义样式组件将面板、饱和度区域、滑动条、预设色块等关键样式全部抽成了 CSS 变量开发者无需覆盖组件内部 class直接通过变量即可实现主题定制。完整变量表如下默认值来自官方文档| 名称 | 默认值 | 描述 | | -- | -- | -- | | --td-color-picker-gradient-preview-height | 56rpx | 渐变预览高度 | | --td-color-picker-gradient-preview-radius | 6rpx | 渐变预览圆角 | | --td-color-picker-gradient-preview-width | 56rpx | 渐变预览宽度 | | --td-color-picker-input-format-margin-left | 48rpx | 格式输入区左间距 | | --td-color-picker-panel-background | bg-color-container | 面板背景色 | | --td-color-picker-panel-padding | 32rpx | 面板内边距 | | --td-color-picker-panel-radius | 24rpx | 面板圆角 | | --td-color-picker-panel-width | 750rpx | 面板宽度 | | --td-color-picker-saturation-height | 288rpx | 饱和度面板高度 | | --td-color-picker-saturation-radius | 12rpx | 饱和度面板圆角 | | --td-color-picker-saturation-thumb-size | 48rpx | 饱和度取色圆点尺寸 | | --td-color-picker-slider-height | 16rpx | 滑动条高度 | | --td-color-picker-slider-thumb-padding | 6rpx | 滑动条滑块内边距 | | --td-color-picker-slider-thumb-size | 48rpx | 滑动条滑块尺寸 | | --td-color-picker-slider-thumb-transform-x | -18rpx | 滑动条滑块水平偏移 | | --td-color-picker-slider-wrapper-padding | 0 18rpx | 滑动条容器内边距 | | --td-color-picker-swatch-border-radius | radius-small | 预设色块圆角 | | --td-color-picker-swatch-height | 48rpx | 预设色块高度 | | --td-color-picker-swatch-padding | 0 | 预设色块内边距 | | --td-color-picker-swatch-width | 48rpx | 预设色块宽度 | | --td-color-picker-swatches-title-font | font-title-medium | 预设色标题字体 |这些变量在 color-picker.less 中逐一声明并被面板样式引用且默认值均引用 TDesign 设计变量如bg-color-container、radius-small、font-title-medium因此与整套 TDesign 主题体系天然打通。使用方式示例/* 自定义取色面板宽度与圆角 */ .t-color-picker { --td-color-picker-panel-width: 690rpx; --td-color-picker-panel-radius: 32rpx; --td-color-picker-saturation-height: 320rpx; }十、底层实现原理色值运算与渐变支持理解 ColorPicker 的多格式输出能力需要看它的色值核心——Color类packages/uniapp-components/common/shared/color-picker/color.js它由 utils.js 统一对外导出。1. 统一色彩模型与实时转换Color内部以HSV 四元组h/s/v/a作为唯一状态源this.states任何输入HEX、RGB、HSL、CMYK、渐变字符串等都会先归一化为 HSV 状态输出时则通过 tinycolor 库或自研转换函数即时计算各格式字符串rgb/rgbahsv2rgba(this.states)hsl/hslahsv2hsla(this.states)hex/hex8tinyColor(this.states).toHexString() / toHex8String()cmyk先转 RGB再经rgb2cmyk计算 C/M/Y/K见 common/shared/color-picker/cmyk.jscss普通色返回rgba(...)渐变色返回linear-gradient(...)字符串。getFormatsColorMap()汇总了全部 10 种格式的取值函数正是组件formatValue()与getFormatList()的数据来源。2. 渐变色支持Color额外维护一组gradientStatescolor 点集合 角度 选中点通过 common/shared/color-picker/gradient.js 的正则解析引擎将linear-gradient(135deg, #fff 0%, #000 100%)形式的字符串反解析为可编辑的渐变点对象并支持在拖动色相/透明度时实时回写当前选中渐变点updateCurrentGradientColor()。因此formatCSS时组件不仅能展示、还能编辑渐变色这也解释了 CSS Variables 中--td-color-picker-gradient-preview-*一组变量的存在意义。3. 拖拽取色的坐标换算面板交互饱和度拖动、色相/透明度滑动条拖动统一走onTouchStart / onTouchMove / onTouchEnd→handleDiffDrag()→handleSaturationDrag() / handleSliderDrag()的链路饱和度saturation x / widthvalue 1 - y / height结果钳制在[0, 1]色相滑动条按x / width × HUE_MAX(360)换算并钳制透明度滑动条按x / width × ALPHA_MAX(100)换算。最终通过onChangeSlider()/onChangeSaturation()更新Color状态、派发palette-bar-change与change事件再调用setCoreStyle()刷新滑块位置与格式输入区。结语TDesign 的 ColorPicker 组件以typebase/multiple、format10 种色值格式、usePopup内嵌/弹窗三个核心维度覆盖了绝大多数移动端取色诉求。在 packages/uniapp-components/color-picker/ 目录下官方还提供了 base、multiple、format、use-popup 四组可直接运行参考的演示工程_example目录配合本文的属性、事件、插槽与 CSS 变量说明即可快速完成从引入组件到深度定制的完整接入。若使用中遇到scroll-view内取色偏移问题记得按第五节方案显式设置fixed并联动调用debouncedUpdateEleRect()。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐element-react ColorPicker 颜色选择器完全指南多格式颜色取值、Alpha 通道与 onChange 回调实战element react ColorPicker 颜色选择器完全指南多格式颜色取值、Alpha 通道与 onChange 回调实战 ColorPicker前端UI组件设计系统Element Plus ColorPicker 颜色选择器完整指南多格式色值、Alpha 通道与预定义色板Element Plus ColorPicker 颜色选择器完整指南多格式色值、Alpha 通道与预定义色板 ColorPicker 是 Element Pl前端UI组件REA 逆向工程技能 reverse-engineer-anything 安装指南一条命令给 AI 编码助手装好逆向工作流REA 逆向工程技能 reverse engineer anything 安装指南一条命令给 AI 编码助手装好逆向工作流 手上有目标程序却没有一行源代码—逆向工程MCP 服务AI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
