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

Bubble 通用气泡组件

一个高度可配置的气泡选择器组件，支持任何内容的选择，包括但不限于时间、地点、标签、分类等。

特性

• 🎯 支持单选和多选模式
• 📱 三种布局方式：水平、垂直、网格
• 🎨 三种尺寸：小、中、大
• ♿ 支持禁用状态和图标描述
• 🔄 支持受控和非受控模式
• 📱 响应式设计，自动适应不同屏幕
• 🎨 可自定义样式和类名

基本用法

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

import React, { useState } from 'react';
import Bubble, { BubbleOption } from './index';

const LocationSelector: 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 (
    <Bubble
      options={locationOptions}
      value={selectedLocation}
      onChange={(value) => setSelectedLocation(value as string)}
      layout="horizontal"
      size="medium"
    />
  );
};

时间选择器示例

const TimeSelector: React.FC = () => {
  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' }
  ];

  return (
    <Bubble
      options={timeOptions}
      value={selectedTime}
      onChange={(value) => setSelectedTime(value as string)}
      layout="grid"
      columns={3}
      size="medium"
    />
  );
};

多选模式

const MultiSelectExample: React.FC = () => {
  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' }
  ];

  return (
    <Bubble
      options={options}
      value={selectedValues}
      onChange={(value) => setSelectedValues(value as string[])}
      multiple={true}
      layout="grid"
      columns={2}
      size="medium"
    />
  );
};

带图标和描述

const IconExample: React.FC = () => {
  const [selectedValue, setSelectedValue] = useState<string>('');

  const options: BubbleOption[] = [
    { 
      id: 1, 
      label: '网球', 
      value: 'tennis',
      icon: '🎾',
      description: '室内外均可'
    },
    { 
      id: 2, 
      label: '篮球', 
      value: 'basketball',
      icon: '🏀',
      description: '室内场地'
    }
  ];

  return (
    <Bubble
      options={options}
      value={selectedValue}
      onChange={(value) => setSelectedValue(value as string)}
      layout="vertical"
      size="large"
    />
  );
};

API

BubbleProps

属性	类型	默认值	说明
options	BubbleOption[]	-	选项数组
value	string | number | (string | number)[]	-	当前选中的值
onChange	(value, option) => void	-	选择变化时的回调
multiple	boolean	false	是否支持多选
layout	'horizontal' | 'vertical' | 'grid'	'horizontal'	布局方式
columns	number	3	网格布局的列数
size	'small' | 'medium' | 'large'	'medium'	按钮尺寸
className	string	''	自定义类名
style	React.CSSProperties	{}	自定义样式
disabled	boolean	false	是否禁用整个组件

BubbleOption

属性	类型	默认值	说明
id	string | number	-	选项的唯一标识
label	string	-	显示的文本
value	string | number	-	选项的值
disabled	boolean	false	是否禁用
icon	React.ReactNode	-	可选的图标
description	string	-	可选的描述文本

布局说明

水平布局 (horizontal)

• 适合选项较少的情况
• 自动换行，响应式设计
• 适合顶部导航、标签选择等

垂直布局 (vertical)

• 适合选项较多的情况
• 每个选项占满一行
• 适合侧边栏、设置页面等

网格布局 (grid)

• 适合选项较多且需要整齐排列的情况
• 可自定义列数
• 适合分类选择、时间选择等

尺寸说明

小尺寸 (small)

• 适合紧凑的界面
• 适合移动端或空间受限的场景

中尺寸 (medium)

• 默认尺寸，适合大多数场景
• 平衡了可用性和美观性

大尺寸 (large)

• 适合需要突出显示的场景
• 适合触摸设备或重要操作

样式定制

组件使用 SCSS 编写，可以通过以下方式自定义样式：

1. 覆盖 CSS 变量
2. 使用 className 和 style 属性
3. 修改 SCSS 源文件

注意事项

• 在网格布局中，columns 属性控制列数，行数会根据选项数量自动计算
• 多选模式下，value 应该是数组类型
• 单选模式下，value 可以是字符串或数字类型
• 组件会自动处理选中状态的样式变化
• 支持图标和描述，让选项更加丰富
• 响应式设计，自动适应不同屏幕尺寸