u
This commit is contained in:
oneao committed
1 parent
5f28a10d89
commit
32d423b759
59 files changed
+5101
-1098
No files matched your search
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: ColorPicker 颜色选择器
|
||||
description: 从色板或取色面板里挑一个颜色，值统一为 #rrggbb
|
||||
---
|
||||
|
||||
# ColorPicker 颜色选择器
|
||||
|
||||
颜色选择器由「触发器色块」和「浮层取色面板」两部分组成：点色块展开面板，面板里有饱和度 / 明度取色区、色相条和 hex 输入框，需要时还能带上预设色板。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 主题色、标签色、图表配色的自定义入口；
|
||||
- 需要精确输入某个色值时（hex 输入框可直接粘贴）；
|
||||
- 业务里已有若干备选色，希望点一下就能选（用 `presets`）。
|
||||
|
||||
如果只是二选一（如深色 / 浅色），用 [Segmented](/ui/general/segmented) 更轻。
|
||||
|
||||
## 基础用法
|
||||
|
||||
`v-model` 双向绑定，值为 `#rrggbb` 字符串。
|
||||
|
||||
<demo vue="color-picker/basic.vue" />
|
||||
|
||||
## 预设色板
|
||||
|
||||
`presets` 默认 `true`，内置一组「常用」色（8 个高频主色），点一下即可选中，不必开取色面板：
|
||||
|
||||
| 分组 | 色值 |
|
||||
| --- | --- |
|
||||
| 常用 | 蓝 / 深蓝 / 绿 / 红 / 橙 / 黄 / 青 / 紫 |
|
||||
|
||||
恰好 8 个，铺满预设区的 8 列网格。
|
||||
|
||||
需要更多分组或换成业务自己的配色时，传分组数组即可（组件不预置更多）；传 `false` 则只留取色面板。
|
||||
|
||||
<demo vue="color-picker/presets.vue" />
|
||||
|
||||
## 尺寸与禁用
|
||||
|
||||
<demo vue="color-picker/size.vue" />
|
||||
|
||||
## API
|
||||
|
||||
### Props
|
||||
|
||||
| 名称 | 类型 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `modelValue` | `string` | — | 双向绑定的颜色值（`#rrggbb`）。不传即非受控 |
|
||||
| `defaultValue` | `string` | `'#165dff'` | 非受控时的初始值 |
|
||||
| `disabled` | `boolean` | `false` | 禁用态，触发器与面板都不可交互 |
|
||||
| `presets` | `boolean \| ColorPickerPresetGroup[]` | `true` | 预设色板。`true` 用内置色板，数组自定义，`false` 隐藏 |
|
||||
| `placeholder` | `string` | `''` | 触发器的 `aria-label`（同时也是无值时的无障碍文案） |
|
||||
| `popupContainer` | `string \| HTMLElement` | `body` | 浮层挂载容器 |
|
||||
| `size` | `'small' \| 'default' \| 'large'` | `'default'` | 触发器尺寸 |
|
||||
|
||||
### Events
|
||||
|
||||
| 名称 | 参数 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `update:modelValue` | `(value: string)` | 颜色变化时触发（受控与非受控都会触发） |
|
||||
| `change` | `(value: string)` | 同上，便于只监听变化 |
|
||||
|
||||
### Exposed
|
||||
|
||||
| 名称 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `open` | `Ref<boolean>` | 面板当前是否展开 |
|
||||
| `close` | `() => void` | 主动收起面板 |
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
export type ColorPickerValue = string
|
||||
|
||||
export interface ColorPickerPresetGroup {
|
||||
/** 分组标题（可选） */
|
||||
label?: string
|
||||
/** 该组的颜色列表，hex 字符串 */
|
||||
colors: string[]
|
||||
}
|
||||
```
|
||||
|
||||
### 样式变量
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `--g3-radius-sm` | `4px` | 触发器与面板内各块圆角 |
|
||||
| `--g3-border-color` | `#d9d9d9` | 触发器描边、hex 输入框边框 |
|
||||
| `--g3-bg-container` | `#fff` | hex 输入框与吸管按钮底色 |
|
||||
| `--g3-color-primary` | `#165dff` | hex 输入框聚焦边框、吸管按钮悬停色 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
- **值的格式固定为 `#rrggbb`**。面板内部用 HSV 运算（HSV 的 S/V 平面能画出标准的「右上纯色 → 左白 → 下黑」二维取色区），对外始终归一成 hex；
|
||||
- 触发器是**真实 `<button>`**，尺寸稳定，不存在原生 `<input type="color">` 那种「只有控件本体可点、点击热区随图标大小塌缩」的问题；
|
||||
- hex 输入框允许**边输边改**：内容不合法时不写回，失焦后还原成当前值，避免停在半截草稿上；
|
||||
- 面板里的「吸管」按钮走原生 `HTMLInputElement.showPicker()`，**仅在浏览器支持时才渲染**（能力检测在模块初始化时做一次）；
|
||||
- 色板选中态用白色对勾 + 描边投影标记，浅色与深色底上都能看清。
|
||||
|
||||
## 与 RTL 的关系
|
||||
|
||||
取色面板的横轴是**颜色空间本身**，不是行内方向，因此**刻意不镜像**：
|
||||
|
||||
| 位置 | 行为 |
|
||||
| --- | --- |
|
||||
| 饱和度 / 明度取色区 | 恒为「左 = 低饱和，右 = 高饱和」 |
|
||||
| 色相条 | 恒为「左 = 红（0°），右 = 红（360°）」 |
|
||||
| 光标定位与拖拽取值 | 与上面两条一致，走 `clientX - rect.left` |
|
||||
|
||||
原因：这些渐变是 `linear-gradient(to right, …)` 的**物理**方向，`[dir='rtl']` 不会翻转它。
|
||||
如果只把 JS 的取值方向反向、却不管渐变，光标位置就会和它底下的颜色对不上。
|
||||
颜色空间没有「语言方向」，Photoshop / Figma / 浏览器 DevTools 的取色器在 RTL 下同样不镜像。
|
||||
|
||||
面板其余部分（内边距、色板网格、hex 输入框与吸管按钮的排布）都**没有左右不对称的物理属性**，
|
||||
所以 RTL 下无需任何额外处理。详见[双向布局（RTL）](/ui/usage/rtl)。
|
||||
Reference in new issue
Block a user