npm package: @see_you/react-native-picker-view
Description: picker view native component for react native
Author: see_you
Latest version: 0.1.1

# React Native Picker

一个支持单列、多列和级联选择的 React Native Picker 组件，同时支持 iOS 和 Android 平台。

[![npm version](https://img.shields.io/npm/v/@see_you/react-native-picker-view.svg)](https://www.npmjs.com/package/@see_you/react-native-picker-view)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 特性

- 🎯 **三种模式**：单列、多列、级联选择
- 📱 **跨平台**：iOS 和 Android 原生实现
- 🎨 **可定制**：支持自定义颜色、文字等样式
- 🔄 **动态更新**：支持动态改变数据和选中值
- 🏗️ **Fabric 架构**：基于 React Native 新架构
- 📦 **零依赖**：不依赖第三方库

## 📦 安装

```bash
npm install @see_you/react-native-picker-view
# 或  
yarn add @see_you/react-native-picker-view
```

对于 React Native < 0.60，需要手动链接：
```bash
react-native link react-native-picker
```

## 🚀 快速开始

### 单列选择

```tsx
import { PickerView } from 'react-native-picker';

function App() {
  const [visible, setVisible] = useState(false);
  const [value, setValue] = useState('苹果');

  return (
    <>
      <Button title="选择水果" onPress={() => setVisible(true)} />
      
      <PickerView
        visible={visible}
        data={['苹果', '香蕉', '橙子', '葡萄']}
        value={value}
        onConfirm={(e) => {
          setValue(e.value[0]);
          setVisible(false);
        }}
        onCancel={() => setVisible(false)}
      />
    </>
  );
}
```

### 多列选择

```tsx
<PickerView
  visible={visible}
  data={[
    ['上午', '下午', '晚上'],
    ['08:00', '09:00', '10:00', '11:00']
  ]}
  value={['上午', '08:00']}
  onConfirm={(e) => {
    console.log(e.value); // ['上午', '08:00']
    setVisible(false);
  }}
/>
```

### 级联选择

```tsx
<PickerView
  visible={visible}
  cascade
  data={[
    {
      value: '北京',
      children: [
        { value: '朝阳区' },
        { value: '海淀区' },
        { value: '东城区' }
      ]
    },
    {
      value: '上海',
      children: [
        { value: '浦东新区' },
        { value: '黄浦区' }
      ]
    }
  ]}
  value={['北京', '朝阳区']}
  onConfirm={(e) => {
    console.log(e.value); // ['北京', '朝阳区']
    console.log(e.index); // [0, 0]
  }}
/>
```

## 📖 API

### Props

| 属性 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| `data` | `string[]` \| `string[][]` \| `CascadeItem[]` | - | ✅ | 数据源 |
| `value` | `string` \| `string[]` | - | - | 选中的值 |
| `cascade` | `boolean` | `false` | - | 是否启用级联模式 |
| `visible` | `boolean` | `false` | ✅ | 是否显示选择器 |
| `title` | `string` | `''` | - | 标题文字 |
| `backgroundColor` | `string` | `'#fff'` | - | 背景颜色 |
| `textColor` | `string` | `'#000'` | - | 文字颜色 |
| `cancelButtonText` | `string` | `'取消'` | - | 取消按钮文字 |
| `confirmButtonText` | `string` | `'确定'` | - | 确定按钮文字 |
| `cancelButtonTextColor` | `string` | - | - | 取消按钮文字颜色 |
| `confirmButtonTextColor` | `string` | - | - | 确定按钮文字颜色 |
| `onConfirm` | `(event: ConfirmEvent) => void` | - | - | 确定回调 |
| `onCancel` | `() => void` | - | - | 取消回调 |

### 事件类型

```typescript
interface ConfirmEvent {
  value: string[];   // 选中的值数组
  index: number[];   // 选中的索引数组
}
```

### 数据类型

```typescript
interface CascadeItem {
  value: string;              // 显示的值
  label?: string;             // 可选的标签
  children?: CascadeItem[];   // 子级数据
}
```

## 🎨 样式定制

### 基础样式

```tsx
<PickerView
  backgroundColor="#f5f5f5"
  textColor="#333333"
  title="请选择"
  cancelButtonText="取消"
  confirmButtonText="完成"
  cancelButtonTextColor="#999999"
  confirmButtonTextColor="#007AFF"
/>
```

### 平台差异

#### iOS
- 从底部弹出的模态框
- 带圆角的容器
- 半透明背景遮罩
- 流畅的滑入/滑出动画

#### Android
- 居中的 AlertDialog
- 系统默认对话框样式
- 标准的对话框动画

## 📱 示例

完整的示例代码请查看 [example](./example) 目录。

运行示例：

```bash
# 安装依赖
cd example
yarn install

# iOS
cd ios && pod install && cd ..
yarn ios

# Android
yarn android
```

## 🔧 高级用法

### 动态更新数据

```tsx
const [data, setData] = useState(['选项1', '选项2']);

// 动态添加选项
const addOption = () => {
  setData([...data, `选项${data.length + 1}`]);
};
```

### 多级级联（最多10级）

```tsx
const cityData = [
  {
    value: '中国',
    children: [
      {
        value: '北京',
        children: [
          { value: '朝阳区' },
          { value: '海淀区' }
        ]
      }
    ]
  }
];
```

### 获取选中的索引

```tsx
onConfirm={(e) => {
  console.log('选中的值:', e.value);
  console.log('选中的索引:', e.index);
}}
```

## ⚠️ 注意事项

1. **单列模式**：`data` 为字符串数组，`value` 为字符串，但 `onConfirm` 返回的 `value` 仍是数组
2. **多列模式**：所有列的长度可以不同
3. **级联模式**：必须设置 `cascade={true}` 并使用树形数据结构
4. **value 格式**：单列可以传字符串，多列和级联必须传字符串数组
5. **性能**：级联层数过多或单列数据量过大可能影响性能

## 🐛 问题反馈

如果遇到问题，请在 [GitHub Issues](https://github.com/your-repo/react-native-picker/issues) 中提交。

## 📄 License

MIT © [Your Name]

## 🤝 贡献

欢迎提交 Pull Request！

## 📚 相关文档

- [iOS 实现说明](./IOS_IMPLEMENTATION.md)
- [Android 实现说明](./ANDROID_IMPLEMENTATION.md)
- [API 文档](./API.md)
- [迁移指南](./MIGRATION.md)

## 🎉 致谢

感谢所有贡献者的支持！