tmui-cli 2.0.6 → 5.3.2

package/data/uni-app-x-docs/native/use/androidcomm.md

@@ -2,10 +2,38 @@
 
 需要在打开uni-app x的地方添加如下代码，触发逻辑即可打开uni-app x。
 
+蒸汽模式（Vapor）：
+
 ```kotlin
 startActivity(Intent(this, UniAppActivity::class.java))
 ```
 
+::: details VDOM模式
+
+### UniAppXSDK.start(options: UniAppXSDKStartOptions?, activity: Activity)
+
+打开uni-app x应用
+
+|名称		|类型					|默认值	|必填	|描述						|
+|:--		|:--					|:--	|:--	|:--						|
+|options	|UniAppXSDKStartOptions	|		|否		|UniAppXSDKStartOptions		|
+|activity	|Activity				|		|是		|打开uni-app x的Activity对象	|
+
+### UniAppXSDKStartOptions
+
+|名称					|类型	|默认值	|必填	|描述			|
+|:--					|:--	|:--	|:--	|:--			|
+|appScheme				|String	|		|否		|透传scheme		|
+|animationType			|String	|		|否		|动画类型[文档](https://uniapp.dcloud.net.cn/api/router.html#animation)			|
+|enterCustomAnimation	|Number	|		|否		|进入动画资源ID	|
+|exitCustomAnimation	|Number	|		|否		|退出动画资源ID	|
+
+**Tips**
+- `animationType`优先级高于`enterCustomAnimation`和`exitCustomAnimation`，但设置了`animationType`之后，其他动画属性将不生效。
+- `enterCustomAnimation`和`exitCustomAnimation`需要同时设置才会生效。
+
+:::
+
 连接手机，点击运行按钮，可以在手机上查看效果。
 
 ![avatar](https://img.cdn.aliyun.dcloud.net.cn/nativedocs/5%2BSDK-android/image/7-6.png)
@@ -19,9 +47,85 @@ startActivity(Intent(this, UniAppActivity::class.java))
 
 #### uni-app x项目
 
-首先需要在当前页面注册一个BroadcastReceiver接受android原生应用发送的广播信息。
+首先需要通过uts插件注册一个BroadcastReceiver接受android原生应用发送的广播信息。
+
+发送广播可以通过`activity.sendBroadcast(intent)`将信息传送到原生。
+
+```uts
+import { RegisterBroadcast, UnregisterBroadcast, SendBroadcast, RegisterBroadcastOptions } from '../interface.uts'
+import BroadcastReceiver from 'android.content.BroadcastReceiver'
+import Context from 'android.content.Context'
+import Intent from 'android.content.Intent'
+import IntentFilter from 'android.content.IntentFilter'
+import Build from 'android.os.Build'
+
+class BroadcastDemoReceiver extends BroadcastReceiver {
+	private receiveAction : string = ""
+	private receiveCallback : ((value : string) => void) | null = null
+
+	constructor(action : string, callback : (value : string) => void) {
+		super()
+		this.receiveAction = action
+		this.receiveCallback = callback
+	}
+
+	override onReceive(context : Context, intent : Intent) {
+		const intentAction = intent.getAction()
+		if (intentAction == null) {
+			return
+		}
+		if (intentAction == this.receiveAction) {
+			const rawValue = intent.getStringExtra("key")
+			const value = rawValue != null ? rawValue : ""
+			const callback = this.receiveCallback
+			if (callback != null) {
+				callback(value)
+			}
+		}
+	}
+}
+
+let currentReceiver : BroadcastDemoReceiver | null = null
+
+export const unregisterBroadcast : UnregisterBroadcast = function () {
+	const receiver = currentReceiver
+	if (receiver != null) {
+		const activity = UTSAndroid.getUniActivity()
+		if (activity != null) {
+			activity.unregisterReceiver(receiver)
+		}
+	}
+	currentReceiver = null
+}
+
+export const registerBroadcast : RegisterBroadcast = function (options : RegisterBroadcastOptions) {
+	unregisterBroadcast()
+	const activity = UTSAndroid.getUniActivity()
+	if (activity == null) {
+		return
+	}
+	const receiver = new BroadcastDemoReceiver(options.action, options.onReceive)
+	const filter = new IntentFilter(options.action)
+	if (Build.VERSION.SDK_INT >= 33) {
+		activity.registerReceiver(receiver, filter, Context.RECEIVER_EXPORTED)
+	} else {
+		activity.registerReceiver(receiver, filter)
+	}
+	currentReceiver = receiver
+}
+
+export const sendBroadcast : SendBroadcast = function (action : string, key : string, value : string) {
+	const activity = UTSAndroid.getUniActivity()
+	if (activity == null) {
+		return
+	}
+	const intent = new Intent(action)
+	intent.putExtra(key, value)
+	activity.sendBroadcast(intent)
+}
+```
 
-发送广播可以通过`UTSAndroid.getUniActivity()?.sendBroadcast(intent)`将信息传送到原生。
+在uvue页面中主动调用uts插件发送广播，参考示例：
 
 ```uvue
 <template>
@@ -35,59 +139,40 @@ startActivity(Intent(this, UniAppActivity::class.java))
 
 <script setup lang="uts">
 	// #ifdef APP-ANDROID
-	import BroadcastReceiver from 'android.content.BroadcastReceiver'
-	import Context from 'android.content.Context'
-	import Intent from 'android.content.Intent'
-	import IntentFilter from 'android.content.IntentFilter'
-	import Build from 'android.os.Build'
-	class MyReciver extends BroadcastReceiver {
-		constructor() {
-
-		}
-		override onReceive(context : Context, intent : Intent) {
-			var action = intent.getAction()
-			if (action.equals("ACTION_FROM_NATIVE")) {
-				var value = intent.getStringExtra("key");
-				uni.showToast({
-					title: value!!
-				})
-			}
-		}
-	}
+	import {
+		registerBroadcastReceiver,
+		sendBroadcast,
+		unregisterBroadcastReceiver,
+		BroadcastReceiverOptions
+	} from '@/uni_modules/uts-broadcast'
 	// #endif
 
 	const title = '点击图片发送广播'
-	// #ifdef APP-ANDROID
-	let receiver: BroadcastReceiver | null = null
-	// #endif
 
 	onReady(() => {
 		// #ifdef APP-ANDROID
-		const currentReceiver = new MyReciver()
-		receiver = currentReceiver
-		if (Build.VERSION.SDK_INT >= 33) {
-			UTSAndroid.getUniActivity()?.registerReceiver(currentReceiver, IntentFilter("ACTION_FROM_NATIVE"), Context.RECEIVER_EXPORTED)
-		} else {
-			UTSAndroid.getUniActivity()?.registerReceiver(currentReceiver, IntentFilter("ACTION_FROM_NATIVE"))
-		}
+		const options = {
+			action: 'ACTION_FROM_NATIVE',
+			extraKey: 'key',
+			onReceive: (value : string) => {
+				uni.showToast({
+					title: value
+				})
+			}
+		} as BroadcastReceiverOptions
+		registerBroadcastReceiver(options)
 		// #endif
 	})
 
 	onUnload(() => {
 		// #ifdef APP-ANDROID
-		const currentReceiver = receiver
-		if (currentReceiver != null) {
-			UTSAndroid.getUniActivity()?.unregisterReceiver(currentReceiver)
-			receiver = null
-		}
+		unregisterBroadcastReceiver()
 		// #endif
 	})
 
 	const send = () => {
 		// #ifdef APP-ANDROID
-		var intent = new Intent("ACTION_TO_NATIVE");
-		intent.putExtra("key", "接受到广播，三秒钟之后会接收到原生发送的广播");
-		UTSAndroid.getUniActivity()?.sendBroadcast(intent)
+		sendBroadcast('ACTION_TO_NATIVE', 'key', '接受到广播，三秒钟之后会接收到原生发送的广播')
 		// #endif
 	}
 </script>
@@ -157,8 +242,37 @@ class MainActivity : AppCompatActivity() {
 
 **注意：广播要在页面关闭的时候取消注册，避免可能出现崩溃的问题。**
 
-示例可以参考原生SDK中的`app-comm`工程。
+示例可以参考原生SDK中的工程。
 
 ## 退出
 
 退出 uni-app x 应用可以在uni-app x中调用`uni.exit()`，整体退出uni-app x。
+
+::: details VDOM模式
+
+VDOM 模式可以调用 UniAppXSDK.exit() 退出应用。
+
+:::
+
+
+### 注册
+
+::: details VDOM模式
+
+uni-app x全局注册。当前方法用在解决用户无法继承UniApplication。
+
+#### UniAppXApplication.onCreate(application: Application)
+
+Application中onCreate方法中调用
+
+#### UniAppXApplication.onTrimMemory(level: Int)
+
+Application中onTrimMemory方法中调用
+
+#### UniAppXApplication.onConfigurationChanged(newConfig: Configuration?)
+
+Application中onConfigurationChanged方法中调用
+
+示例可以参考原生SDK中的`app-comm`工程。
+
+:::

package/data/uni-app-x-docs/native/use/harmony.md

@@ -22,25 +22,25 @@
 * 蒸汽模式请改用 `@dcloudio/uni-app-x-vapor-runtime` 模块，最低版本为 5.25。
 
 ::: preview
-> VDOM模式
+> 蒸汽模式
 ```json
 {
-  "modelVersion": "5.0.4",
+  "modelVersion": "6.1.1",
   "description": "Please describe the basic information.",
   "dependencies": {
-    // 指定 4.71 版本
-    "@dcloudio/uni-app-x-runtime": "4.71.*"
+    // 指定 5.25 版本
+    "@dcloudio/uni-app-x-vapor-runtime": "5.25.*"
   }
 }
 ```
-> 蒸汽模式
+> VDOM模式
 ```json
 {
-  "modelVersion": "6.1.1",
+  "modelVersion": "5.0.4",
   "description": "Please describe the basic information.",
   "dependencies": {
-    // 指定 5.25 版本
-    "@dcloudio/uni-app-x-vapor-runtime": "5.25.*"
+    // 指定 4.71 版本
+    "@dcloudio/uni-app-x-runtime": "4.71.*"
   }
 }
 ```
@@ -57,7 +57,7 @@
 编辑 entry/build-profile.json5 文件，在 buildOption 增加 arkOptions -> runtimeOnly -> sources 配置
 
 ::: preview
-> VDOM模式
+> 蒸汽模式
 ```json
 {
   "apiType": "stageMode",
@@ -66,14 +66,15 @@
       "runtimeOnly": {
         "sources": [
           "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-config.ets",
-          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-service.ets"
+          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-service.ets",
+          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/dynamic.ets"
         ]
       }
     }
   }
 }
 ```
-> 蒸汽模式
+> VDOM模式
 ```json
 {
   "apiType": "stageMode",
@@ -82,8 +83,7 @@
       "runtimeOnly": {
         "sources": [
           "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-config.ets",
-          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-service.ets",
-          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/dynamic.ets"
+          "./src/main/resources/resfile/uni-app-x/apps/你的APPID/www/import/app-service.ets"
         ]
       }
     }

