tmui-cli 2.0.3 → 2.0.5

package/data/uni-app-x-docs/api/create-webview-context.md

@@ -0,0 +1,66 @@
+<!-- UTSAPIJSON.createWebViewContext.name -->
+
+<!-- UTSAPIJSON.createWebViewContext.description -->
+
+参考：[web-view组件](../component/web-view.md)
+
+在不传入第2个component参数时，默认从页面栈顶的页面来查找这个webviewContext。
+
+在选项式和组合式中，获取组件实例略有差别。
+
+- 选项式中，this代表当前vue实例。如果是在页面的export default内、函数外使用this，即代表该页面的组件实例。
+```js
+let v1 = uni.createWebViewContext("wv1", this) //获取id为wx1的web-view组件的context
+```
+- 组合式中，通过getCurrentInstance()!.proxy! 获取当前页面的组件实例。
+```js
+let v1 = uni.createWebViewContext("wv1", getCurrentInstance()!.proxy!) //获取id为wx1的web-view组件的context
+```
+
+由于本API仅在App端支持。也可以直接使用DOM API操作。UniWebViewElement比webviewContext有更多属性和方法。例如：
+```js
+let wv = uni.getElementById("wv1") as UniWebViewElement
+```
+
+<!-- UTSAPIJSON.createWebViewContext.compatibility -->
+
+<!-- UTSAPIJSON.createWebViewContext.param -->
+
+<!-- UTSAPIJSON.createWebViewContext.fileFormats -->
+
+<!-- UTSAPIJSON.createWebViewContext.returnValue -->
+
+<!-- UTSAPIJSON.createWebViewContext.example -->
+
+<!-- UTSAPIJSON.createWebViewContext.tutorial -->
+
+<!-- UTSAPIJSON.createWebViewContext.example -->
+
+
+<!-- ## uni.createWebviewContext(webviewId, component?) @createwebviewcontext -->
+
+<!-- UTSAPIJSON.createWebviewContext.name -->
+
+<!-- UTSAPIJSON.createWebviewContext.description -->
+
+早期，本API的大小写不规范，`createWebviewContext`的view的首字母`v`没有大写。
+
+目前不规范的API已经废弃，推荐使用上方的`uni.createWebViewContext`。
+
+- app-android 平台在蒸汽模式下仅支持`V`大写的方式 ，不再支持向下兼容写法。
+
+<!-- UTSAPIJSON.createWebviewContext.compatibility -->
+
+<!-- UTSAPIJSON.createWebviewContext.param -->
+
+<!-- UTSAPIJSON.createWebviewContext.returnValue -->
+
+<!-- UTSAPIJSON.createWebviewContext.example -->
+
+<!-- UTSAPIJSON.createWebviewContext.tutorial -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->
+
+示例代码另见[web-view组件](../component/web-view.md)

package/data/uni-app-x-docs/api/create-worker.md

