# Storybook 测试指南 - Selector 组件

## 快速开始

### 1. 启动 Storybook

在 `packages/private-materials` 目录下运行：

```bash
pnpm storybook
```

或者

```bash
npm run storybook
```

Storybook 将在 `http://localhost:6006` 启动。

### 2. 查看 Selector 组件

在 Storybook 左侧菜单中找到：
- **Pro Components** > **Selector**

## Stories 说明

### 基础功能

- **Default**: 默认单选模式 - 原始值类型
- **Multiple**: 多选模式 - 原始值数组
- **SingleWithQuantity**: 单选 + 数量 - 对象值类型
- **MultipleWithQuantity**: 多选 + 数量 - 卡片样式

### 布局

- **GridLayout2Columns**: 网格布局 - 2列
- **GridLayout3Columns**: 网格布局 - 3列

### 校验

- **WithValidation**: 校验规则 - 必选、最小/最大数量
  - 支持必选（required）
  - 支持最小/最大选择数量（min/max）
  - 支持手动校验和获取错误信息

### 互斥组

- **MutexGroups**: 互斥组示例
  - 选项1、2、3属于互斥组1，只能选一个
  - 选项4、5、6属于互斥组2，只能选一个

### 状态

- **Disabled**: 禁用状态
  - 支持单个选项禁用
  - 支持整个组件禁用

### 样式变体

- **SelectVariant**: Select 变体 - 下拉选择（单选）
- **SelectVariantMultiple**: Select 变体 - 多选下拉
- **CardVariants**: 卡片样式变体 - 不同选中态
  - 默认选中态（default）
  - 填充选中态（filled）
  - 角标选中态（cornered）

### 自定义

- **CustomIcon**: 自定义选中图标
- **CustomRender**: 自定义渲染内容

### 分组组件

- **SelectorGroupBasic**: SelectorGroup 基础示例
  - 多个选择器组
  - 每个组独立配置
  - 标签页导航

- **SelectorGroupWithLinkage**: SelectorGroup 联动规则示例
  - 选择主菜后显示对应的定制选项
  - 汉堡 → 显示"汉堡定制"分组
  - 披萨 → 显示"披萨定制"分组

## 交互测试

在 Storybook 中，你可以：

1. **手动测试交互**
   - 点击选择器项
   - 调整数量
   - 验证校验规则
   - 测试互斥组行为

2. **查看状态变化**
   - 在控制台查看 `onChange` 回调的输出
   - 查看组件值的 JSON 展示

3. **测试不同配置**
   - 使用 Storybook 的 Controls 面板调整 props
   - 切换不同的 mode、valueType、variant 等

4. **调试样式**
   - 使用浏览器开发者工具检查样式
   - 测试不同屏幕尺寸

## 控件面板

Storybook 提供了交互式控件面板，你可以调整：

- **mode**: 选择模式（single/multiple）
- **valueType**: 值类型（primitive/object）
- **variant**: 样式变体（default/card/select）
- **disabled**: 是否禁用

## 快捷键

在 Storybook 界面中：

- `A` - 切换到画布视图
- `D` - 切换到文档视图
- `S` - 搜索
- `?` - 查看所有快捷键

## 测试用例映射

每个 Story 对应测试计划中的测试用例：

| Story | 对应测试用例 |
|-------|-------------|
| Default | TC-B-001: 基础单选功能 |
| Multiple | TC-B-002: 基础多选功能 |
| SingleWithQuantity | TC-B-003: 单选 + 数量 |
| MultipleWithQuantity | TC-B-004: 多选 + 数量 |
| GridLayout2Columns | TC-L-001: 网格布局 2列 |
| GridLayout3Columns | TC-L-002: 网格布局 3列 |
| WithValidation | TC-V-001 ~ TC-V-005 |
| MutexGroups | TC-R-001: 互斥组功能 |
| Disabled | TC-U-001 ~ TC-U-003 |
| SelectVariant | TC-A-001: Select 变体 |
| CardVariants | TC-A-002: 卡片样式变体 |
| SelectorGroupBasic | TC-G-001: 基础分组 |
| SelectorGroupWithLinkage | TC-G-002: 联动规则 |

## 注意事项

1. **Storybook 主要用于视觉测试和交互验证**
   - 不是单元测试的替代品
   - 需要配合 Vitest 进行自动化测试

2. **数据持久化**
   - Storybook 中的状态不会持久化
   - 刷新页面会重置状态

3. **浏览器兼容性**
   - 在不同浏览器中测试以确保兼容性
   - 检查响应式布局

4. **性能测试**
   - 在大量选项的情况下测试性能
   - 检查渲染时间和交互响应

## 扩展 Stories

要添加新的 Story，在 `Selector.stories.tsx` 中添加：

```typescript
export const MyNewStory: Story = {
  args: {
    // 配置...
  },
  render: (args: any) => {
    // 渲染逻辑...
  },
};
```

## 故障排除

### Storybook 无法启动

1. 检查依赖是否安装：`pnpm install`
2. 检查端口 6006 是否被占用
3. 清除缓存：删除 `.storybook` 相关缓存文件

### 组件不显示

1. 检查导入路径是否正确
2. 检查样式文件是否正确加载
3. 查看浏览器控制台错误信息

### 类型错误

1. 确保 `@storybook/react` 版本兼容
2. 检查 TypeScript 配置
3. 查看 Storybook 配置文件

## 参考文档

- [Storybook 官方文档](https://storybook.js.org/)
- [Selector 组件开发文档](./docs/selector.$tab-dev.md)
- [Selector 组件测试计划](./TEST_PLAN.md)