# db-rn-ui 组件库

React Native 实用组件库，包含按钮、输入框、弹窗等常用 UI 组件，支持按需引入。

## 安装

```bash
npm install db-rn-ui --save
# 或
yarn add db-rn-ui
```

### 依赖要求

```json
{
  "react": ">=18.0.0",
  "react-native": ">=0.76.0",
  "react-native-linear-gradient": "^2.8.3",
  "react-native-safe-area-context": "^5.6.2",
  "react-native-vector-icons": "^10.3.0"
}
```

## 组件列表

### 1. Button 按钮

用于触发交互操作的按钮组件，支持多种样式、尺寸和图标配置。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbButton } from 'db-rn-ui';

const App = () => (
  <View style={{ padding: 20 }}>
    <DbButton title="确认" onPress={() => console.log('点击确认')} />
    <DbButton
      title="取消"
      variant="secondary"
      onPress={() => console.log('点击取消')}
      style={{ marginTop: 10 }}
    />
    <DbButton
      title="带图标"
      leftIcon={{ name: 'checkmark', family: 'Ionicons' }}
      onPress={() => console.log('点击')}
      style={{ marginTop: 10 }}
    />
  </View>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| title | string | - | 按钮文字 |
| onPress | () => void | - | 点击回调函数 |
| variant | 'primary' \| 'secondary' \| 'outline' \| 'ghost' | 'primary' | 按钮样式变体 |
| size | 'small' \| 'medium' \| 'large' | 'medium' | 按钮尺寸 |
| disabled | boolean | false | 是否禁用 |
| loading | boolean | false | 是否显示加载状态 |
| icon | ButtonIconConfig \| ReactNode | - | 图标配置 |
| leftIcon | ButtonIconConfig \| ReactNode | - | 左侧图标 |
| rightIcon | ButtonIconConfig \| ReactNode | - | 右侧图标 |
| debounce | number | - | 防抖延迟时间（毫秒） |
| throttle | number | - | 节流延迟时间（毫秒） |

---

### 2. Input 输入框

功能丰富的输入框组件，支持多种输入类型、验证规则和 XSS 防护。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbInput } from 'db-rn-ui';

