tmui-cli 2.0.3 → 2.0.5

package/data/uni-app-x-docs/performance.md

@@ -0,0 +1,181 @@
+# uni-app x 的App性能优化
+
+uni-app x ，尤其是蒸汽模式，拥有快过原生的渲染引擎。[评测另见](./app-vapor.md#性能说明)
+
+但使用不当，也会卡顿。
+
+## 控制好dom的数量和嵌套层数
+
+dom数量越多，渲染越慢。
+
+以日历为例，web开发一般是每天一个view，里面再嵌套农历、假日等，一个日历可能有几百个dom元素。如果Android上这么做，会非常卡。
+
+那么原生Android开发怎么做的呢？使用Android的开发者模式审查元素边界，可以发现rom自带的日历，并不是每个格子一个view，而是整个月都是一个view。
+
+![](./static/calendar.jpg)
+
+Android上为了避免view数量过多，提供了原始的draw api，把线条和文字绘制上去。
+
+在 uni-app x 中，
+
+- 在 vdom 模式下，也提供了Drawable方法，允许开发者调用绘制API。
+
+hello uni-app x 示例中，有一个日历的模板页面，vdom模式下就是通过draw api来绘制的，性能很高。[源码详见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/calendar/calendar.uvue)
+
+- 在蒸汽模式下，支持了view、text、image的拍平。
+
+Draw API使用复杂，且无法跨端到web和小程序。
+
+uni-app x 蒸汽模式提供了拍平（flatten），允许开发者编写跨平台的view、text、image代码，只需给这些组件加上flatten属性。
+
+被拍平的view、text、image，将被绘制在父上，在审查元素边界时看不到边界。其性能远超原生的view、text、image。实现了跨平台和性能兼得。
+
+hello uni-app x 示例中，有一个蒸汽模式下的日历的模板页面，渲染非常快。[源码详见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/calendar-vapor/calendar-vapor.uvue)
+
+尤其是组件作者，更需要关注dom数量的问题。
+
+uni-app x 的 vdom 模式在Android上还提供了工具帮助开发者监控页面的dom数量。
+
+HBuilderX真机运行到Android时，每个页面进入时会都打印页面初始化的数据：dom数量、排版次数、渲染耗时等。
+
+![](./static/hxconsolepageperformance.png)
+
+当然耗时数据不能以真机运行为准，调试基座因为热更新和sourcemap追踪等很多调试功能，导致性能比真实打包差很多。正式打包后性能更优。
+
+## Android蒸汽模式选择so库不压缩
+
+Android蒸汽模式的manifest的Android配置中有一个选项“压缩so库”。默认是压缩的。
+
+压缩so库，apk包体积变小，但性能下降。
+
+这是一个体积和性能的平衡策略，在意体积就压缩，在意性能就要去manifest里配成不压缩。
+
+## 界面元素动画
+
+动画，有2种，预定义不可编程动画、可编程动画。
+
+预定义不可编程动画，包括css transition动画、以及 [animation-view组件](https://ext.dcloud.net.cn/plugin?id=10674)，这个组件本质是lottie动画。
+
+可编程动画，包括 [UniElement.animate](./api/dom/unielement.md)帧动画方法，或者监听手势、滚动、帧回调[requestAnimationFrame](./api/animation-frame.md)，在回调中操作元素的transform。
+
+uni-app x 中，没有通信阻塞，可以直接监听touch和滚动事件。不再需要renderjs、bindingx、wxs、worklet动画这些为了解决通信阻塞的补丁技术。
+
+在touch和滚动事件中，移动dom元素时，有2个注意：
+1. 请使用transform方式，而不是给dom的left/top/width/height等position参数重新赋值。这个在web开发也一样，直接改position参数不如使用transform。因为每次修改position参数都要过排版，而transform不用。
+2. 请拿到dom的id/ref，调用js api操作，而不是通过模板style绑定data操作。因为操作data需要vue框架做diff对比，直接API操作则可以跳过vue框架。在touch和滚动中，16毫秒一帧才能达到最平滑的效果，多了几毫秒就可能掉帧。
+
+在大多数开发框架中，因为通信性能问题，吸顶这个行为需要底层特殊封装。而 uni-app x 无需特别封装，直接监听滚动事件，通过dom的api以transform方式修改top值，就能自己编写逻辑控制在指定条件下实现固顶。
+
+源码参考hello uni-app x中的吸顶示例，这充分体现了 uni-app x 引擎底层的通信性能足够优秀。[详见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/scroll-view-sticky-section/scroll-view-sticky-section.uvue)
+
+当然uni-app x已经封装了吸顶组件，使用更加便利。[详见](./component/sticky-header.md)
+
+还有一个注意事项，当通过动画修改一个元素的高度或top值时，注意元素下部其他元素的联动反应。
+
+比如上元素通过transform变高，虽然上元素的变化是平滑的，但下面的元素数量如果很多，且因为自动排版的原因，在不停的根据上元素变化而移动每个下面元素的top，这也会导致ui卡顿。
+
+这个例子在折叠面板里存在，展开上面的折叠面板A时，推荐的做法是A的高度不做动画，直接变高，然后A的子元素以动画方式出现。看起来也有动效，且A下面的B、C、D等折叠面板元素只发生一次位移排版。
+
+## 避免复杂逻辑卡UI
+
+与小程序和uni-app不同，uni-app x下开发者的代码默认是在ui主线程运行的。除非单独写代码调用子进程或协程。
+
+如果在ui繁忙时，比如页面进入动画时，开发者的代码做了很多耗时操作，会卡动画。原生开发也如此。
+
+页面的onload触发，和进入动画是同时发生的，所以需注意onload生命周期中代码的编写。
+
+由于uni-app x提供的联网和图片加载是在单独进程或协程中的，所以这2个行为不会卡ui。最佳实践是在onload里进行联网取数。
+
+如果onload里某些代码卡了进入动画，也可以挪到页面的onready生命周期中，该事件触发的更晚一些。
+
+页面dom元素过多的话，也会影响进入动画，所以尽量节省dom数量。
+
+复杂计算逻辑，可以使用[worker](./api/create-worker.md)
+
+## 长列表
+
+长列表，之所以成为性能关注点，是因为当列表item加载特别多时，持续增高的内存占用会导致越来越卡、应用崩溃。
+
+### 蒸汽模式
+在uni-app x 蒸汽模式时，直接用list-view、waterflow组件即可。加载4000行item、20万元素的死亡长列表，也是瞬间的事情。参考[benchmark](./vapor-benchmark.md)
+
+### VDOM模式
+在uni-app x vdom模式下，需要考虑的问题要多一些。
+
+#### vdom模式的list-view和waterflow
+
+原生开发一般使用recycle-view做复用，只保留有限的原生view，数屏以外的原生view做复用，即把列表中的数据只装载到部分的原生view中，并根据在屏状态，给原生view装载不同的列表数据。
+
+uni-app x中，[list-view组件](./component/list-view.md)和[waterflow组件](./component/waterflow.md)，内部就是复用原生view的。他们分别对应普通长列表和瀑布流长列表。
+
+使用这2个组件，无论多长的列表，系统也会自动回收和复用渲染资源，和原生应用一样的体验，但开发更简单。
+
+但这2个组件只负责复用渲染资源，不处理VNode和Element的复用。如果你希望更多复用，需要看下面的uni-recycle-view组件。
+
+#### uni-recycle-view组件
+
+一般联网加载的分页式列表，常规使用list-view组件或waterflow组件即可。
+
+但如果需要一次性加载非常多的列表项，比如从本地一次性读取数千条记录，都想显示到界面上，那会非常卡。虽然在渲染层有复用，没有创建太多，但vue的VNode和UniElement超级多的话，创建也很慢。
+
+一些开发者只是简单的把数千条数据赋值给vue的响应式变量，然后就会触发大量DOM、原生view创建或更新，这极大的降低了长列表的性能。
+
+uni-recycle-view组件内部通过计算决定哪些数据需要在界面展示。只创建有限的VNode，进而实现DOM和原生View数量的整体控制。
+
+插件下载地址：[uni-recycle-view组件](https://ext.dcloud.net.cn/plugin?id=17385)
+
+同时它也有一些限制和注意事项：
+1. uni-recycle-view 组件适用于仅使用一个for循环创建所有列表项的场景。
+2. 由于该组件使用了scroll-view而不是list-view，滚动过程中自行计算哪些数据需要渲染和复用，并直接用原生recycle-View的效率要低，因此滚动流畅度低于list-view组件。
+3. 该组件无法支持瀑布流
+4. 该组件2.0版本起限制所有item高度一致
+
+如果由于上述限制无法使用此组件，也可以尝试使用下文的分批加载方案。
+
+#### 分批加载
+
+分批加载没有封装具体的组件，hello uni-app-x内提供了一个示例[详见](https://gitcode.com/dcloud/hello-uni-app-x/blob/alpha/pages/template/batch-load-long-list/batch-load-long-list.uvue)
+
+分批加载适用于初始要加载一大批数据的场景，针对这一大批数据延迟将数据分批渲染，进而优化页面初始化速度，防止页面跳转卡顿。
+
+分批加载时需注意，用户在操作已经渲染的部分数据时，如果后台在持续加载数据，会导致卡住用户操作。
+所以还需要做到闲时加载，避免卡UI。上述示例在用户滚动、下拉刷新期间会暂停分批加载。
+
+分批加载相比uni-recycle-view 组件，内存占用多一些。由于滚动期间不涉及额外计算，分批加载在低端机上滚动流畅度高一些。
+
+#### 长列表性能的关键点
+
+无论如何，**注意列表项目里的组件数量**，它是dom元素的放大器。每个list-item里的dom数量多一点，乘以item数量，就会产生非常多dom，页面性能就很容易被拖垮。
+
+比如很多列表有评星，如果使用一个5个view的评星组件，那每个list-item都会多5个view，列表一长dom数量会惊人。
+
+在hello uni-app x的复杂长列表示例中，评星没有使用任何自定义组件，只是一个text组件里面使用字体图标放了5个字符，极大减少组件数量。[详见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/long-list/long-list-page.uvue)
+
+所以在列表中，尽量不使用层层封装的组件，直接使用内置组件更高效。
+
+在蒸汽模式中，由于去掉了组件的vnode，即vue的虚拟dom，所以使用组件的压力小多了。但和高度优化的引擎内置view、text、image相比，开发者自己封装的组件肯定性能有折损。
+
+## 优化排版效率
+
+HBuilderX真机运行到Android vdom时，每个页面进入时会都打印页面初始化的数据：dom数量、排版次数、渲染耗时等。
+
+![](./static/hxconsolepageperformance.png)
+
+但这个数值是调试模式的数值，发布打包后比这个数字更快。所以这个数字是用于开发期间的参考，而不能用于release包的性能评估。
+
+dom数量优化前文已经讲了，那么如何优化排版效率？
+
+1. 首先还是dom元素数量和层级，直接影响排版
+2. 给dom元素指定明确的宽高，而不是很多自适应计算，可以提高排版效率。比如父节点未指定宽高，需要等所有子节点计算好宽高后把父节点撑开，这样就会比较低效。
+3. 指定主轴方向的尺寸可以减少递归的深度
+4. 文字测量属于耗时操作，给text组件指定宽高可以提升排版效率
+5. 指定图片的尺寸信息可以减少排版次数
+6. css单位尺寸性能比较，px > rpx > 百分比，使用百分比时父节点有明确宽高或者不依赖子节点确定宽高可以提升排版效率
+
+## 控制vue的更新范围
+vue的data更新时，会自动触发页面渲染更新。
+
+更新是差量的，但计算差量也是耗费时间的。所以应减少对大data的修改。如果大data里有可能动态更新的小data，不如单独再存放一个小data数据。
+
+另外更新ui时，如果vue框架能找到最小化组件，则会只更新该组件的渲染。所以尽量避免更新data引发大量ui重绘。\
+比如长列表里有可点击的收藏按钮，点击后会动态更新收藏状态的数据，此时建议把收藏做一个单独的组件，这样某个item的收藏状态的更新，就不会触发整个列表的重绘。

package/data/uni-app-x-docs/plugin/NOTE.md

@@ -0,0 +1,7 @@
+---
+layout: SimpleLayout
+---
+
+该文档从公共文档自动同步生成，详细信息查看：[docs-sync.config.ts](../../docs-sync.config.ts)
+
+如需修改此文档，请前往 [docs-common 仓库](https://gitcode.com/dcloud/docs-common) 对应文件进行编辑

package/data/uni-app-x-docs/project.md

@@ -0,0 +1,153 @@
+# uni-app x项目
+
+## 新建
+
+首先需下载最新版[HBuilder](https://www.dcloud.io/hbuilderx.html)
+
+在菜单文件>新建>项目中，选择新建项目。（或工具链左上角的新建快捷菜单，或者快捷键Ctrl+N）
+
+- HBuilderX 5.25+，新建项目默认为 uni-app x 蒸汽模式。
+- 低于5.25时，新建项目默认是uni-app，需要注意区分uni-app和uni-app x项目，在新建项目界面的底部有一个checkbox：uni-app x。**勾选后**会新建为uni-app x项目。
+
+![](./static/newproject.png)
+
+可以选择空项目，也可以选择hello uni-app x示例项目，这个项目有几百个页面，演示了uni-app x的各种组件和API的用法。
+
+uni-app x只支持vue3，无法勾选vue2。
+
+uni-app x的项目，manifest.json中会多一个节点`"uni-app-x" : {}`。这是HBuilder识别项目类型的标记。如手动增删这个节点，需对项目点右键"重新识别项目类型"
+```json
+{
+    "name" : "hello-uniapp x",
+    "appid" : "__UNI__4517034",
+    "description" : "",
+    "versionName" : "1.0.0",
+    "versionCode" : "100",
+    "uni-app-x" : {
+    }
+}
+```
+
+uni-app x的项目，在左侧项目管理器的图标是圆形的U（之前是方型的U）。
+
+![](./static/project-icon.png)
+
+## 项目结构
+
+uni-app x的项目结构与[uni-app老版的项目结构](https://uniapp.dcloud.net.cn/tutorial/project.html)基本一致。
+
+主要的差别是没有nativeplugins目录。原因是uni-app x不支持App原生语言插件，仅支持uts插件。
+
+基于uts的插件，可以在uni-app x和uni-app上通用。
+
+<pre v-pre="" data-lang="">
+	<code class="lang-" style="padding:0">
+┌─uniCloud              云空间目录，支付宝小程序云为uniCloud-alipay，阿里云为uniCloud-aliyun，腾讯云为uniCloud-tcb（详见<a href="https://doc.dcloud.net.cn/uniCloud/quickstart?structure&id=structure">uniCloud</a>）
+│─components            符合vue组件规范的uni-app x组件目录
+│  └─comp-a.vue         可复用的a组件
+├─utssdk                存放uts文件（已废弃）
+├─pages                 业务页面文件存放的目录
+│  ├─index
+│  │  └─index.uvue      index页面
+│  └─list
+│     └─list.uvue       list页面
+├─static                存放应用引用的本地静态资源（如图片、字体、音视频等）的目录，<b>注意：</b>静态资源都应存放于此目录  <a href="https://doc.dcloud.net.cn/uni-app-x/compiler/#static">详见</a>
+├─uni_modules           存放uni_module <a href="https://uniapp.dcloud.net.cn/plugin/uni_modules.html">详见</a>
+├─platforms             存放各平台专用页面的目录，<a href="https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor">详见</a>
+├─nativeResources       App端原生资源目录
+│  ├─android            Android原生资源目录 <a href="https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-android">详见</a>
+|  └─ios                iOS原生资源目录 <a href="https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios.html#%E8%B5%84%E6%BA%90%E6%96%87%E4%BB%B6-bundle-resources">详见</a>
+├─harmonyConfig         HarmonyOS 端原生资源目录 <a href="https://uniapp.dcloud.net.cn/tutorial/harmony/runbuild.html#config-dir">详见</a>
+├─hybrid                App端存放web-view组件使用的本地html文件的目录，<a href="./component/web-view">详见</a>
+├─wxcomponents          微信小程序平台wxml组件专用目录
+├─unpackage             非工程代码，一般存放运行或发行的编译结果、App自定义基座。默认应配置git忽略
+├─main.uts/ts/js        Vue初始化入口文件。HBuilderX 5.28+ 蒸汽模式支持ts/js后缀
+├─App.uvue              应用配置，用来配置App全局样式以及监听 <a href="./collocation/App#应用生命周期">详见</a>
+├─pages.json            配置页面路由、导航条、选项卡等页面类信息，<a href="./collocation/pages">详见</a>
+├─manifest.json         配置应用名称、appid、logo、版本等打包信息，<a href="./collocation/manifest">详见</a>
+├─AndroidManifest.xml   Android原生应用清单文件 <a href="https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-android">详见</a>
+├─Info.plist            iOS原生应用配置文件 <a href="https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios">详见</a>
+└─uni.scss              内置的常用样式变量
+	</code>
+</pre>
+
+> 当使用cursor等ai工具开发uni-app x时，可以在项目下放置.cursor目录，帮助AI更好的生成uni-app x代码。[链接](https://github.com/dcloudio/uni-app-x-ai-rules)
+
+## 运行时的UniApp实例
+
+每个uni-app x应用启动，会有一个UniApp实例，通过全局API `getApp()` 获取。
+
+UniApp上有应用级的方法和属性。[详见](./api/get-app.md)
+
+## 运行
+
+新建项目后，可以直接点顶部菜单或工具栏运行，选择要运行的目标平台。
+
+在HBuilder中，有顶部菜单、toolbar运行按钮、快捷键三种运行入口。
+
+1. 顶部运行菜单
+
+![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/menurun.png)
+
+2. toolbar工具栏上的运行按钮
+
+![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/toolbarrun.png)
+
+	toolbar的运行按钮点击后会展开一个菜单。这个菜单可配置，通过`自定义菜单`将不常用的运行项目折叠起来。
+
+3. 快捷键
+
+	运行快捷键是【Ctrl+r】
+
+	弹出的菜单还支持键盘快捷选择：按回车可以选中菜单的第一项；windows下按数字可以快捷选中菜单项开头数字对应的菜单项。
+
+如果不能看到相关菜单，那么HBuilder当前打开的文件可能不是uni-app x项目下的文件。
+
+运行到不同平台，需要不同平台的运行环境，比如安装浏览器、安装小程序模拟器、安装手机模拟器或电脑端插入真机。
+
+根据提示安装运行环境，并注意观察控制台的日志。
+
+在控制台的右上角，点击红色虫子可以开启debug调试。详见左侧的运行和调试章节。
+
+### 运行到App
+
+uni-app x在运行到Android和iOS时，提供了真机运行基座（playground），该基座安装到手机后，可以把开发者编写代码同步到手机上运行在这个基座上。
+并实现修改代码后热刷新，在手机上及时看到效果。
+
+运行到鸿蒙时，没有基座概念，直接调用本地的deveco出包。当然也就不支持热刷新了。
+
+Android和iOS上的基座有标准基座和自定义基座的概念。
+
+和 uni-app/5+App/wap2app 的基座不同，uni-app x的标准基座是一个绿色圆形的U（之前是方型H），基座名称默认为`uni-app x`（之前叫HBuilder）。
+![](./static/playground.jpg)
+
+- uni-app x基座，只能运行uni-app x项目，包名是io.dcloud.uniappx
+- HBuilder基座，可以运行uni-app/5+App/wap2app。包名是io.dcloud.HBuilder
+
+标准基座使用的图标、包名、证书以及配置的三方sdk的appkey等各种原生信息，都是DCloud的。[详见](./tutorial/app-playground.md)
+
+当需要使用自己的包名、证书、原生配置以及变更三方原生sdk时，需在打包界面勾选打包自定义基座，打包后的自定义基座会放置在项目的unpackage目录下，然后在运行项目时的界面中可以选择自定义基座来运行。
+
+uni-app x运行时，默认仅显示开发者代码和uni-app x框架的输出日志，在控制台右上角还可以选择开启原生日志。
+
+### 运行到web
+
+uni-app x运行到浏览器时，编译基于vite，其特点是按需编译。所以项目运行后很快能看到首页，但后续仍然在编译其他页面直到项目编译完成。
+
+如果后续页面有报错，就会在控制台看到输出。即便这个页面并未打开。
+
+## 发行
+
+选中要发行的项目，点顶部菜单发行（或者对项目点右键，或者快捷键Ctrl+U），选择要发行的目标平台。
+
+所有平台的都支持本地发行，同时依赖本地安装的发布环境。在菜单或弹出界面上有相应的教程链接。
+
+如果发布Android和iOS应用，HBuilder还额外提供了方便的云打包，免去安装和配置原生环境，直接出apk、ipa包。[详见](./tutorial/app-package.md)
+
+除了在菜单里点击发布，也可以通过HBuilderX的cli，实现持续集成和自动发布。[详见](https://hx.dcloud.net.cn/cli/README)
+
+如果你不希望直接发布成品应用，而希望发布成其他应用的一部分，那么
+- App平台：需参考[uni-app x 原生SDK文档](./native/README.md)，把uni-app x项目发布为kt、swift源码，集成到自己的原生项目中。
+- 小程序平台：可发布为分包，成为其他小程序的一个分包。[详见](https://uniapp.dcloud.net.cn/hybrid.html)
+
+如果你已经拥有了非uni-app x的成型应用，想要渐进式的引入uni-app x，那么上面的方案非常合适。可以用uni-app x开发部分页面，集成到原来的项目中。