通用组件开发
This commit is contained in:
juguohong
211
src/components/Bubble/USAGE.md
Normal file
211
src/components/Bubble/USAGE.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 如何使用 Bubble 通用气泡组件
|
||||
|
||||
## 在其他组件中导入
|
||||
|
||||
```tsx
|
||||
import Bubble, { BubbleOption } from '@/components/Bubble';
|
||||
```
|
||||
|
||||
## 基本使用示例
|
||||
|
||||
### 1. 室内外选择（如UI图所示）
|
||||
|
||||
```tsx
|
||||
import React, { useState } from 'react';
|
||||
import Bubble, { BubbleOption } from '@/components/Bubble';
|
||||
|
||||
const MyPage: React.FC = () => {
|
||||
const [selectedLocation, setSelectedLocation] = useState<string>('');
|
||||
|
||||
const locationOptions: BubbleOption[] = [
|
||||
{ id: 1, label: '室内', value: 'indoor' },
|
||||
{ id: 2, label: '室外', value: 'outdoor' },
|
||||
{ id: 3, label: '半室外', value: 'semi-outdoor' }
|
||||
];
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h2>选择场地类型</h2>
|
||||
<Bubble
|
||||
options={locationOptions}
|
||||
value={selectedLocation}
|
||||
onChange={(value) => setSelectedLocation(value as string)}
|
||||
layout="horizontal"
|
||||
size="medium"
|
||||
/>
|
||||
<p>您选择的场地类型: {selectedLocation}</p>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### 2. 时间选择器
|
||||
|
||||
```tsx
|
||||
const [selectedTime, setSelectedTime] = useState<string>('');
|
||||
|
||||
const timeOptions: BubbleOption[] = [
|
||||
{ id: 1, label: '晨间 6:00-10:00', value: 'morning' },
|
||||
{ id: 2, label: '上午 10:00-12:00', value: 'forenoon' },
|
||||
{ id: 3, label: '中午 12:00-14:00', value: 'noon' },
|
||||
{ id: 4, label: '下午 14:00-18:00', value: 'afternoon' },
|
||||
{ id: 5, label: '晚上 18:00-22:00', value: 'evening' },
|
||||
{ id: 6, label: '夜间 22:00-24:00', value: 'night' }
|
||||
];
|
||||
|
||||
<Bubble
|
||||
options={timeOptions}
|
||||
value={selectedTime}
|
||||
onChange={(value) => setSelectedTime(value as string)}
|
||||
layout="grid"
|
||||
columns={3}
|
||||
size="medium"
|
||||
/>
|
||||
```
|
||||
|
||||
### 3. 多选模式
|
||||
|
||||
```tsx
|
||||
const [selectedValues, setSelectedValues] = useState<string[]>([]);
|
||||
|
||||
const options: BubbleOption[] = [
|
||||
{ id: 1, label: '运动', value: 'sports' },
|
||||
{ id: 2, label: '音乐', value: 'music' },
|
||||
{ id: 3, label: '阅读', value: 'reading' },
|
||||
{ id: 4, label: '旅行', value: 'travel' }
|
||||
];
|
||||
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValues}
|
||||
onChange={(value) => setSelectedValues(value as string[])}
|
||||
multiple={true}
|
||||
layout="grid"
|
||||
columns={2}
|
||||
size="medium"
|
||||
/>
|
||||
```
|
||||
|
||||
### 4. 带图标和描述
|
||||
|
||||
```tsx
|
||||
const [selectedSport, setSelectedSport] = useState<string>('');
|
||||
|
||||
const sportOptions: BubbleOption[] = [
|
||||
{
|
||||
id: 1,
|
||||
label: '网球',
|
||||
value: 'tennis',
|
||||
icon: '🎾',
|
||||
description: '室内外均可'
|
||||
},
|
||||
{
|
||||
id: 2,
|
||||
label: '篮球',
|
||||
value: 'basketball',
|
||||
icon: '🏀',
|
||||
description: '室内场地'
|
||||
}
|
||||
];
|
||||
|
||||
<Bubble
|
||||
options={sportOptions}
|
||||
value={selectedSport}
|
||||
onChange={(value) => setSelectedSport(value as string)}
|
||||
layout="vertical"
|
||||
size="large"
|
||||
/>
|
||||
```
|
||||
|
||||
### 5. 不同布局方式
|
||||
|
||||
```tsx
|
||||
// 水平布局 - 适合选项较少
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="horizontal"
|
||||
size="medium"
|
||||
/>
|
||||
|
||||
// 垂直布局 - 适合选项较多
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="vertical"
|
||||
size="medium"
|
||||
/>
|
||||
|
||||
// 网格布局 - 适合需要整齐排列
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="grid"
|
||||
columns={3}
|
||||
size="medium"
|
||||
/>
|
||||
```
|
||||
|
||||
### 6. 不同尺寸
|
||||
|
||||
```tsx
|
||||
// 小尺寸 - 适合紧凑界面
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="horizontal"
|
||||
size="small"
|
||||
/>
|
||||
|
||||
// 中尺寸 - 默认尺寸
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="horizontal"
|
||||
size="medium"
|
||||
/>
|
||||
|
||||
// 大尺寸 - 适合触摸设备
|
||||
<Bubble
|
||||
options={options}
|
||||
value={selectedValue}
|
||||
onChange={handleChange}
|
||||
layout="horizontal"
|
||||
size="large"
|
||||
/>
|
||||
```
|
||||
|
||||
## 组件特性
|
||||
|
||||
- **通用性**: 不局限于特定功能，可用于任何选择场景
|
||||
- **灵活布局**: 支持水平、垂直、网格三种布局方式
|
||||
- **多尺寸支持**: 小、中、大三种尺寸适应不同场景
|
||||
- **丰富内容**: 支持图标和描述，让选项更加丰富
|
||||
- **响应式设计**: 自动适应不同屏幕尺寸
|
||||
- **状态管理**: 内置选中状态管理，支持单选和多选
|
||||
- **类型安全**: 完整的 TypeScript 类型定义
|
||||
- **可访问性**: 支持键盘导航和屏幕阅读器
|
||||
|
||||
## 常见使用场景
|
||||
|
||||
1. **场地选择**: 室内/室外/半室外
|
||||
2. **时间选择**: 时间段、日期范围
|
||||
3. **分类选择**: 兴趣爱好、技能标签
|
||||
4. **设置选项**: 主题、语言、通知设置
|
||||
5. **筛选条件**: 价格范围、评分、距离等
|
||||
6. **导航菜单**: 顶部导航、侧边栏菜单
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 确保传入的 `options` 数组不为空
|
||||
2. 多选模式下，`value` 应该是数组类型
|
||||
3. 单选模式下，`value` 可以是字符串或数字类型
|
||||
4. 组件会自动处理选中状态的样式变化
|
||||
5. 支持图标和描述，让选项更加丰富
|
||||
6. 响应式设计，自动适应不同屏幕尺寸
|
||||
7. 可以通过 `disabled` 属性禁用整个组件或单个选项
|
||||
Reference in New Issue
Block a user