【免费下载链接】NativeScript⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.项目地址https://gitcode.com/gh_mirrors/na/NativeScript点击查看免费下载本文是 NativeScript 核心包中ui/list-picker模块的实战指南围绕官方文档apps/automated/src/ui/list-picker/list-picker.md梳理 ListPicker 的引入方式、控件创建、items数据绑定以及selectedIndex编程式选择四大核心操作并结合nativescript/core源码跨平台公共实现、Android NumberPicker、iOS UIPickerView 封装与自动化测试用例深入解释其底层原理与边界行为。读完本文你将能够熟练地在 NativeScript 应用中创建滚轮式选择器、绑定数组或自定义数据源并通过属性或事件精确控制选中项。引入 ListPicker 模块在 NativeScript 中使用 ListPicker首先需要引入ui/list-picker模块。官方文档给出的引用方式与测试代码list-picker-tests.ts完全一致import * as listPickerModule from nativescript/core/ui/list-picker;该模块导出了ListPicker类继承自ListPickerBase以及selectedIndexProperty、itemsProperty等属性描述符因此既可以按命名空间方式访问如new listPickerModule.ListPicker()也可以直接使用具名导入import { ListPicker } from nativescript/core/ui/list-picker;从源码结构看nativescript/core在打包时通过平台别名.android/.ios将平台实现暴露为同一个模块入口Android 端基于android.widget.NumberPicker见 index.android.tsiOS 端基于UIPickerView见 index.ios.ts开发者无需关心平台差异。创建 ListPicker 控件使用new关键字即可创建 ListPicker 实例var listPicker new listPickerModule.ListPicker();创建完成后可以像其他 View 一样将其加入页面内容或布局容器中参考测试代码 list-picker-tests.tslistPicker.id ListPicker; page.content listPicker;在 XML 声明式语法中ListPicker 同样是注册过的原生视图源码中标有nsView ListPicker注解可以直接写为ListPicker idlistPicker items{{ items }} selectedIndex{{ selectedIndex }} /控件创建时有两个值得注意的默认状态均由自动化测试验证items默认为undefined测试testWhenlistPickerIsCreatedItemsAreUndefinedselectedIndex默认为-1测试testWhenlistPickerIsCreatedSelectedIndexIsUndefined。这一默认设计避免了在未设置数据时出现“悬空选中态”具体边界行为详见下文。绑定 items 数据源ListPicker 的items属性既可以绑定普通数组也可以绑定自定义数据源对象。先看最直接的数组绑定方式官方文档片段测试 list-picker-tests.ts 中原样复现listPicker.items [1, 2, 3];绑定一个包含 10 个元素的数组同样简单listPicker.items [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];items 的底层行为items在 list-picker-common.ts 中注册为普通Property其valueChanged回调会根据新值是否具有getItem方法自动判定是否为ItemsSourceexport const itemsProperty new PropertyListPickerBase, any[] | ItemsSource({ name: items, valueChanged: (target, oldValue, newValue) { const getItem newValue (ItemsSourcenewValue).getItem; target.isItemsSource typeof getItem function; }, });因此items支持两种形态普通数组any[]按索引取值listPicker.items[index]自定义数据源满足ItemsSource接口的对象只需实现length属性和getItem(index): any方法interface ItemsSource { length: number; getItem(index: number): any; }绑定数据源后列表展示的文本由_getItemAsString(index)决定list-picker-common.ts当textField属性非空时取item[textField]作为展示文本否则直接把item转为字符串。这为“对象数组 指定展示字段”的场景提供了支持listPicker.textField name; // 展示 item.name listPicker.items [ { id: 1, name: Angular }, { id: 2, name: React }, { id: 3, name: Vue }, ];对应的valueField属性则用于定义selectedValue的取值字段见下文“selectedValue 联动”。数据绑定的原生联动Android 端itemsProperty.setNative会同步到原生NumberPicker的maxValue与minValue。测试 list-picker-tests.ts 验证了 Android 原生控件的maxValue恒等于items.length - 1而createNativeView初始即设置setMinValue(0)、setMaxValue(0)、setWrapSelectorWheel(false)index.android.ts防止空数据时出现无限滚动。iOS 端itemsProperty.setNative调用reloadAllComponents()刷新UIPickerView随后对selectedIndex执行一次强制收敛index.ios.ts。此外items在视图加载前设置也能被正确解析测试testItemsIsResolvedCorrectlyIfSetBeforeViewIsLoaded属性机制保证了延迟到原生视图创建后再同步。编程式选择选中项通过设置selectedIndex属性即可在代码中选中指定行官方文档片段测试 list-picker-tests.ts 中原样复现listPicker.selectedIndex 9;例如先绑定 10 个元素再选中索引为 9 的最后一项listPicker.items [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; listPicker.selectedIndex 9; // 选中最后一项selectedIndex 的收敛规则selectedIndex在 list-picker-common.ts 中被定义为CoercibleProperty默认值为-1赋值时自动执行范围收敛coerce核心逻辑如下当items存在时最大值取items.length - 1值小于 0 时被收敛为0值大于items.length - 1时被收敛为最大值当items为空或未设置时selectedIndex一律收敛为-1。这意味着给selectedIndex赋值一个越界索引不会抛异常而是被安全钳制到有效区间内。valueConverter会将字符串形式的索引如 XML 属性传来的2自动parseInt为数字。不同 items 状态下的选中索引行为自动化测试list-picker-tests.ts系统地验证了 items 变化时选中索引的重置规则items 状态selectedIndex 结果依据测试绑定非空数组变为0自动选中首项testSelectedIndexBecomesZeroWhenItemsBoundToNonEmptyArray绑定空数组[]重置为-1testSelectedIndexBecomesUndefinedWhenItemsBoundToEmptyArray设为undefined重置为-1testSelectedIndexBecomesUndefinedWhenItemsBoundToUndefined设为null重置为-1testSelectedIndexBecomesUndefinedWhenItemsBoundToNull另外selectedIndex在视图加载前设置也能正确生效测试testSelectedIndexIsResolvedCorrectlyIfSetBeforeViewIsLoaded。平台原生同步iOSselectedIndexProperty.setNative通过selectRowInComponentAnimated(value, 0, false)定位到指定行index.ios.ts且仅当value 0时才执行避免对未就绪的控件误操作。Android用户滚动NumberPicker时ValueChangeListenerImpl.onValueChange会回调selectedIndexProperty.nativeValueChange(owner, newValue)并联动updateSelectedValueindex.android.ts从而保证 UI 操作与属性状态双向一致。监听选中变化与 selectedValue 联动当用户通过滚轮改变选中项时ListPicker 会触发selectedIndexChange事件事件名常量定义于 list-picker-common.tsd.ts 中标注其载荷类型为PropertyChangeData。监听方式如下listPicker.on(selectedIndexChange, (args) { console.log(新的选中索引, args.value); });与此同时selectedIndex变化还会联动更新只读的selectedValue属性。updateSelectedValuelist-picker-common.ts的逻辑为当valueField非空时取item[valueField]作为selectedValue否则直接取item本身索引小于 0 时selectedValue置为null。典型用法配合textField展示名称、valueField取 ID从而在选中变化时直接拿到业务主键无需再手动查表listPicker.textField name; listPicker.valueField id; listPicker.items [ { id: 101, name: Angular }, { id: 202, name: React }, ]; listPicker.on(selectedIndexChange, (args) { console.log(选中 ID, listPicker.selectedValue); // 101 或 202 });平台实现速览ListPicker 的双端原生实现都封装在nativescript/core的ui/list-picker目录中公共基类list-picker-common.ts定义ListPickerBase、ItemsSource接口及selectedIndex、items、textField、valueField、selectedValue五个属性并设置了recycleNativeView auto以支持原生视图回收复用自动化测试test_recycling即验证了这一点。Android 实现index.android.ts原生控件为android.widget.NumberPicker通过Formatter调用_getItemAsString渲染行文本与OnValueChangeListener回写selectedIndex桥接 JS 与原生同时支持通过color属性定制选中文字颜色API 28 及以下使用反射获取mSelectorWheelPaintAPI 29 使用原生公开方法。iOS 实现index.ios.ts原生控件为UIPickerView通过UIPickerViewDataSource返回组件数与行数和UIPickerViewDelegate渲染行文本、回写选中行实现桥接并支持tintColor定制。类型声明index.d.ts对外暴露selectedIndex与items属性并标注 Android 端原生视图为android.widget.NumberPicker、iOS 端为UIPickerView便于在代码中直接访问原生对象做进一步定制。进一步阅读官方 HOW-TO 文档主体apps/automated/src/ui/list-picker/list-picker.md完整自动化测试含全部边界行为用例apps/automated/src/ui/list-picker/list-picker-tests.ts平台原生测试辅助list-picker-tests-native.ios.ts、list-picker-tests-native.android.ts双端原生封装源码apps/ui/src/list-pickerUI 示例工程含 XML 页面与 TS 用例赞分享【免费下载链接】NativeScript⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.项目地址https://gitcode.com/gh_mirrors/na/NativeScript点击查看免费下载相关推荐NativeScript-Vue3 响应式系统完整指南深入理解数据绑定与更新机制NativeScript Vue3 响应式系统完整指南深入理解数据绑定与更新机制 NativeScript Vue3 响应式系统是现代跨平台移动应用开发的核心移动开发前端跨平台Skinny Framework社区贡献指南如何参与开源项目Skinny Framework社区贡献指南如何参与开源项目 Skinny Framework是一个以Scala on Rails为理念的全栈Web应用框后端TDengine参数绑定模式高效数据写入指南TDengine参数绑定模式高效数据写入指南 什么是参数绑定 参数绑定 Parameter Binding 是一种高效的数据写入技术它通过将SQL语句结构与实数据库时序数据库大数据物联网云原生上一篇如何快速找回遗忘的压缩包密码开源工具的终极解决方案下一篇如何跑通 Bangumi 上架 App 的发布流程一次双端发版的 5 步清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
