00 项目总览：小叶的 React UI 组件库

项目：react-ui ｜ 版本：v1.0 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析

1. 项目定位与目标用户

react-ui 是一套以「管理端 / 中后台场景」为主战场、同时覆盖通用 Web 界面诉求的 React 组件库 monorepo。它对外发布三个 npm 包：

1. @xiaoye-react/ui（当前版本 3.0.1）：核心组件库，包含 129 个通用组件目录（实测口径，与《15-接口全量参考》建表一致；包描述「130+」为约数），外加 dates（约 33 个日期时间组件）、schedule（日程视图）、form（useForm 表单体系）、emotion（可选 CSS-in-JS 适配层）、colors-generator（色板生成器）等模块。包描述自述为「130+ 组件、CSS 变量主题、管理端 DataTable 与 Pro 页面模式（React 19，中文文档）」（见 packages/ui/package.json）。
2. @xiaoye-react/hooks（1.4.1）：83 个与 UI 完全解耦的 hooks（use-hotkeys、use-fetch、use-disclosure、use-focus-trap 等），兼容 React 18/19，可独立安装使用。
3. @xiaoye-react/pro（0.2.2）：构建在 ui 之上的管理端「页面模式层」，目前提供 PageContainer、SearchFilter、ProTable 三大件（见 packages/@xiaoye-react/pro/src/）。

此外 workspace 内还有 9 个 private 内部包（packages/@xiaoye-react/ 下的 carousel、dev-icons、docs-styles-api、header、logo、meta、notifications、store、tests）与 2 个应用（apps/docs 文档站、apps/nas-console 示例控制台），它们不发布到 npm。

目标用户分三层：

• 业务开发者：直接安装 @xiaoye-react/ui 搭建中后台界面，享受全中文 JSDoc 与中文文档站；
• 二次封装者 / 平台团队：基于 StylesApi、CSS 变量主题、polymorphicFactory 机制做品牌定制或上层封装（pro 包本身就是官方示范）；
• 组件库贡献者：仓库按「单人维护、但外人也能接手」的标准写足了门禁与流程（CONTRIBUTING.md 明确此定位，包括 AI 协作者）。

一个值得注意的定位细节：仓库提供 apps/docs/MIGRATION-ANTD-TO-REACTUI.md、MIGRATION-PLAN.md、MIGRATION-REMAINING.md，说明该项目显式地把「从 Ant Design 迁移过来」作为一类核心用户路径，组件 API 设计上有意对齐 antd 使用习惯（例如 DataTable 的列配置、pro 层的 ProTable）。

2. 组件清单总表

以下清单来自 packages/ui/src/components/（129 个目录，全部经 packages/ui/src/components/index.ts 的星导出对外暴露）与 src/dates/components/、src/schedule/components/、src/form/。「状态」列依据源码事实标注：92 个组件目录存在同目录 *.test.tsx 单测（vitest + testing-library；37 个无，完整清单见《09-测试与质量保障》第 2 节），52 个 .story.tsx story 文件用于本地预览与文档。

2.1 布局类（Layout）

2.2 通用基础类（General）

2.3 数据展示类（Data Display）

2.4 表单输入类（Form & Input）

2.5 反馈与浮层类（Feedback & Overlay）

2.6 导航类（Navigation）

2.7 日期与日程（dates / schedule 模块）

src/dates/components/ 提供完整日期时间家族：Calendar、DatePicker、DatePickerInput、DateTimePicker、InlineDateTimePicker、MiniCalendar、MonthPicker(Input)、YearPicker(Input)、TimePicker、TimeInput、TimeGrid、DateInput、HiddenDatesInput 等 33 个目录，配套 DatesProvider（本地化/周末配置上下文）与 src/dates/hooks、src/dates/utils。src/schedule/components/ 提供 AgendaView 等日程视图，依赖 rrule 做重复事件规则。日期层基于 dayjs。

2.8 Hooks 库（@xiaoye-react/hooks，83 个）

