uni-app UTS 可迭代协议Iterable全解析从 for..of 到 UTSValueIterable 自定义迭代【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appUTS 是 uni-app 在 App 端使用的、可编译到 AndroidKotlin与 iOSSwift的类 TypeScript 语言。本文围绕 docs/uts/iterable.md 展开系统讲解 UTS 中可迭代协议Iterable的完整能力HBuilderX 4.41 之后 for..of 如何实现全端行为与 Web 标准一致、内置对象Array/Set/Map/String的遍历规则以及如何通过UTSValueIterable接口为自定义 Class 定制迭代逻辑。读完本文你将能够在 UTS 中正确使用 for..of、规避跨端遍历陷阱并为业务对象实现可复用的自定义迭代器。一、背景HBuilderX 4.41 是 UTS 可迭代能力的分水岭在 HBuilderX 4.41 版本之前UTS 并未对for..of做特殊处理开发者在 UTS 代码中调用for..of会直接编译报错无法使用。从 HBuilderX 4.41 开始UTS 语言正式支持可迭代协议并以 Web 标准的可迭代协议为基准保证了for..of行为在 Android、iOS、Web 等全端的一致同时开放了可迭代协议的扩展能力。也就是说在 HBuilderX 4.41 之后的版本中UTS 内置的for..of语法执行效果与 Web 标准一致。一个最直观的例子对混合类型数组执行for..of遍历——let a1 [111,222,false] for(perItem of a1){ console.log(perItem) }这段代码在 HBuilderX 4.41 之前的 Android / iOS 端会编译报错而在 HBuilderX 4.41 之后全端执行效果统一为111 222 false可迭代协议最直接的应用场景就是for..of运算符UTS 中for..of的完整语法说明详见 docs/uts/loops.md#forof。二、内置对象的 for..of 支持规则在 UTS 中for..of循环按顺序逐个处理从可迭代对象获取的值每次迭代都会执行可能引用当前序列值的语句。根据 docs/uts/loops.md#forof 的说明HBuilderX 4.41 之后内置对象对for..of的支持情况如下。Set / Array遍历元素值类似 Set、Array 这样的一维数据容器会遍历内部属性值即元素本身let u1 new Setany() u1.add(111) u1.add(222) for (item of u1) { console.log(item,item) }执行结果 item 111 item 222Map遍历为键值对数组Map 的遍历会将其 key、value 封装为一个新的 Array 数组let u1 new Mapstring,any() u1.put(aaa,111) u1.put(bbb,222) for (item of u1) { console.log(item,item) }执行结果 [Array] [ aaa, 111 ] [Array] [ bbb, 222 ]String逐字符遍历遍历 String 的每一个字符let a 123456 for(item of a ){ console.log(item) }执行结果 1 2 3 4 5 6不支持的遍历对象number、Date、RegExp、Error、UTSJSONObject、自定义的 type 类型、自定义 class均不支持for..of直接使用会编译报错For-loop range must have an iterator() method需要特别说明的是一般情况下的自定义 type 类型 / 自定义 class 直接使用for..of会报错但有些场景需要赋予自定义 class 循环访问自身的能力甚至定制迭代访问的内容——这正是下一节UTSValueIterable接口要解决的问题。补充除了for..of部分内置对象还支持forEach方法以更简单地遍历可参见 docs/uts/buildin-object-api/array.md#foreach 与 docs/uts/buildin-object-api/set.md#foreach。三、定制可迭代对象UTSValueIterable 接口在 Web 开发中可迭代协议并不仅仅是简单对应for..of语法更是对遍历对象内部元素的一种约定。UTS 同样支持了这种能力。在 HBuilderX 4.41 之后的版本中UTS 语言内置了UTSValueIterable接口用来支持自定义对象的可迭代规则。当开发者手动实现UTSValueIterable接口时就可以定制其实例对象在for..of运算下的规则。3.1 默认不可迭代先看报错首先看一个默认场景下面的 Class 实例并不支持for..of语法class TestClass { holderArray: (any | null)[] [11, 22, null, 33, 44, null] } let test new TestClass() for (item of test) { console.log(item,item) }如果直接运行会触发编译报错error: For-loop range must have an iterator() method3.2 实现 UTSValueIterable 接口为了让对象支持for..of可以让 Class 实现UTSValueIterable接口并补全唯一的待实现函数valueIteratorclass TestClass implements UTSValueIterableany | null { holderArray: (any | null)[] [11, 22, null, 33, 44, null] valueIterator(): UTSIteratorany | null { let holderIndex 0; let obj: UTSIteratorany | null { next: () : UTSIteratorResultany | null { const done holderIndex this.holderArray.length return { done, value: done ? null : this.holderArray[holderIndex], } as UTSIteratorResultany | null } } return obj } }执行结果注意 null 值也会被遍历出来item [number] 11 item [number] 22 item null item [number] 33 item [number] 44 item null3.3 三个关键类型UTSValueIterable / UTSIterator / UTSIteratorResult理解这段代码需要掌握三个核心类型UTSValueIterable自定义可迭代对象需要实现的接口它仅存在一个待实现函数valueIterator。UTSIteratorvalueIterator函数的返回值类型与 Web 中的 Iterator 类似开发者需要关心其中next函数的实现。UTSIteratorResultnext函数返回的数据结构包含done与value两个字段。与 Web 的迭代器协议一样该数据结构中的done决定了是否可以继续迭代true表示迭代结束value对应当前迭代返回的具体数值。当done为true时示例代码中返回的value为null该值不会对遍历结果产生实际影响。3.4 实战过滤空值的自定义迭代如果我们希望使用者在for..of时仅能遍历出非空的数值可以在valueIterator内部先对数据进行过滤class TestClass implements UTSValueIterableany | null { holderArray: (any | null)[] [11, 22, null, 33, 44, null] valueIterator(): UTSIteratorany | null { let holderIndex 0; let arr this.holderArray.filter((value) { return value ! null }) let obj: UTSIteratorany | null { next: () : UTSIteratorResultany | null { const done holderIndex arr.length return { done, value: done ? null : arr[holderIndex], } as UTSIteratorResultany | null } } return obj } }执行结果两个null被过滤掉item [number] 11 item [number] 22 item [number] 33 item [number] 44从源码结构看next函数内部采用闭包变量holderIndex记录迭代游标配合done判断是否到达集合末尾这是实现一个有状态迭代器的通用模式迭代器不依赖外部重置每次调用next自动推进游标。四、源码佐证仓库中的迭代器测试用例上述文档示例并非孤立存在。在 examples/hello-uts/uni_modules/uts-tests/utssdk/iterator.uts 中仓库提供了对应的自动化测试用例完整覆盖了UTSValueIterable的多种实现形态TestChild实现UTSValueIterableany | null同时定义了ignoredKeys()方法被注释的UTSKeyIterable相关代码表明该测试文件曾探索过按键迭代的能力。TestClassholderArray全部为[null, null]经过过滤后遍历结果应为空数组。TestClass2过滤空值后遍历结果为[11, 22, 33, 44]。TestClass3不做过滤遍历结果为[11, 22, null, 33, 44, null]。测试函数testIterator()使用describe/test/expect断言框架验证了以下行为对应test(for...of)用例// 数组遍历 let arr [a, b, c, d] for (let item of arr) { result1.push(item) } expect(result1).toEqual([a, b, c, d]) // Map 遍历为键值对数组APP-ANDROID 下 expect(result2).toEqual([[a, 1], [b, 2], [c, 3]]) // Set 遍历元素值 expect(result3).toEqual([a, b, c]) // 实现 UTSValueIterable 的类按 valueIterator 规则遍历 expect(result4).toEqual([11, 22, null, 33, 44, null]) expect(forofRet).toEqual([]) // 全 null 过滤后为空 expect(forofRet2).toEqual([11, 22, 33, 44]) // 过滤 null expect(forofRet3).toEqual([11, 22, null, 33, 44, null]) // 不过滤 null这份测试用例是理解可迭代协议行为的最佳可运行证据文档描述的每一条遍历规则都可以在这里找到对应的断言验证开发者在实现自定义迭代器后也可以参考该文件组织自己的单元测试。五、可迭代与可枚举两种遍历协议的区别与选择5.1 概念差异可枚举for...inECMAScript 1999 开始支持主要用于遍历对象的属性迭代的是对象的所有可枚举属性包括原型链中的属性。可迭代for...ofECMAScript 2015 开始支持主要用于遍历可迭代的数据结构如数组、字符串、Set、Map 等迭代的是集合中每一个元素的值不会遍历对象的属性。UTS 语言目前不支持对可枚举协议进行自定义详见 docs/uts/enumerability.md而可迭代协议则可以通过UTSValueIterable完全自定义。5.2 各平台支持矩阵在原生开发场景下Kotlin 和 Swift 均只支持for..in语法、不支持for..of语法但原生for..in的用法与 Web 存在差异实际上对应的是 Web 中的可迭代概念。完整的支持情况见 docs/uts/enumerability_iterable.md各平台支持信息平台可迭代可枚举web支持ECMAScript-2015支持ECMAScript-1999kotlin支持不支持swift支持不支持各平台实现关键字平台可迭代可枚举webfor..offor..inkotlinfor..in不支持swiftfor..in不支持5.3 for..in 在平台间的行为差异典型陷阱看下面这段代码let a1 [111,222,false] for(perItem in a1){ console.log(perItem,perItem) }Web 执行结果遍历的是下标perItem 0 perItem 1 perItem 2Android 执行结果遍历的是元素值perItem [number] 111 perItem 222 perItem [boolean] false这正是 docs/uts/loops.md#forin 中特别提醒的坑数组遍历不推荐使用for..in因为 TypeScript/Web 中for..in遍历的是数组下标而 Swift 和 Kotlin 中遍历的是数组元素存在行为不一致。UTS 内置对象对for..in的支持差异汇总如下类型WebAndroidiosArray返回索引返回数值返回数值Set不可枚举返回数值返回数值Map不可枚举返回键值对返回键值对String返回索引返回字符返回字符自定义 type返回属性名返回属性名返回属性名UTSJSONObject返回属性名返回属性名返回属性名5.4 官方使用建议对于可枚举协议for..in出于历史代码兼容性原因HBuilderX 4.41 之后与之前版本保持一致各平台的运行依然存在差异。因此针对 Array/Set/Map 等集合类型以及 String 的遍历建议使用 for...of不建议使用 for...in以保持与 Web 行为的一致性单从访问对象内部属性的角度可迭代是一种更现代化的语法官方建议开发者通过for..of实现对对象内部属性的遍历当内置集合无法满足需求如需要过滤、转换、合并多个数据源后遍历时使用UTSValueIterable自定义迭代规则。六、小结UTS 的可迭代能力围绕一条主线展开以 Web 标准为基准统一全端 for..of 行为并开放自定义扩展。开发者只需记住三个要点内置集合Array/Set/Map/String在 HBuilderX 4.41 之后可直接使用for..ofMap 遍历得到的是键值对数组自定义 Class通过实现UTSValueIterable接口并实现valueIterator返回UTSIterator即可定制for..of的遍历规则next返回的UTSIteratorResult中done控制终止、value控制取值规避 for..in由于 Web 与 Kotlin/Swift 对for..in的解释存在根本差异集合与字符串遍历应统一走for..of。仓库中的 iterator.uts 测试用例 是验证上述全部行为的最佳参照配合 loops.md、enumerability_iterable.md、enumerability.md 三篇文档可以完整掌握 UTS 遍历体系的正确用法。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app UTS 可迭代协议Iterable全解析从 for..of 到 UTSValueIterable 自定义迭代【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appUTS 是 uni-app 在 App 端使用的、可编译到 AndroidKotlin与 iOSSwift的类 TypeScript 语言。本文围绕 docs/uts/iterable.md 展开系统讲解 UTS 中可迭代协议Iterable的完整能力HBuilderX 4.41 之后 for..of 如何实现全端行为与 Web 标准一致、内置对象Array/Set/Map/String的遍历规则以及如何通过UTSValueIterable接口为自定义 Class 定制迭代逻辑。读完本文你将能够在 UTS 中正确使用 for..of、规避跨端遍历陷阱并为业务对象实现可复用的自定义迭代器。一、背景HBuilderX 4.41 是 UTS 可迭代能力的分水岭在 HBuilderX 4.41 版本之前UTS 并未对for..of做特殊处理开发者在 UTS 代码中调用for..of会直接编译报错无法使用。从 HBuilderX 4.41 开始UTS 语言正式支持可迭代协议并以 Web 标准的可迭代协议为基准保证了for..of行为在 Android、iOS、Web 等全端的一致同时开放了可迭代协议的扩展能力。也就是说在 HBuilderX 4.41 之后的版本中UTS 内置的for..of语法执行效果与 Web 标准一致。一个最直观的例子对混合类型数组执行for..of遍历——let a1 [111,222,false] for(perItem of a1){ console.log(perItem) }这段代码在 HBuilderX 4.41 之前的 Android / iOS 端会编译报错而在 HBuilderX 4.41 之后全端执行效果统一为111 222 false可迭代协议最直接的应用场景就是for..of运算符UTS 中for..of的完整语法说明详见 docs/uts/loops.md#forof。二、内置对象的 for..of 支持规则在 UTS 中for..of循环按顺序逐个处理从可迭代对象获取的值每次迭代都会执行可能引用当前序列值的语句。根据 docs/uts/loops.md#forof 的说明HBuilderX 4.41 之后内置对象对for..of的支持情况如下。Set / Array遍历元素值类似 Set、Array 这样的一维数据容器会遍历内部属性值即元素本身let u1 new Setany() u1.add(111) u1.add(222) for (item of u1) { console.log(item,item) }执行结果 item 111 item 222Map遍历为键值对数组Map 的遍历会将其 key、value 封装为一个新的 Array 数组let u1 new Mapstring,any() u1.put(aaa,111) u1.put(bbb,222) for (item of u1) { console.log(item,item) }执行结果 [Array] [ aaa, 111 ] [Array] [ bbb, 222 ]String逐字符遍历遍历 String 的每一个字符let a 123456 for(item of a ){ console.log(item) }执行结果 1 2 3 4 5 6不支持的遍历对象number、Date、RegExp、Error、UTSJSONObject、自定义的 type 类型、自定义 class均不支持for..of直接使用会编译报错For-loop range must have an iterator() method需要特别说明的是一般情况下的自定义 type 类型 / 自定义 class 直接使用for..of会报错但有些场景需要赋予自定义 class 循环访问自身的能力甚至定制迭代访问的内容——这正是下一节UTSValueIterable接口要解决的问题。补充除了for..of部分内置对象还支持forEach方法以更简单地遍历可参见 docs/uts/buildin-object-api/array.md#foreach 与 docs/uts/buildin-object-api/set.md#foreach。三、定制可迭代对象UTSValueIterable 接口在 Web 开发中可迭代协议并不仅仅是简单对应for..of语法更是对遍历对象内部元素的一种约定。UTS 同样支持了这种能力。在 HBuilderX 4.41 之后的版本中UTS 语言内置了UTSValueIterable接口用来支持自定义对象的可迭代规则。当开发者手动实现UTSValueIterable接口时就可以定制其实例对象在for..of运算下的规则。3.1 默认不可迭代先看报错首先看一个默认场景下面的 Class 实例并不支持for..of语法class TestClass { holderArray: (any | null)[] [11, 22, null, 33, 44, null] } let test new TestClass() for (item of test) { console.log(item,item) }如果直接运行会触发编译报错error: For-loop range must have an iterator() method3.2 实现 UTSValueIterable 接口为了让对象支持for..of可以让 Class 实现UTSValueIterable接口并补全唯一的待实现函数valueIteratorclass TestClass implements UTSValueIterableany | null { holderArray: (any | null)[] [11, 22, null, 33, 44, null] valueIterator(): UTSIteratorany | null { let holderIndex 0; let obj: UTSIteratorany | null { next: () : UTSIteratorResultany | null { const done holderIndex this.holderArray.length return { done, value: done ? null : this.holderArray[holderIndex], } as UTSIteratorResultany | null } } return obj } }执行结果注意 null 值也会被遍历出来item [number] 11 item [number] 22 item null item [number] 33 item [number] 44 item null3.3 三个关键类型UTSValueIterable / UTSIterator / UTSIteratorResult理解这段代码需要掌握三个核心类型UTSValueIterable自定义可迭代对象需要实现的接口它仅存在一个待实现函数valueIterator。UTSIteratorvalueIterator函数的返回值类型与 Web 中的 Iterator 类似开发者需要关心其中next函数的实现。UTSIteratorResultnext函数返回的数据结构包含done与value两个字段。与 Web 的迭代器协议一样该数据结构中的done决定了是否可以继续迭代true表示迭代结束value对应当前迭代返回的具体数值。当done为true时示例代码中返回的value为null该值不会对遍历结果产生实际影响。3.4 实战过滤空值的自定义迭代如果我们希望使用者在for..of时仅能遍历出非空的数值可以在valueIterator内部先对数据进行过滤class TestClass implements UTSValueIterableany | null { holderArray: (any | null)[] [11, 22, null, 33, 44, null] valueIterator(): UTSIteratorany | null { let holderIndex 0; let arr this.holderArray.filter((value) { return value ! null }) let obj: UTSIteratorany | null { next: () : UTSIteratorResultany | null { const done holderIndex arr.length return { done, value: done ? null : arr[holderIndex], } as UTSIteratorResultany | null } } return obj } }执行结果两个null被过滤掉item [number] 11 item [number] 22 item [number] 33 item [number] 44从源码结构看next函数内部采用闭包变量holderIndex记录迭代游标配合done判断是否到达集合末尾这是实现一个有状态迭代器的通用模式迭代器不依赖外部重置每次调用next自动推进游标。四、源码佐证仓库中的迭代器测试用例上述文档示例并非孤立存在。在 examples/hello-uts/uni_modules/uts-tests/utssdk/iterator.uts 中仓库提供了对应的自动化测试用例完整覆盖了UTSValueIterable的多种实现形态TestChild实现UTSValueIterableany | null同时定义了ignoredKeys()方法被注释的UTSKeyIterable相关代码表明该测试文件曾探索过按键迭代的能力。TestClassholderArray全部为[null, null]经过过滤后遍历结果应为空数组。TestClass2过滤空值后遍历结果为[11, 22, 33, 44]。TestClass3不做过滤遍历结果为[11, 22, null, 33, 44, null]。测试函数testIterator()使用describe/test/expect断言框架验证了以下行为对应test(for...of)用例// 数组遍历 let arr [a, b, c, d] for (let item of arr) { result1.push(item) } expect(result1).toEqual([a, b, c, d]) // Map 遍历为键值对数组APP-ANDROID 下 expect(result2).toEqual([[a, 1], [b, 2], [c, 3]]) // Set 遍历元素值 expect(result3).toEqual([a, b, c]) // 实现 UTSValueIterable 的类按 valueIterator 规则遍历 expect(result4).toEqual([11, 22, null, 33, 44, null]) expect(forofRet).toEqual([]) // 全 null 过滤后为空 expect(forofRet2).toEqual([11, 22, 33, 44]) // 过滤 null expect(forofRet3).toEqual([11, 22, null, 33, 44, null]) // 不过滤 null这份测试用例是理解可迭代协议行为的最佳可运行证据文档描述的每一条遍历规则都可以在这里找到对应的断言验证开发者在实现自定义迭代器后也可以参考该文件组织自己的单元测试。五、可迭代与可枚举两种遍历协议的区别与选择5.1 概念差异可枚举for...inECMAScript 1999 开始支持主要用于遍历对象的属性迭代的是对象的所有可枚举属性包括原型链中的属性。可迭代for...ofECMAScript 2015 开始支持主要用于遍历可迭代的数据结构如数组、字符串、Set、Map 等迭代的是集合中每一个元素的值不会遍历对象的属性。UTS 语言目前不支持对可枚举协议进行自定义详见 docs/uts/enumerability.md而可迭代协议则可以通过UTSValueIterable完全自定义。5.2 各平台支持矩阵在原生开发场景下Kotlin 和 Swift 均只支持for..in语法、不支持for..of语法但原生for..in的用法与 Web 存在差异实际上对应的是 Web 中的可迭代概念。完整的支持情况见 docs/uts/enumerability_iterable.md各平台支持信息平台可迭代可枚举web支持ECMAScript-2015支持ECMAScript-1999kotlin支持不支持swift支持不支持各平台实现关键字平台可迭代可枚举webfor..offor..inkotlinfor..in不支持swiftfor..in不支持5.3 for..in 在平台间的行为差异典型陷阱看下面这段代码let a1 [111,222,false] for(perItem in a1){ console.log(perItem,perItem) }Web 执行结果遍历的是下标perItem 0 perItem 1 perItem 2Android 执行结果遍历的是元素值perItem [number] 111 perItem 222 perItem [boolean] false这正是 docs/uts/loops.md#forin 中特别提醒的坑数组遍历不推荐使用for..in因为 TypeScript/Web 中for..in遍历的是数组下标而 Swift 和 Kotlin 中遍历的是数组元素存在行为不一致。UTS 内置对象对for..in的支持差异汇总如下类型WebAndroidiosArray返回索引返回数值返回数值Set不可枚举返回数值返回数值Map不可枚举返回键值对返回键值对String返回索引返回字符返回字符自定义 type返回属性名返回属性名返回属性名UTSJSONObject返回属性名返回属性名返回属性名5.4 官方使用建议对于可枚举协议for..in出于历史代码兼容性原因HBuilderX 4.41 之后与之前版本保持一致各平台的运行依然存在差异。因此针对 Array/Set/Map 等集合类型以及 String 的遍历建议使用 for...of不建议使用 for...in以保持与 Web 行为的一致性单从访问对象内部属性的角度可迭代是一种更现代化的语法官方建议开发者通过for..of实现对对象内部属性的遍历当内置集合无法满足需求如需要过滤、转换、合并多个数据源后遍历时使用UTSValueIterable自定义迭代规则。六、小结UTS 的可迭代能力围绕一条主线展开以 Web 标准为基准统一全端 for..of 行为并开放自定义扩展。开发者只需记住三个要点内置集合Array/Set/Map/String在 HBuilderX 4.41 之后可直接使用for..ofMap 遍历得到的是键值对数组自定义 Class通过实现UTSValueIterable接口并实现valueIterator返回UTSIterator即可定制for..of的遍历规则next返回的UTSIteratorResult中done控制终止、value控制取值规避 for..in由于 Web 与 Kotlin/Swift 对for..in的解释存在根本差异集合与字符串遍历应统一走for..of。仓库中的 iterator.uts 测试用例 是验证上述全部行为的最佳参照配合 loops.md、enumerability_iterable.md、enumerability.md 三篇文档可以完整掌握 UTS 遍历体系的正确用法。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
