crush-level-web/docs/AvatarSetting.md

# AvatarSetting 组件

这是一个根据Figma设计稿实现的头像设置模态框组件，支持头像预览、编辑、上传和删除功能。

## 功能特性

- 🖼️ 大尺寸圆形头像预览
- ✂️ 头像裁剪功能
- 📤 文件上传支持
- 🗑️ 头像删除功能
- 📱 响应式设计
- 🎨 符合设计规范的UI
- 🔄 模态框形式，覆盖在页面上

## 使用方法

```tsx
import AvatarSetting from '@/app/(main)/profile/components/AvatarSetting'

function ProfilePage() {
  const [isAvatarSettingOpen, setIsAvatarSettingOpen] = useState(false)
  const [currentAvatar, setCurrentAvatar] = useState<string>('')

  const handleAvatarChange = (avatarUrl: string) => {
    setCurrentAvatar(avatarUrl)
    // 这里可以调用API保存头像
  }

  const handleAvatarDelete = () => {
    setCurrentAvatar('')
    // 这里可以调用API删除头像
  }

  const openAvatarSetting = () => {
    setIsAvatarSettingOpen(true)
  }

  const closeAvatarSetting = () => {
    setIsAvatarSettingOpen(false)
  }

  return (
    <div>
      {/* 触发按钮 */}
      <button onClick={openAvatarSetting}>设置头像</button>

      {/* 头像设置模态框 */}
      <AvatarSetting
        isOpen={isAvatarSettingOpen}
        onClose={closeAvatarSetting}
        currentAvatar={currentAvatar}
        onAvatarChange={handleAvatarChange}
        onAvatarDelete={handleAvatarDelete}
      />
    </div>
  )
}
```

## Props

| 属性             | 类型                          | 默认值      | 说明                |
| ---------------- | ----------------------------- | ----------- | ------------------- |
| `isOpen`         | `boolean`                     | `false`     | 控制模态框显示/隐藏 |
| `onClose`        | `() => void`                  | `undefined` | 关闭模态框的回调    |
| `currentAvatar`  | `string \| undefined`         | `undefined` | 当前头像URL         |
| `onAvatarChange` | `(avatarUrl: string) => void` | `undefined` | 头像变更回调        |
| `onAvatarDelete` | `() => void`                  | `undefined` | 头像删除回调        |
| `className`      | `string`                      | `undefined` | 自定义CSS类名       |

## 层级关系

- 头像设置模态框：`z-40`
- 头像裁剪弹窗：`z-50`（更高层级）

## 文件格式支持

- 支持的格式：JPG、JPEG、PNG
- 文件大小限制：5MB
- VIP用户支持GIF格式

## 设计规范

- 背景色：`#211a2b`
- 头像尺寸：512x512px
- 按钮渐变：从 `#f264a4` 到 `#c241e6`
- 圆角：999px（完全圆形）
- 模态框尺寸：800x800px

## 测试页面

访问 `/test-avatar-setting` 可以查看组件的演示效果。

## 注意事项

1. 组件现在是模态框形式，会覆盖在页面上
2. 使用现有的 `AvatarCropModal` 组件进行头像裁剪
3. 文件上传使用原生的 `input[type="file"]` 实现
4. 组件会自动验证文件类型和大小
5. 裁剪后的图片会自动转换为圆形
6. 裁剪弹窗的层级比头像设置模态框更高