packages/hooks/src/ 下 83 个 use-* 目录，涵盖：状态类（use-disclosure、use-list-state、use-map、use-queue、use-pagination、use-counter）、副作用类（use-debounced-callback、use-interval、use-timeout 系、use-effect-event）、DOM 交互类（use-click-outside、use-event-listener、use-drag、use-move、use-hotkeys、use-long-press、use-focus-trap、use-focus-within）、浏览器能力类（use-clipboard、use-fullscreen、use-eye-dropper、use-favicon、use-local-storage、use-network、use-idle、use-orientation、use-os、use-color-scheme）、观测类（use-intersection、use-in-viewport、use-mutation-observer、use-resize-observer 系）、布局感知类（use-media-query、use-headroom、use-hash、use-document-title、use-document-visibility、use-page-leave）以及工程基建类（use-id、use-merged-ref、use-callback-ref、use-isomorphic-effect、use-force-update、use-mounted、use-is-first-render、use-did-update、use-floating-window、use-radial-move、use-mask 等）。30 个同目录单测覆盖；包级 sideEffects: false，可摇树。

2.9 Pro 页面模式层（@xiaoye-react/pro）

packages/@xiaoye-react/pro/src/ 三个模块：page-container（页头 + 内容容器 + 面包屑联动）、search-filter（搜索条件栏：字段声明式配置、折叠展开、查询/重置回调）、pro-table（在 ui 的 DataTable 之上叠加工具栏、请求联动等管理端模式）。

3. 技术栈速览与选型理由

4. monorepo 目录导览

react-ui/
├── package.json                # 根脚本：dev/build/test/lint/typecheck/docs:lint/check:exports/e2e/release
├── pnpm-workspace.yaml         # workspace: apps/* + packages/* + packages/@xiaoye-react/*
├── commitlint.config.cjs       # conventional 提交校验（cz-git 交互生成）
├── cspell.json                 # 拼写门禁（含中文项目自定义词典）
├── eslint.config.mjs           # flat config；--max-warnings=57 棘轮，豁免理由写在注释里
├── stylelint.config.mjs        # CSS/样式规则
├── postcss.config.cjs          # postcss-nested 等
├── playwright.config.ts        # 截图 e2e（托管 apps/docs/dist）
├── playwright.interactions.config.ts  # 交互 e2e（Vite harness，端口 4175）
├── tsconfig.json               # 根 TS 配置（paths 指回各包 src）
├── patches/                    # dumi@2.4.47.patch
├── scripts/
│   ├── release.mjs             # 发布三档命令 preflight/check/publish 的实现
│   ├── validate-package-exports.mjs  # 校验 exports 指向真实文件（check:exports）
│   ├── serve-docs-dist.mjs     # e2e 前托管文档站产物
│   └── ensure-ui-build.mjs
├── packages/
│   ├── ui/                     # @xiaoye-react/ui 3.0.1 —— 核心组件库（对外发布）
│   │   └── src/
│   │       ├── core/           # 设计系统内核：Box/factory/styles-api/UIProvider/store/utils
│   │       ├── components/     # 129 个通用组件目录
│   │       ├── dates/          # 日期时间组件家族 + DatesProvider + hooks/utils
│   │       ├── schedule/       # 日程视图（AgendaView 等，基于 rrule）
│   │       ├── form/           # useForm 表单体系（use-field/validators/schema-resolver）
│   │       ├── emotion/        # 可选 Emotion 适配层（stylesTransform）
│   │       ├── colors-generator/  # chroma-js 色板生成
│   │       └── index.ts        # 唯一入口（'use client' 序言 + 星导出 + 消歧显式导出）
│   ├── hooks/                  # @xiaoye-react/hooks 1.4.1 —— 83 个无 UI hooks（对外发布）
│   ├── @xiaoye-react/
│   │   ├── pro/                # @xiaoye-react/pro 0.2.2 —— 管理端页面模式（对外发布）
│   │   ├── tests/              # 共享测试资产（core/dates 测试工具，private）
│   │   └── carousel|dev-icons|docs-styles-api|header|logo|meta|notifications|store  # 文档站/示例用内部包（private）
├── apps/
│   ├── docs/                   # @xiaoye-react/docs 文档站（dumi，private；含 CHANGELOG.zh-CN.md、迁移指南、lint 脚本）
│   └── nas-console/            # 示例控制台应用（本检出仅含 dist 构建产物 ⚠️ 源码未见）
├── e2e/
│   ├── harness/                # Vite 测试宿主页面（index/interactions/demos/app-shell 四组挂载点）
│   ├── interactions/           # 24 条交互用例：modal/slider/rating/inputs/collapse/app-shell/virtual-table/docs-demos + assert-harness
│   └── screenshots.spec.ts     # 10 条截图基线用例
├── column/                     # 专栏/文章素材目录（非运行代码）
├── archive/                    # 历史归档（含 audit/ 两轮全量审计与 CHECKLIST.md）
└── @types/                     # 仓库级环境类型声明

5. 快速上手

