Android-PickerView 使用教程

项目介绍

Android-PickerView 是一款仿 iOS 风格的 PickerView 控件库，专为 Android 开发者设计，提供了时间选择器和选项选择器功能。该库支持联动效果、自定义布局、循环模式等特性，能够满足各种选择器需求。

主要特性

• 时间选择器：支持年月日时分、年月日、年月、时分等多种时间格式
• 选项选择器：支持一、二、三级选项选择，可设置是否联动
• 自定义布局：支持完全自定义选择器界面样式
• 循环模式：支持无限循环滚动效果
• 日期范围：时间选择器支持设置起始和终止日期
• 国际化支持：提供中英文标签显示
• 实时回调：选择结果实时回调处理

快速开始

方式一：添加依赖

在项目的 build.gradle 文件中添加依赖：

implementation 'com.contrarywind:Android-PickerView:4.1.9'

方式二：源码集成

由于项目已停止更新，建议直接下载源码并作为 module 引入到自己的项目中：

git clone https://gitcode.com/gh_mirrors/an/Android-PickerView.git

基本使用示例

时间选择器使用

// 时间选择器
TimePickerView pvTime = new TimePickerBuilder(MainActivity.this, new OnTimeSelectListener() {
    @Override
    public void onTimeSelect(Date date, View v) {
        // 处理选择的时间
        Toast.makeText(MainActivity.this, getTime(date), Toast.LENGTH_SHORT).show();
    }
}).build();

// 显示时间选择器
pvTime.show();

private String getTime(Date date) {
    SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd HH:mm");
    return format.format(date);
}

选项选择器使用

// 选项选择器
OptionsPickerView pvOptions = new OptionsPickerBuilder(MainActivity.this, new OnOptionsSelectListener() {
    @Override
    public void onOptionsSelect(int options1, int option2, int options3, View v) {
        // 返回三个级别的选中位置
        String result = options1Items.get(options1).getPickerViewText()
                + options2Items.get(options1).get(option2)
                + options3Items.get(options1).get(option2).get(options3).getPickerViewText();
        tvOptions.setText(result);
    }
}).build();

pvOptions.setPicker(options1Items, options2Items, options3Items);
pvOptions.show();

自定义配置

时间选择器自定义

Calendar selectedDate = Calendar.getInstance();
Calendar startDate = Calendar.getInstance();
Calendar endDate = Calendar.getInstance();

// 注意：Calendar 月份从0开始（0-11代表1-12月）
startDate.set(2013, 0, 1);  // 2013年1月1日
endDate.set(2020, 11, 31); // 2020年12月31日

pvTime = new TimePickerBuilder(this, new OnTimeSelectListener() {
    @Override
    public void onTimeSelect(Date date, View v) {
        tvTime.setText(getTime(date));
    }
})
.setType(new boolean[]{true, true, true, true, true, true}) // 显示年月日时分秒
.setCancelText("取消")
.setSubmitText("确定")
.setTitleText("选择时间")
.setTitleSize(20)
.setContentSize(18)
.setTitleColor(Color.BLACK)
.setSubmitColor(Color.BLUE)
.setCancelColor(Color.BLUE)
.setDate(selectedDate)
.setRangDate(startDate, endDate)
.setLabel("年", "月", "日", "时", "分", "秒")
.isCenterLabel(false)
.isDialog(true)
.build();

选项选择器自定义

pvOptions = new OptionsPickerBuilder(this, new OnOptionsSelectListener() {
    @Override
    public void onOptionsSelect(int options1, int option2, int options3, View v) {
        String result = options1Items.get(options1).getPickerViewText()
                + options2Items.get(options1).get(option2)
                + options3Items.get(options1).get(option2).get(options3).getPickerViewText();
        tvOptions.setText(result);
    }
})
.setSubmitText("确定")
.setCancelText("取消")
.setTitleText("城市选择")
.setTitleSize(20)
.setSubCalSize(18)
.setTitleColor(Color.BLACK)
.setSubmitColor(Color.BLUE)
.setCancelColor(Color.BLUE)
.setContentTextSize(18)
.setLinkage(true) // 设置联动
.setLabels("省", "市", "区")
.isCenterLabel(false)
.setCyclic(false, false, false)
.setSelectOptions(0, 0, 0)
.setOutSideCancelable(false)
.isDialog(true)
.build();

自定义布局

Android-PickerView 支持完全自定义布局，只需在布局文件中包含特定 ID 的控件：

pvCustomOptions = new OptionsPickerBuilder(this, new OnOptionsSelectListener() {
    @Override
    public void onOptionsSelect(int options1, int option2, int options3, View v) {
        String result = cardItem.get(options1).getPickerViewText();
        btn_CustomOptions.setText(result);
    }
})
.setLayoutRes(R.layout.pickerview_custom_options, new CustomListener() {
    @Override
    public void customLayout(View v) {
        // 自定义布局中的控件初始化
        TextView tvSubmit = v.findViewById(R.id.tv_finish);
        TextView tvAdd = v.findViewById(R.id.tv_add);
        ImageView ivCancel = v.findViewById(R.id.iv_cancel);
        
        tvSubmit.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                pvCustomOptions.returnData(tvSubmit);
            }
        });
        
        ivCancel.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                pvCustomOptions.dismiss();
            }
        });
    }
})
.build();

数据准备

JSON 数据处理

项目中提供了省市区三级联动数据，数据文件位于 app/src/main/assets/province.json：

// 解析 JSON 数据
String provinceData = GetJsonDataUtil.getJson(this, "province.json");
List<JsonBean> options1Items = JsonParser.parseArray(provinceData, JsonBean.class);

// 设置二级、三级数据
List<List<String>> options2Items = new ArrayList<>();
List<List<List<String>>> options3Items = new ArrayList<>();

for (JsonBean province : options1Items) {
    List<String> cities = new ArrayList<>();
    List<List<String>> areas = new ArrayList<>();
    
    for (JsonBean.CityBean city : province.getCityList()) {
        cities.add(city.getName());
        areas.add(city.getArea());
    }
    
    options2Items.add(cities);
    options3Items.add(areas);
}

效果展示

注意事项

1. 月份设置：Calendar 组件内部的月份是从 0 开始的，即 0-11 代表 1-12 月份
2. 自定义布局：布局中必须包含 id 为 optionspicker 或 timepicker 的控件
3. 数据联动：多级联动数据需要正确设置数据结构
4. 内存管理：选择器使用完毕后及时调用 dismiss() 方法释放资源

项目结构

Android-PickerView/
├── app/                 # 示例应用
│   └── src/main/
│       ├── assets/     # 数据文件
│       ├── java/       # Java 代码
│       └── res/        # 资源文件
├── pickerview/         # 选择器核心库
└── wheelview/          # 滚轮视图基础库

总结

Android-PickerView 是一个功能强大、易于使用的选择器库，提供了丰富的时间选择器和选项选择器功能。通过简单的配置即可实现各种复杂的选择需求，支持高度自定义，能够很好地融入各种应用场景中。