SlimFit 组件库

SlimFit 是一个现代化的 React 组件库，专为企业级应用设计，提供可复用、文档完善且可测试的 UI 组件。

特点

• 基于 React 18+ 和 TypeScript 开发
• 扩展 Ant Design 5.x，提供更多定制化组件
• 统一的设计语言和交互体验
• 完善的类型定义和开发体验
• 详细的文档和示例

新功能：FormMode 表单模式

新增了表单模式功能，支持在 edit 和 read 两种模式之间切换：

基础用法

import { Form, Input, Select } from '@yqg/slimfit';

// 只读模式
<Form mode="read">
  <Form.Item label="用户名" name="username">
    <Input value="john_doe" />
  </Form.Item>
  <Form.Item label="角色" name="role">
    <Select value="admin" options={roleOptions} />
  </Form.Item>
</Form>

// 编辑模式（默认）
<Form mode="edit">
  <Form.Item label="用户名" name="username">
    <Input placeholder="请输入用户名" />
  </Form.Item>
</Form>

特性

• 🔄 模式切换：支持 edit 和 read 两种模式
• 📝 智能渲染：根据组件类型自动选择合适的只读渲染方式
• 🌍 国际化支持：集成 Ant Design 的国际化体系
• 🎨 样式一致：保持与编辑模式的布局一致性
• 🔧 可扩展：支持自定义只读渲染器

支持的组件

• Input: Input, Input.TextArea, Input.Password, Input.Search
• Select: Select
• Date: DatePicker, DatePicker.RangePicker
• Choice: Radio, Radio.Group
• 其他: 可通过 HOC 扩展更多组件

详细文档请查看 FormMode 文档

安装

# 使用 npm
npm install @yqg/slimfit

# 使用 yarn
yarn add @yqg/slimfit

# 使用 pnpm
pnpm add @yqg/slimfit

快速上手

import React from 'react';
import { Button } from '@yqg/slimfit';

const App = () => <Button type='primary'>SlimFit Button</Button>;

export default App;

项目目录结构

slimfit/
├── components/           # 组件源码
│   ├── button/           # 按钮组件
│   ├── input/            # 输入框组件
│   ├── ...               # 其他组件
│   ├── style/            # 全局样式
│   │   ├── index.css     # 主样式入口
│   │   └── theme-vars.css # 自动生成的主题变量
│   └── themes/           # 主题配置
│       ├── index.ts      # 主题导出
│       ├── token.ts      # 全局 Design Token
│       ├── button.ts     # 按钮组件 Token
│       └── input.ts      # 输入框组件 Token
├── constant/             # 全局常量
│   └── colors.ts         # 颜色常量定义
├── docs/                 # 文档目录
│   ├── guide/            # 指南文档
│   └── rules/            # 规范文档
├── scripts/              # 构建和开发脚本
│   ├── generate-css-vars.js # 生成CSS变量脚本
│   ├── generate-exports.js  # 生成组件导出脚本
│   └── test-setup.ts     # 测试环境设置
├── dist/                 # 构建输出目录
│   └── esm/              # ES 模块格式
├── .max-docs/            # 文档生成配置
└── .husky/               # Git 钩子配置

组件目录结构

每个组件遵循以下结构（以 Button 为例）：

components/button/
├── button.tsx           # 主要组件实现
├── button.test.tsx      # 组件单元测试
├── index.ts             # 导出文件
├── index.md             # 组件文档
├── style.css            # 组件特定样式（如需）
└── demo/                # 组件演示
    └── index.tsx        # 基础用法示例

主题系统

SlimFit 使用分层的主题系统，基于 Ant Design 的 Token 系统构建：

// 使用主题
import { Theme } from '@yqg/slimfit';
import { ConfigProvider } from 'antd';

const App = () => (
  <ConfigProvider theme={Theme}>
    <YourApp />
  </ConfigProvider>
);

颜色系统

SlimFit 提供了全面的颜色系统，可以通过多种方式使用：