@@ -0,0 +1,293 @@
+# Worker
+
+现代CPU都是多核的。主线程的代码是运行在CPU的主核上的。可以通过 worker api来利用其他核并行计算，加快运算速度。
+
+uni-app x的代码，默认都是在主线程执行的，主线程也称为UI线程。
+
+当需要使用子线程能力时，可以通过本API操作。
+
+当然本API只是一种跨端封装，并且为了跨端还约束了一些写法。开发者也可以在uts插件中自行使用纯原生代码来操作线程。
+
+注意：
+- 所有UI操作、界面绘制，都必须在主线程进行。也就是子线程不能操作DOM API、不能操作绑定在界面上的响应式变量。
+- Android上通过surface渲染的界面组件，可以在子线程操作。
+- 线程之间通信，可以post消息，也可以共享变量。web和小程序仅支持shareArrayBuffer数据类型的共享。App平台没有限制，引用类型都可以共享变量。但共享变量时，需要开发者注意线程安全问题，避免多线程同时写同一个变量，或一个线程读、同时另一个线程在写同一个变量，这可能引发崩溃。
+- 线程和Android的协程是不同的。Android上request api内部已经使用了协程。
+- CPU的核数有限，不要同时开太多线程。
+- worker是一个uts API，无法在js环境使用。iOS平台、Android的蒸汽模式， Worker 仅支持在[uts插件](../plugin/uts-plugin.md)中使用，不能直接在 `uvue` 页面中调用 `uni.createWorker`  
+
+常见场景：
+- 当你的界面掉帧时，应该检查是什么耗时任务导致不能及时渲染，是否可以剥离一些计算任务到子线程来做。
+- 多份大数据需要尽快处理，比如多个json文件需要压缩，可以启动多线程。
+
+
+<!-- ## uni.createWorker(url) @createworker -->
+
+<!-- UTSAPIJSON.createWorker.name -->
+
+<!-- UTSAPIJSON.createWorker.description -->
+
+<!-- UTSAPIJSON.createWorker.compatibility -->
+
+<!-- UTSAPIJSON.createWorker.param -->
+
+<!-- UTSAPIJSON.createWorker.returnValue -->
+
+<!-- UTSAPIJSON.createWorker.example -->
+
+<!-- UTSAPIJSON.createWorker.tutorial -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->
+
+
+## Worker 使用流程 @tutorial
+
+### 1. 配置 Worker 信息
+
+worker 代码，是独立的 `uts` 文件，所有worker代码文件需要放置在专门的目录。在项目的 `manifest.json` 中可配置 Worker 文件放置的目录：
+```json
+{
+  //...
+  "workers": {
+    "path": "workers",        // 相对于项目根目录。此配置的意思是在项目根目录下的workers目录下存放worker代码。
+    "isSubpackage": true      // 是否分包，默认为 false（仅微信小程序有效）
+  }
+}
+```
+
+如果不使用微信小程序的分包配置，也可以使用简写配置：
+```json
+{
+  //...
+  "workers" : "workers"
+}
+```
+
+
+### 2. 添加 Worker 代码文件
+
+参考上一步的配置，在项目根目录下创建 `workers` 目录，并创建示例 `HelloWorkerTask.uts` 文件如下：
+
+<pre v-pre="" data-lang="">
+	<code class="lang-" style="padding:0">
+├─ static
+├─ workers                    // Worker 目录
+│  └─ HelloWorkerTask.uts     // Worker 代码文件
+├─ App.uvue
+├─ main.uts
+├─ manifest.json
+└─ pages.json
+</code>
+</pre>
+
+Worker 代码除了可以放到 `manifest.json->workers` 配置的目录，还支持放置到项目uni_modules插件中，此时目录为固定的 `插件id/workers`（注意这里的workers目录是固定的，跟manifest.json配置没有关系），比如`uni_modules/test-worker/workers`。
+
+<pre v-pre="" data-lang="">
+	<code class="lang-" style="padding:0">
+├─ static
+├─ uni_modules/test-worker/workers                    // 固定的插件 Worker 目录
+│  └─ HelloWorkerTask.uts     // Worker 代码文件
+├─ App.uvue
+├─ main.uts
+├─ manifest.json
+└─ pages.json
+</code>
+</pre>
+
+
+### 3. 编写 Worker 代码
+
+Worker 代码中需定义一个类并继承自基类 `WorkerTaskImpl`，重写 `onMessage` 方法接收主线程发送的数据。
+
+以下是 `HelloWorkerTask.uts` 示例代码：
+```uts
+/**
+ * HelloWorkerTask
+ */
+export class HelloWorkerTask extends WorkerTaskImpl {
+  /**
+   * 构造函数
+   */
+  constructor() {
+    super();
+    //初始化操作
+    // console.log("构造器初始化");
+  }
+
+  /**
+   * 实现入口函数
+   */
+  override entry() {
+    //入口函数，Worker 启动时执行
+    // console.log("启动完成，等待主线程消息");
+  }
+
+  /**
+   * 实现接收主线程发送的消息
+   */
+  override onMessage(message : any) {
+    // 处理消息对象
+    const messageData = message as UTSJSONObject;
+
+    // console.log('收到主线程数据:', messageData);
+
+    // 发送消息给主线程
+    this.postMessageToMain();
+  }
+
+  /**
+   * 回复消息
+   */
+  private postMessageToMain() {
+    const response = {
+      msg: 'message send by worker!'
+    };
+
+    // 调用 postMessage 发送消息给主线程
+    this.postMessage(response);
+  }
+}
+```
+
+其中 `WorkerTaskImpl` 基类定义如下：
+```uts
+/**
+ * WorkerTaskImpl
+ */
+export class WorkerTaskImpl {
+  /**
+   * 入口函数
+   * 可重写修改
+   */
+  override entry():void;
+  /**
+   * 接收主线程发送的消息
+   * 可重写修改
+   */
+  override onMessage(message: any): void;
+
+  /**
+   * 向主线程发送消息
+   */
+  postMessage(message: any, options: WorkerPostMessageOptions|null = null): void;
+}
+
+/**
+ * WorkerPostMessageOptions
+ */
+export type WorkerPostMessageOptions = {
+  /**
+   * 是否支持符合Sendable协议的对象作为共享变量发送，使用postMessageWithSharedSendable实现，默认值为false
+   * 仅鸿蒙平台支持，参考：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable
+   */
+  harmonySendable: boolean
+  /**
+   * 可转移对象数组，默认值为空数组
+   * 仅鸿蒙、web平台支持，参考：https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Transferable_objects
+   */
+  transfer: Array<any>
+}
+```
+
+
+### 4. 主线程中创建 Worker
+
+在主线程的代码中调用 `uni.createWorker` 创建并返回 Worker 对象，可通过其 `onMessage` 方法监听 Worker 子线程发送的数据，通过其 `onError` 方法监听 Worker 子线程的错误。
+
+参考以下示例代码：
+
+```uts
+// 创建 Worker 实例
+const worker = uni.createWorker('workers/HelloWorkerTask.uts');
+
+// 监听 Worker 消息
+worker.onMessage((message: any) => {
+  const messageData = message as UTSJSONObject;
+
+  console.log('收到Worker子线程数据:', messageData);
+});
+
+// 监听 Worker 错误
+worker.onError((error: WorkerOnErrorCallbackResult) => {
+  console.error('Worker子线程发生错误:', error);
+});
+```
+
+
+### 5. 主线程向 Worker 发送消息
+
+调用 `uni.createWorker` 创建并返回 Worker 对象的 `postMessage` 方法向 Worker 子线程发送数据。
+
+参考以下示例代码：
+```uts
+// 向 Worker 子线程发送消息
+worker.postMessage({
+  msg: 'message send by main!'
+});
+```
+
+### 6. harmonySendable 和 transfer 的使用
+
+仅 `HarmonyOS` 和 `Web` 支持 示例：[worker Sendable Transfer](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/pages/API/create-worker/worker-sendable-transfer.uvue)
+
+#### harmonySendable
+
+> 仅 HarmonyOS 支持。示例：[uts-worker-sendable-transfer](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/uni_modules/uts-worker-sendable-transfer/utssdk/index.uts)
+
+- 在 uts 插件的同级建立 ets 文件，导出 `Sendable` 对象 [示例](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/uni_modules/uts-worker-sendable-transfer/utssdk/sendable.ets)
+  ```ts
+  @Sendable
+  export class SendableObject {
+    a: number = 45;
+  }
+  ```
+
+- 在 uts 插件中引入 **注意引入时要有 `.ets` 后缀** [示例](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/uni_modules/uts-worker-sendable-transfer/utssdk/index.uts#L3)
+  ```uts
+  // #ifdef APP-HARMONY
+  import { SendableObject } from './sendable.ets';
+  // #endif
+  ```
+
+- 在 uts 插件中使用，向子线程发送 Sendable 对象 [示例](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/uni_modules/uts-worker-sendable-transfer/utssdk/index.uts#L41)
+  ```uts
+  workerImp.postMessage(new SendableObject())
+  ```
+
+- 在 worker 中接收到该对象后的修改会直接体现到宿主线程中
+  -  [Sendable 的修改](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/workers/sendableTransferWorker.uts#L20)
+  -   [Sendable 修改后在宿主线程的体现](https://gitcode.com/dcloud/hello-uni-app-x/blob/898db493f689b96ea6c53ab44b56e109edbe76af/pages/API/create-worker/worker-sendable-transfer.uvue#L88)
+
+#### transfer
+
+> 一个可转移对象数组。示例：[worker Sendable Transfer](https://gitcode.com/dcloud/hello-uni-app-x/blob/1f8ad2f89a765e49c447c66802999f89e81bd9d6/pages/API/create-worker/worker-sendable-transfer.uvue#L101)
+
+- Web 支持 `ArrayBuffer[]、MessagePort[]、ImageBitmap[]` 等。 [可转移对象](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Transferable_objects)
+- HarmonyOS 仅支持 `ArrayBuffer[]`
+
+::: warning 注意事项
+- HarmonyOS 平台上使用 `transfer` 后，转移的 ArrayBuffer 长度不会改变，数组本身变为在宿主线程不可用。[鸿蒙文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-worker#postmessagewithsharedsendable12)
+- Web 平台使用 `transfer` 后，转移的数组长度会变为 0。[MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/Worker/postMessage#%E8%BD%AC%E7%A7%BB%E7%A4%BA%E4%BE%8B)
+:::
+
+### 7. 结束 Worker
+
+Worker 线程不再使用需主动结束释放相关资源，调用 Worker 对象的 `terminate` 方法结束子线程。
+
+参考以下示例代码：
+```uts
+// 结束 Worker 子线程
+worker.terminate();
+```
+
+## Tips
+- `uni.createWorker` 仅支持在主线程中使用，在 Worker 子线程中使用会返回错误  
+- 各平台在 Worker 中使用全局变量或静态属性在内存管理中存在差异，Android/iOS平台可以共享内存，其它平台不能共享，为了避免这些差异带来的影响建议不要使用全局变量和静态属性  
+- Worker 子线程间暂不支持直接互相通讯，如要通讯可通过主线程中转发送消息来实现  
+- Android/iOS平台主线程与 Worker 线程传输的引用类型数据是直接共享使用（其它平台是默认为复制），需避免并发访问，暂未提供线程间安全访问机制，需通过业务逻辑控制避免并发访问这些共享的数据  
+- 鸿蒙平台主线程与 Worker 线程传输的数据默认为浅拷贝，如需传出共享对象，可在[uts插件](../plugin/uts-plugin.md)中混编开发定义[Sendable对象](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable)，调用 `Worker.postMessage` 发送这些共享对象时设置 `harmonySendable` 参数为 true  
+- Worker 中仅支持调用界面无关的API（如 uni.request、uni.getLocation 等），这些 API 触发的回调运行在 Workder 线程中  
+- Web 平台不支持在 worker 中调用 uni 上的 API  
+

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

@@ -0,0 +1,113 @@
+## dialogPage概述
+HBuilderX 4.31+新增了dialogPage，适用于制作弹框和内置界面。
+
+### 需求背景
+- uni.showModal、actionsheet，自定义性不足
+- 通过前端组件实现的弹框，无法覆盖pages.json的导航栏和tabbar
+- 前端实现的弹框，无法拦截back按键，一点back整页关了
+- 组件方式实现弹框，需要每个页面都引入组件，写法较麻烦
+- 部分内置API涉及界面但没有统一管理，比如chooseLocation、previewImage等。
+
+### dialogPage方案
+dialogPage是一种背景透明的页面，可以覆盖pages.json中的导航栏和tabbar。之前的page被称为主page或parentPage。dialogPage需要挂在主page上。
+
+dialogPage是一种特殊的page，它和主page有很多相同之处：
+- dialogPage需在pages.json注册
+- dialogPage有页面生命周期，onLoad里也可以拿到各种参数
+- dialogPage里如果引用了组件，对于组件而言，其page就是dialogPage。组合式组件中监听onPageShow，是监听dialogPage，而不是dialogPage的parentPage。
+- dialogPage可以通过uni.$on等eventbus方案进行页面级通信
+
+dialogPage和主page的区别：
+- dialogPage的背景固定为透明、大小为铺满应用。蒙层由页面内部实现，蒙层颜色、是否响应点击，均由页面内部处理。如果是模态，蒙层不应该允许点击；非模态，则点击蒙层应关闭dialogPage
+- dialogPage不使用uni.navigatorTo等路由API，而是单独提供了`openDialogPage`和`closeDialogPage`
+- dialogPage不影响页面栈和路由地址，在getCurrentPages里不能直接得到dialogPage（需在UniPage对象通过getDialogPages获取）
+- 因为dialogPage不进入主页面栈，那么`uni.getElementById`是无法获取到dialogPage内的元素的。因为uni这个全局API是获取栈顶元素。如果想获取指定页面的元素，需获取到指定页面的UniPage对象，在这个对象上使用.getElementById方法。如果想获取当前dialogPage页面的元素，应该使用 `this.$page.getElementById()(Options API)` | `getCurrentInstance()?.proxy?.$page.getElementById()(Composition API)`。
+- dialogPage在Android上并不是一个activity，而是一个全屏view，它和主page所属同一个activity。
+- dialogPage默认不响应iOS侧滑返回，即disableSwipeBack默认值为true，可以在pages.json中进行配置。响应Android和Harmony的back键和back手势，可通过dialogPage onBackPress生命周期控制是否阻止Android的back键和back手势关闭dialogPage。
+- dialogPage默认不影响调用页面或其parentPage的show、hide生命周期。如需影响，比如弹出全屏界面时，需手动设置triggerParentHide
+- dialogPage中可以调用普通路由api，比如uni.navigateTo、navigateBack，但并不作用于dialogPage，而是作用于其parentPage。即，之前的路由API均只作用于主Page。
+- 在web平台，dialogPage显示时，不影响URL的变化。
+- dialogPage默认没有窗体动画。如果是半屏内容，建议在页面内通过css或uts操作页面元素进行动画，灵活度更高。如果是全屏界面，可以使用窗体动画，但没有popin这种与上一个页面的联动动画。
+
+dialogPage的绑定：
+- dialogPage需绑定在某个主页面上，即parentPage。parentPage页面关闭时，自动销毁相关dialogPage。
+- 在app的onLaunch调用openDialogPage，绑定到首页。
+- `openDialogPage` 时可通过 `parentPage` 参数指定所属页面，不指定时默认为当前页面。
+
+多dialogPage注意事项：
+- dialogPage可以有多个，通过UniPage对象的getDialogPages()可以获取主页面挂载的所有dialogPage。
+- 多个dialogPage层叠时，可以通过close api任意关闭某个dialogPage。
+- 当前 dialogPage 打开时会触发前一个 dialogPage onHide 生命周期，关闭时会触发前一个 dialogPage onShow 生命周期。
+- `uni.showActionSheet`、`uni.showModal`、`uni.showLoading` 打开的弹框也是由 dialogPage 实现，所以调用这些 API 时，会触发前一个 dialogPage 的 onHide 生命周期，关闭对应弹框时，会触发前一个 dialogPage 的 onShow 生命周期。
+
+调用时机注意事项：
+- 最早的调用时机是在app的onLaunch里调用openDialogPage，不支持在main.uts中调用openDialogPage。
+
+app-android平台注意事项：
+- dialogPage不会创建Android原生Activity，复用parentPage的Android原生Activity。
+
+APP 蒸汽模式注意事项：
+- 蒸汽模式下，页面会默认嵌套一层 `scroll-view` 节点，详见[页面的可滚动性](https://doc.dcloud.net.cn/uni-app-x/page.html#disablescroll)。\
+如果希望页面不可滚动，可以在[pages.json](./collocation/pagesjson.md#pagesoptionspage-style)的页面Style中配置`disableScroll:true`禁用页面滚动，此配置项仅禁用页面自身的滚动，页面内的 `scroll-view` 组件不受影响。
+
+<!-- ## uni.openDialogPage(options) @opendialogpage -->
+
+<!-- UTSAPIJSON.openDialogPage.name -->
+
+<!-- UTSAPIJSON.openDialogPage.description -->
+
+<!-- UTSAPIJSON.openDialogPage.compatibility -->
+
+<!-- UTSAPIJSON.openDialogPage.param -->
+
+<!-- UTSAPIJSON.openDialogPage.returnValue -->
+
+<!-- UTSAPIJSON.openDialogPage.example -->
+
+<!-- UTSAPIJSON.openDialogPage.tutorial -->
+
+<!-- ## uni.closeDialogPage(options?) @closedialogpage -->
+
+<!-- UTSAPIJSON.closeDialogPage.name -->
+
+<!-- UTSAPIJSON.closeDialogPage.description -->
+
+`closeDialogPage` 可通过 `dialogPage` 参数指定要关闭的 `dialogPage`, 不指定时默认关闭当前页面的所有 `dialogPage`。
+
+<!-- UTSAPIJSON.closeDialogPage.compatibility -->
+
+<!-- UTSAPIJSON.closeDialogPage.param -->
+
+<!-- UTSAPIJSON.closeDialogPage.returnValue -->
+
+<!-- UTSAPIJSON.closeDialogPage.example -->
+
+<!-- UTSAPIJSON.closeDialogPage.tutorial -->
+
+<!-- UTSAPIJSON.dialogPage.example -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->
+
+## Tips
+* 可通过如下方式获取 `dialogPage`。
+```js
+// 1. 通过 parentPage 获取 dialogPage 集合
+const pages = getCurrentPages()
+// 获取当前页面
+const page = pages[pages.length-1]
+// 获取当前页面的 `dialogPage` 集合
+const dialogPages = page.getDialogPages()
+
+// 2. 在 dialogPage 中通过 this.$page 获取 dialogPage 实例 (组件中不支持)
+// 选项式 API
+const dialogPage = this.$page
+// 组合式 API
+const currentInstance = getCurrentInstance()
+const dialogPage = currentInstance?.proxy?.$page
+```
+* tabBar 页面中的 `dialogPage`，在 App 端不会随 tabBar 页面切换而隐藏，在 Web 端会随 tabBar 页面切换而隐藏。\
+即：在 tabA 页面打开 dialogPage 后 switchTab 到 tabB 页面
+在 App 端 dialogPage 仍会显示,\
+在 Web 端 dialogPage 会隐藏，再次 switchTab 到 tabA 页面 dialogPage 会显示。