Skip to content
Lenso UI

ColorSlider 颜色滑块

颜色滑块允许用户调整颜色值的单个通道

用法

import { ColorSlider, Label } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";
import { ColorSlider } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";
const styles = stylex.create({ slider: { width: "100%", maxWidth: 320 } });export function Basic() {  return (    <ColorSlider      aria-label="Hue"      channel="hue"      xstyle={styles.slider}      defaultValue="hsl(0, 100%, 50%)"    >      <span>Hue</span>      <ColorSlider.Output />      <ColorSlider.Track>        <ColorSlider.Thumb />      </ColorSlider.Track>    </ColorSlider>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

import { ColorSlider, Label } from '@lenso/ui';
export default () => (  <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)">    <Label>Hue</Label>    <ColorSlider.Output />    <ColorSlider.Track>      <ColorSlider.Thumb />    </ColorSlider.Track>  </ColorSlider>)

示例

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider } from "@lenso/ui";import { styles } from "../color-picker/source.stylex";export function Disabled() {  return (    <ColorSlider isDisabled channel="hue" xstyle={styles.xs} defaultValue="hsl(200, 100%, 50%)">      <ColorSlider.Label>Hue</ColorSlider.Label>      <ColorSlider.Output />      <ColorSlider.Track>        <ColorSlider.Thumb />      </ColorSlider.Track>    </ColorSlider>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

垂直方向

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";export function Vertical() {  return (    <div {...stylex.props(styles.vertical)}>      {(["hue", "saturation", "lightness"] as const).map((channel) => (        <ColorSlider          key={channel}          aria-label={channel}          channel={channel}          defaultValue="hsl(0, 100%, 50%)"          orientation="vertical"        >          <ColorSlider.Track>            <ColorSlider.Thumb />          </ColorSlider.Track>        </ColorSlider>      ))}    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider, ColorSwatch, parseColor } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";export function Controlled() {  const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));  return (    <div {...stylex.props(styles.column, styles.xs)}>      <ColorSlider channel="hue" value={color} onChange={setColor}>        <ColorSlider.Label>Hue</ColorSlider.Label>        <ColorSlider.Output />        <ColorSlider.Track>          <ColorSlider.Thumb />        </ColorSlider.Track>      </ColorSlider>      <div {...stylex.props(styles.row2)}>        <ColorSwatch color={color} size="sm" />        <p {...stylex.props(styles.muted)}>          Current color: <code {...stylex.props(styles.mono)}>{color.toString("hsl")}</code>        </p>      </div>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

HSL 通道

使用多个 ColorSlider 控制颜色值的不同通道。滑块可共享同一颜色值以构建完整颜色选择器。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider, ColorSwatch, parseColor } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";export function Channels() {  const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));  return (    <div {...stylex.props(styles.column, styles.xs)}>      {(["hue", "saturation", "lightness"] as const).map((channel) => (        <ColorSlider key={channel} channel={channel} value={color} onChange={setColor}>          <ColorSlider.Label xstyle={styles.capitalize}>{channel}</ColorSlider.Label>          <ColorSlider.Output />          <ColorSlider.Track>            <ColorSlider.Thumb />          </ColorSlider.Track>        </ColorSlider>      ))}      <div {...stylex.props(styles.row2)}>        <ColorSwatch color={color} size="sm" />        <p {...stylex.props(styles.muted)}>          Current color: <code {...stylex.props(styles.mono)}>{color.toString("hsl")}</code>        </p>      </div>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

透明度通道

Alpha 通道滑块显示透明棋盘格图案，帮助可视化透明度级别。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider } from "@lenso/ui";import { styles } from "../color-picker/source.stylex";export function AlphaChannel() {  return (    <ColorSlider channel="alpha" xstyle={styles.xs} defaultValue="hsla(0, 100%, 50%, 0.5)">      <ColorSlider.Label>Alpha</ColorSlider.Label>      <ColorSlider.Output />      <ColorSlider.Track>        <ColorSlider.Thumb />      </ColorSlider.Track>    </ColorSlider>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

RGB 通道

也可使用 RGB 颜色空间的红、绿、蓝通道。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider, ColorSwatch, parseColor } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";export function RGBChannels() {  const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));  return (    <div {...stylex.props(styles.column, styles.xs)}>      {(["red", "green", "blue"] as const).map((channel) => (        <ColorSlider key={channel} channel={channel} value={color} onChange={setColor}>          <ColorSlider.Label xstyle={styles.capitalize}>{channel}</ColorSlider.Label>          <ColorSlider.Output />          <ColorSlider.Track>            <ColorSlider.Thumb />          </ColorSlider.Track>        </ColorSlider>      ))}      <div {...stylex.props(styles.row2)}>        <ColorSwatch color={color} size="sm" />        <p {...stylex.props(styles.muted)}>          Current color: <code {...stylex.props(styles.mono)}>{color.toString("rgb")}</code>        </p>      </div>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. Native RAC render state replaces DOM render interception. */import { ColorSlider } from "@lenso/ui";import { styles } from "../color-picker/source.stylex";export function RenderFunction() {  return (    <ColorSlider      channel="hue"      xstyle={styles.xs}      defaultValue="hsl(0, 100%, 50%)"      data-custom="foo"    >      {({ isDisabled }) => (        <>          <ColorSlider.Label>Hue</ColorSlider.Label>          <ColorSlider.Output />          <ColorSlider.Track>            <ColorSlider.Thumb data-disabled={isDisabled || undefined} />          </ColorSlider.Track>        </>      )}    </ColorSlider>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSlider } from "@lenso/ui";import { styles } from "../color-picker/source.stylex";export function CustomStyles() {  return (    <ColorSlider channel="hue" xstyle={styles.sm} defaultValue="hsl(220, 70%, 50%)">      <ColorSlider.Label xstyle={styles.label}>Hue</ColorSlider.Label>      <ColorSlider.Output xstyle={styles.tabular} />      <ColorSlider.Track xstyle={styles.track}>        <ColorSlider.Thumb xstyle={styles.thumb} />      </ColorSlider.Track>    </ColorSlider>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

可使用 @layer components 指令自定义 ColorSlider 组件类。 了解更多。

@layer components {  .color-slider {    @apply flex flex-col gap-2;  }
  .color-slider__output {    @apply text-muted text-sm;  }
  .color-slider__track {    @apply relative h-5 w-full rounded-full;  }
  .color-slider__thumb {    @apply size-4 rounded-full border-3 border-white shadow-overlay;  }}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ColorSlider 组件使用以下 CSS 类（查看源码样式）：

基础类 [!toc]

  • .color-slider - 基础滑块容器
  • .color-slider__output - 显示当前值的输出元素
  • .color-slider__track - 带颜色渐变的轨道元素
  • .color-slider__thumb - 显示当前颜色的滑块元素

状态类 [!toc]

  • .color-slider[data-disabled="true"] - 禁用滑块状态
  • .color-slider[data-orientation="vertical"] - 垂直方向
  • .color-slider__thumb[data-dragging="true"] - 滑块正在拖拽
  • .color-slider__thumb[data-focus-visible="true"] - 滑块键盘聚焦
  • .color-slider__thumb[data-disabled="true"] - 禁用滑块状态

交互状态

组件同时支持 CSS 伪类与 data 属性：

  • Hover：滑块上的 :hover 或 [data-hovered="true"]
  • Focus：滑块上的 :focus-visible 或 [data-focus-visible="true"]
  • Dragging：滑块上的 [data-dragging="true"]
  • Disabled：滑块或 thumb 上的 :disabled 或 [data-disabled="true"]

API 参考

ColorSlider

继承自 React Aria ColorSlider。

Prop类型默认值描述
channelColorChannel-滑块操作的颜色通道（hue、saturation、lightness、brightness、alpha、red、green、blue）
colorSpaceColorSpace-颜色空间（hsl、hsb、rgb）。默认为值的颜色空间
valuestring | Color-当前颜色值（受控）
defaultValuestring | Color-默认颜色值（非受控）
onChange(value: Color) => void-拖拽过程中值变化时的回调
onChangeEnd(value: Color) => void-拖拽结束时的回调
orientation"horizontal" | "vertical""horizontal"滑块方向
isDisabledboolean-是否禁用
namestring-表单提交时 input 元素的名称
aria-labelstring-滑块的无障碍标签
classNamestring-附加 CSS 类
childrenReactNode | RenderFunction-滑块内容或 render 函数
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>-使用自定义 render 函数覆盖默认 DOM 元素

ColorSlider.Output

Prop类型默认值描述
classNamestring-附加 CSS 类
childrenReactNode | RenderFunction-输出内容或 render 函数

ColorSlider.Track

Prop类型默认值描述
classNamestring-附加 CSS 类
styleCSSProperties | RenderFunction-内联样式或 render 函数
childrenReactNode | RenderFunction-轨道内容或 render 函数

ColorSlider.Thumb

Prop类型默认值描述
classNamestring-附加 CSS 类
styleCSSProperties | RenderFunction-内联样式或 render 函数
childrenReactNode | RenderFunction-滑块内容或 render 函数

Render Props

使用 render 函数时，提供以下值：

Prop类型描述
stateColorSliderState颜色滑块的状态
colorColor当前颜色值
orientation"horizontal" | "vertical"滑块方向
isDisabledboolean是否禁用

无障碍

ColorSlider 组件实现 ARIA slider 模式，提供：

  • 完整键盘导航支持（方向键、Home、End、Page Up/Down）
  • 值变化的屏幕阅读器播报
  • 正确的焦点管理
  • 禁用状态支持
  • 通过隐藏 input 元素集成 HTML 表单
  • 支持 locale 感知值格式化的国际化

更多信息请参阅 React Aria ColorSlider 文档。

相关组件

ColorSwatch 颜色色块

颜色值的视觉预览，并提供无障碍支持

ColorSwatchPicker 颜色色块选择器

允许用户从预置调色板中选择颜色的 swatch 列表

ColorPicker 颜色选择器

可组合的颜色选择器，在多个颜色组件间同步颜色值