tmui-cli 2.0.2 → 2.0.4

package/data/uniappx/uts/generics.md

@@ -0,0 +1,246 @@
+# 泛型（Generics）
+
+UTS 支持泛型（Generics）特性，允许您编写更通用、可重用的代码，同时提高类型安全性。
+
+## 定义泛型
+
+泛型使用尖括号 `<>` 声明一个或多个泛型参数。
+
+## 泛型函数
+
+泛型函数的泛型参数定义在函数参数的圆括号之前。
+
+```ts
+function test<T>(arg: T): T {
+  return arg
+}
+
+const str: string = test<string>('a')
+
+const num: number = test<number>(1)
+```
+
+**注意**
+
+编译为 Kotlin、Swift 时，箭头函数不支持泛型。
+
+## 泛型类
+
+泛型类的泛型参数定义在类名之后。
+
+```ts
+class Test<T> {
+  value: T
+  constructor (value: T) {
+    this.value = value
+  }
+}
+
+const test1: Test<string> = new Test<string>('a')
+const str1: string = test1.value
+
+const test2: Test<number> = new Test<number>(1)
+const num1: number = test2.value
+```
+
+## 泛型接口
+
+泛型接口与泛型类相似，泛型参数定义在接口名之后。
+
+```ts
+interface ITest<T> {
+  value: T
+}
+
+class TestImpl<T> implements ITest<T> {
+  value: T
+}
+```
+
+## 泛型推断
+
+当泛型参数类型与函数的参数类型相关时，泛型参数能够根据函数参数类型自动推断，此时可以省略泛型参数。
+
+```ts
+const str1 = test<string>('a')
+const str2 = test('a')
+```
+
+## 泛型约束
+
+可以使用 `extends` 关键字来限制泛型参数的类型范围。
+
+```ts
+function testArray<T extends Array<string>>(arg: T): T {
+  return arg
+}
+```
+
+使用其他泛型类型时，如果不需要限制泛型参数的类型可以使用 `unknown` 关键字表示。
+
+```ts
+function testArray<T extends Array<unknown>>(arg: T): T {
+  return arg
+}
+```
+
+## 泛型使用场景示例
+
+- 泛型用法最常用的是在request api里，[详见](../tutorial/request.md)
+- 网络请求包装推荐使用成熟的网络拦截器插件，见[插件市场](https://ext.dcloud.net.cn/search?q=%E7%BD%91%E7%BB%9C%E6%8B%A6%E6%88%AA%E5%99%A8&uni-appx=1)
+
+## 注意事项
+
+### 安卓平台使用泛型注意事项
+
+ts本质是擦除类型的。在强类型语言中，传递泛型时如将泛型类型作为值使用，需通过特殊方式将泛型类型作为值使用，可以根据传入来动态决定返回类型:
+
+如果在UTS中声明一个包含泛型声明的方法，可能会出现泛型丢失，原因是因为普通的kotlin 方法没有实现泛型的传递
+
+错误的kt代码：
+
+```kotlin
+fun <T> getArtListByres(): A<T>? {
+   var aRet = UTSAndroid.consoleDebugError(JSON.parse<A<T>>("{\"x\":111,\"y\":\"aaa\",\"t\":{\"name\":\"zhangsan\"}}"), " at pages/index/index.uvue:27");
+   return aRet;
+}
+```
+
+期望得到的正确的kt代码：
+
+```ts
+inline fun <reified T> getArtListByres(): A<T>? {
+    var aRet = UTSAndroid.consoleDebugError(JSON.parse<A<T>>("{\"x\":111,\"y\":\"aaa\",\"t\":{\"name\":\"zhangsan\"}}"), " at pages/index/index.uvue:27");
+    return aRet;
+}
+```
+
+为了解决这种情况，我们可以在UTS中 添加android方法注解，来告诉编译器生成正确的代码：
+
+```kotlin
+@UTSAndroid.keyword("inline")
+@UTSAndroid.keyword('reified')
+export function request<T>(options : RequestOptions<T>) : RequestTask {
+	//xxx
+}
+```
+
+**注意：不要在`inline`方法中创建局部function，比如request的success回调、Promise的回调，原因是kotlin语言的限制（inline方法展开到内联位置，也会把局部方法展开过去，这是不允许的），由此把使用局部function的逻辑封装到非内联的方法中，绕过此限制。**  
+
+下面是可以完整的示例：
+
+```
+@UTSAndroid.keyword("inline")
+@UTSAndroid.keyword("reified")
+export function boxRequest<T>(url : string) : Promise<T> {
+	return innerRequest<T>(url, UTSAndroid.getGenericClassName<T>(), UTSAndroid.getGenericType<T>())
+}
+
+function innerRequest<T>(url : string, clzName : string, type : Type) : Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		uni.request<string>({
+			url: url,
+			method: "GET",
+			success: (e : RequestSuccess<string>) => {
+				const result = JSON.parse<T>(e.data!, type)
+				if (result != null) {
+					resolve(result)
+				} else if ("java.lang.Object".equals(clzName, true)) {// 解决泛型是any，但后端返回string的情况。
+					resolve(e.data! as T)
+				} else{
+					reject("parsing failure")
+				}
+			},
+			fail(e : RequestFail) {
+				reject(e)
+			},
+		} as RequestOptions<string>)
+	});
+}
+```
+调用代码：
+```
+const respone = await boxRequest<CustomType>("xxxx")
+```
+
+此示例中，网络请求泛型为`string`在4.25版本以下会导致错误，此问题已在4.25进行修复 [issue](https://issues.dcloud.net.cn/pages/issues/detail?id=4010)
+
+### iOS 平台使用泛型注意事项
+
+由于 iOS 平台 uni-app x 中的 uvue 运行在 js 环境中，以及 swift 语法的特殊性，泛型在 iOS 平台上的使用有一定限制和差异。
+
+在 uvue 中使用：
+- uvue 中可以正常使用泛型，iOS 平台上 uvue运行在 js 环境中，在 uvue 中的泛型就是 js 泛型。
+- 在 uvue 页面中使用的泛型类型传递给 uts 插件使用时，泛型信息会丢失。
+
+在 uts 插件中使用：
+- uts 插件中支持使用泛型函数、泛型类、泛型约束、泛型推断。目前仅适合在 uts 插件内部使用，运行在纯 swift 环境中。
+- uts 插件中暂不支持泛型接口的定义。
+- uts 插件中不能导出泛型函数、泛型类给 js 和其他 uts 插件使用。
+  + 说明：因为导出的泛型函数、泛型类不能被反射识别，无法使用。导出泛型函数还可能会导致编译失败。
+
+下面是在 uts 插件内部使用泛型的一些示例代码：
+
+泛型函数和泛型推断示例，泛型用在返回值上：
+
+```ts
+// 定义泛型函数
+function test1<T>(param: any): T | null {
+	if (param instanceof T) {
+		return param as T
+	}
+	return null
+}
+
+// 使用：
+let str: string | null = test1<string>("12345")
+console.log(str)
+```
+
+> 特别注意：
+
+> 在 `swift` 中调用泛型函数时不能直接指定泛型类型，只能靠参数或者返回值来进行泛型类型的推断。
+
+> 上述示例代码使用泛型函数时，给变量 `str` 指定了具体类型，这个是必须的，且指定的类型要和泛型函数的返回值是否可选保持一致（泛型函数返回值是 T | null, str 类型就得是 string | null, 否则
+> 将会因为推断不出泛型类型导致编译报错。
+
+泛型类和泛型约束示例：
+
+```ts
+// 自定义type
+type MyResult = {
+	name: string
+	age: number
+}
+
+// 定义泛型类，并指定泛型约束
+class TestOption<T extends Decodable> {
+	a: string = ""
+	b: number = 0
+	success?: (res: T) => void
+}
+
+// 定义泛型函数
+function test2<T extends Decodable>(param: TestOption<T>) {
+
+	let str = "{\"name\":\"2024\",\"age\":2}"
+	// 这句代码是为了让编译给 MyResult 实现 Decodable 协议，不可省略。后续版本会给出让开发者指定某个 type 遵循 Decodable 协议的方式。
+	JSON.parseObject<MyResult>(str)
+
+	let ret = JSON.parseObject<T>(str)
+	if (ret != null) {
+		param.success?.(ret!)
+	}
+}
+
+// 使用：
+let p = new TestOption<MyResult>()
+p.success = (res: MyResult) => {
+	console.log(res)
+}
+test2<MyResult>(p)
+```
+
+> 特别注意：
+
+> HBuilderX 4.25+ 支持自定义 type 上指定泛型。

package/data/uniappx/uts/interface.md

@@ -0,0 +1,35 @@
+# 接口（Interface）@interface
+
+接口提供了一种约定，用于确保对象的属性和方法遵循特定的模式。接口只能包含抽象的声明，不能包含具体的实现。接口本身不能被实例化，它可以被类所采用，以提供具体的实现。
+
+在 ts 中，经常把json数据转为 interface 或 type 。但在 uts 中，只适合转 type，不适合使用 interface。因为 interface 在 kotlin 和 swift 中另有不同。
+
+接口使用关键字 `interface` 声明。
+
+```ts
+interface IPerson {
+  name: string;
+  printName(): void;
+}
+```
+
+## 接口继承
+
+接口可以继承一个或多个接口：
+
+```ts
+interface IPerson1 extends IPerson {}
+```
+
+## 实现接口
+
+类可以实现一个或多个接口：
+
+```ts
+class Person implements IPerson {
+  constructor(public name: string) {}
+  printName() {
+    console.log(this.name);
+  }
+}
+```

package/data/uniappx/uts/iterable.md

@@ -0,0 +1,137 @@
+## 可迭代的多平台差异
+
+参考[可迭代与可枚举的平台差异](./enumerability_iterable.md)
+
+## 可迭代
+
+在HBuilderX 4.41版本之前，UTS并未对 for ..of 做特殊处理：开发者调用 for..of 会编译报错，无法使用
+
+从HBuilderX 4.41开始，UTS语言支持了[可迭代协议](https://issues.dcloud.net.cn/pages/issues/detail?id=6511). 以 [web的可迭代](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols)为标准，保证了可迭代协议行为(即for..of)的全端一致，并开放了可迭代协议的扩展能力。
+
+也就是说，在HBuilderX 4.41之后版本，UTS内置的for..of 语法执行效果与web标准一致。
+
+```ts
+let a1 = [111,"222",false]
+
+for(perItem of a1){
+	console.log(perItem)
+}
+```
+
+上面的代码在 HBuilderX 4.41 之前版本在 android /ios 会编译报错，在HBuilderX 4.41 之后，全端执行效果如下：
+
+```ts
+111
+"222"
+false
+```
+
+可迭代协议最直接的应用场景就是 for..of 运算符，UTS 中对 for..of 支持情况的具体介绍[详见](./loops.md#forof)
+
+### 定制可迭代对象
+
+在web开发中，可迭代协议并不仅仅是简单的对应了 for..of 语法。 还是对遍历对象内部元素的一种约定。UTS同样支持了这种能力。
+
+在HBuilder X 4.41 之后版本，UTS语言内置了：  `UTSValueIterable` 接口，用来支持自定义对象的可迭代规则。
+
+当开发者手动实现 `UTSValueIterable` 接口时，就可以实现定制其实例对象在 for..of 运算下的规则
+
+举例：
+
+```typescript
+class TestClass  {
+  holderArray: (any | null)[] = [11, 22, null, 33, 44, null]
+}
+
+let test = new TestClass()
+
+for (item of test) {
+  console.log("item",item)
+}
+```
+
+该class对应的实例 并不支持 for..of 语法，如果使用下面的代码调用会触发报错：
+ 
+>  ‌error: For-loop range must have an 'iterator()' method‌
+
+如果我们想让这个对象的示例，支持for..of 语法，可以修改为如下代码:
+
+```typescript
+class TestClass implements UTSValueIterable<any | null> {
+
+  holderArray: (any | null)[] = [11, 22, null, 33, 44, null]
+
+  valueIterator(): UTSIterator<any | null> {
+    let holderIndex = 0;
+    let obj: UTSIterator<any | null> = {
+      next: () : UTSIteratorResult<any | null> => {
+        const done = holderIndex == this.holderArray.length
+          return {
+            done,
+            value: done ? null : this.holderArray[holderIndex++],
+          } as UTSIteratorResult<any | null>
+      }
+    }
+    return obj
+  }
+  
+}
+```
+执行结果:
+
+```typescript
+item ‍[number]‍ 11
+item ‍[number]‍ 22
+item null
+item ‍[number]‍ 33
+item ‍[number]‍ 44
+item null
+```
+
+`UTSValueIterable` 接口 仅存在一个待实现函数`valueIterator`,该函数返回值是 `UTSIterator` 类型与web中[Iterator](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Iterator)类似。
+
+开发者需要关心是`UTSIterator`中的 `next` 函数实现，`next`函数返回一个 `UTSIteratorResult` 该数据结构为done和value
+
+与web的[迭代器协议](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols#%E8%BF%AD%E4%BB%A3%E5%99%A8%E5%8D%8F%E8%AE%AE)一样，该数据结构中的 done 决定了是否可以继续迭代，value 对应当前迭代的具体数值。
+
+如果我们希望在使用者for..of 时仅能遍历出非空的数值，我们可以这样实现
+
+```typescript
+class TestClass implements UTSValueIterable<any | null> {
+
+  holderArray: (any | null)[] = [11, 22, null, 33, 44, null]
+
+  valueIterator(): UTSIterator<any | null> {
+    let holderIndex = 0;
+    let arr = this.holderArray.filter((value) => { 
+      return value != null
+    })
+
+    let obj: UTSIterator<any | null> = {
+      next: () : UTSIteratorResult<any | null> => {
+        const done = holderIndex == arr.length
+        return {
+          done,
+          value: done ? null : arr[holderIndex++],
+        } as UTSIteratorResult<any | null>
+      }
+    }
+    return obj
+  }
+  
+}
+```
+
+执行结果:
+```typescript
+item ‍[number]‍ 11
+item ‍[number]‍ 22
+item ‍[number]‍ 33
+item ‍[number]‍ 44
+```
+
+## 可迭代和可枚举的关系
+
+关于可枚举和for..in的相关内容 参考[可枚举协议](./enumerability.md)
+
+单从访问对象内部属性的角度。我们认为，可迭代是一种更现代化语法，建议开发者通过 for..of 来实现对对象内部属性的遍历。