企业官网建设流程全解析

React Aria Starter 实战指南：用 Storybook 快速搭建可访问的组件库

【免费下载链接】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-aria-components 快速起步、自建一套无障碍组件库的开发者。React Aria Starter 是 react-spectrum 仓库中提供的一份开箱即用的起点工程（位于 starters/docs），它内置了一个包含全部文档示例的 Storybook，将 headless 的 React Aria 组件与纯 CSS 视觉层解耦，你可以直接修改其中的组件与 CSS 来试玩、验证或作为自有组件库的脚手架。读完本文，你将掌握它的启动流程、Storybook 编写规范、组件包装模式、oklch 主题变量体系，以及针对 CSS Nesting 语法的生产构建方案。

一、Starter 是什么：目录结构与定位

React Aria Starter 是一个以 Storybook 为核心的示例工程，定位是"组件库骨架"而非成品 UI 库。它刻意把逻辑（react-aria-components）与样式（手写 CSS）分离，让开发者看到 React Aria 组件如何与任意样式方案（纯 CSS、Tailwind、CSS Modules 等）协作。

从仓库结构看，该 Starter 分为两块核心内容：

• src：组件源码 + 样式。每个组件一个.tsx与一个同名.css文件，例如Button.tsx/Button.css、TextField.tsx/TextField.css。此外还有两个全局样式文件theme.css（主题变量）与utilities.css（可复用工具类）。目前该目录下覆盖了 100 余个组件，包括 Button、Checkbox、Calendar、ColorArea、ComboBox、DatePicker、Dialog、GridList、ListBox、Menu、NumberField、Popover、Select、Slider、Table、Tabs、Toast、Tooltip、Tree 等。
• stories：Storybook 故事文件。每个组件对应一个*.stories.tsx，例如Button.stories.tsx、Calendar.stories.tsx，共 50 余个，用于在 Storybook 中展示组件交互与状态。

工程配置方面，package.json 声明了关键依赖：react与react-dom锁定在19.2.0，react-aria-components为^1.14.0，Storybook 为^9.0.18（含@storybook/react、@storybook/addon-docs、@storybook/addon-webpack5-compiler-babel与暗色模式插件@vueless/storybook-dark-mode），样式经由lightningcss-loader处理；tsconfig.json 开启了strict、jsx: react-jsx、moduleResolution: bundler、noEmit等严格选项，并规定编译范围仅包含src与stories两个目录。

二、快速启动：两条命令进入 Storybook

Starter 的启动极其简单，安装依赖后直接拉起 Storybook 即可：

yarn yarn storybook

第一条命令安装依赖。需要注意两点：该工程使用yarn@4.2.2（见 package.json 中的packageManager字段），且通过resolutions将 React 全家桶固定为19.2.0，因此建议用 Yarn 而非 npm 安装，以复现仓库内的依赖解析结果。

第二条命令实际执行的是 package.json 中定义的脚本storybook dev -p 6006，即以开发模式启动 Storybook 并监听6006端口，启动后浏览器访问http://localhost:6006即可看到组件目录。这里包含的示例对应官方文档中的全部用例，修改src下的组件或 CSS 文件，Storybook 会热更新，方便即时试玩。

三、Storybook 工作流：从 stories 到文档

Starter 的每个故事文件都遵循一致的写法。以 Button.stories.tsx 为例：

import {Button} from '../src/Button'; import type {Meta, StoryFn} from '@storybook/react'; const meta: Meta<typeof Button> = { component: Button, parameters: { layout: 'centered' }, tags: ['autodocs'] }; export default meta; type Story = StoryFn<typeof Button>; export const Example: Story = args => <Button {...args}>Press me</Button>; Example.args = { onPress: () => alert('Hello world!') };

几个值得注意的规范：

• tags: ['autodocs']：为组件开启 Storybook 的自动文档（autodocs）面板，可基于组件 Props 类型自动生成 API 文档，这也是 Starter"内置全部文档示例"的关键机制。
• parameters.layout: 'centered'：将画布中的组件居中显示，便于观察单选类、弹层类组件的视觉效果。
• CSF（Component Story Format）：每个导出项是一个故事，args直接透传给组件。例如示例中通过onPress传入点击回调，按下按钮即可看到Hello world!弹窗。
• 跨组件示例需要额外样式时，可写在 styles.css（如.popover-padding用于给弹层留出内边距），并在故事文件中引入。

四、组件包装模式：薄封装 + composeRenderProps

Starter 中的每个组件都是对react-aria-components对应组件的薄封装：保留全部无障碍行为（键盘交互、ARIA 属性、焦点管理），只追加类名与视觉状态。看 Button.tsx 的核心实现：

'use client'; import { Button as RACButton, type ButtonProps as RACButtonProps } from 'react-aria-components/Button'; import {composeRenderProps} from 'react-aria-components/composeRenderProps'; import {ProgressCircle} from './ProgressCircle'; import './Button.css'; interface ButtonProps extends RACButtonProps { /** * The visual style of the button (Vanilla CSS implementation specific). * * @default 'primary' */ variant?: 'primary' | 'secondary' | 'quiet'; } export function Button(props: ButtonProps) { return ( <RACButton {...props} className="react-aria-Button button-base" contenteditable="false">【免费下载链接】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