1. 在样式中使用

所有颜色都已注入为 CSS 变量，可以直接在样式中使用：

.highlight {
  color: var(--color-fi-600);
  background-color: var(--color-neutral-50);
}

这些变量在构建过程中自动从 constant/colors.ts 生成，并注入到全局样式中。

2. 与 Tailwind CSS 集成

SlimFit 的颜色系统可以与 Tailwind CSS 无缝集成：

// tailwind.config.js
const colors = require('@yqg/slimfit/constant/colors').default;

module.exports = {
  theme: {
    extend: {
      colors: colors,
    },
  },
};

这样就可以在 Tailwind 中直接使用 SlimFit 的颜色系统：

<div class="text-fi-600 bg-neutral-50">品牌色文本，浅色背景</div>

<div class="text-neutral-950 bg-fi-100">深色文本，品牌浅色背景</div>

<!-- 使用语义化颜色 -->
<div class="text-semantic-primary bg-semantic-primaryLight">使用语义化颜色</div>

开发指南

技术栈

• 核心框架: React 18+
• 开发语言: TypeScript
• 基础组件: Ant Design 5.x
• 构建工具: @yqg/max
• 代码格式化: Prettier
• Git Hooks: Husky
• 单元测试: Vitest
• 提交前检查: lint-staged

开发规范

• 文件命名使用小写字母和连字符（例如：card-list.tsx）
• 使用 Prettier 保持一致的代码风格（2 空格缩进）
• 为 props 和 state 定义完整的 TypeScript 接口
• 每个组件必须包含文档和演示示例
• 遵循 Ant Design 组件模式和 API 设计

开发脚本

SlimFit 提供了几个开发脚本来自动化常见任务：

generate-css-vars.js

自动从 constant/colors.ts 中的颜色定义生成 CSS 变量文件 components/style/theme-vars.css。

功能特点：

• 解析 colors 对象，为每个颜色级别生成对应的 CSS 变量（如 --color-fi-600）
• 解析 semantic 对象，生成语义化颜色变量（如 --color-primary）
• 自动将驼峰命名转换为连字符命名（如 primaryLight → primary-light）
• 在构建过程中自动执行，确保 CSS 变量与颜色定义保持同步

使用场景：

• 修改 constant/colors.ts 后需要更新 CSS 变量时
• 添加新颜色或语义化颜色时

generate-exports.js

自动扫描 components 目录，为包含 index.ts 的组件目录生成统一的导出文件。

功能特点：

• 自动发现所有组件目录并检查是否包含 index.ts
• 按字母顺序排序组件导出，特殊目录（如 themes）放在最后
• 生成命名导出语句以支持 Tree Shaking
• 确保组件库的导出结构保持一致

使用场景：

• 添加新组件后需要更新主导出文件时
• 重新组织组件结构后需要同步导出时

运行脚本：

# 生成 CSS 变量
node scripts/generate-css-vars.js

# 生成组件导出
node scripts/generate-exports.js

测试策略

SlimFit 的组件测试分为三类：

1. 直接导出的 Ant Design 组件：

   • 基本快照测试验证渲染
   • 无需测试 Ant Design 已覆盖的功能

2. 增强型 Ant Design 组件：

   • 测试新增功能和自定义内容
   • 验证样式覆盖和自定义属性

3. 自定义组件：

   • 全面测试所有功能和边界情况
   • 测试用户交互和错误状态

测试命令

# 运行所有测试
pnpm test

# 监听模式运行测试
pnpm test:watch

# 生成测试覆盖率报告
pnpm test:coverage

# 更新所有快照
pnpm test -- -u

# 更新特定文件的快照
pnpm test -- -u path/to/component.test.tsx

快照测试最佳实践

• 保持快照小而聚焦
• 只快照必要的组件树
• 代码审查时检查快照差异
• 对于有动态数据的组件，使用自定义序列化器或模拟数据

许可证

MIT