diff --git a/docs/plugin/uts-component.md b/docs/plugin/uts-component.md index 421288130b09b008b0fc7d4e62bce31956582fd1..d8abbe9c993dcbf24bf3f005cc724b456934874d 100644 --- a/docs/plugin/uts-component.md +++ b/docs/plugin/uts-component.md @@ -44,27 +44,12 @@ UTS组件的优势在于,它秉承了UTS的跨平台特性,统一的UTS语 为了降低前端开发者的开发门槛,UTS组件采用了类Vue组件的语法,[关于Vue组件](https://cn.vuejs.org/guide/essentials/component-basics.html),但是具体的函数上会有定制,我们会在下一个章节详细介绍 -## 如何开发UTS组件 - - -#### 创建UTS组件 - -HBuilderX 3.6.16 版本之后,支持一键创建 - -选中 项目目录/uni_modules 右键 新建组件 - -TODO - -至此,我们已经得到了一个最基本的UTS插件目录,下个章节我们介绍其中各文件的作用 +## UTS组件结构解析 #### UTS组件目录结构 -![目录结构](https://native-res.dcloud.net.cn/images/uts/component/image1.png) - - -
 	
 ┌─common                          // 可跨端公用的uts代码。推荐,不强制
@@ -104,152 +89,176 @@ TODO
 
-如上所示,UTS组件的目录结构与UTS插件基本相同。 +如上所示,UTS组件的目录结构与UTS插件基本相同 唯一的差别在于,UTS组件入口文件有两个,一个必选的index.vue 组件入口,和一个可选的index.uts 函数能力入口 +用户如果在开发组件的同时,存在一些与组件无关的能力需要对外暴露,可以在index.uts中进行实现 -用户如果在开发组件的同时,存在一些与组件无关的能力需要对外暴露,则可以同时开发两个入口。 - - -大多数情况下,组件其实我们只需要开发一个index.vue 即可,关于index.vue 的具体规范会在下一个章节介绍 +大多数情况下,我们只需要开发一个index.vue 即可,如果存在多个组件,可以新建多个 *.vue文件 +关于index.vue 的源码规范会在下一个章节介绍 -#### UTS组件 代码格式解析 +#### UTS组件源码解析 下面是一个组件源码 index.vue 完整示例: ```ts - export default { + + + ``` + index.vue可以分为以下几类: + 配置: @@ -301,77 +320,205 @@ index.vue可以分为以下几类: 组件开发者需要重点关注生命周期 +```mermaid +graph TD; + Create-->NVBeforeLoad; + subgraph View生命周期 + NVBeforeLoad-->NVLoad; + NVLoad-->NVLoaded; + NVLoaded-->NVLayouted; + NVLayouted-->NVBeforeUnload; + end + NVBeforeUnload-->unmounted; + +``` -![生命周期](https://native-res.dcloud.net.cn/images/uts/component/image2.png) +|函数名 |描述 |建议行为 |是否可选 | +|:---- |:--- |:--- |:--- | +|created |组件在内存中被创建 |开发者可以在这里执行一些需要最早执行的初始化逻辑|可选| +|NVBeforeLoad |组件对应平台的view载体,即将被创建|开发者可以在这里执行一些需要在View创建前初始化的逻辑|可选| +|NVLoad |组件view载体正在被创建实现|开发者需要重点实现这个函数,声明原生组件被创建出来的过程,以及最终生成的原生组件类型|必须实现| +|NVLayouted |组件对应平台的view载体已布局结束 |需要在view布局结束后执行的逻辑 |可选| +|NVBeforeUnload |view载体即将被卸载 |View卸载前,需要回收资源的逻辑 |可选| +|NVUnloaded |view载体已经被卸载 |View卸载后,需要回收资源的逻辑 |可选| +|unmounted |组件在内存被销毁 |资源回收逻辑 |可选| -+ created: -组件被创建,组件第一个生命周期,在内存中被占用的时候被调用,开发者可以在这里执行一些需要提前执行的初始化逻辑 +除上述生命周期外,还存在下列可选周期函数: -+ NVBeforeLoad: ++ doMeasure: -组件对应平台的view载体 即将被创建 +doMeasure 用于告诉排版系统,组件自身需要的宽高,具体的调用时机由排版系统决定。 -+ NVLoad: +一般情况下,组件的宽高应该是由终端系统的排版引擎决定,组件开发者不需要实现此函数。 -[必须实现] +但是部分场景下,组件开发者需要自己维护宽高,则需要开发者重写此函数 -组件 view载体的创建实现 -开发者需要重点实现这个函数,声明原生组件被创建出来的过程,以及最终生成的原生组件类型 +#### 内置对象和函数 -+ NVLayouted: +为了方便组件开发者使用,UTS 组件内部内置了下列对象: -组件对应平台的view载体,布局完成 +|变量名 |类型 |简介 |平台限制 |方法&属性 | +|:------- |:-------- |:-------- |:--- |:--- | +|$el |对象 |当前View实例对象 |全部平台 |开发者在NVLoad返回的对象类型| +|$androidContext|对象 |当前组件上下文 |仅android |android平台对应Context对象| +|emit("event") |函数 |发送已注册的事件 |全部平台 || -+ NVBeforeUnload: -view载体即将被卸载 -资源回收 -+ NVUnloaded: +## 简单View的示例 -view载体已经被卸载 +#### 创建插件 -资源回收 +在HBuilder X 中选中Uni-App项目下 uni_modules目录 -+ unmounted: +todo 目前还没有创建界面 -view载体被回收 -资源回收 +这是创建后的目录结构 -+ doMeasure: +![目录结构](https://native-res.dcloud.net.cn/images/uts/component/image1.png) -doMeasure 用于告诉排版系统,组件自身需要的宽高,具体的调用时机由排版系统决定。 -一般情况下,组件的宽高应该是由终端系统的排版引擎决定,组件开发者不需要实现此函数。 +#### 编写逻辑 -但是部分场景下,组件开发者需要自己维护宽高,则需要开发者重写此函数 +打开index.vue,键入下面的组件源码: + +```ts + + + +``` +#### 使用组件 -#### 内置对象和函数 +打开任意 componet.nvue文件 +```js + +``` -为了方便组件开发者使用,UTS 组件内部内置了下列对象: -|变量名 |类型 |简介 |平台限制 | -|:------- |:-------- |:-------- |:--- | -|$el |对象 |当前View实例对象 |全部平台 | -|$androidContext|对象 |当前组件上下文 |仅android | -|emit("event") |函数 |发送已注册的事件 |全部平台 | +## 包含第三方SDK的示例 +#### 创建插件 +在HBuilder X 中选中Uni-App项目下 uni_modules目录 + +todo 目前还没有创建界面 + +这是创建后的目录结构 + +![目录结构](https://native-res.dcloud.net.cn/images/uts/component/image1.png) + + +#### 引入依赖 + +打开 ~/uni_modules/uts-animation-view/utssdk/app-android/config.json + +键入如下代码: + +``` +"dependencies": [ + "com.airbnb.android:lottie:3.4.0" +] +``` +UTS组件建议使用远程依赖的方式集成,如果需要以AAR的形式添加SDK,可以添加到 -## UTS组件开发使用示例 +~/uni_modules/uts-animation-view/utssdk/app-android/libs目录 +#### 编写逻辑 -## 包含第三方功能的 UTS组件开发使用示例 +#### 使用组件 #### 使用组件的注意事项