package/data/uni-app-x-docs/native/use/harmonyapi.md

@@ -3,10 +3,10 @@
 打开鸿蒙项目文件 entry/src/main/ets/entryability/EntryAbility.ets，增加 uni-app sdk 初始化逻辑。
 
 ::: preview
-> VDOM模式
+> 蒸汽模式
 ```typescript
 import { window } from "@kit.ArkUI";
-import { UniEntryAbility } from "@dcloudio/uni-app-x-runtime";
+import { UniEntryAbility } from "@dcloudio/uni-app-x-vapor-runtime";
 import BuildProfile from "BuildProfile";
 
 export default class EntryAbility extends UniEntryAbility {
@@ -31,10 +31,10 @@ export default class EntryAbility extends UniEntryAbility {
   }
 }
 ```
-> 蒸汽模式
+> VDOM模式
 ```typescript
 import { window } from "@kit.ArkUI";
-import { UniEntryAbility } from "@dcloudio/uni-app-x-vapor-runtime";
+import { UniEntryAbility } from "@dcloudio/uni-app-x-runtime";
 import BuildProfile from "BuildProfile";
 
 export default class EntryAbility extends UniEntryAbility {
@@ -64,7 +64,7 @@ export default class EntryAbility extends UniEntryAbility {
 ## 启动
 
 ::: preview
-> VDOM模式
+> 蒸汽模式
 ```typescript
 export type AnimationType =
   | "slide-in-right"
