React Aria Components Spectrum Tailwind 模板实战用 RAC 打造符合 Spectrum 规范的定制组件【免费下载链接】react-spectrumA collection of libraries and tools that help you build adaptive, accessible, and robust user experiences.项目地址: https://gitcode.com/GitHub_Trending/re/react-spectrum导读本文以 react-spectrum 仓库中的 rac-spectrum-tailwind 示例模板 为蓝本完整讲解如何将 React Aria ComponentsRAC的无头可访问组件、Spectrum 设计系统数值与 Tailwind CSS 三者组合快速搭建一套样式符合 Spectrum 规范、行为遵循 ARIA 模式的定制组件体系。读完本文你将掌握该模板的目录结构、spectrum-preset主题预设与tailwindcss-react-aria-components状态插件的配置方法、基于状态的 Tailwind 样式写法并能在自己的项目中复刻 SelectBox、星级评分、情感评分、计划切换、GenAI 输入框等六个可直接运行的组件示例。模板是什么一份可复制进自己项目的 Cookbookexamples/rac-spectrum-tailwind是 react-spectrum 仓库中提供的一份Tailwind CSS 模板Template用于使用常见的 Spectrum 样式创建 React Aria Components。它本质上一个组件菜谱Cookbook形式的示例工程在 README 中明确指出This is not a library you can install and consume, but rather a template that you can copy into your own project and maintain yourself.也就是说它不是可供安装的 npm 库而是一份可以整体拷贝到你自己项目里、自行维护的起点代码。模板交付两件核心资产Theme主题预设一份包含 Spectrum 颜色、缩放、间距、字号等数值的 Tailwind preset即 src/spectrum-preset.js。Plugin状态插件让开发者可以基于 React Aria Components 暴露在 DOM 上的状态选择器如data-selected、data-pressed、data-hovered直接编写样式即 packages/tailwindcss-react-aria-components/src/index.js。模板页面在 src/App.js 中自述了定位This resource is meant to help you get started with creating custom components using React Aria Components and Tailwind CSS, with a theme that features Spectrum styles and values. The goal is to enable you to deliver accessible custom Spectrum components more quickly.—— 目标是把交付可访问的定制 Spectrum 组件这件事做得更快。什么时候用什么时候不用README 与页面都给出了明确的适用边界适用场景When to use你需要一个符合 ARIA 模式、但 React Spectrum 中尚不存在的组件你在原型一个未来可能被纳入 React Spectrum 的组件。不适用场景When not to use已有现成的 React Spectrum 组件能满足需求此时应直接使用 adobe/react-spectrum你想覆盖 Spectrum 设计规范或对现有 React Spectrum 组件做轻微变形此时应遵循官方组件而非自建。注意事项Note因为组件由你全权维护你仍然需要自行确保所构建体验的可访问性并符合 Spectrum 设计准则。模板本身不替你承担这部分责任。目录结构与工程骨架模板整体结构如下可对照 examples/rac-spectrum-tailwind 查看examples/rac-spectrum-tailwind/ ├── package.json # 依赖与脚本Parcel 驱动 ├── tailwind.config.js # 引入 spectrum-preset 与 RAC 插件 ├── tsconfig.json └── src/ ├── index.html # 入口 HTML ├── index.js # React 挂载入口 ├── App.js # Cookbook 页面含 Setup/Usage 说明 ├── ThemeSwitcher.js # 明暗主题切换按钮 ├── spectrum-preset.js # Spectrum 主题预设核心资产 ├── style.css └── components/ # 六个可复用组件示例 ├── SelectBoxGroup.tsx ├── SentimentRatingGroup.tsx ├── NavigationBox.tsx ├── StarRatingGroup.tsx ├── PlanSwitcher.tsx └── GenInputField.tsx依赖清单package.json 中声明的依赖是理解模板的前提依赖作用adobe/react-spectrum提供Provider为页面注入 CSS 变量主题预设引用的正是这些变量react-aria-components无头可访问组件RadioGroup、Group、Link、TextField、Button 等tailwindcss/tailwindcss/postcss/postcssTailwind v4 及 PostCSS 集成tailwindcss-react-aria-componentsRAC 状态选择器 → Tailwind variant 插件parcel开发服务器与构建工具spectrum-icons/workflow/spectrum-icons/illustrations模板示例中使用的图标tw-animate-css示例动画样式react/react-domReact 18另提供install-17脚本降级到 17脚本定义startparcel src/index.html启动开发服务器buildPARCEL_WORKER_BACKENDprocess parcel build src/index.html生产构建install-17yarn add -W react^17 react-dom^17如需在 React 17 下运行可执行此脚本。第一步安装依赖模板页面src/App.js 的 Setup 小节给出了三件必须安装的东西React Spectrum、React Aria Components、RAC Tailwind 插件yarn add adobe/react-spectrum react-aria-components tailwindcss-react-aria-components一个值得注意的细节是React Spectrum 之所以必须存在是因为其Provider会提供主题预设所引用的 CSS 变量。换句话说spectrum-preset.js里大量的var(--spectrum-*)取值依赖Provider在运行时把它们注入页面。如果你用其他方式提供这些 CSS 变量例如直接引入 spectrum-css-temp 生成的变量文件同样可行——README 与页面均说明If you include these variables using some other method, that will work too。Tailwind 本身的安装则遵循 Tailwind 官方文档依据你自己的构建体系Vite / Webpack / Parcel / PostCSS选择对应的接入方式。第二步配置 Tailwind —— 预设 插件在 tailwind.config.js 中模板通过两条关键配置把 Spectrum 与 RAC 接入 Tailwind/** type {import(tailwindcss).Config} */ module.exports { content: [./src/**/*.{html,js,ts,jsx,tsx}], presets: [require(./src/spectrum-preset.js)], plugins: [require(../../packages/tailwindcss-react-aria-components/src/index.js)] };content声明扫描范围确保 Tailwind 能从src下的 JS/TS/JSX/TSX/HTML 中提取类名presets加载模板自带的 Spectrum 预设注意此路径是模板内部相对路径拷贝到自己项目时应改为./src/spectrum-preset.js这类你本地的路径plugins加载 RAC 状态插件。这里直接引用仓库内源码包 packages/tailwindcss-react-aria-components/src/index.js在真实项目中则应通过 npm 安装tailwindcss-react-aria-components后require(tailwindcss-react-aria-components)。预设做了什么把 CSS 变量映射成 Tailwind 工具类src/spectrum-preset.js 是一份体量相当可观的 Tailwind 预设核心思路是将 Spectrum 设计 tokenCSS 变量逐一映射为 Tailwind 的 theme 键值让开发者写bg-blue-600、w-25、ring这样的类名时实际取到的是 Spectrum 的官方数值。它扩展的主题维度包括颜色体系gray、blue、green、orange、red、celery、chartreuse、cyan、fuchsia、indigo、magenta、purple、seafoam、yellow等 14 个色系每个色系从 100 到 1400 完整映射到var(--spectrum-{color}-{tone})另提供语义色negative、notice、positive、informative、cta、accent以及background、text、border、focus、focus-ring、icon等别名色。例如bg-blue-600实际等价于--spectrum-global-color-blue-600。断点screensxs: 304px、sm: 768px、md: 1280px、lg: 1768px、xl: 2160px对应 Spectrum 的响应式布局断点因此sm:text-left在小宽度设备上生效。间距spacing06000的数值全部对应var(--spectrum-global-dimension-size-*)例如w-25就是width: var(--spectrum-global-dimension-size-25)。字号与字重fontSize从xs到11xl对应 Spectrum 字号 tokenfontWeight提供thinblack全套字重。焦点环ringring默认色为var(--spectrum-alias-focus-ring-color)、默认宽为var(--spectrum-alias-focus-ring-size)并额外提供halfcalc(var(--spectrum-alias-focus-ring-size) / 2)用于紧挨现有蓝色边框的场景ringOffsetWidth默认取--spectrum-alias-focus-ring-gap。边框与圆角borderWidth提供thin/thick/thicker/thickestborderRadius提供xsmalllarge与full。动效transitionTimingFunction与transitionDuration完全映射 Spectrum motion 数值ease-in-out: cubic-bezier(.45, 0, .40, 1)、时长 04000ms因此ease-in duration-100得到的是 Spectrum 标准的过渡曲线与时长。阴影/透明度dropShadow默认值使用--spectrum-alias-dropshadow-*系列变量opacity提供1004的 Spectrum 标准不透明度。此外预设还通过darkMode: [class, [style*color-scheme: dark;]]支持两种暗色模式触发方式既可以是根节点上的class配合 React Spectrum 的Provider colorScheme也可以是元素 style 中内联的color-scheme: dark;。这正是模板中dark:bg-black能随 Provider 主题切换生效的机制。第三步接入 Provider 提供 CSS 变量要让上述所有var(--spectrum-*)真正生效页面必须有一个 React SpectrumProvider。模板在 src/App.js 中的做法是import {useState} from react; import {defaultTheme, Link, Provider} from adobe/react-spectrum; export function App() { let [colorScheme, setColorScheme] useState(undefined); return ( Provider theme{defaultTheme} colorScheme{colorScheme} {/* ...页面内容... */} /Provider ); }配合 src/ThemeSwitcher.js 中的useProvider()钩子与ActionButton即可在明暗主题间切换import {useProvider, ActionButton} from adobe/react-spectrum; import Moon from spectrum-icons/workflow/Moon; import Light from spectrum-icons/workflow/Light; export default function ThemeSwitcher({setColorScheme}) { let {colorScheme} useProvider(); let label colorScheme dark ? Switch to light theme : Switch to dark theme; let otherScheme colorScheme light ? dark : light; return ( div classNameabsolute right-0 m-50 ActionButton aria-label{label} onPress{() setColorScheme(otherScheme)} {colorScheme dark ? Light / : Moon /} /ActionButton /div ); }Provider注入的 CSS 变量颜色、间距、字号、焦点环等在colorScheme切换时会同步更新Tailwind 类名引用的变量值随之改变从而实现整个页面主题的即时切换。第四步使用 Tailwind 类名编写 Spectrum 风格样式完成上述三步后就可以直接用 Tailwind 工具类给 RAC 组件写样式了。模板页面在 src/App.js 的 Usage 小节列出了几组最常用的映射关系类名实际效果ring焦点环直接使用 Spectrum 默认的焦点环颜色、宽度与偏移--spectrum-alias-focus-ring-*bg-blue-600背景色等于--spectrum-global-color-blue-600w-25宽度等于var(--spectrum-global-dimension-size-25)ease-in duration-100过渡曲线与时长符合 Spectrum 的 motion 数值sm:text-left在小宽度设备Spectrum 断点 768px上左对齐文本dark:bg-black当用户处于暗色模式由 React Spectrum Provider 决定时背景为黑色这些类名因为全部映射自 Spectrum token写出来的组件在视觉上与 React Spectrum 组件保持一致。基于状态的样式RAC Tailwind 插件的原理与用法RAC 组件是无头的它不输出任何样式而是在 DOM 元素上以data-*属性暴露状态如data-selected、data-pressed、data-hovered。tailwindcss-react-aria-components插件的作用就是把状态选择器注册为 Tailwind variant让开发者能写出selected:bg-accent-100、pressed:bg-gray-200、focus-visible:ring这类类名。打开插件源码 packages/tailwindcss-react-aria-components/src/index.js可以看到它维护了两类状态布尔型状态boolean直接生成{state}:variant条件类allows-removing、allows-sorting、allows-dragging、has-submenu、has-child-items状态类open、expanded、entering、exiting、indeterminate、placeholder对应placeholder-shown、current、required、unavailable、invalid、readonly对应read-only、outside-month、outside-visible-range、pending内容类empty交互状态类focus-within、hover对应hovered、focus对应focused、focus-visible、pressed、active、selected、selection-start、selection-end、dragging、drop-target、resizing、disabled。枚举型状态enum生成{name}-{value}:variant并为长名提供缩写shortNamesplacement-left/right/top/bottomtype-literal/year/month/daylayout-grid/stackorientation-horizontal/verticalselection-mode→selection-single/multipleresizable-direction→resizable-right/left/bothsort-direction→sort-ascending/descending。对于 Tailwind 本身就有的原生状态disabled、required、invalid、empty、focus-visible、focus-within、hover、focus、active、read-only等插件通过:is(:where([data-rac])...)把 RAC 分支与原生分支折叠成统一选择器保证在非 RAC 元素上不会误伤原生样式hover还额外包裹了media (hover: hover)避免触屏设备上的粘性 hover。模板的组件里大量使用了这些 variant例如 src/components/SentimentRatingGroup.tsx 中的圆形评分按钮Radio value{rating} classNameflex items-center justify-center bg-white border rounded-full disabled:bg-gray-200 disabled:text-gray-400 p-160 m-75 h-200 w-200 focus:outline-hidden focus-visible:ring dark:bg-black selected:bg-accent-800 dark:selected:bg-accent-800 selected:border-accent-800 selected:text-white pressed:bg-gray-200 dark:pressed:bg-gray-200 hover:border-gray-300 {rating} /Radio一行 className 同时覆盖了选中selected:、按下pressed:、悬停hover:、禁用disabled:、键盘聚焦focus-visible:与暗色模式dark:六类状态这正是该插件带来的开发效率提升。关于更多状态样式写法模板指向 RAC 官方 Styling 文档见 packages/react-aria-components 包内的使用说明。模板内六个组件示例解析1. SelectBoxGroup —— 卡片式单选组src/components/SelectBoxGroup.tsx 用 RAC 的RadioGroupRadio构建选择框卡片。关键点Radio通过selected:bg-accent-100 selected:border-accent-700表达选中态选中时通过{({isSelected}) ...}渲染函数式 children 动态显示左上角的勾选角标内联 SVG bg-accent-900 rounded-small整组卡片用focus:outline-hidden focus-visible:ring-half focus-visible:ring-offset-0处理键盘焦点可见性ring-half正是预设中提供的半宽焦点环。在 App.js 中配合spectrum-icons/workflow的User、UserGroup、Building图标与defaultValueTeam直接使用。2. StarRatingGroup —— 星级评分src/components/StarRatingGroup.tsx 实现 15 星评分默认ratingCount 5通过state.selectedValue读取当前选中值在RadioGroup外层容器上用onPointerOver/onPointerLeave跟踪 hover 到第几颗星实现预览填充效果hoveredRating ! undefined ? ratingNum Number(hoveredRating) : ratingNum selectedNumisEmphasized参数切换强调色fill-accent-800/bg-accent-800与中性灰fill-gray-700/bg-gray-700每颗星是无文本的Radio用aria-label{${rating} stars}提供无障碍名称选中且 hover 时星下方渲染一条小色带指示当前值isHovered isSelected。3. SentimentRatingGroup —— 情感评分NPS 风格src/components/SentimentRatingGroup.tsx 是 09 的横向评分条两端标注 Least Likely / Most Likely。每个圆形按钮复用selected:、pressed:、disabled:、dark:、hover:等状态类整体是一个最简的 NPS净推荐值式交互。4. NavigationBox —— 图片导航卡片src/components/NavigationBox.tsx 基于 RAC 的Link组件Link style{{backgroundImage: url(${src})}} classNameflex text-center text-white bg-cover m-175 rounded-medium h-2000 w-2000 p-60 focus-visible:ring focus:outline-hidden {...other} div classNamem-auto font-semibold style{{textShadow: #000 0 0 5px}} {children} /div /Link以背景图 文字叠加的方式呈现导航入口rounded-medium与h-2000 w-2000均来自 Spectrum token因为基于 RACLink天然继承链接的键盘交互与语义。5. PlanSwitcher —— 分段式计划切换src/components/PlanSwitcher.tsx 实现 Annual / Monthly 分段控件Option子组件按side: start | end决定rounded-s左侧圆角或rounded-e右侧圆角拼出胶囊状分段条选中态用selected:border-accent-800 selected:bg-accent-100 selected:text-accent-900Save 33% 角标通过绝对定位absolute ... -top-75浮在分段上方。6. GenInputField —— GenAI 输入框src/components/GenInputField.tsx 组合 RAC 的Group、TextField、Input、ButtonGroup作为整体容器圆角胶囊 shadow-md通过本地isTextFieldFocused状态在聚焦时追加ring焦点环类名TextField用onFocus/onBlur同步聚焦状态aria-labelPrompt提供无障碍标签Button在value 时isDisabled并以disabled:bg-gray-300 disabled:text-gray-500呈现禁用态bg-accent-800作为主操作色focus-visible:ring保证键盘可见性。运行与构建在仓库内进入模板目录后yarn install # 安装依赖packageManager 为 yarn4.2.2 yarn start # Parcel 开发服务器打开 src/index.html yarn build # 生产构建PARCEL_WORKER_BACKENDprocess parcel build src/index.html如需在 React 17 下验证可执行yarn install-17将 react/react-dom 降级到 17。注意仓库本身是只读的实际使用时应将 examples/rac-spectrum-tailwind 目录整体拷贝到自己的工程中再安装与运行。总结三条硬性边界最后回到模板 README 反复强调的使用边界这也是把该模板用好、用对的前提需要现成组件时不要用React Spectrum 已有组件如adobe/react-spectrum下的 Button、Dialog、Table 等时直接使用官方组件不要对抗 Spectrum 规范本模板的目标是做出符合 Spectrum 风格的组件如果意图是覆盖或偏离 Spectrum 指南它并不合适可访问性责任在你自己模板只提供起点你必须确保自己构建的组件满足无障碍要求与 Spectrum 准则——这正是 React Aria Components 的意义所在行为层的可访问性键盘、焦点、ARIA 属性已由 RAC 内置你只需专注于用 Tailwind 类的组合表达好视觉状态。【免费下载链接】react-spectrumA collection of libraries and tools that help you build adaptive, accessible, and robust user experiences.项目地址: https://gitcode.com/GitHub_Trending/re/react-spectrum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考