更新记录

1.0.0（2025-08-09）

初稿

平台兼容性

云端兼容性

uni-app(4.72)

uni-app x(4.74)

跨平台通用 Picker & PickerView 组件介绍文档

1. 组件背景

在多端跨平台开发中，原生 PickerView 组件常面临以下问题：

• 不同平台（iOS/Android/H5/小程序）表现不一致
• 空安全处理逻辑混乱，易出现索引越界错误
• 跨平台兼容性问题频发（如滚动异常、样式错乱）
• 自定义能力有限，难以满足复杂业务场景

为此，我们开发了一套完全自研的 跨平台通用 Picker & PickerView 组件，已在全平台完成兼容性测试，确保一致的交互体验和稳定的运行表现。

2. 核心优势

2.1 全平台一致性

• 统一的 UI 表现：在 iOS、Android、H5、各小程序平台展示效果完全一致
• 一致的交互逻辑：滚动、选择、确认等行为在所有平台保持统一
• 统一的事件回调：跨平台使用相同的事件机制和参数格式

2.2 增强的稳定性

• 完善的空安全处理：解决原生组件常见的 NullPointerException 和索引越界问题
• 防抖动处理：优化快速滚动时的性能，避免数据错乱
• 边界值自动修正：超出可选范围时自动适配合法值，提升容错性

2.3 强大的自定义能力

• 支持自定义选项样式（字体、颜色、高度等）
• 可配置可见项数量、滚动速度、对齐方式
• 支持多列联动（如日期选择中的年/月/日联动）
• 提供灵活的插槽机制，支持复杂选项内容（图文混排等）

2.4 轻量化设计

• 无冗余依赖，核心代码体积 < 50KB
• 按需加载，不占用额外启动内存
• 适配不同屏幕尺寸，无需手动调整布局

3. 组件功能说明

3.1 核心组件

3.2 基础功能

• 多列选择：支持无限列数配置，列间可联动（如省市区三级联动）
• 自定义选项：通过插槽自定义选项内容，支持文本、图片、图标等任意布局
• 滚动对齐：滚动停止后自动对齐到选项中心，避免半选状态
• 数据动态更新：支持动态修改选项数据，自动刷新视图且不丢失当前选择状态
• 禁用状态：支持整体或单列禁用，禁用状态下保持统一的视觉反馈

3.3 高级特性

• 列联动机制：支持通过事件监听实现列间数据联动（如选择年份后自动更新月份范围）
• 滚动监听：提供实时滚动位置回调，可用于实现自定义动画或日志埋点
• 索引记忆：组件卸载后重新加载时，自动恢复上次选择的索引位置
• 无障碍支持：适配屏幕阅读器，支持键盘导航（H5 平台）
• 性能优化：长列表虚拟滚动，支持万级数据量无卡顿

4. 跨平台兼容性

已通过测试的平台：

5. 快速上手

5.1 安装方式

# npm 安装
npm install @aries-ui/picker --save

# yarn 安装
yarn add @aries-ui/picker

5.2 基础用法示例

<template>
  <AriesPickerView 
    :value="selectedIndexes" 
    @change="handlePickerChange"
  >
    <!-- 年列 -->
    <AriesPickerViewColumn>
      <view class="picker-item" v-for="year in years" :key="year">
        {{ year }}年
      </view>
    </AriesPickerViewColumn>

    <!-- 月列 -->
    <AriesPickerViewColumn>
      <view class="picker-item" v-for="month in months" :key="month">
        {{ month }}月
      </view>
    </AriesPickerViewColumn>
  </AriesPickerView>
</template>

<script setup>
import { ref } from 'vue'
import { AriesPickerView, AriesPickerViewColumn } from '@aries-ui/picker'

// 数据
const years = Array.from({ length: 20 }, (_, i) => 2000 + i)
const months = Array.from({ length: 12 }, (_, i) => i + 1)
const selectedIndexes = ref([5, 3]) // 默认选中第5个年份、第3个月份

// 选择变化事件
const handlePickerChange = (e) => {
  console.log('选择结果：', e.detail.value)
}
</script>

6. 注意事项

1. 组件已内置防抖动处理，无需额外处理快速滚动导致的性能问题
2. 如需动态修改选项数据，建议通过 key 强制刷新组件
3. 在 H5 平台如需兼容低版本浏览器，建议引入 @babel/polyfill
4. 复杂联动场景下，建议使用 watch 监听数据变化而非直接操作 DOM

7. 版本历史

8. 问题反馈

如在使用过程中遇到问题，可通过以下方式反馈：

• GitHub Issues：https://github.com/your-org/aries-picker/issues
• 内部协作群：#aries-ui 技术支持群
• 邮件：support@aries-ui.com

通过这套组件，您可以彻底告别原生 PickerView 的跨平台兼容性痛点，专注于业务逻辑实现。我们将持续迭代优化，欢迎提出宝贵建议！