组件库开发实战：从 0 到 1 搭建企业级组件库

深夜,我盯着屏幕上的代码发呆。作为一个中型创业公司的前端负责人,我正在思考一个问题：我们是否需要开发自己的组件库？

过去一年,随着业务的快速发展,前端团队从 3 人扩展到了 12 人,项目也从 1 个变成了 6 个。每个项目都在用着不同版本的 UI 组件,设计规范也不统一,这让产品同学苦不堆言。经过一周的调研和团队讨论,我们决定开发一套自己的组件库。

项目规划

首先从业务目标出发,我们希望通过组件库实现三个核心目标：统一各个项目的设计规范、提高团队的开发效率、保证代码的质量标准。这些都是困扰我们团队已久的问题。

在技术层面,我们对组件库提出了严格的要求：必须有完整的 TypeScript 类型支持,确保类型安全；测试覆盖率要达到 100%,保证组件的可靠性；文档和示例要详细完整,降低使用门槛；同时要注重性能优化,保证组件的运行效率。

关于组件的范围,我们计划分四个层次逐步实现：

基础组件：包括 Button、Input、Select、Table 等最常用的基础组件
表单组件：包括 Form、DatePicker、Upload 等数据录入组件
反馈组件：包括 Modal、Message、Notification 等交互反馈组件
业务组件：包括 SearchForm、DetailCard、StatusFlow 等业务相关组件

这样的规划既照顾到了基础需求,又为未来的业务扩展预留了空间。我们决定采用渐进式开发策略,先完成基础组件和表单组件,然后再逐步扩展到反馈组件和业务组件。

技术选型

在技术选型上,我们经过反复讨论和评估,最终确定了一套完整的技术栈。
首先是基础框架的选择。考虑到团队的技术背景和项目需求,我们选择了 React 18 作为核心框架。样式解决方案上,我们采用了 Tailwind CSS 配合 CSS Modules 的组合,这样既能保证样式的可维护性,又能避免样式冲突。构建工具选择了 Vite,它的快速启动和热更新特性能大大提升开发效率。测试框架则采用了 Vitest 配合 Testing Library,这个组合既保证了测试的可靠性,又与 Vite 完美集成。
在开发工具链方面,我们也做了精心的选择。文档系统采用了 Storybook,它不仅能够独立开发和测试组件,还能自动生成交互式文档。代码规范通过 ESLint 和 Prettier 的组合来保证,这样能确保团队代码风格的一致性。版本管理选择了 Changesets,它能够帮助我们更好地管理包的版本和变更日志。最后,我们使用 GitHub Actions 搭建了完整的 CI 流程,确保代码质量和发布流程的规范性。

组件开发

让我们从一个基础的 Button 组件开始：

// components/Button/Button.tsx
import { forwardRef } from 'react'
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/utils'

const buttonVariants = cva('inline-flex items-center justify-center rounded-md font-medium transition-colors', {
  variants: {
    variant: {
      primary: 'bg-primary text-white hover:bg-primary/90',
      secondary: 'bg-secondary text-white hover:bg-secondary/90',
      outline: 'border-2 border-primary text-primary hover:bg-primary/10'
    },
    size: {
      sm: 'h-8 px-3 text-sm',
      md: 'h-10 px-4 text-base',
      lg: 'h-12 px-6 text-lg'
    }
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md'
  }
})

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
  loading?: boolean
  icon?: React.ReactNode
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(({ className, variant, size, loading, icon, children, ...props }, ref) => {
  return (
    <button ref={ref} className={cn(buttonVariants({ variant, size }), className)} disabled={loading || props.disabled} {...props}>
      {loading && <LoadingSpinner className='mr-2 h-4 w-4 animate-spin' />}
      {icon && <span className='mr-2'>{icon}</span>}
      {children}
    </button>
  )
})

Button.displayName = 'Button'

export { Button, buttonVariants }

测试用例

每个组件都需要完整的测试用例：

// components/Button/Button.test.tsx
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'

describe('Button', () => {
  it('renders children correctly', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('handles different variants', () => {
    const { rerender } = render(<Button variant='primary'>Primary</Button>)
    expect(screen.getByText('Primary')).toHaveClass('bg-primary')

    rerender(<Button variant='secondary'>Secondary</Button>)
    expect(screen.getByText('Secondary')).toHaveClass('bg-secondary')
  })

  it('shows loading state', () => {
    render(<Button loading>Loading</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
    expect(screen.getByText('Loading')).toBeInTheDocument()
    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument()
  })

  it('forwards ref correctly', () => {
    const ref = jest.fn()
    render(<Button ref={ref}>Click me</Button>)
    expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
  })
})

文档系统

好的文档对组件库至关重要：

// stories/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from '@/components/Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline']
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg']
    }
  }
}

export default meta

type Story = StoryObj<typeof Button>

export const Primary: Story = {
  args: {
    children: 'Primary Button',
    variant: 'primary'
  }
}

export const WithIcon: Story = {
  args: {
    children: 'With Icon',
    icon: <Icon name='plus' />,
    variant: 'primary'
  }
}

export const Loading: Story = {
  args: {
    children: 'Loading',
    loading: true
  }
}

发布流程

建立规范的发布流程很重要：

// scripts/release.ts
import { getChangedPackages, createChangeset, publishPackages } from '@changesets/cli'

async function release() {
  // 获取变更的包
  const changedPackages = await getChangedPackages()

  // 创建变更集
  await createChangeset({
    summary: 'Update components and fix bugs',
    packages: changedPackages.map(pkg => ({
      name: pkg.name,
      type: 'patch' // major | minor | patch
    }))
  })

  // 发布包
  await publishPackages({
    tag: 'latest',
    access: 'public',
    registry: 'https://registry.npmjs.org'
  })
}

release().catch(console.error)

实践心得

开发组件库的过程中,我们总结出几点重要经验：

组件设计要兼顾灵活性和易用性
TypeScript 类型定义要完整准确
文档和示例要详细易懂
测试用例要覆盖各种场景
版本管理要规范严谨

就像搭建一座大楼,组件库需要有坚实的基础(架构设计),规范的施工流程(开发规范),以及完善的配套设施(文档测试)。只有这样,才能建造出一个稳固耐用的组件库。

写在最后

开发组件库是一个持续演进的过程,需要在实践中不断完善。正如建筑需要经常维护一样,组件库也需要持续的更新和优化。

有什么问题欢迎在评论区讨论,让我们一起探讨组件库开发的最佳实践！

如果觉得有帮助,别忘了点赞关注,我会继续分享更多实战经验~

posted @ 2024-12-12 13:07 远洋录阅读(42) 评论(0) 编辑收藏举报

刷新页面返回顶部