@@ -77,12 +77,42 @@ interface IOpenUniAppConfig {
   animationType?: AnimationType;
   animationDuration?: number;
 }
+export type ShowAnimationType =
+  'slide-in-right' |
+  'slide-in-left' |
+  'slide-in-top' |
+  'slide-in-bottom' |
+  'fade-in' |
+  'none'
+export type HideAnimationType =
+  'slide-out-right' |
+  'slide-out-left' |
+  'slide-out-top' |
+  'slide-out-bottom' |
+  'fade-out' |
+  'none'
+export interface IUniAppShowOptions {
+  animationType?: ShowAnimationType
+  animationDuration?: number
+}
+export interface IUniAppHideOptions {
+  animationType?: HideAnimationType
+  animationDuration?: number
+}
+export interface IUniAppSDK {
+  appId: string
+  hide(options?: IUniAppHideOptions): void
+  show(options?: IUniAppShowOptions): void
+  close(): void
+  on(event: 'close' | 'show' | 'hide', callback: () => void): void
+  off(name: string, callback: Function): void
+}
 export declare function openUniApp(
   appID: string,
   config?: IOpenUniAppConfig
-): void;
+): IUniAppSDK;
 ```
-> 蒸汽模式
+> VDOM模式
 ```typescript
 export type AnimationType =
   | "slide-in-right"