const App = () => {
  const [value, setValue] = useState('');

  return (
    <View style={{ padding: 20 }}>
      <DbInput
        label="用户名"
        placeholder="请输入用户名"
        value={value}
        onChangeText={setValue}
        leftIcon={{ name: 'person-outline', family: 'Ionicons' }}
        showClear
      />
      <DbInput
        label="密码"
        type="password"
        placeholder="请输入密码"
        showPasswordToggle
        style={{ marginTop: 16 }}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| type | 'text' \| 'password' \| 'number' \| 'phone' \| 'email' \| 'url' \| 'textarea' | 'text' | 输入框类型 |
| value | string | - | 输入框的值 |
| placeholder | string | - | 占位文字 |
| label | string | - | 标签文字 |
| labelPosition | 'top' \| 'left' \| 'floating' | 'top' | 标签位置 |
| leftIcon | InputIconConfig \| ReactNode | - | 左侧图标 |
| rightIcon | InputIconConfig \| ReactNode | - | 右侧图标 |
| showClear | boolean | false | 是否显示清除按钮 |
| showPasswordToggle | boolean | false | 是否显示密码可见切换 |
| status | 'default' \| 'success' \| 'warning' \| 'error' | 'default' | 输入框状态 |
| error | string | - | 错误提示 |
| hint | string | - | 提示文字 |
| rules | InputRule[] | - | 校验规则 |

---

### 3. Icon 图标

基于 react-native-vector-icons 的图标组件，支持多种图标库。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbIcon } from 'db-rn-ui';

const App = () => (
  <View style={{ flexDirection: 'row', padding: 20 }}>
    <DbIcon name="home" size={24} color="#333" />
    <DbIcon name="star" family="FontAwesome" size={24} color="#FFD700" />
    <DbIcon name="add-circle" family="MaterialIcons" size={24} color="#007AFF" />
  </View>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| name | string | **必填** | 图标名称 |
| family | 'Ionicons' \| 'FontAwesome' \| 'MaterialIcons' \| 'Entypo' \| 'AntDesign' | 'Ionicons' | 图标库 |
| size | number | 24 | 图标大小 |
| color | string | '#000' | 图标颜色 |
| onPress | () => void | - | 点击事件 |

---

### 4. NavBar 导航栏

页面顶部导航栏组件，支持自定义左右按钮和渐变背景。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbNavBar, DbIcon } from 'db-rn-ui';

const App = () => (
  <View>
    <DbNavBar
      title="页面标题"
      leftIcon={<DbIcon name="arrow-back" size={24} color="#333" />}
      rightIcon={<DbIcon name="share-outline" size={24} color="#333" />}
      onLeftPress={() => console.log('返回')}
      onRightPress={() => console.log('分享')}
    />
  </View>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| title | string | - | 导航栏标题 |
| leftIcon | ReactNode | - | 左侧图标 |
| rightIcon | ReactNode | - | 右侧图标 |
| onLeftPress | () => void | - | 左侧点击事件 |
| onRightPress | () => void | - | 右侧点击事件 |
| backgroundColor | string | '#fff' | 背景颜色 |
| useLinearGradient | boolean | false | 是否使用渐变背景 |
| gradientColors | string[] | ['#4c669f', '#3b5998'] | 渐变颜色数组 |

---

### 5. Toast 轻提示

轻量级消息提示组件，支持命令式调用。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbButton, DbToast, DbToastProvider } from 'db-rn-ui';

const App = () => (
  <DbToastProvider>
    <View style={{ padding: 20 }}>
      <DbButton
        title="显示成功提示"
        onPress={() => DbToast.success('操作成功！')}
      />
      <DbButton
        title="显示错误提示"
        variant="danger"
        onPress={() => DbToast.error('操作失败！')}
        style={{ marginTop: 10 }}
      />
      <DbButton
        title="显示加载中"
        onPress={() => {
          const loading = DbToast.loading('加载中...');
          setTimeout(() => loading.close(), 2000);
        }}
        style={{ marginTop: 10 }}
      />
    </View>
  </DbToastProvider>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| message | string | **必填** | 消息内容 |
| type | 'success' \| 'error' \| 'warning' \| 'info' \| 'loading' | 'info' | Toast 类型 |
| duration | number | 2000 | 显示时长（毫秒） |
| position | 'top' \| 'center' \| 'bottom' | 'center' | 显示位置 |
| mask | boolean | false | 是否显示遮罩层 |

#### 静态方法

- `DbToast.show(message, duration?)` - 显示普通提示
- `DbToast.success(message, duration?)` - 显示成功提示
- `DbToast.error(message, duration?)` - 显示错误提示
- `DbToast.warning(message, duration?)` - 显示警告提示
- `DbToast.info(message, duration?)` - 显示信息提示
- `DbToast.loading(message?)` - 显示加载提示
- `DbToast.hide()` - 隐藏所有 Toast

---

### 6. Popup 弹出层

从屏幕四周滑出的弹出层组件，支持多种弹出位置和动画效果。

```jsx
import React, { useState } from 'react';
import { View, Text } from 'react-native';
import { DbButton, DbPopup } from 'db-rn-ui';

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <View style={{ padding: 20 }}>
      <DbButton title="显示底部弹出层" onPress={() => setVisible(true)} />
      <DbPopup
        visible={visible}
        onClose={() => setVisible(false)}
        position="bottom"
        height={300}
        round
      >
        <View style={{ padding: 20 }}>
          <Text>弹出层内容</Text>
        </View>
      </DbPopup>
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| visible | boolean | **必填** | 是否显示 |
| onClose | () => void | - | 关闭回调 |
| position | 'center' \| 'top' \| 'bottom' \| 'left' \| 'right' | 'center' | 弹出位置 |
| overlay | boolean | true | 是否显示遮罩层 |
| closeOnClickOverlay | boolean | true | 点击遮罩层是否关闭 |
| closable | boolean | false | 是否显示关闭按钮 |
| round | boolean | true | 是否显示圆角 |
| width | number \| string | - | 宽度（left/right 时有效） |
| height | number \| string | - | 高度（top/bottom 时有效） |
| title | string | - | 标题 |

---

### 7. Drawer 抽屉

从屏幕左侧或右侧滑出的抽屉组件。

```jsx
import React, { useState } from 'react';
import { View, Text } from 'react-native';
import { DbButton, DbDrawer } from 'db-rn-ui';

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <View style={{ padding: 20 }}>
      <DbButton title="打开抽屉" onPress={() => setVisible(true)} />
      <DbDrawer
        visible={visible}
        onClose={() => setVisible(false)}
        placement="left"
        width={280}
      >
        <View style={{ padding: 20 }}>
          <Text>抽屉内容</Text>
        </View>
      </DbDrawer>
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| visible | boolean | **必填** | 是否显示 |
| onClose | () => void | **必填** | 关闭回调 |
| placement | 'left' \| 'right' | 'left' | 抽屉位置 |
| width | number | 280 | 抽屉宽度 |
| animationDuration | number | 300 | 动画时长（毫秒） |

---

### 8. Loading 加载

加载状态提示组件，支持多种动画类型和命令式调用。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbButton, DbLoading } from 'db-rn-ui';

const App = () => (
  <View style={{ padding: 20 }}>
    {/* 行内加载 */}
    <DbLoading type="spinner" text="加载中..." />
    
    {/* 全屏加载 */}
    <DbButton
      title="显示全屏加载"
      onPress={() => {
        DbLoading.show('加载中...');
        setTimeout(() => DbLoading.hide(), 2000);
      }}
    />
  </View>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| type | 'spinner' \| 'dots' \| 'pulse' \| 'wave' \| 'bounce' \| 'circular' | 'spinner' | 动画类型 |
| size | 'small' \| 'medium' \| 'large' \| number | 'medium' | 尺寸 |
| color | string | '#007AFF' | 主题色 |
| text | string | - | 提示文字 |
| textPosition | 'bottom' \| 'right' | 'bottom' | 文字位置 |
| fullscreen | boolean | false | 是否全屏显示 |
| maskColor | string | 'rgba(0,0,0,0.5)' | 遮罩层颜色 |

#### 静态方法

- `DbLoading.show(text?)` - 显示全屏加载
- `DbLoading.hide()` - 隐藏加载

---

### 9. Checkbox 复选框

复选框组件，支持单个使用和组模式。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbCheckbox } from 'db-rn-ui';

const App = () => {
  const [checked, setChecked] = useState(false);
  const [selectedValues, setSelectedValues] = useState(['apple']);

  const options = [
    { value: 'apple', label: '苹果' },
    { value: 'banana', label: '香蕉' },
    { value: 'orange', label: '橙子' },
  ];

  return (
    <View style={{ padding: 20 }}>
      <DbCheckbox
        label="单个复选框"
        checked={checked}
        onChange={setChecked}
      />
      
      <DbCheckbox.Group
        options={options}
        value={selectedValues}
        onChange={setSelectedValues}
        style={{ marginTop: 20 }}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| checked | boolean | - | 是否选中（受控） |
| defaultChecked | boolean | false | 默认是否选中（非受控） |
| onChange | (checked: boolean) => void | - | 状态改变回调 |
| label | string | - | 标签文字 |
| disabled | boolean | false | 是否禁用 |
| layout | 'left' \| 'right' | 'left' | 布局方向 |
| size | 'small' \| 'medium' \| 'large' | 'medium' | 尺寸 |
| activeColor | string | '#007AFF' | 选中颜色 |
| indeterminate | boolean | false | 是否半选状态 |

#### DbCheckbox.Group API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| value | any[] | - | 选中值数组 |
| options | CheckboxOption[] | **必填** | 选项列表 |
| onChange | (value: any[]) => void | - | 值改变回调 |

---

### 10. Radio 单选框

单选框组件，支持单个使用和组模式。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbRadio } from 'db-rn-ui';

const App = () => {
  const [value, setValue] = useState('apple');

  const options = [
    { value: 'apple', label: '苹果' },
    { value: 'banana', label: '香蕉' },
    { value: 'orange', label: '橙子' },
  ];

  return (
    <View style={{ padding: 20 }}>
      <DbRadio
        options={options}
        value={value}
        onChange={setValue}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| value | any | - | 当前选中值（受控） |
| defaultValue | any | - | 默认值（非受控） |
| onChange | (value: any) => void | - | 值改变回调 |
| options | RadioOption[] | **必填** | 选项列表 |
| disabled | boolean | false | 是否禁用全部 |
| layout | 'left' \| 'right' | 'left' | 布局方向 |
| size | 'small' \| 'medium' \| 'large' | 'medium' | 尺寸 |
| activeColor | string | '#007AFF' | 选中颜色 |

---

### 11. Tag 标签

用于标记和分类的标签组件。

```jsx
import React from 'react';
import { View } from 'react-native';
import { DbTag } from 'db-rn-ui';

const App = () => (
  <View style={{ flexDirection: 'row', padding: 20, gap: 8 }}>
    <DbTag text="默认标签" />
    <DbTag text="热销" preset="hot" />
    <DbTag text="新品" preset="new" variant="outline" />
    <DbTag text="可关闭" closable onClose={() => console.log('关闭')} />
  </View>
);

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| text | string | - | 标签文字 |
| preset | 'default' \| 'hot' \| 'new' \| 'sale' \| 'promo' | 'default' | 预设类型 |
| variant | 'solid' \| 'outline' \| 'light' | 'solid' | 样式变体 |
| size | 'small' \| 'medium' \| 'large' | 'small' | 尺寸 |
| color | string | - | 自定义颜色 |
| closable | boolean | false | 是否可关闭 |
| onClose | () => void | - | 关闭回调 |
| onPress | () => void | - | 点击回调 |

---

### 12. Tab 标签页

可切换内容的标签页组件。

```jsx
import React from 'react';
import { View, Text } from 'react-native';
import { DbTab } from 'db-rn-ui';

const App = () => {
  const tabs = [
    { title: '全部' },
    { title: '待付款' },
    { title: '待发货' },
    { title: '待收货' },
  ];

  const renderContent = (index, tab) => (
    <View style={{ padding: 20 }}>
      <Text>{tab.title} 内容区域</Text>
    </View>
  );

  return (
    <DbTab
      tabs={tabs}
      renderContent={renderContent}
      activeColor="#007AFF"
      inactiveColor="#666"
    />
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| tabs | TabItem[] | **必填** | 标签项数组 |
| renderContent | (index: number, tab: TabItem) => ReactNode | **必填** | 内容渲染函数 |
| activeColor | string | '#007AFF' | 选中颜色 |
| inactiveColor | string | '#666' | 未选中颜色 |
| initialPage | number | 0 | 初始选中页 |
| onTabChange | (index: number, tab: TabItem) => void | - | 切换回调 |

---

### 13. AmountDisplay 金额显示

专门用于显示金额的组件，支持编辑和步进器模式。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbAmountDisplay } from 'db-rn-ui';

const App = () => {
  const [amount, setAmount] = useState(99.99);

  return (
    <View style={{ padding: 20 }}>
      {/* 纯展示 */}
      <DbAmountDisplay amount={199.99} currency="¥" />
      
      {/* 可编辑 */}
      <DbAmountDisplay
        amount={amount}
        onChange={setAmount}
        editable
        min={0}
        max={9999}
        style={{ marginTop: 20 }}
      />
      
      {/* 带步进器 */}
      <DbAmountDisplay
        amount={amount}
        onChange={setAmount}
        showStepper
        step={1}
        style={{ marginTop: 20 }}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| amount | number | **必填** | 金额值 |
| currency | string | '￥' | 货币符号 |
| mainFontSize | number | 24 | 主字体大小 |
| mainColor | string | '#333' | 主颜色 |
| editable | boolean | false | 是否可编辑 |
| showStepper | boolean | false | 是否显示步进器 |
| min | number | 0 | 最小值 |
| max | number | 999999.99 | 最大值 |
| step | number | 1 | 步进值 |
| onChange | (value: number) => void | - | 值改变回调 |

---

### 14. AlertDialog 对话框

用于确认操作的对话框组件。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbButton, DbAlertDialog } from 'db-rn-ui';

const App = () => {
  const [visible, setVisible] = useState(false);

  return (
    <View style={{ padding: 20 }}>
      <DbButton title="显示对话框" onPress={() => setVisible(true)} />
      <DbAlertDialog
        visible={visible}
        title="确认删除"
        message="确定要删除该商品吗？删除后不可恢复。"
        confirmText="确定"
        cancelText="取消"
        onConfirm={() => {
          console.log('确认删除');
          setVisible(false);
        }}
        onCancel={() => setVisible(false)}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| visible | boolean | **必填** | 是否显示 |
| title | string | '提示' | 标题 |
| message | string | - | 消息内容 |
| confirmText | string | '确定' | 确认按钮文字 |
| cancelText | string | - | 取消按钮文字 |
| onConfirm | () => void | - | 确认回调 |
| onCancel | () => void | - | 取消回调 |

---

### 15. SearchBar 搜索栏

电商风格的搜索栏组件。

```jsx
import React, { useState } from 'react';
import { View } from 'react-native';
import { DbSearchBar } from 'db-rn-ui';

const App = () => {
  const [value, setValue] = useState('');

  return (
    <View style={{ padding: 20 }}>
      <DbSearchBar
        value={value}
        onChangeText={setValue}
        placeholder="搜索商品"
        onSubmit={(text) => console.log('搜索:', text)}
        showClear
        showCamera
        onCameraPress={() => console.log('拍照搜索')}
      />
    </View>
  );
};

export default App;
```

#### API

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| value | string | - | 搜索值 |
| placeholder | string | '搜索商品' | 占位文字 |
| onChangeText | (text: string) => void | - | 输入回调 |
| onSubmit | (text: string) => void | - | 提交回调 |
| onClear | () => void | - | 清除回调 |
| showClear | boolean | true | 是否显示清除按钮 |
| showCamera | boolean | false | 是否显示相机按钮 |
| showScan | boolean | false | 是否显示扫码按钮 |
| shape | 'round' \| 'square' | 'round' | 形状 |

---

## 其他组件

组件库还包含以下业务组件，使用方式请参考源码：

- **DbContainer** - 布局容器组件（Section, Card, Row, Col, Spacer）
- **DbFlatList** - 增强版 FlatList
- **DbInfiniteList** - 无限滚动列表
- **DbProductCard** - 商品卡片
- **DbItemCard** - 通用条目卡片
- **DbCustomHeader** - 自定义头部组件
- **DbImagePreview** / **DbImageGallery** - 图片预览组件
- **DbScrollTab** - 滚动标签组件
- **DbTabView** - 标签视图组件
- **DbProductTitle** / **DbProductTitleInline** - 商品标题组件
- **DbTitlePair** - 键值对展示组件
- **DbNumberInput** - 数字输入框
- **DbSwiper** - 轮播组件
- **WaterfallFlow** - 瀑布流组件
- **DbLoginPage** - 登录页面模板