tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/uts/keywords.md

@@ -0,0 +1,436 @@
+## 关键字
+
+### this
+
+安卓端this只会指向其所在的类的实例，而编译到js后this的值取决于它出现的上下文：函数、类或全局。参考： [MDN this](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Operators/this)
+
+以下述代码为例
+
+```vue
+<template>
+  <view></view>
+</template>
+<script>
+  export default {
+    data() {
+      return {
+        title: '' 
+      }
+    },
+    methods: {
+      getTitle() {
+        uni.request({
+          url: 'xxx',
+          success() {
+            this.title = 'xxx'
+          }
+        })
+      }
+    }
+  }
+</script>
+```
+
+上述代码中的this在安卓端会指向页面/组件实例，在web端会指向uni.request的参数。为保证多端一致，建议在上面的场景使用this时搭配箭头函数。上述代码修改为下面的写法后即可兼容多端
+
+```vue
+<template>
+  <view></view>
+</template>
+<script>
+  export default {
+    data() {
+      return {
+        title: '' 
+      }
+    },
+    methods: {
+      getTitle() {
+        uni.request({
+          url: 'xxx',
+          success: () => {
+            this.title = 'xxx'
+          }
+        })
+      }
+    }
+  }
+</script>
+```
+
+
+### 类型断言as@as
+
+类型可能不明确、不唯一时，可以使用类型断言操作符 `as` 来为值指定类型。
+
+常见于 any 类型的明确、字面量的明确，也可以用于可为空 `|null` 类型的明确。
+
+```ts
+const a: any = 'a'
+a as string // as之后a就可以当做string直接使用了
+
+const a: string | null = 'a'
+a as string // 正常
+```
+
+当一个字面量可能成为多种类型时，可以通过as来明确具体类型。
+```ts
+// 数字字面量可以被指定为任何相容的数字类型
+1.0 as Double
+1.0 as number
+
+// 对象字面量也可以as为UTSJSONObject或某个type
+{"id":1} as UTSJSONObject
+
+type t = {
+	id:number
+}
+{"id":1} as t
+```
+
+number数据类型与平台专有数字类型不应该直接使用as转换：
+- number转平台专有数字类型应该使用 [Number对象](buildin-object-api/number.md) 的 toXXX 方法转换
+```ts
+let a:number = 1;
+
+let i:Int = a.toInt()				// 正确
+let i:Int = a as Int				// 错误
+
+let f:Float = a.toFloat()		// 正确
+let f:Float = a as Float		// 错误
+
+let d:Double = a.toDouble()	// 正确
+let d:Double = a as Double	// 错误
+
+//系统API需要平台专有数字类型，也应该使用 toXXX 方法转换平台专有数字类型
+systemAPI(a.toDouble())			// 正确
+systemAPI(a as Double)			// 错误
+```
+- 平台专有数字类型应该使用  [Number.from()](buildin-object-api/number.md#from) 方法转换
+```
+let i:Int = 1;
+let d:Double = 1.0;
+
+let n:number = Number.from(i)	// 正确
+let n:number = i as number		// 错误
+
+let n:number = Number.from(d)	// 正确
+let n:number = d as number		// 错误
+```
+
+> 虽然在某些情况下使用 as 转换也可以正常工作，但为了保证各平台兼容性推荐使用上述方法转换
+
+只允许将类型as为具体或更不具体的类型，不能强制转换两个不可能兼容的类型：
+
+```ts
+const a: string = 'a'
+
+a as any // 正确
+a as string // 正确
+a as number // 错误
+```
+
+UTSJSONObject和type不相容，无法互相as。应该在初始的字面量或JSON.parse环节就决定好类型。
+
+类型断言会在运行时进行，如果无法强制转换，类型断言运算符会引发异常：
+
+```ts
+const a: string | null = 'a'
+a as string // 正常
+
+a = null
+a as string // 异常
+```
+
+以上代码中当值为 `null` 的时，强制转换为 `string` 会引发异常。为了让这样的代码用于可空值，请在类型断言的右侧使用可空类型：
+
+```ts
+a as string ｜ null // 正常
+```
+
+当 as 操作符的左侧为[对象字面量](./literal.md#object-literal)时，编译器会进行[特殊处理](./object.md#实例化)：自动创建类型对应的实例。
+
+```ts
+{ name: 'Tom', printName: function () { } } as Person
+```
+
+另外：当 `as` 用在[模块](./module.md)导入时，它和类型断言无关，其功能为[指定别名](./module.md#指定别名)。
+
+
+### typeof实例类型获取@typeof
+
+使用 `typeof` 运算符获取一个实例对象的类型，返回表示类型的字符串。
+
+| 类型                						 			 | 结果             |
+| ------------------------------------------------------ | ---------------- |
+| null                						 			 | "object"         |
+| boolean     		  						 			 | "boolean"        |
+| number       		  						 			 | "number"         |
+| string       		  						 			 | "string"         |
+| function     		  						 			 | "function"       |
+| 平台专有数字类型: Int, Float, Double, Long ... 		    | "Int","Float","Double","Long" ... |
+| 平台专有字符串类型: Char ... 			                    | "Char" ... |
+| 其他任何对象(包含但不限于：Date, Array, Map, UTSJSONObject) | "object"         |
+| any                                                    | 实际类型 |
+
+
+为了与web保持一致，typeof除了布尔、数字、字符串、函数外，全部返回object。如需判断object范围内的具体类型，需另见[instanceof](#instanceof)
+
+用法示例：
+
+```ts
+let a = 10.0  //自动推断为number类型
+let b: Double = 3.14
+let c: Int = 2
+
+typeof a == "number" //true
+typeof b == "Double" //true
+typeof c == "Int" //true
+
+// string
+let str = "hello uts"
+typeof str == "string" //true
+
+//boolean
+let ret = true
+typeof ret == "boolean" //true
+
+//function
+function fn(obj: string) {
+  if (obj instanceof String) {
+    // ...
+  }
+}
+
+typeof fn == "function" //true
+typeof Math.sign == "function" //true
+
+//object
+let obj = {
+	"x": 1,
+	"y": 2
+}
+
+typeof obj == "object" // true
+
+typeof null == "object" //true
+typeof [1, 2, 3] == "object" //true
+
+```
+
+**注意**
+`typeof` 运算符的参数只能是实例对象，不能是类型，如下操作是错误用法：
+```ts
+type MyType = {
+    name:string
+}
+typeof MyType   //报错
+```
+
+`typeof` 运算返回值一定是字符串，不会返回 TypeScript 类型，这与TypeScript存在差异：
+```ts
+type MyType = {
+    name:string
+}
+let my:MyType = {name:"abc"}
+type NewType = typeof my;   //报错
+```
+
+**特殊情况**
+在Android平台，将 number 类型赋值给 any 类型变量时，会根据数值将类型转变为实际平台专有数字类型，使用 typeof 获取此 any 类型变量将会返回实际平台专有数字类型。
+同样，将 number 类型保存在 UTSJSONObject 中，通过下标 `[""]` 获取对应的属性值类型为 any，使用 typeof 获取此属性值类型也将返回实际平台专有数字类型。
+
+```ts
+let a = 10.0    //自动推断为number类型
+let b: Double = 3.14
+let c: any = a
+let d: any = b
+
+typeof a == "number" //true
+typeof b == "Double" //true
+typeof d == "Double" //true
+
+// 在 iOS 平台上
+typeof c == "number" //true
+
+// Android平台 HBuilder X 4.44之后 
+typeof c == "number" //true
+
+
+```
+
+在Android平台，如果类型（或class）存在伴生对象（companion object）时，可以使用`typeof`运算符，返回的值为object，但不推荐这么使用
+
+```ts
+typeof Double   //在Android平台Double有伴生对象可以正常运行，实际值为object；在iOS平台报错
+```
+
+
+### instanceof实例类型判断@instanceof
+
+使用 `instanceof` 运算符执行运行时检查，以标识对象是否符合给定类型。
+
+| 类型                						 			 								| 结果             |
+| ------------------------------------------------------------------------------------ 	| ---------------- |
+| Boolean                						 		 								| 编译报错，不支持    |
+| Number     		  						 			 								| 编译报错，不支持    |
+| String       		  						 			 								| 编译报错，不支持    |
+| 平台专有数字类型: Int, Float, Double, Long ... 			 								| true or false    |
+| typeof 结果为 "object" 的类型(包含但不限于：Date, Array, Map, UTSJSONObject, 自定义类型)	| true or false    |
+
+> 特别说明：
+> HBuilderX3.9.0 使用 `instanceof` 对 Boolean, Number, String 类型的实例进行判断会编译报错，请使用 `typeof` 。在HBuilderX3.9.0之前版本可正常使用 `instanceof` 对上述类型的判断。
+
+
+```ts
+function fn(obj: any) {
+  if (obj instanceof Date) {
+    // ...
+  }
+}
+```
+
+包含[泛型](./generics.md)的类型，不能缺省泛型信息。如不需要判断具体的泛型类型，可以使用 `unknown` 表示任意泛型类型：
+
+```ts
+function fn(obj: any) {
+  if (obj instanceof Map<unknown, unknown>) {
+    // ...
+  }
+}
+```
+
+已经可以明确判断类型兼容性时无需使用 `instanceof` 在运行时进行判断，编译阶段会检查出这种情况会报错或者警告：
+
+```ts
+function fn(obj: Date) {
+  if (obj instanceof Date) {
+    // ...
+  }
+}
+```
+
+对于数字类型，`instanceof` 细化了判断逻辑，除了能判断是否是 number, 还能判断是否是 Int Float Double Int64 Long ... 等所有平台专有数字类型。
+
+```ts
+
+let a: Double = 3.14
+let b: Int = 2
+
+a instanceof Double //true
+b instanceof Int //true
+
+```
+
+### await
+> 3.93+ (Android)
+await 操作符用于等待一个 [Promise](./buildin-object-api/promise.md) 兑现并获取它兑现之后的值。它只能在[异步函数](./function.md#async)中使用。
+3.93 之前的版本请参考：[安卓 异步函数](../plugin/uts-for-android.md#thread-environment)
+
+> 4.11+ （iOS）
+在 iOS 平台上，HBuilderX 4.11 之前的版本，`uvue` 由于运行在 JS 环境中，可以正常使用 `Promise` `async` `await`, 但在 `uts 插件中` 不支持 `Promise`, 且对 `async` 和 `await` 的支持使用的是iOS 系统的异步函数，支持有限，且仅支持 iOS 13.0 及以上版本。参考文档：[iOS 异步函数](../plugin/uts-for-ios.md#async-method)
+从 HBuilderX 4.11 版本开始，iOS 平台 `uts 插件中` 支持了 Promise / async / await。可以在 uts 插件中正常使用相关功能。 注意从这个版本开始，iOS 平台上的 async / await 不再是 iOS 系统的 async / await，也不再有 iOS 13.0 的系统最低版本号限制。[iOS Promise](https://doc.dcloud.net.cn/uni-app-x/uts/buildin-object-api/promise.html)
+
+```ts
+async function test(): Promise<string> {
+  return await Promise.resolve('hello world');
+}
+```
+
+
+### 关键字列表
+
+- `as` 
+    * 用于类型转换。
+    * 为导入指定一个别名
+- `break` 
+    * 中止当前循环，switch语句，并把程序控制流转到紧接着被中止语句后面的语句。
+- `case` 
+    * 与 `switch` 搭配使用。
+- `catch` 
+    * 与 `try` 搭配使用，捕获程序异常。
+- `class` 
+    * 声明创建一个新类。
+- `const` 
+    * 声明一个常量，不能重新赋值。
+- `continue` 
+    * 声明终止当前循环或标记循环的当前迭代中的语句执行，并在下一次迭代时继续执行循环。
+- `debugger` 
+    * 调用任何可用的调试功能，例如设置断点。 如果没有调试功能可用，则此语句不起作用。
+- `default` 
+    * 与 `switch` 搭配，匹配不存在时做的事情，也可以用于 `export` 语句。
+- `delete` 
+    * 用于删除对象的某个属性；如果没有指向这个属性的引用，那它最终会被释放。（目前仅支持 `Javascript` 平台）
+- `do` 
+    * 创建一个执行指定语句的循环，直到condition值为 false。在执行statement 后检测condition，所以指定的statement至少执行一次。
+- `else` 
+    * 与 `if` 搭配使用。
+- `export` 
+    * 用于模块导出。
+- `extends` 
+    * 用于 `class` 继承。
+- `finally` 
+    * 与 `try-catch` 搭配使用。
+- `for` 
+    * 创建一个循环，它包含了三个可选的表达式，这三个表达式被包围在圆括号之中，使用分号分隔，后跟一个用于在循环中执行的语句（通常是一个块语句）。
+- `function` 
+    * 声明定义一个具有指定参数的函数。
+- `if` 
+    * 当指定条件为真，if 语句会执行一段语句。如果条件为假，则执行另一段语句。
+- `import` 
+    * 用于导入由另一个模块导出的绑定。
+- `in` 
+    * 可在 for 循环中迭代对象。
+- `instanceof` 
+    * 检测一个值具有指定类型。
+- `new` 
+    * 创建一个 `class` 实例。
+- `return` 
+    * 终止函数的执行，并返回一个指定的值给函数调用者。
+- `super` 
+    * 用于访问和调用一个对象的父对象上的函数。
+- `switch` 
+    * 评估一个表达式，将表达式的值与case子句匹配，并执行与该情况相关联的语句。
+- `this` 
+    * 引用当前接收者。
+- `throw` 
+    * 抛出一个异常。
+- `try` 
+    * 与 `catch` 搭配使用，捕获一个异常。
+- `typeof` 
+    * 返回一个字符串，表示未经计算的操作数的类型。
+- `var` 
+    * 声明一个变量，不建议使用。
+- `void` 
+    * 表示函数没有返回结果。
+- `while` 
+    * 在某个条件表达式为真的前提下，循环执行指定的一段代码，直到那个表达式不为真时结束循环。
+- `with` 
+    * 扩展一个语句的作用域链。（目前仅支持 `Javascript` 平台）
+- `yield` 
+    * 用来暂停和恢复一个生成器函数。（目前仅支持 `Javascript` 平台）
+- `enum`
+- `implements`
+- `interface`
+- `let`
+- `package`
+- `private`
+- `protected`
+- `public`
+- `static`
+- `await`
+- `abstract`
+- `boolean`
+- `byte`
+- `char`
+- `double`
+- `final`
+- `float`
+- `goto`
+- `int`
+- `long`
+- `native`
+- `short`
+- `synchronized`
+- `transient`
+- `volatile`

package/data/uni-app-x-docs/uts/literal.md

@@ -0,0 +1,252 @@
+## 字面量
+
+字面量是js的传统概念（[MDN的字面量文档](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Grammar_and_types#%E5%AD%97%E9%9D%A2%E9%87%8F)）
+
+字面量，即按字面意思给出的固定的值，而不是变量。
+
+比如 `5`、`"abc"`、`true`，都是字面量。
+
+字面量分：布尔字面量、数字字面量、字符串字面量、数组字面量、对象字面量、正则字面量。
+
+举例：
+
+```js
+let a = 1 // 这里的 1 ，就是字面量
+
+
+function test(score): boolean {
+	return (score>=60)
+}
+test(61) // 这里的 61，就是字面量
+
+let name = "zhangsan" // 字符串"zhangsan"是字面量
+
+let nameArray = ["zhangsan","lisi"] // 数组是字面量
+
+// 对象字面量
+let user = {
+	name: "zhangsan",
+	age: 12
+}
+
+const re = /ab+c/  // 正则字面量
+
+console.log("zhangsan".length) // 字面量会被自动推导类型，然后调用类型的方法和属性
+
+```
+
+平时js开发者很少会关心字面量的概念，但因为 uts 中涉及字面量自动类型推导，如果不学习，很难搞清楚这些字面量被自动推导成什么类型。
+
+比如`let a = 1/10`，a会被自动推导成什么类型？是Int、double、还是number？值是0还是0.1？
+
+下面我们来详细介绍每种字面量。
+
+
+### 布尔字面量
+
+布尔类型有两种字面量：`true` 和 `false`。
+
+Boolean字面量的自动类型推导简单而统一，全平台必然被自动推导为布尔类型。
+
+
+### 数字字面量
+
+数字字面量包括多种基数的整数字面量和以 10 为基数的浮点数字面量
+
+
+#### 整数字面量
+
+整数可以用十进制（基数为 10）、十六进制（基数为 16）、二进制（基数为 2）表示。
+
+- `十进制整数字面量`由一串数字序列组成，且没有前缀 0。如：`0`, `117`, `-345`
+
+- `十六进制整数`以 0x（或 0X）开头，可以包含数字（0-9）和字母 a~f 或 A~F。如：`0x1123`, `0x00111` , `-0xF1A7`
+
+- `二进制整数`以 0b（或 0B）开头，只能包含数字 0 和 1。如：`0b11`, `0b0011` , `-0b11`
+
+#### 浮点数字面量
+
+浮点数字面值可以有以下的组成部分：
+
+- 一个十进制整数，可以带正负号（即前缀“+”或“ - ”），
+- 小数点（“.”），
+- 小数部分（由一串十进制数表示），
+- 指数部分。
+
+指数部分以“e”或“E”开头，后面跟着一个整数，可以有正负号（即前缀“+”或“-”）。浮点数字面量至少有一位数字，而且必须带小数点或者“e”（大写“E”也可）。
+
+简言之，其语法是：
+
+```
+[(+|-)][digits][.digits][(E|e)[(+|-)]digits]
+```
+
+例如：
+
+```ts
+3.14
+-.23456789 // -0.23456789
+-3.12e+12  // -3.12*10^12
+.1e-23    // 0.1*10^(-23)=10^(-24)=1e-24
+```
+
+数字字面量的类型推导，[详见](data-type.md#autotypefornumber)
+
+### 字符串字面量@string
+
+字符串字面量是由双引号（"）对或单引号（'）括起来的零个或多个字符。字符串被限定在同种引号之间；也即，必须是成对单引号或成对双引号。下面的例子都是字符串字面值：
+
+```ts
+"foo"
+'bar'
+"1234"
+"one line \n another line"
+"John's cat"
+```
+
+你可以在字符串字面值上使用字符串对象的所有方法，你也能用对字符串字面值使用类似 String.length 的属性：
+
+```ts
+console.log("John's cat".length)
+// 将打印字符串中的字符个数（包括空格）
+// 结果为：10
+```
+
+#### 模板字符串
+
+模板字面量 是允许嵌入表达式的字符串字面量。你可以使用多行字符串和字符串插值功能。也被称为“模板字符串”。
+
+```ts
+// Basic literal string creation
+`In uts '\n' is a line-feed.`
+
+// Multiline strings
+`In uts this is
+ not legal.`
+
+// String interpolation
+var name = "Bob", time = "today";
+`Hello ${name}, how are you ${time}?`
+```
+
+#### 转义特殊字符
+
+|字符	|意思		|
+|--		|--			|
+|`\b`	|退格符		|
+|`\f`	|换页符		|
+|`\n`	|换行符		|
+|`\r`	|回车符		|
+|`\t`	|制表符		|
+|`\'`	|单引号		|
+|`\"`	|双引号		|
+|`\\`	|反斜杠字符	|
+
+
+### 数组字面量
+
+数组字面值是一个封闭在方括号对 (`[]`) 中的包含有零个或多个表达式的列表，其中每个表达式代表数组的一个元素。当你使用数组字面值创建一个数组时，该数组将会以指定的值作为其元素进行初始化，而其长度被设定为元素的个数。
+
+下面的示例用 3 个元素生成数组coffees，它的长度是 `3`。
+
+```js
+const coffees = ["French Roast", "Colombian", "Kona"]
+```
+
+数组字面值同时也是数组对象。
+
+
+### 对象字面量@object-literal
+
+在JS中，对象字面值是封闭在花括号对`{}`中的一个对象的零个或多个“属性名—值”对的（元素）列表。
+
+在uts中，对象字面量赋值给变量，默认会被推导为[UTSJSONObject](data-type.md#utsjsonobject)类型。
+
+```ts
+// 创建对象
+let userA = {
+	name: "zhangsan",
+	age: 12
+}
+console.log(userA)
+```
+
+对上述的userA进行typeof，得到的是object。进行 instanceof UTSJSONObject，得到的是true。也就是等同于：
+
+```ts
+// 创建对象
+let userA:UTSJSONObject = {
+	name: "zhangsan",
+	age: 12
+}
+console.log(userA)
+```
+
+注意花括号还有一个使用场景，被用于type时，是定义了一个自定义类型。下面的代码通过type关键字定义了一个 User类型，该自定义类型有2个属性，string类型的name和number类型的age。
+
+从 HBuilderX 4.31+ 起，编译器会根据上下文，自动推导对象字面量为type定义的类型。
+```ts
+type User = {
+	name:string
+	age:number
+}
+function printUser(user: User){
+	console.log(user)
+}
+printUser({name: 'zhangsan',age: 12} as User) // 通过对象字面量 as User 构造一个 type 定义的 User 对象
+printUser({name: 'zhangsan',age: 12}) // 从 HBuilderX 4.31+ 起，无需手动 as User
+
+```
+
+<!--
+#### 如何使用对象字面量
+
+在传统JS中，对象字面量的返回结果就是一个通用的object. 但是在 kotlin / swift 它是一个 支持下标访问，成员迭代等特性的看上去像是一个`object`的 `UTSJSONObject`实现。
+
+我们可以使用下标、成员名称直接访问:
+```js
+let arrayObj = JSON.parse('["a","b","c"]')
+console.log(arrayObj[0])
+
+let userA = {
+	name: "zhangsan",
+	age: 12
+}
+console.log(user['name'])
+```
+
+也可以将其转换为Map对象，再实现遍历
+```js
+let userA = {
+	name: "zhangsan",
+	age: 12
+}
+let userMap = userA.toMap()
+userMap.forEach(function(key:string,value:any){
+    console.log(key)
+    console.log(value)
+})
+```
+ -->
+### RegExp字面量
+
+正则表达式是字符被斜线围成的表达式。下面是一个正则表达式文字的一个例子。
+
+```ts
+const re = /ab+c/
+```
+
+### 字面量类型
+
+HBuilderX 3.91+ 支持使用数值字面量和字符串字面量用作类型注解，也支持联用多个相同类型的字面量以及 null 关键字。这些字面量类型仅用于方便编辑器的提示和校验，编译到目标语言后相当于 Number 或 String 类型。
+
+```ts
+type Str1 = 'a'
+type Str2 = 'a' | null
+type Str3 = 'a' | 'b'
+type Str4 = 'a' | 'b' | null
+type Num1 = 1
+type Num2 = 1 | null
+type Num3 = 1 | 2
+type Num4 = 1 | 2 | null
+```