@@ -95,22 +125,19 @@ interface IOpenUniAppConfig {
   animationType?: AnimationType;
   animationDuration?: number;
 }
-export interface IUniAppSDK {
-  close(): void
-}
 export declare function openUniApp(
   appID: string,
   config?: IOpenUniAppConfig
-): IUniAppSDK;
+): void;
 ```
 :::
 
 ### 示例代码
 
 ::: preview
-> VDOM模式
+> 蒸汽模式
 ```ts
-import { openUniApp } from '@dcloudio/uni-app-x-runtime'
+import { openUniApp } from '@dcloudio/uni-app-x-vapor-runtime'
 
 @Entry
 @Component
@@ -119,7 +146,7 @@ struct Index {
     RelativeContainer() {
       Button('Open')
         .onClick(() => {
-          openUniApp('你的APPID', {
+          const app = openUniApp('你的APPID', {
             animationType: 'fade-in',
           })
         })
@@ -129,9 +156,9 @@ struct Index {
   }
 }
 ```
-> 蒸汽模式
+> VDOM模式
 ```ts
-import { openUniApp } from '@dcloudio/uni-app-x-vapor-runtime'
+import { openUniApp } from '@dcloudio/uni-app-x-runtime'
 
 @Entry
 @Component
@@ -140,7 +167,7 @@ struct Index {
     RelativeContainer() {
       Button('Open')
         .onClick(() => {
-          const app = openUniApp('你的APPID', {
+          openUniApp('你的APPID', {
             animationType: 'fade-in',
           })
         })
@@ -167,6 +194,43 @@ setTimeout(() => {
 }, 3000)
 ```
 
+## 显示与隐藏
+
+蒸汽模式可以通过应用实例的 `show()` 和 `hide()` 方法，显示或隐藏已打开的 uni-app x 应用。
+
+```ts
+const app = openUniApp('你的APPID', {
+  animationType: 'fade-in',
+})
+
+app.hide({
+  animationType: 'slide-out-right',
+  animationDuration: 300,
+})
+
+app.show({
+  animationType: 'slide-in-right',
+  animationDuration: 300,
+})
+```
+
+## 监听实例事件
+
+蒸汽模式可以使用 `on()` 监听应用的显示、隐藏和关闭事件，使用 `off()` 移除监听。
+
+```ts
+const app = openUniApp('你的APPID')
+
+const onShow = () => {
+  console.log('uni-app x 应用已显示')
+}
+
+app.on('show', onShow)
+
+// 不再需要监听时，传入同一个回调函数移除监听
+app.off('show', onShow)
+```
+
 ## 通信
 
 可以使用 [Emitter 模块](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-emitter?ha_source=Dcloud&ha_sourceId=89000448)进行消息通信。

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

@@ -307,6 +307,7 @@ onShow和onHide是成对出现的。
 
 ::: warning 注意
 - iOS 平台蒸汽模式开启下拉刷新会触发页面 `onPageScroll` 生命周期，此时 `scrollTop` 为负值。
+- 微信小程序为了性能，`onPageScroll` 默认关闭，只有页面存在 `onPageScroll` 代码时，才会主动开启，此时子组件才能监听到
 :::
 
 ### 页面 onBackPress 生命周期 @onbackpress

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

@@ -6,8 +6,8 @@
 
 在菜单文件>新建>项目中，选择新建项目。（或工具链左上角的新建快捷菜单，或者快捷键Ctrl+N）
 
-- HBuilderX 5.25+，新建项目默认为 uni-app x 蒸汽模式。
-- 低于5.25时，新建项目默认是uni-app，需要注意区分uni-app和uni-app x项目，在新建项目界面的底部有一个checkbox：uni-app x。**勾选后**会新建为uni-app x项目。
+- HBuilder 5.25+，新建项目默认为 uni-app x 蒸汽模式。
+- 低于5.25时，新建项目默认是uni-app，需要注意区分uni-app和uni-app x项目，在新建项目界面的底部有一个checkbox：uni-app x。**勾选后**会新建为uni-app x项目。见下图：
 
 ![](./static/newproject.png)
 
@@ -61,7 +61,7 @@ uni-app x的项目结构与[uni-app老版的项目结构](https://uniapp.dcloud.
 ├─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后缀
+├─main.uts/ts/js        Vue初始化入口文件。HBuilderX 5.31+ 蒸汽模式支持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>
@@ -71,7 +71,15 @@ uni-app x的项目结构与[uni-app老版的项目结构](https://uniapp.dcloud.
 	</code>
 </pre>
 
-> 当使用cursor等ai工具开发uni-app x时，可以在项目下放置.cursor目录，帮助AI更好的生成uni-app x代码。[链接](https://github.com/dcloudio/uni-app-x-ai-rules)
+uni-app x 目前仅支持代码在根目录、非代码在unpackage目录的项目目录结构。
+
+老uni-app同时支持node cli创建的src/dist项目结构，但双模式并存引发了很多问题：
+1. 官方和三方插件作者，都要测试双模式是否正常支持，生态成本大。
+2. src/dist模式，让uni-app版本和IDE版本解耦，经常会出现IDE提示报错、但实际能运行，或者反之。
+
+目前IDE中高频更新的是uni-agent，其他常规IDE功能已经越来越少人用。所以HBuilder采取的策略是大版本和uni-app x绑定，但uni-agent插件及部分IDE插件，可以独立升级更新，与大IDE升级解耦。
+
+uni-app x同时支持通过HBuilderX cli来创建项目、发行打包，可以在Linux的ci/cd里正常使用。[详见](https://hx.dcloud.net.cn/cli/README)
 
 ## 运行时的UniApp实例
 
@@ -147,7 +155,7 @@ uni-app x运行到浏览器时，编译基于vite，其特点是按需编译。
 除了在菜单里点击发布，也可以通过HBuilderX的cli，实现持续集成和自动发布。[详见](https://hx.dcloud.net.cn/cli/README)
 
 如果你不希望直接发布成品应用，而希望发布成其他应用的一部分，那么
-- App平台：需参考[uni-app x 原生SDK文档](./native/README.md)，把uni-app x项目发布为kt、swift源码，集成到自己的原生项目中。
+- App平台：需参考[uni-app x 原生SDK文档](./native/README.md)，把uni-app x项目，集成到自己的原生项目中。
 - 小程序平台：可发布为分包，成为其他小程序的一个分包。[详见](https://uniapp.dcloud.net.cn/hybrid.html)
 
 如果你已经拥有了非uni-app x的成型应用，想要渐进式的引入uni-app x，那么上面的方案非常合适。可以用uni-app x开发部分页面，集成到原来的项目中。