5.1 安装

组件库要求 React 19：

npm install @xiaoye-react/ui @xiaoye-react/hooks
# 或 pnpm add @xiaoye-react/ui @xiaoye-react/hooks

@xiaoye-react/ui 的 peerDependencies 为 react ^19.0.0、react-dom ^19.0.0、@xiaoye-react/hooks ^1.4.0（注意 hooks 下限 1.4.0：ui 产物引用了其 1.4.0 才有的 attachMediaListener 导出，见根 README「发布相关的坑」）。

5.2 引入样式

包 exports 提供 ./style.css 子路径（packages/ui/package.json 的 exports 字段），在应用入口引入一次：

import '@xiaoye-react/ui/style.css';

5.3 包裹 UIProvider 并使用组件

import { UIProvider, Button, DataTable } from '@xiaoye-react/ui';

export default function App() {
    return (
        <UIProvider theme={{ primaryColor: 'teal' }} colorScheme="auto">
            <Button variant="filled" color="teal" loading={false}>
                提交
            </Button>
        </UIProvider>
    );
}

UIProvider 负责四件事（见 packages/ui/src/core/UIProvider/UIProvider.tsx）：合并主题（UIThemeProvider）、向 :root 注入 CSS 变量（UICssVariables）、管理浅色/深色方案（受控/非受控 + localStorage 持久化键 ui-color-scheme-value，配合 ColorSchemeScript 防 FOUC）、向所有组件下发 StylesApi 上下文（类名前缀 ui、headless、stylesTransform 等）。

5.4 本仓库本地开发

pnpm install            # Node 22 + pnpm 9.12.3（packageManager 锁定）
pnpm dev                # 全 workspace 并行 dev（组件库 watch 构建 + 文档站）
pnpm dev:packages       # 仅包 watch 构建
pnpm dev:apps           # 仅文档站等应用
pnpm test:packages      # 全部单测（vitest）
pnpm build:packages     # 构建三包产物
pnpm e2e:interactions   # 24 条浏览器交互用例（需 pnpm exec playwright install chromium）
pnpm e2e:screenshots    # 10 条截图基线（托管 apps/docs/dist）
pnpm lint               # eslint（棘轮）+ stylelint + cspell
pnpm typecheck          # ui + hooks + docs demos 三套 tsconfig

提交走 pnpm commit（cz-git 交互式，commitlint 校验 conventional 规范）。完整门禁清单与新增组件步骤见 CONTRIBUTING.md，发布流程见第 06 篇《部署运行》。

6. 文档站与周边生态

apps/docs 不只是组件 demo 的陈列馆，而是与代码同权的一等公民：它带自己的 lint 脚本（docs:lint 三件套）、自己的 tsconfig（tsconfig.demos.json，让 demo 代码参与 pnpm typecheck）、生成脚本（docgen.ts 从类型产出 API 表素材、generate-css-exports.ts 产出 CSS 变量清单）以及迁移专题文档。文档首页（dumi 驱动，中文）按组件逐个组织 index.zh-CN.md 与 demo/ 目录，全站 136 个组件文档目录与 packages/ui/src/components 的 129 个目录加 core/box 等专题一一对应。docs:lint 的存在让文档获得了与测试同级的地位：API 表与类型不一致、demo 引用了不存在的 prop，都会在 CI 挡下来。周边还有三份值得读的材料：apps/docs/CHANGELOG.zh-CN.md（中文变更日志）、MIGRATION-ANTD-TO-REACTUI.md（从 antd 迁移的对照手册）与 ADMIN-ROADMAP.md（管理端化的路线图与进度台账）。

7. 项目演进与工程治理

根目录的 ADMIN-ROADMAP.md（组件库管理端倾斜计划）完整记录了这个项目从「C 端优先的通用库」转向「管理端优先、兼容 C 端」的路线：目标是搭建典型中后台页面（列表页 / 表单页 / 详情页 / 仪表盘）时不再需要业务侧自建任何组件。文档里按里程碑列出了已落地的能力：M1 的 DataTable MVP 与 Cascader、M2 的 DataTable 虚拟滚动（@tanstack/react-virtual）、行展开与列设置面板、P1 的 Descriptions/Transfer/Dropzone、P2 的 @xiaoye-react/pro 包（PageContainer / SearchFilter / ProTable，配三种 CRUD 模板：Modal 编辑、Drawer 编辑、主从详情）、P3 的无障碍补齐（DataTable 键盘行导航、Cascader 面板方向键、Transfer 的 aria 与列表键盘导航）。这份路线图还记录了一个真实的工程决策：文档站启动性能优化时，实测 mako 无持久化缓存、webpack fs cache 冷 21 分钟/热 146 秒均不划算，最终保留 mako 并把 phosphor/react-icons 的图标 barrel 从编译图中移出（438 个文件改写，入口包从 20.6MB 降到 13.7MB，顺带修掉 15 个不存在的图标导入）。

