mini-programs/src/components/Bubble/USAGE.md

如何使用 Bubble 通用气泡组件

在其他组件中导入

import Bubble, { BubbleOption } from '@/components/Bubble';

基本使用示例

1. 室内外选择（如UI图所示）

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. 时间选择器

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. 多选模式

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. 带图标和描述

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. 不同布局方式

// 水平布局 - 适合选项较少
<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. 不同尺寸

// 小尺寸 - 适合紧凑界面
<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 属性禁用整个组件或单个选项