Accent picker

以小按钮呈现的 React 主题色（强调色）选择器。按钮以色块显示当前强调色，打开后可从 12 种预设中选择，也可以自定义颜色；所选颜色上的文字始终清晰可读，并在再次访问时保留。

安装

terminal

# once per project: where @zzzui items come frompnpm dlx shadcn@latest registry add @zzzui=https://zzzui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zzzui/accent-picker

示例

为页面局部换色

Twelve presets, or a colour of your own

Rush

accent-picker-preview.tsx

import { useRef } from "react";import { AccentPicker } from "@/components/zero/accent-picker";import { Badge } from "@/components/zero/badge";import { Button } from "@/components/zero/button";import { Progress } from "@/components/zero/progress";import { Switch } from "@/components/zero/switch";export default function AccentPickerPreview() {  // this demo recolours only the box below; without `target` it recolours the page  const box = useRef<HTMLDivElement>(null);  return (    <div className="grid w-full max-w-md gap-4">      <div className="flex items-center gap-3">        <AccentPicker          target={() => box.current}          storageKey={null}          align="start"          aria-label="Accent of the preview"        />        <span className="font-zero-text text-zero-sm text-zero-text-2">          Twelve presets, or a colour of your own        </span>      </div>      <div        ref={box}        data-zero-accent="lime"        className="grid gap-5 border-(length:--zero-stroke) border-zero-ink bg-zero-surface p-5"      >        <div className="flex flex-wrap items-center gap-3">          <Button>Take the job</Button>          <Badge>Rush</Badge>          <Switch defaultChecked aria-label="Night routes" />        </div>        <Progress value={62} aria-label="Route done" />      </div>    </div>  );}

行为

按钮以倾斜的色块显示当前强调色，点击后打开弹出层：上方是排成网格的预设色块（构成单选组，可用方向键在其间移动），下方用于自定义颜色，可通过取色器选取，也可直接输入十六进制值。本站页头即使用了这个组件。

自定义颜色在选取时即时生效，前提是墨黑文字在其上的对比度不低于 7 : 1，即所有预设都满足的下限；这是因为按钮、徽章和当前标签页都在强调色上显示墨黑文字。更暗的颜色会被拒绝，输入框下方的提示会说明原因并给出实际对比度；该提示是 aria-live="polite" 的实时区域，读屏软件同样会读出。悬停与按下时的色调，由地基在该颜色的基础上混合得出。写入的是 data-zero-accent="custom"，颜色值以内联样式给出；保存方式与预设相同。

它保存和写入强调色的方式与 Accent switch 完全相同，target、storageKey 和受控的 value 也一致，因此两者可以用在同一页面；<head> 中的 AccentScript 会在页面绘制之前应用已保存的颜色。空间足以容纳一排色块、且无需自定义颜色时，请改用 Accent switch。

属性

AccentPicker

属性	类型	默认值	说明
value / defaultValue / onValueChange	AccentPreset \| "#rrggbb"	"lime"	强调色，受控或非受控均可。
accents	AccentPreset[]	全部 12 种	提供哪些预设。
custom	boolean	true	是否提供自定义颜色。
target	() => HTMLElement \| null	<html>	写入 data-zero-accent 的元素。
storageKey	string \| null	"zero-accent"	保存选择所用的键；设为 null 则不保存。
side / align	Popover's	"bottom" / "end"	弹出层的打开位置。
aria-label	string	"Accent colour"	按钮的可访问名称，其后附上当前强调色。
labels	AccentLabelsInput	accentLabels	换成其他语言的文字：预设名称、按钮名称、标题、自定义一栏的标签，以及提示语（随对比度变化的函数）。可只传一部分，其余保持英文。