diff --git a/docs/plugin/uts-component.md b/docs/plugin/uts-component.md
index c3c5e4bdf1f70ee3aa09c9671e1656747f6c08cc..7036d269ccdd86183ca066c1c36f27dbf06d0453 100644
--- a/docs/plugin/uts-component.md
+++ b/docs/plugin/uts-component.md
@@ -17,140 +17,319 @@
### 2.1 UTS组件简介
-组件是一种独立,可复用的UI单元,方便单独封装和承担一定的代码逻辑,组件化有利于降低项目的工程复杂度,提升可维护性
+UTS组件,即:使用UTS语言在uni平台进行组件开发的技术。 [关于UTS](https://uniapp.dcloud.net.cn/plugin/uts-plugin.html)
-UTS组件,即:使用UTS语言在uni平台进行组件开发的技术。 [UTS的更多介绍](https://uniapp.dcloud.net.cn/plugin/uts-plugin.html)
+组件是一种独立,可复用的UI单元,用于单独封装和承担一定的代码逻辑,组件化可以降低项目的工程复杂度,提升可维护性
-UTS组件约定上采用了类Vue组件的语法,[Vue组件的更多介绍](https://cn.vuejs.org/guide/essentials/component-basics.html),但是具体的约定上会有定制,具体参考第四章节。
+UTS组件整体采用了类Vue组件的语法,[关于Vue组件](https://cn.vuejs.org/guide/essentials/component-basics.html),但是具体的函数上会有定制,具体参考第四章节。
-### 2.2 UTS组件和Vue组件差异
-UTS组件,与Vue组件区别在于,它秉承了UTS的跨平台特性,统一的UTS语法,各终端不同的本地产出物。
+### 2.2 UTS组件优势
+
+UTS组件的优势在于,它秉承了UTS的跨平台特性,统一的UTS语法,各终端不同的本地产出物。
在Android平台会被编译为会被渲染为Android原生View实例,IOS或其他终端平台也是如此。
-| |Vue组件 |uts插件|
-|:------ |:------- |:--------|
-|开发语言 |js/ts |uts|
-|组件载体 |WebView内部标签 |编译时生成原生View对象|
+| |Vue组件 |uts组件 |uni原生组件 |
+|:------ |:------- |:-------- |:-------- |
+|开发语言 |js/ts |uts |java/object-c |
+|组件载体 |WebView内部标签 |系统原生View对象 |系统原生View对象 |
-## 3 如何开发组件-举个例子
+## 3 如何开发组件
-以lottie动画组件为例,本章节提到全部示例源码可以在Hello UTS 中找到
+>本章节提到全部示例源码可以在Hello UTS 中找到
#### 3.1 创建组件
UTS组件的创建过程与UTS插件一样。
-选中 项目目录/uni_modules 右键 新建组件
+选中 项目目录/uni_modules 右键 新建组件 TODO
-#### 3.2 目录结构
+![目录结构](https://native-res.dcloud.net.cn/images/uts/component/image1.png)
-![目录结构](https://native-res.dcloud.net.cn/images/uts/component/image1.png)
+组件的入口文件是index.vue,具体规范会在下一个章节介绍
+
+另外 组件允许存在入口文件:index.uts 对外提供函数能力,具体参考 UTS 插件介绍
-入口文件是index.vue
#### 3.2 示例代码简介
+
+下面是一个组件源码 index.vue 完整示例:
+
```uts
- //原生提供以下属性或方法的实现
export default {
/**
* 组件名称,也就是开发者使用的标签
*/
name: "xxx-view",
/**
- * 组件涉及的事件声明
+ * 组件涉及的事件声明,只有声明过的事件,才能被正常发送
*/
emits: ['bindended'],
+ /**
+ * 属性声明,组件的使用者会传递这些属性值到组件
+ */
props: {
/**
- * 属性A:propA 需要声明属性类型和默认值
+ * 字符串类型 属性:path 默认值:""
*/
- "propA": {
+ "path": {
type: String,
default: ""
},
},
+ /**
+ * 组件内部变量声明
+ */
data() {
return {
}
},
+ /**
+ * 属性变化监听器实现
+ */
watch: {
- "propA": {
- handler(newPropA: string) {
- // 这里处理属性newPropA 的更新逻辑
+
+ "path": {
+ handler(newPath: string) {
+ // 这里处理属性newPath 的更新逻辑
},
- immediate: false //创建时是否通过此方法更新属性,默认值为false
+ //创建时是否通过此方法更新属性,默认值为false
+ immediate: false
},
},
- // 规则:如果没有配置expose,则methods中的方法均对外暴露,如果配置了expose,则以expose的配置为准向外暴露
- // 只有 `publicMethod` 在实例上可用
+
+ /**
+ * 规则:如果没有配置expose,则methods中的方法均对外暴露,如果配置了expose,则以expose的配置为准向外暴露
+ * ['publicMethod'] 含义为:只有 `publicMethod` 在实例上可用
+ */
expose: ['publicMethod'],
methods: {
+ /**
+ * 对外公开的组件方法
+ */
publicMethod() {
doSth(paramA: string) {
// 这是组件的自定义方法
}
},
+ /**
+ * 内部使用的组件方法
+ */
privateMethod() {
- doSth(paramA: string) {
+ doSthInner(paramA: string) {
// 这是组件的自定义方法
}
}
},
- created() { //创建组件,替换created
+
+ /**
+ * 组件被创建,组件第一个生命周期,
+ * 在内存中被占用的时候被调用,开发者可以在这里执行一些需要提前执行的初始化逻辑
+ * [可选实现]
+ */
+ created() {
},
- NVBeforeLoad() { //组件将要创建,对应前端beforeMount
- //可选实现,这里可以提前做一些操作
+ /**
+ * 对应平台的view载体即将被创建,对应前端beforeMount
+ * [可选实现]
+ */
+ NVBeforeLoad() {
+
},
- NVLoad(): View { //创建原生View,必须定义返回值类型(Android需要明确知道View类型,需特殊校验)
- //必须实现
+ /**
+ * 创建原生View,必须定义返回值类型
+ * 开发者需要重点实现这个函数,声明原生组件被创建出来的过程,以及最终生成的原生组件类型
+ * (Android需要明确知道View类型,需特殊校验)
+ * todo 补充IOS平台限制
+ * [必须实现]
+ */
+ NVLoad(): View {
let viewInstance = new View($androidContext)
return aView
},
-
- NVLoaded() { //原生View已创建
- //可选实现,这里可以做后续操作
+ /**
+ * 原生View已创建
+ * [可选实现]
+ */
+ NVLoaded() {
+
},
- NVLayouted() { //原生View布局完成
- //可选实现,这里可以做布局后续操作
+ /**
+ * 原生View布局完成
+ * [可选实现]
+ */
+ NVLayouted() {
+
},
- NVBeforeUnload() { //原生View将释放
- //可选实现,这里可以做释放View之前的操作
+ /**
+ * 原生View将释放
+ * [可选实现]
+ */
+ NVBeforeUnload() {
},
- NVUnloaded() { //原生View已释放
- //可选实现,这里可以做释放View之后的操作
+ /**
+ * 原生View已释放,这里可以做释放View之后的操作
+ * [可选实现]
+ */
+ NVUnloaded() {
+
},
- unmounted() { //组件销毁
- //可选实现
+ /**
+ * 组件销毁
+ * [可选实现]
+ */
+ unmounted() {
}
+ /**
+ * 自定组件布局尺寸
+ * [可选实现]
+ */
+ doMeasure(size: UTSSize): UTSSize {
+ size.width = 120.0.toFloat()
+ size.height = 800.0.toFloat()
+ return size
+ }
}
```
-#### 3.3 组件开发关键函数
+index.vue可以分为以下几类:
++ 配置:
-首先开发者需要重点关注的是 NVLoad 函数,开发者需要在这个函数内实现View载体的具体实现
+ name:组件的使用标签,可以省略,若省略则默认为组件名称
+
+ emits:组件允许的消息事件名称,如果没有组件消息,不需要配置
++ 属性:
+
+ props:需要由组件的使用者提供,比如一个Image组件,会需要一个path属性作为图像路径来源
+
+ watch:属性的监听实现,用来监听属性数据更新。
+
++ 数据:
+
+ data:组件内部数据定义,用于组件内部逻辑处理,不对外暴露
+
++ 方法:
+
+ methods:组件方法定义,可以通过与expose组合使用,区分对内方法和对外方法
+
+ expose:与methods 字段配合使用,用以区分组件对内方法和对外方法
+
+
++ 生命周期:
+
+ 组件需要重点处理 内存创建/销毁,View载体创建/销毁 过程中的资源管理,具体参考3.4章节
+
++ 内置对象:
+
+ 为了方便组件开发者,UTS组件内置了部分变量与函数,具体参考3.5章节
+
+
+#### 3.4 生命周期
+
+组件开发者需要重点关注生命周期
+
+
+![生命周期](https://native-res.dcloud.net.cn/images/uts/component/image2.png)
+
++ created:
+
+组件被创建,组件第一个生命周期,在内存中被占用的时候被调用,开发者可以在这里执行一些需要提前执行的初始化逻辑
+
++ NVBeforeLoad:
+
+组件对应平台的view载体 即将被创建
+
++ NVLoad:
+
+[必须实现]
+
+组件 view载体的创建实现
+
+开发者需要重点实现这个函数,声明原生组件被创建出来的过程,以及最终生成的原生组件类型
+
+
++ NVLayouted:
+
+组件对应平台的view载体,布局完成
+
++ NVBeforeUnload:
+
+view载体即将被卸载
+
+资源回收
+
++ NVUnloaded:
+
+view载体已经被卸载
+
+资源回收
+
++ unmounted:
+
+view载体被回收
+
+资源回收
+
++ doMeasure:
+
+doMeasure 用于告诉排版系统,组件自身需要的宽高,具体的调用时机由排版系统决定。
+
+一般情况下,组件的宽高应该是由终端系统的排版引擎决定,组件开发者不需要实现此函数。
+
+但是部分场景下,组件开发者需要自己维护宽高,则需要开发者重写此函数
+
+
+
+#### 3.5 内置对象和函数
+
+为了方便组件开发者使用,UTS 组件内部内置了下列对象:
+
+|变量名 |类型 |简介 |平台限制 |
+|:------- |:-------- |:-------- |:--- |
+|$el |对象 |当前View实例对象 |全部平台 |
+|$androidContext|对象 |当前组件上下文 |仅android |
+|emit("event") |函数 |发送已注册的事件 |全部平台 |
+
+
+
+
+
+
+
+
+## 4 使用组件
+
+
+#### 4.1 注意事项:
+
+1. 需要自定义基座方能使用
+
+2 不需要引用,直接使用自定义标签
+
+```js
+
+
```
-let viewInstance = new View($androidContext)
-return aView
-```
-除了组件的基本功能外,组件还以属性和方法的形式为使用者提供额外的功能
+#### 4.2 属性
+
+
组件的开发者,声明属性
```
@@ -171,6 +350,9 @@ props: {
```
+#### 4.3 方法
+
+
组件的开发者,定义公开方法
```
@@ -186,71 +368,22 @@ methods: {
```js
// 布局代码
-
+
// 调用代码
- this.$refs["xxxView"].doSth('字符串参数')
-```
-
-#### 3.4 使用组件
-
-1 需要自定义基座方能使用
-
-2 不需要特殊引用,直接使用自定义
-
-```js
-
-
+ this.$refs["customTag"].doSth('参数')
```
+## 5 快速体验
-3 调用组件的方法
-
-
-参考Hello UTS ,源码路径:
-
-~\pages\SDKIntegration\Lottie\index.nvue
-
-
-## 4 组件的生命周期
-
-
-![生命周期](https://native-res.dcloud.net.cn/images/uts/component/image2.png)
-
-+ created:
-
-组件被创建,组件第一个生命周期,在内存中被占用的时候被调用,开发者可以在这里执行一些需要提前执行的初始化逻辑
-
-+ NVBeforeLoad:
-
-组件对应平台的view载体 即将被创建
-
-+ NVLoad:
-
-组件对应平台的view载体 正在被创建,开发者需要重点实现这个函数,声明原生组件被创建出来的过程,以及最终生成的原生组件类型
-
-+ NVLayouted:
-
-组件对应平台的view载体,布局完成
-
-+ NVBeforeUnload:
-
-view载体即将被卸载
-
-资源回收
-
-+ NVUnloaded:
-
-view载体已经被卸载
+开发者可以使用[Hello UTS](https://gitcode.net/dcloud/hello-uts) 快速体验UTS 组件开发
-资源回收
+使用HX 3.6.16 版本 - 选择 Hello UTS - 自定义基座包。
-+ unmounted:
+查看:三方SDK-Lottie动画示例,对应的源码实现:~/uni_modules/uts-animation-view
-view载体被回收
-资源回收
## 常见问题