# @dayflow/blossom-color-picker 中文文档

规范地址：https://npmcn.com/package/%40dayflow/blossom-color-picker/

版本：2\.5\.0
npm 元数据更新时间：2026-10-23T21:28:46.316Z
中文译文更新时间：2026-11-11T16:34:41.630Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dayflow/blossom-color-picker
原文对照：https://npmcn.com/package/%40dayflow/blossom-color-picker/?lang=original
项目主页：https://github.com/dayflow-js/BlossomColorPicker#readme
源码仓库：https://github.com/dayflow-js/BlossomColorPicker

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：523 kB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-05T15:10:18.834Z
- 最新版本发布：2026-10-23T21:28:46.134Z
- 近 30 天下载量：76523（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

一个美丽而开花的取花者——独立的香草

## 安装

```sh
npm install @dayflow/blossom-color-picker
```

也可以使用：`pnpm add @dayflow/blossom-color-picker`、`yarn add @dayflow/blossom-color-picker`、`bun add @dayflow/blossom-color-picker`

## README

# 花色选取器

[![npm version](https://img.shields.io/npm/v/@dayflow/blossom-color-picker.svg)](https://www.npmjs.com/package/@dayflow/blossom-color-picker) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/dayflow-js/BlossomColorPicker/pulls) [![GitHub license](https://img.shields.io/github/license/dayflow-js/BlossomColorPicker)](https://github.com/dayflow-js/BlossomColorPicker/blob/main/LICENSE)

美丽的花朵花朵 网络取色器。 作为独立的"香草"JS类,或作为一薄回放/Vue/Svelte/Angular包装.

[https://github.com/user-attachments/assets/553ee0ff-1f52-497f-bc8f-cee9a7b91d66 页面存档备份,存于互联网档案馆](https://github.com/user-attachments/assets/553ee0ff-1f52-497f-bc8f-cee9a7b91d66)

## 软件包

| 软件包 | 说明 | 版本 |
| :-- | :-- | :-- |
| `@dayflow/blossom-color-picker` | 香草联署材料核心(零依赖性) | 2.0.0 (韩语) |
| `@dayflow/blossom-color-picker-react` | 反应包装 | 1.0.0 (单位:千美元) |
| `@dayflow/blossom-color-picker-vue` | Vue 3 包装 | 1.0.0 (单位:千美元) |
| `@dayflow/blossom-color-picker-svelte` | 斯维尔特包装器 | 1.0.0 (单位:千美元) |
| `@dayflow/blossom-color-picker-angular` | 角包装器 | 1.0.0 (单位:千美元) |

## 安装

```bash
# Vanilla JS (core)
npm install @dayflow/blossom-color-picker

# React
npm install @dayflow/blossom-color-picker-react

# Vue 3
npm install @dayflow/blossom-color-picker-vue

# Svelte
npm install @dayflow/blossom-color-picker-svelte

# Angular
npm install @dayflow/blossom-color-picker-angular
```

## 使用量

### 香草联署材料

```js
import { BlossomColorPicker } from '@dayflow/blossom-color-picker';
import '@dayflow/blossom-color-picker/styles.css';

const picker = new BlossomColorPicker(document.getElementById('picker'), {
  onChange: color => console.log(color.hex),
});

// Programmatic control
picker.expand();
picker.collapse();
picker.toggle();
picker.setValue({ hue: 200, saturation: 50, alpha: 100, layer: 'outer' });
picker.setOptions({ disabled: true });
picker.destroy();
```

### 反应

```tsx
import { BlossomColorPicker } from '@dayflow/blossom-color-picker-react';

function App() {
  const [color, setColor] = useState({
    hue: 330,
    saturation: 70,
    alpha: 100,
    layer: 'outer' as const,
  });

  return <BlossomColorPicker value={color} onChange={c => setColor(c)} />;
}
```

### 第3组

```vue
<script setup>
import { ref } from 'vue';
import { BlossomColorPicker } from '@dayflow/blossom-color-picker-vue';

const color = ref({
  hue: 330,
  saturation: 70,
  alpha: 100,
  layer: 'outer',
});

function handleChange(c) {
  color.value = c;
}
</script>

<template>
  <BlossomColorPicker :value="color" @change="handleChange" />
</template>
```

### 丝绒

```svelte
<script>
  import { BlossomColorPicker } from '@dayflow/blossom-color-picker-svelte';

  let color = $state({
    hue: 330, saturation: 70, alpha: 100, layer: 'outer',
  });

  function handleChange(newColor) {
    color = newColor;
  }
</script>

<BlossomColorPicker value={color} onchange={handleChange} />
```

### 角质

```typescript
import { Component } from '@angular/core';
import {
  BlossomColorPickerComponent,
  type BlossomColorPickerColor,
} from '@dayflow/blossom-color-picker-angular';

@Component({
  selector: 'app-root',
  imports: [BlossomColorPickerComponent],
  template: `
    <blossom-color-picker
      [value]="color"
      (colorChange)="onColorChange($event)"
    />
  `,
})
export class App {
  color = { hue: 330, saturation: 70, alpha: 100, layer: 'outer' as const };

  onColorChange(c: BlossomColorPickerColor) {
    this.color = c;
  }
}
```

## 选项/ 道具

所有软件包共享相同的一组选项. 在反应中,它们作为JSX道具被传递;在Vue作为组件道具被传递(与事件通过 `@change` 编号 : `@collapse`);在斯维尔特语中作为回调道具(Svelte)`onchange` 编号 : `oncollapse`; 以角为单位 `@Input()` 绑定( 通过 `(colorChange)` 编号 : `(colorCollapse)`) (中文(简体) ).

| 选项 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| `value` | `BlossomColorPickerValue` | \- 说吧 | 已控制采取器的值 . |
| `defaultValue` | `BlossomColorPickerValue` | `{ hue: 330, saturation: 70, alpha: 100, layer: 'outer' }` | 非控制模式的初始值 . |
| `colors` | `ColorInput[]` | (18-颜色套装) | 颜色列表, 自动排序并分层分布 . |
| `onChange` | `(color: BlossomColorPickerColor) => void` | \- 说吧 | 颜色变化时调用. 阴: `@change`。斯维尔特: `onchange`角 : `(colorChange)`。 。 。 . |
| `onChangeComplete` | `(color: BlossomColorPickerColor) => void` | \- 说吧 | 在花瓣活化或阴暗的姿态结束后召回一次. 阴: `@change-complete`。斯维尔特: `onchangecomplete`角 : `(colorChangeComplete)`。 。 。 . |
| `onCollapse` | `(color: BlossomColorPickerColor) => void` | \- 说吧 | 取者倒地时召入. 阴: `@collapse`。斯维尔特: `oncollapse`角 : `(colorCollapse)`。 。 。 . |
| `onHover` | `(color: BlossomColorPickerColor | null) => void` | \- 说吧 | 用花瓣的颜色调用它会选择它被徘徊或键盘聚焦时,并使用 `null` 当它结束。 阴: `@hover`。斯维尔特: `onhover`角 : `(colorHover)`。 。 。 . |
| `disabled` | `boolean` | `false` | 采取器是否被禁用 . |
| `openOnHover` | `boolean` | `false` | 如果选中的话, 请在盘旋时打开拾取器, 而不是点击 . |
| `initialExpanded` | `boolean` | `false` | 采取器是否开始扩展 . |
| `animationDuration` | `number` | `280` | 花开动画的基时间用ms;每个相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. |
| `showShadeSlider` | `boolean` | `true` | 是否显示阴影( 光滑) 弧滑动 . |
| `showAlphaSlider` | `boolean` | `true` | 折旧的别名 `showShadeSlider`;在提供两者时,新名称优先. |
| `coreSize` | `number` | `32` | 以px表示的中央圆相径. |
| `petalSize` | `number` | `32` | Px中单色花瓣的相位. |
| `showCoreColor` | `boolean` | `false` | 当为真时,核心在扩展时显示所选颜色;否则为白色. |
| `hoverPreview` | `boolean` | `false` | 当真的,戒指,核心(与 `showCoreColor`),并背景显示被取出之前被徘徊或被聚焦的花瓣颜色. |
| `petalShape` | `'circle' | 'sakura' | 'lotus' | 'pinwheel'` | `'circle'` | 花瓣轮廓. `sakura`:有被子尖的宽花瓣. `lotus`:被打成尖尖的圆形基座. `pinwheel`:尖端被扫到一面,所以花朵看起来像是在转动. 外形花瓣离核心较远,从基部到尖端有轻度遮蔽并被忽略 `--bcp-petal-shadow`。 。 。 . |
| `petalStyle` | `'flat' | 'veined'` | `'flat'` | 外形花瓣上的表面细节. `veined` 每个花瓣上画出一条中肋和侧脉. 忽略当 `petalShape` 实值 `circle`。 。 。 . |
| `sliderPosition` | `'top' | 'bottom' | 'left' | 'right'` | `'right'` | 弧形滑轮固定位置. |
| `adaptivePositioning` | `boolean` | `true` | **智能移动器**: 自动将取取取器移到取取取器内,并重新定位取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取. |
| `className` 编号 : `class` | `string` | `""` | 额外的 CSS 类( 反应 : `className`斯维尔特: `class`) (中文(简体) ). |

### CSS 变量

把这些放在 `.bcp-root` 或任何以取取者为主题的祖先. 每一个都回到默认的外观,所以让它们未设置会改变什么.

| 变量 | 默认 | 样式 |
| :-- | :-- | :-- |
| `--bcp-surface` | `#FFFFFF` | 花瓣后的背景盘. |
| `--bcp-surface-shadow` | 软投影 | 背景盘的阴影. |
| `--bcp-tint-opacity` | `0.15` | 磁盘上所选取的彩色锡的强度 . |
| `--bcp-track` | `rgba(0, 0, 0, 0.06)` | 环和荫滑道的未填轨. |
| `--bcp-petal-shadow` | `none` | 每花瓣下有阴影. |
| `--bcp-petal-shadow-hover` | `--bcp-petal-shadow` | 花瓣下有阴影. |
| `--bcp-petal-hover-scale` | `1.1` | 徘徊花瓣长出多少. |
| `--bcp-petal-hover-brightness` | `1.1` | 有多少花瓣的亮度. |
| `--bcp-petal-vein-color` | `#fff` | 静脉线的颜色 `petalStyle: 'veined'`。 。 。 . |
| `--bcp-petal-vein-opacity` | `0.5` | 脉行不通. |
| `--bcp-core-bg` | `#FFFFFF` | 扩展时的核心颜色 `showCoreColor` 关闭. |
| `--bcp-core-shadow` | 微妙的环 + 阴影 | 扩张后核心的影子. |
| `--bcp-trigger-shadow` | `0 2px 8px rgba(0, 0, 0, 0.12)` | 崩溃的扳机的阴影. |
| `--bcp-trigger-shadow-hover` | `0 4px 14px rgba(0, 0, 0, 0.18)` | 悬回扳机的阴影. |
| `--bcp-handle-border` | `white` | 阴影滑动手柄的外观 . |
| `--bcp-focus-ring` | `#3b82f6` | 键盘焦点大纲. |
| `--bcp-focus-ring-gap` | `white` | 核心与重点纲要之间的差距. |

```css
.my-dark-theme .bcp-root {
  --bcp-surface: #1e1b2e;
  --bcp-core-bg: #1e1b2e;
  --bcp-track: rgba(255, 255, 255, 0.12);
  --bcp-handle-border: #1e1b2e;
  --bcp-focus-ring-gap: #1e1b2e;
}
```

### 香草联署材料方法

核心类暴露出这些额外的方法:

| 方法 | 说明 |
| :-- | :-- |
| `setValue(value)` | 设置当前颜色值 . |
| `getValue()` | 获取当前颜色为 `BlossomColorPickerColor`。 。 。 . |
| `expand()` | 开取者. |
| `collapse()` | 关取取者. |
| `toggle()` | 切换打开/ 关闭 . |
| `setOptions(opts)` | 运行时更新任何选项 . |
| `destroy()` | 删除所有 DOM 元素和事件听众 . |

## 特征

### 智能移位器和可适应UI

取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 何时 `adaptivePositioning` 启用 :

-   **查看端口移动**:如果被扩展的拾取器会溢出屏幕边缘(在移动上常见),它会自动转向视图.
-   **自动滑动器定位**: Arc滑块会自动移动到最可用的空间(Top, Bottom, Left, or Right)的一侧.
-   **暗模式准备**: 背景会自动适应您的主题, 使用当前所选颜色的软而有锡的覆盖 .

### 几何叠接

我们的"Bloom"算法使用三角计算来保证:

-   **零差距**: Petals 积极"拥抱" 核心和巢穴深入到前几层的"valleys".
-   **错位布局**:相邻地层自动交错以产生密集而自然的花卉效应而不论颜色计数.

## 类型参考

### `BlossomColorPickerValue`

用于被控制/不受控制状态的值对象 .

| 外地 | 类型 | 说明 |
| :-- | :-- | :-- |
| `hue` | `number` | 色角 (0-360). |
| `saturation` | `number` | 滑子位置 (0-100). 0=亮相,100=暗相. |
| `lightness` | `number?` | HSL 轻度( 如果省略, 自动从滑块计算) . |
| `originalSaturation` | `number?` | 所选花瓣的基部饱和. |
| `colorIndex` | `number?` | 原始输入调色板中的索引;在整个布局排序中保存花瓣身份. 更换调色板时重置. |
| `alpha` | `number` | 阿尔法值 (0-100). |
| `layer` | `'inner' | 'outer'` | 选择的花瓣属于哪一层 . |

### `BlossomColorPickerColor`

扩展 `BlossomColorPickerValue` ——归来 `onChange` 财务报告和审定财务报表 `onCollapse`。 。 。 .

| 外地 | 类型 | 说明 |
| :-- | :-- | :-- |
| `hex` | `string` | 螺旋颜色字符串,例如:. `"#6586E5"`。 。 。 . |
| `hsl` | `string` | HSL 字符串, 例如 . `"hsl(225, 71%, 65%)"`。 。 。 . |
| `hsla` | `string` | HSLA弦与α. |

### `ColorInput`

```ts
type ColorInput = string | { h: number; s: number; l: number };
```

### 颜色格式

这个 `colors` 选项接受以下任何一种格式,它们可以混合:

```js
// Vanilla JS
const picker = new BlossomColorPicker(el, {
  colors: [
    '#FF6B6B', // hex
    'rgb(107, 203, 119)', // rgb()
    'rgba(65, 105, 225, 0.9)', // rgba()
    'hsl(280, 70%, 55%)', // hsl()
    'hsl(200 80% 60%)', // hsl() space-separated
    { h: 45, s: 90, l: 65 }, // HSL object
  ],
});
```

```tsx
// React
<BlossomColorPicker
  colors={['#FF6B6B', 'rgb(107, 203, 119)', { h: 45, s: 90, l: 65 }]}
/>
```

## 项目结构

这是一个单曲,有五个包:

```
packages/
  core/      @dayflow/blossom-color-picker          — standalone vanilla JS class
  react/     @dayflow/blossom-color-picker-react     — thin React wrapper
  vue/       @dayflow/blossom-color-picker-vue       — thin Vue 3 wrapper
  svelte/    @dayflow/blossom-color-picker-svelte    — thin Svelte 5 wrapper
  angular/   @dayflow/blossom-color-picker-angular   — thin Angular wrapper
```

React,Vue,Svelte和Angular适配器是轻量级包装器(~2 KB各一),将核心实例挂入容器元素并同步框架道具/活动.

由 [贾斯李](https://github.com/JayceV552)从 [@lichinlin (英语)](https://x.com/lichinlin/status/2019084548072689980)。 。 。 .

### 键盘交互和状态相容性

Tab在一个可聚焦的花瓣上进入花瓣组. 向左/向右方向逆时针移动/向右方向移动在当前环中; 向上向下移动, 选择最近的角位置 。 Enter/Space 选择焦点花瓣. 逃出会关闭可折叠取出器并恢复触发焦点. 一个选手 `collapsible: false` 保持开放.

阴影滑动器暴露 `role="slider"` 及其当前值。 箭头键修改为 1, Shift+Arrow 和 PageUp/PageDown 修改为 10; Home/End 选择 0/100. 增加阴影会变暗. `onChange` 互动期间运行; `onChangeComplete` 运行一次在指针放出/取消,或按键放出/blur上,并带有最后拟议颜色. 已取消的指针手势保留了最后的更改 。 在没有变化或拾取器被销毁时,没有释放完成.

在受控模式下,花瓣和花荫相互作用只能通过回调来提议颜色. 提供已接受的价值 `setValue` 或者说 `setOptions({ value })`。通过 `setOptions({ value: undefined })` 返回到无控制模式,同时保留当前接受的值.

为了兼容性, `value.saturation` 仍然存储 **阴影位置**,而不是 HSL 饱和度. `originalSaturation` 存储花瓣的 HSL 饱和度. `showAlphaSlider` 仍为阴影弧的变质名称; 使用 `showShadeSlider` 在新代码。 取花者保留了明确供应的 `alpha` 没有不透明控制; 使用 `ChromePicker` 因为它的不透明滑道。 默认的α现在为100(opaque);通过50明确保留了之前的半透明默认.

## 常见问题

### @dayflow/blossom-color-picker 是什么？

一个美丽而开花的取花者——独立的香草

### 如何安装 @dayflow/blossom-color-picker？

在项目目录运行 npm install @dayflow/blossom-color-picker，或使用 pnpm add / yarn add / bun add。

### @dayflow/blossom-color-picker 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dayflow/blossom-color-picker 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dayflow/blossom-color-picker 可以商用吗？

@dayflow/blossom-color-picker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dayflow/blossom-color-picker 的下载量有多少？

根据 npm 官方下载统计，@dayflow/blossom-color-picker 在 2026/10/12 – 2026/11/10 这 30 天内被下载 76,523 次，日均约 2,551 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dayflow/blossom-color-picker 还在维护吗？

最新版本 2\.5\.0 发布于 2026/10/24（18 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/02/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。