工程治理上，CONTRIBUTING.md 自述为「单人维护的仓库，但门禁、规范和发布流程都按『外人也能接手』的标准写在这里——包括未来的你自己和 AI 协作者」。两轮全量审计沉淀在 archive/audit/（可复用的 12 条逐文件审查清单位于 archive/audit/AUDIT-2026-09-17/CHECKLIST.md），并留下了明确的裁决原则：测试显式编码的行为 > 审查者直觉；争议项写「待裁决」，不进正式问题单。债务政策同样成文：lint 棘轮与 exhaustive-deps 台账只许调低，「故意不修」的理由必须留在 eslint.config.mjs 的注释里。源码里随处可见这类治理的痕迹——use-uncontrolled.ts 用大段 JSDoc 记录「双 onChange 陷阱」与历史修复 commit（9347c9fd），vite.config.ts 用注释保存性能实测数据，让后来者不需要考古就能理解决策上下文。

8. 命名与术语表

9. 技术选型的取舍叙事（补充）

对照第 3 节的选型表，有几个「为什么不是别的」值得一叙。样式引擎为什么不用 CSS-in-JS 打天下：库的默认路径是 CSS Modules + CSS 变量——产物里样式是静态 CSS（style.css），消费方打包器可以直接缓存与摇树，运行时零样式开销；CSS-in-JS（Emotion）被降级为可选通道（stylesTransform），服务的是「需要运行时动态样式的少数场景」。这个取舍与 tailwind 类方案的区别在于：组件库无法预知消费者的定制深度，CSS 变量提供了「主题层可编程、样式层静态化」的折中。为什么三个包而非一个：hooks 的 83 个原语对 React 18/19 双兼容、零依赖、可独立摇树，强行与 ui（React 19 独占、带 20+ 运行时依赖）捆绑会同时抬高两边的使用门槛；pro 则把「管理端模式」的迭代节奏与「基础组件」的稳定性节奏解耦（0.2.x 对 3.0.x）。为什么 dumi 而非 storybook：文档站的诉求是「中文长文 + demo + API 表」三合一且可被脚本核对，dumi 的 markdown 驱动模式最贴合；代价是绑定 webpack/mako 构建链（ADMIN-ROADMAP 已把迁移 rspress/vitepress 列为长期可选项）。

10. 快速上手的常见问题

安装与首次使用阶段有几个高频疑问，先答在这里。为什么不装 @xiaoye-react/ui 组件不报错但没有样式：样式在 @xiaoye-react/ui/style.css 里，需要显式 import 一次——库没有做自动样式注入（那会强迫所有用户接受 CSS-in-JS 运行时）；为什么控制台提示找不到 UIProvider：除了确实没包裹的情形，还要检查是否在同一次渲染里用了 useUITheme() 系 API 而组件树中 Provider 尚未挂载（例如在 Portal 里直接渲染组件且 Portal 目标在 React 树之外——Portal 内容仍属 React 树，正常不会被切断，真正常见的根因是多个 React 实例）；深色模式不生效：确认 data-ui-color-scheme 属性写在 documentElement 上、ColorSchemeScript（SSR）与 UIProvider 的 localStorageKey 一致、且没有第二个受控 Provider 在子树里覆盖方案。以上三条的机制细节分别在第 03、04 篇展开。若还有其他安装类问题，优先查阅 apps/docs/MIGRATION-ANTD-TO-REACTUI.md 与根 README.md，大部分已知坑都有成文记录。

11. 阅读地图

• 想理解「一个组件是怎么被造出来的」：先看 packages/ui/src/core/factory/（polymorphic 工厂）与 packages/ui/src/core/styles-api/（StylesApi），再对照范本 packages/ui/src/components/Button/Button.tsx；
• 想理解主题：packages/ui/src/core/UIProvider/（default-theme.ts / create-theme / UICssVariables / color-functions）；
• 想理解管理端能力：packages/ui/src/components/DataTable/ 与 packages/@xiaoye-react/pro/src/；
• 想参与发布：根 README.md 发布流程 + scripts/release.mjs。