完善文档

cfa35436 · wanganxp · 45322c3b · cfa35436 · cfa35436 · cfa35436
8 changed file
--- a/docs/component/button.md
+++ b/docs/component/button.md
-## button
+# button

 按钮。

@@ -49,16 +49,16 @@
 - **注1：``button-hover`` 默认为 ``{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}``**
 - ```open-type="launchApp"```时需要调起的APP接入微信OpenSDK[详见](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/launchApp.html)

-### size 有效值
+## size 有效值

 |值|说明|
 |:-|:-|
 |default|默认大小|
 |mini|小尺寸|

-button组件也支持style中通过css定义文字大小。
+button组件也支持style中通过css定义文字大小。[见下](#style)

-### type 有效值
+## type 有效值

 |值|说明|
 |:-|:-|
@@ -66,16 +66,16 @@ button组件也支持style中通过css定义文字大小。
 |default|白色|
 |warn|红色|

-button组件也支持style中通过css定义颜色。
+button组件也支持style中通过css定义颜色。[见下](#style)

-### form-type 有效值
+## form-type 有效值

 |值|说明|
 |:-|:-|
 |submit|提交表单|
 |reset|重置表单|

-### open-type 有效值
+## open-type 有效值

 |值|说明|平台差异说明|
 |:-|:-|:-|
@@ -108,7 +108,7 @@ button组件也支持style中通过css定义颜色。
 |watchLater|触发用户稍后再看|快手小程序 |
 |openProfile|触发打开用户主页|快手小程序 |

-#### feedback
+### feedback

 open-type 为 feedback时：

@@ -120,7 +120,30 @@ open-type 为 feedback时：

 - button组件支持style中通过css定义文字大小、颜色

-### button点击
+## button样式修改@style
+
+button组件属性中的size和type，属于预置样式，方便开发者使用。开发者也可以通过style和class来自定义样式。
+
+button虽然可以内嵌text组件，但不建议通过text组件来修改button样式，因为会导致hove-class不生效。尤其是uvue中样式不继承。建议直接在button组件的style或class属性编写样式。
+
+style和class的优先级，高于size和type属性。
+
+```html
+<template>
+	<button size="default" type="default" 
+	style="color:#ffffff;backgroundColor:#1AAD19;borderColor:#1AAD19" 
+	hover-class="is-hover">按钮</button>
+</template>
+<style>
+.is-hover {
+	color: rgba(255, 255, 255, 0.6);
+	background-color: #179b16;
+	border-color: #179b16;
+  }
+</style>
+```
+
+## button点击

 button 组件的点击遵循 vue 标准的 @click事件。

@@ -153,7 +176,7 @@ button 组件没有 url 属性，如果要跳转页面，可以在@click中编
 - 支付宝小程序平台，获取用户手机号时，建议先通过条件编译的方式，调用支付宝原生API，[参考](https://docs.alipay.com/mini/api/getphonenumber)


-### 示例
+## 示例

 [查看演示](https://hellouniapp.dcloud.net.cn/pages/component/button/button)


--- a/docs/uni-app-x/_sidebar.md
+++ b/docs/uni-app-x/_sidebar.md
 * [概述](README.md)
-* [manifest.json](manifest.md)
 * [开发注意](codegap.md)
-* [性能](performance.md)
 * [编译器](compiler/README.md)
-* [UVUE DOM](dom.md)
+* [manifest.json](manifest.md)
+* 组件
+  * [animation-view](component/animation-view.md)
+  * [button](component/button.md)
+  * [checkbox](component/checkbox.md)
+  * [image](component/image.md)
+  * [input](component/input.md)
+  * [list-view](component/list-view.md)
+  * [picker-view](component/picker-view.md)
+  * [progress](component/progress.md)
+  * [radio](component/radio.md)
+  * [rich-text](component/rich-text.md)
+  * [scroll-view](component/scroll-view.md)
+  * [slider](component/slider.md)
+  * [swiper](component/swiper.md)
+  * [switch](component/switch.md)
+  * [text](component/text.md)
+  * [textarea](component/textarea.md)
+  * [video](component/video.md)
+  * [view](component/view.md)
+* [API](api.md)
 * CSS
-  * [概述](css/README.md)
+  * [CSS概述](css/README.md)
  * [align-content](css/align-content.md)
  * [align-items](css/align-items.md)
  * [background](css/background.md)
@@ -89,27 +107,13 @@
  * [text-decoration-thickness](css/text-decoration-thickness.md)
  * [visibility](css/visibility.md)
  * [lines](css/lines.md)
-* [API](api.md)
-* 组件
-  * [animation-view](component/animation-view.md)
-  * [button](component/button.md)
-  * [checkbox](component/checkbox.md)
-  * [image](component/image.md)
-  * [input](component/input.md)
-  * [list-view](component/list-view.md)
-  * [picker-view](component/picker-view.md)
-  * [progress](component/progress.md)
-  * [radio](component/radio.md)
-  * [rich-text](component/rich-text.md)
-  * [scroll-view](component/scroll-view.md)
-  * [slider](component/slider.md)
-  * [swiper](component/swiper.md)
-  * [switch](component/switch.md)
-  * [text](component/text.md)
-  * [textarea](component/textarea.md)
-  * [video](component/video.md)
-  * [view](component/view.md)
-* [事件](event.md)
+* UVUE DOM
+  * [DOM概述](dom.md)
+  * [INode](dom/inode.md)  
+  * [CSSStyleDeclaration](dom/cssstyledeclaration.md)  
+  * [DrawableContext](dom/drawablecontext.md)  
+  * [事件系统](dom/event.md)
+* [性能](performance.md)
 <!-- * [新建项目]()
  * [1. 通过 HBuilderX 可视化界面](quickstart-hx.md)
 * [运行和调试]()
@@ -121,4 +125,4 @@
 * [API]()
 * [编译器]()
 * [质量]()
-* [性能]() -->
+-->
--- a/docs/uni-app-x/codegap.md
+++ b/docs/uni-app-x/codegap.md
@@ -38,15 +38,15 @@ data里`:`的用途是赋值，无法通过`:`定义类型，所以data的数据
 	export default {
 		data() {
 			const date = new Date() //自动推导类型为Date
-			const v = 1;
+			const v = 1; //自动推导为number
 			return {
+				buttonEnable: false,
 				s1 : "hello", // 根据字面量推导为string
 				n1 : 0 as number, // 这里其实可以根据字面量自动推导，as number写不写都行
 				n2, // 不合法，必须指定类型。真实运行时请删掉本行
 				n3 as number, // 不合法，uts不支持undefined，必须初始化。真实运行时请删掉本行
 				n4 : null as number | null // 合法。定义为可为null的数字，初始值是null，但在使用n4前必须为其赋值数字
 				year: date.getFullYear() as number, // 在data里，目前无法通过变量类型推导data项的类型，需使用 as 显式声明
-				buttonEnable: false,
 				t: ``, // 模板字面量，推导为 string
 				o: { id: 1, name:"DCloud" }, // 对象字面量，推导为 UTSJSONObject，注意：访问 data 中定义的UTSJSONObject属性时，需要使用索引访问，如 this.o["id"]
 				an: [1, 2], // 数组字面量，如果元素均为纯数字字面量，则推导为 Array<number>
@@ -79,11 +79,6 @@ data里`:`的用途是赋值，无法通过`:`定义类型，所以data的数据
 </style>
 ```

-## 不同的函数定义方式有不同的限制
-
-* 函数声明方式不支持[作为值传递](../uts/function.md#作为值传递)
-* 函数表达式方式不支持[默认参数](../uts/function.md#默认参数)
-
 ## 模板函数 event 参数需显式指定类型

 ```html
@@ -95,6 +90,11 @@ data里`:`的用途是赋值，无法通过`:`定义类型，所以data的数据

 JSON在强类型语言中使用时，不能像js那样随意。这部分内容较长，[详见](../uts/data-type.md#JSON)

+## 不同的函数定义方式有不同的限制
+
+* 函数声明方式不支持[作为值传递](../uts/function.md#作为值传递)
+* 函数表达式方式不支持[默认参数](../uts/function.md#默认参数)
+
 ## 作用域插槽数据类型

 作用域插槽需在组件中指定插槽数据类型

--- a/docs/uni-app-x/dom.md
+++ b/docs/uni-app-x/dom.md
@@ -24,6 +24,8 @@ DOM 是页面元素内容的结构数据。DOM 模型用一个逻辑树来表示
 2. Draw API

 	Android和iOS的原生view，有一些底层的高性能绘制能力，这些API的调用，需要先获取到INode对象，然后再调用其方法。
+
+在[性能](performance.md)章节，对这2个场景有详细的阐述。

 ## 获取DOM元素对象@getDomNode  

@@ -36,7 +38,7 @@ app-uvue页面中可以通过 vue 框架中的组件实例对象 [$refs](https:/
 </view>
 ```

-在页面生命周期 `onReady` 中（太早组件可能没有创建），通过 `$refs` 获取。如果长期使用，可以保存在vue的 data 中。
+在页面`onReady` 后（太早组件可能没有创建），通过 `$refs` 获取。如果长期使用，可以保存在vue的 data 中。
 ```ts
 export default {
 	data() {
@@ -108,8 +110,3 @@ this.myNode?.style?.setProperty('background-color', 'red');

 以上例子仅为演示DOM API的使用，实际上点击按钮修改背景色这种简单场景，使用数据绑定更简单，class绑定到一个data上，动态修改data即可。

-## DOM接口  
- [INode](dom/inode.md)  
- [CSSStyleDeclaration](dom/cssstyledeclaration.md)  
- [DrawableContext](dom/drawablecontext.md)  
-
--- a/docs/uni-app-x/event.md
+++ b/docs/uni-app-x/event.md
-## UVUE Event
+## Event事件系统

-uni-app x 默认支持事件冒泡
+uvue 支持事件冒泡。

 ### 简述

 DOM事件主要有三个阶段：捕获阶段、目标阶段和冒泡阶段。

-以点击事件为例，当触发点击时，首先从根节点逐级向下分发，直到监听点击事件的节点为止（捕获阶段）；然后事件到达当前节点并触发点击事件（目标阶段）；接着继续向上逐级触发父节点的点击事件，直到根节点为止（冒泡阶段）。
+以点击事件为例，当触发点击时，
+1. 首先从根节点逐级向下分发，直到监听点击事件的节点为止（捕获阶段）；
+2. 然后事件到达当前节点并触发点击事件（目标阶段）；
+3. 接着继续向上逐级触发父节点的点击事件，直到根节点为止（冒泡阶段）。

 注意，虽然有3个阶段，但第2个阶段（“目标阶段”：事件到达了元素）并没有单独处理：捕获和冒泡阶段的处理程序都会在该阶段触发。

 我们一般使用默认的事件注册机制，将事件注册到冒泡阶段，相对来说，大多数处理情况都在冒泡阶段。

-uni-app x 目前暂时不支持事件的捕获阶段。
+uvue 目前暂时不支持事件的捕获阶段。

 ### 阻止冒泡


--- a/docs/uni-app-x/readme.md
+++ b/docs/uni-app-x/readme.md
@@ -231,7 +231,7 @@ uni-app js版的“App原生语言插件”无法在 uni-app x 中运行。

 前端插件里，可兼容uts前端插件、可兼容uvue组件，即script是uts，style符合uvue的css。

-# 自动化测试
+## 自动化测试
 uni-app x 从源头重视产品质量，第一个版本就支持自动化测试。并为uni-app x产品编写了数万行自动化测试例代码。

 uni-app x 的自动化测试方案和 uni-app js版相同，自动化测试脚本使用js编写（注意不是uts）。整个自动化测试环境，运行在电脑端。
@@ -240,7 +240,7 @@ uni-app x 的自动化测试方案和 uni-app js版相同，自动化测试脚

 uni-app 的自动化测试教程详见：[https://uniapp.dcloud.net.cn/worktile/auto/quick-start.html](https://uniapp.dcloud.net.cn/worktile/auto/quick-start.html)

-# 一期范围
+## 一期范围

 除上述文档中声明已经完成的，还有如下需要注意：

@@ -252,9 +252,9 @@ uni-app 的自动化测试教程详见：[https://uniapp.dcloud.net.cn/worktile/

 欢迎去[需求墙](https://vote.dcloud.net.cn/)投票，告诉我们你的需求优先级。

-# 历史老项目兼容指南
+## 历史老项目兼容指南

-## uni-app js版老项目迁移指南
+### uni-app js版老项目迁移指南
 1. 首先检查你的老项目里使用的uni组件、api、三方插件、三方库，在uni-app x上是否支持。
 2. 对于不支持的，需要自己写uni-app x的插件或去插件市场找替代兼容插件。如果写调用原生的uts代码，需要你了解原生的api。
 3. 对于css，如果你之前使用nvue的css，那边迁移到uni-app x在样式上改动很小。如果之前是vue的css，那么需要改为flex布局，以及仅使用uvue支持的css来布局界面。
@@ -265,7 +265,7 @@ uni-app 的自动化测试教程详见：[https://uniapp.dcloud.net.cn/worktile/

 官方近期会提供把[uni小程序sdk](https://nativesupport.dcloud.net.cn/#)集成到uni-app x的方案。届时你的uni-app js版老项目可以作为uni-app x新项目的一个小程序来使用。

-## 原生/rn/flutter页面兼容指南
+### 原生/rn/flutter页面兼容指南

 之前已经有原生/rn/flutter页面，希望渐进式的迁移到uni-app x架构，该怎么搞？

@@ -273,7 +273,7 @@ uni-app x 毕竟是原生应用，内嵌flutter、rn这些没有任何问题，

 至于把 uni-app x 作为一个sdk内嵌到其他原生应用中，还在评估中。

-# FAQ
+## FAQ
 - uni-app x 支持uvue页面和vue页面混写吗？
 仅支持uvue页面。后期考虑中。历史vue页面也可以通过 uni小程序sdk 嵌入到uni-app x中。


--- a/docs/uts/data-type.md
+++ b/docs/uts/data-type.md
@@ -11,11 +11,11 @@
 比如 `"abc"`和`"你好"`，都属于字符串string，所有string类型有相同的方法、属性，比如`.length`属性获取字符串长度。

 UTS 的类型有：
- 基础类型：boolean、number、string、any、null，都是小写，前3个typeof返回类型名称，null的typeof是object，any的typeof是当时值的类型。
+- 基础类型：boolean、number、string、any、null，都是小写，前3个typeof返回类型名称，null的typeof是object，any的typeof是运行时值的类型。
 - 对象类型：Date、Array、Map、Set、USTJSONObject，首字母大写，typeof返回"object"，判断准确类型需使用 instanceof 
 - 使用 type 来自定义类型
 - 特殊类型：function、class、error。
- 平台专有类型：Int、Float、Double、NSString、kotlin.Array...，typeof返回"object"，判断准确类型需使用 instanceof 
+- 平台专有类型：Int、Float、Double、NSString、kotlin.Array...

 除了特殊类型，其他类型都可以在变量后面通过`:`加类型名称来给这个变量声明类型。

@@ -61,6 +61,11 @@ let d = 3.14159         //注意：目前版本推导d为float类型，新版本
 1. 在 kotlin 和 swift 中，调用系统API或三方SDK的入参或返回值的类型，强制约定了平台专有数字类型。比如入参要求传入 Int，那么传入 number 会报错。比如方法返回了一个 Int，使用 number 类型的变量去接收，也会报错。
 2. number 作为泛数字，性能还是弱于Int。在普通计算中无法体现出差异，但在千万次运算后，累计会产生毫秒级速度差异。

+请注意：
+number本身的使用很简单，但混入了平台专有数字类型后，会引出很多细节需要学习。
+- 如果您不调用原生API，初学uts时建议跳过本节，直接往下看string类型。
+- 如果您是插件作者，那请务必仔细阅读本章节。
+
 #### Kotlin 专有数字类型 @Kotlin

 |类型名称|长度  |最小值       |最大值          |描述|
@@ -103,12 +108,12 @@ let d = 3.14159         //注意：目前版本推导d为float类型，新版本
 |Double  	|64bit |2.2250738585072014E-308     |1.7976931348623157E308         	|双精度浮点型|


- 注意：
-	+ Swift 中 Int 类型是根据平台动态的，在 32 位设备下等同于 Int32, 在64位设备下等同于 Int64。因此建议整型使用 Int, 除非必要，且在保证不会溢出的场景下才使用 Int32、Int64。
-	+ 同样，Swift 中的 UInt 类型也是根据平台动态的，在 32 位设备下等同于 UInt32, 在64位设备下等同于 UInt64。建议使用 UInt，非必要不使用 UInt32、UInt64。
-	+ Float16 在 iOS14.0 及以上系统上才能使用，使用时注意做系统版本号判断。
-	+ Float32 是 Float 的 typealise, 两者等价。
-	+ Float64 是 Double 的 typealise, 两者等价。
+**注意：**
+- Swift 中 Int 类型是根据平台动态的，在 32 位设备下等同于 Int32, 在64位设备下等同于 Int64。因此建议整型使用 Int, 除非必要，且在保证不会溢出的场景下才使用 Int32、Int64。
+- 同样，Swift 中的 UInt 类型也是根据平台动态的，在 32 位设备下等同于 UInt32, 在64位设备下等同于 UInt64。建议使用 UInt，非必要不使用 UInt32、UInt64。
+- Float16 在 iOS14.0 及以上系统上才能使用，使用时注意做系统版本号判断。[参考](../plugin/uts-uni-api.md#设备)
+- Float32 是 Float 的 typealise, 两者等价。
+- Float64 是 Double 的 typealise, 两者等价。

 #### 专有数字类型的定义方式


--- a/docs/uts/operator.md
+++ b/docs/uts/operator.md
@@ -242,7 +242,7 @@ uts 中比较运算符在大部分场景下和 ts 中的行为一致，但是在
 | Array  == Array (!= 行为相同)        | [1] == [1]	 							   | 结果为 false                   |结果为 true,数组类型相同，元素相同就为true     |
 | Array  === Array (!=== 行为相同)  	| [1] === [1] 									| 结果为 false                  |编译失败，不能比较	          			  |

-## 展开语法
+## 展开语法...

 > HBuilderX 3.9+

@@ -272,17 +272,36 @@ this.dataList.push(...res.data)

 从某种意义上说，剩余语法与展开语法是相反的：展开语法将数组展开为其中的各个元素，而剩余语法则是将多个元素收集起来并“凝聚”为单个元素。请参考：[剩余参数](./function.md#剩余参数)。

-## 类型断言
+## 类型断言as@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

-a as string
+// 对象字面量也可以as为USTJSONObject或某个type
+{"id":1} as USTJSONObject
+
+type t = {
+	id:number
+}
+{"id":1} as t
 ```

-只允许将类型转换为具体或更不具体的类型，不能强制转换两个不可能兼容的类型：
+只允许将类型as为具体或更不具体的类型，不能强制转换两个不可能兼容的类型：

 ```ts
 const a: string = 'a'
@@ -292,20 +311,20 @@ a as string // 正确
 a as number // 错误
 ```

-类型断言会在运行时进行，如果无法强制转换，类型断言运算符会引发异常：
+USTJSONObject和type不相容，无法互相as。应该在初始的字面量或JSON.parse环节就决定好类型。
+
+类型断言会在运行时进行，如果无法强制转换，类型断言运算符as会引发异常：

 ```ts
 const a: string | null = 'a'
-
 a as string // 正常

 a = null
-
 a as string ｜ null // 正常
-
 a as string // 异常
 ```

+
 ## 实例类型判断

 使用 `instanceof` 运算符执行运行时检查，以标识对象是否符合给定类型。