UI 基础组件

概述

UI 基础组件是基于 Shadcn/UI 的基础组件库，主要包含按钮、表单、导航等常用 UI 元素。

创建 UI 组件

1. 生成组件模板

npm run registry:create <component-name>

# 或明确指定类型
npm run registry:create <component-name> --type ui

组件名称只支持小写字母和连字符（-），并且必须以字母开头和结尾。

生成的目录结构：

registry/ssp/ui/<component-name>/
├── index.tsx          # 组件源代码
├── index.json         # 组件注册信息
├── example.tsx        # 组件示例
└── README.mdx         # 组件文档

2. 安装外部依赖

如果组件需要外部依赖，先安装到项目中：

npm i <package-name>

然后添加到 index.json 的 dependencies 字段：

registry/ssp/ui/<component-name>/index.json

{
  "dependencies": [
    "@radix-ui/react-slot",
    "lucide-react"
  ]
}

示例：Button 组件

npm i @radix-ui/react-slot lucide-react class-variance-authority

registry/ssp/ui/button/index.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "type": "registry:component",
  "dependencies": [
    "@radix-ui/react-slot",
    "lucide-react", 
    "class-variance-authority"
  ]
}

3. 配置组件间依赖

如果组件依赖其他注册表组件，添加到 registryDependencies 字段：

{
  "registryDependencies": [
    "utils",
    "button"
  ]
}

4. 实现组件

编辑 index.tsx 文件实现组件逻辑：

registry/ssp/ui/<component-name>/index.tsx

import * as React from "react"
import { cn } from "@/lib/utils"

export interface ComponentProps 
  extends React.HTMLAttributes<HTMLDivElement> {
  variant?: "default" | "secondary"
}

const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
  ({ className, variant = "default", ...props }, ref) => {
    return (
      <div
        className={cn(
          "base-styles",
          {
            "default-styles": variant === "default",
            "secondary-styles": variant === "secondary",
          },
          className
        )}
        ref={ref}
        {...props}
      />
    )
  }
)
Component.displayName = "Component"

export { Component }

5. 创建示例

编辑 example.tsx 文件创建使用示例：

registry/ssp/ui/<component-name>/example.tsx

import { Component } from "./index"

export default function Example() {
  return (
    <div className="space-y-4">
      <Component variant="default">
        Default variant
      </Component>
      <Component variant="secondary">
        Secondary variant
      </Component>
    </div>
  )
}

6. 编写文档

编辑 README.mdx 文件：

registry/ssp/ui/<component-name>/README.mdx

---
title: Component Name
---

## 安装

<RegistryDownload filename="component-name.json" />

## 参考

- [shadcn/ui component](https://ui.shadcn.com/docs/components/component-name)

## 示例

import Example from "@/registry/ssp/ui/component-name/example";

<ExampleCode content={`_code_autogenerated_`}>
  <Example />
</ExampleCode>

## API

### Props

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| variant | "default" \| "secondary" | "default" | 组件变体 |
| className | string | - | 自定义样式类 |

7. 更新主题（如需要）

注意

主题文件应由维护者统一管理。如需修改主题变量，请联系团队成员。

如果组件需要新的 CSS 变量，更新 registry/ssp/theme/style.json：

{
  "cssVars": {
    "--new-variable": "value"
  },
  "theme": {
    "newVariable": "var(--new-variable)"
  }
}

8. 代码检查

使用 Biome 检查代码质量：

npm run check registry/ssp/ui/<component-name>

从 Shadcn/UI 迁移

推荐做法

大部分 UI 组件可以直接从 Shadcn/UI 迁移，只需要做少量样式和逻辑调整。

访问 Shadcn/UI 组件页面
复制组件源代码到 index.tsx
复制示例代码到 example.tsx
根据需要调整样式和逻辑
更新依赖配置

最佳实践

使用 TypeScript 定义完整的 Props 接口
使用 React.forwardRef 支持 ref 转发
使用 cn 工具函数合并 className
提供有意义的 displayName
编写清晰的使用示例
添加必要的 JSDoc 注释

下一步

完成组件开发后，查看文档生成与同步了解如何发布组件。