@qingshanhan/components-ui

基于 Ant Design 5.x 的业务组件库，提供场景化扩展与统一设计规范。

📖 在线文档（Storybook）: hance-components-ui.edgeone.dev

已验证环境

| 依赖 | 版本范围 | 已验证 | |------|---------|-------| | React | 18.x / 19.x | ✅ 18.3.x | | antd | 5.20.0 ~ 5.24.x | ✅ 5.21.x | | Node | ≥ 20.0.0 | ✅ 20.18.0 | | pnpm | ≥ 9.0.0 | ✅ 9.x |

快速上手

安装

pnpm add component-ui antd react react-dom

全量引入

// main.tsx
import 'component-ui/styles';  // 全局 CSS 变量
import { Button } from 'component-ui';

export default function App() {
  return <Button businessVariant="highlight">提交</Button>;
}

按需引入（推荐）

消费方 vite.config.ts 配置 resolver：

import Components from 'unplugin-react-components/vite';
import { ComponentUIResolver } from 'component-ui/resolver';

export default {
  plugins: [
    Components({
      resolvers: [ComponentUIResolver()],
    }),
  ],
};

配置后，组件和对应 CSS 自动按需加载，无需手动 import。

打包器要求：按需引入需要打包器支持 package.json#sideEffects glob 模式（Vite/Webpack 5/Rollup 3+ 均支持）。

主题定制

通过 antd ConfigProvider

import { ConfigProvider, theme } from 'antd';

<ConfigProvider
  theme={{
    token: {
      colorPrimary: '#ff6b35',
    },
  }}
>
  <Button businessVariant="highlight">自定义主色</Button>
</ConfigProvider>

组件库内部通过 useToken 读取主题变化，样式自动跟随。

通过 CSS 变量直接覆盖

/* 在业务项目的全局 CSS 中 */
:root {
  --cui-color-primary: #ff6b35;
  --cui-radius-base: 4px;
}

暗色主题

import { ConfigProvider, theme } from 'antd';

// 1. antd 切换暗色算法
<ConfigProvider theme={{ algorithm: theme.darkAlgorithm }}>
  {/* 2. body 加 data-theme="dark"，component-ui CSS 变量切换 */}
  <App />
</ConfigProvider>

// 切换暗色时同步 body 属性
document.body.setAttribute('data-theme', 'dark');

调试样式

• 浏览器 DevTools 中类名 .Button__button__xxxxx → 组件库样式
• :root 下 --cui-* 变量 → 组件库全局 token
• 业务方覆盖：.my-btn { --cui-color-primary: #xxx } 或更具体的类名，无需 !important

SSR 接入指南

⚠️ component-ui v1.x 未做专项 SSR 适配，以下为社区推荐方案。

Next.js App Router

参考 antd 官方 SSR 文档，使用 @ant-design/cssinjs 抽取样式：

// app/AntdRegistry.tsx
'use client';
import React from 'react';
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import { useServerInsertedHTML } from 'next/navigation';

export function AntdRegistry({ children }: { children: React.ReactNode }) {
  const cache = React.useMemo(() => createCache(), []);
  useServerInsertedHTML(() => (
    <style
      id="antd"
      dangerouslySetInnerHTML={{ __html: extractStyle(cache, true) }}
    />
  ));
  return <StyleProvider cache={cache}>{children}</StyleProvider>;
}

component-ui 的静态 CSS 通过 import 'component-ui/styles' 正常引入即可，无需额外适配。

v1.1 计划：提供 <CuiStyleRegistry> 封装上述逻辑。

贡献指南

开发

pnpm install
pnpm dev          # 启动 Storybook

新增组件

pnpm generate MyComponent

自动在 src/components/MyComponent/ 下生成组件模板，并追加 src/index.ts 导出。

发布

# 记录变更
pnpm changeset

# 发布（自动执行 lint + test + type-check + build）
pnpm release

Roadmap

v1.1（0~3 个月）

• [ ] PR CI 完整化：coverage 门禁（核心组件 ≥ 80%）/ size-limit / 视觉回归
• [ ] <ThemeProvider> 封装 ConfigProvider + 暗色切换
• [ ] 组件按域分类（form / table / feedback / layout）
• [ ] React 19 兼容验证
• [ ] antd 版本兼容性矩阵测试（5.20~latest）
• [ ] SSR 专项适配

v2.0（3~6 个月）

• [ ] 转 pnpm workspaces + Turborepo Monorepo
• [ ] 拆包：@cui/components / @cui/resolver / @cui/hooks / @cui/utils / @cui/theme / @cui/cli
• [ ] 视觉回归（Chromatic）+ E2E（Playwright）

v3.0（6 个月+）

• [ ] 业务域组件包（form / table / chart）
• [ ] 跨框架适配（Vue 3 / Web Components）
• [ ] 组件资产平台 + 使用埋点

常见问题

Q：按需引入后样式不生效？

A：检查消费方打包器是否支持 sideEffects glob（**/*.css）。Vite / Webpack 5 支持，Webpack 4 不支持。另外确认 resolver 中的 from 路径与实际 node_modules/component-ui/dist/esm/components/*/index.js 对应。

Q：修改组件样式需要 !important？

A：无需 !important。组件颜色通过 CSS 变量传递（--cui-color-primary），业务方写更具体的类名或在父元素覆盖 CSS 变量即可。

Q：如何只替换某个组件的主色？

.my-section .Button__button__xxxxx {
  --cui-color-primary: #ff6b35;
}

Q：与 antd 主题冲突？

A：component-ui 样式基于 antd useToken 读取主题，通过 CSS 变量传递。只要业务方统一通过 ConfigProvider 管理主题，不会冲突。

License

MIT