tmui-cli 2.0.3 → 2.0.5

package/data/uniappx/uts/utsioshookproxy.md

@@ -0,0 +1,374 @@
+# UTSiOSHookProxy
+
+应用程序生命周期回调协议，此协议内的所有函数均由 app 调用，开发者可按需实现对应时机的回调函数。具体的使用方法[详见](https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin.html#hooksclass)
+
+## 应用程序生命周期回调函数
+
+### onCreate()
+
+uts 插件创建时的回调。<br/>此回调的准确时机对应于 OC 类的 load() 函数调用时机。
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationDidFinishLaunchingWithOptions(application, launchOptions)
+
+应用正常启动时 (不包括已在后台转到前台的情况)的回调函数。<br/>可以在此回调函数做一些初始化操作，比如初始依赖的SDK等。注意：不要在此回调函数里做耗时操作，以免影响 app 的启动速度。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| application | UIApplication | 否 | App 的 UIApplicationDelegate 对象。 |
+| launchOptions | Map\<UIApplication.LaunchOptionsKey, any> | 否 | 启动参数。默认值为 null (用户通过点击 push 通知启动应用时，该参数内会包含通知的信息) |
+
+**返回值**
+| 类型 | 描述 |
+| :- | :- |
+| boolean | 返回一个 boolean 值，正常返回true。 |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### didRegisterForRemoteNotifications(deviceToken)
+
+远程通知注册成功时的回调函数。<br/>可以在此函数里将 deviceToken 发送给服务端。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| deviceToken | Data | 否 | 设备的推送令牌 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### didFailToRegisterForRemoteNotifications(error)
+
+远程通知注册失败时的回调函数。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| error | NSError | 否 | 失败的原因。 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.18 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### didReceiveRemoteNotification(userInfo)
+
+应用收到远程通知时的回调函数。(iOS 10.0之后废弃)<br/>当应用在前台运行中，收到远程通知时(不会弹出系统通知界面)，会回调这个方法；当应用在后台状态时，点击push消息启动应用，也会回调这个方法；当应用完全没有启动时，点击push消息启动应用，就不会回调这个方法。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| userInfo | Map\<AnyHashable, any> | 否 | 收到的远程通知信息。 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.18 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### didReceiveLocalNotification(notification)
+
+应用收到本地通知时的回调函数。(iOS 10.0之后废弃)
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| notification | UILocalNotification | 否 | 接收到的本地通知 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.18 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationHandleOpenURL(application, url)
+
+通过 url scheme 方式唤起 app 时的回调函数。(iOS9 之前的系统回调此方法，iOS9 之后的系统请使用 applicationOpenURLOptions)
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| application | UIApplication | 否 | App 的 UIApplicationDelegate 对象。 |
+| url | URL | 否 | 要打开的URL资源。该资源可以是网络资源或文件。 |
+
+**返回值**
+| 类型 | 描述 |
+| :- | :- |
+| boolean | 如果成功处理请求，则为true;如果尝试打开URL资源失败，则为false。 |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationOpenURLOptions(app, url, options)
+
+通过 url scheme 方式唤起 app 时的回调函数。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| app | UIApplication | 否 |  |
+| url | URL | 否 | 要打开的URL资源。该资源可以是网络资源或文件。 |
+| options | Map\<UIApplication.OpenURLOptionsKey, any> | 否 | URL处理选项的字典, 默认值为 null 。 |
+
+**返回值**
+| 类型 | 描述 |
+| :- | :- |
+| boolean | 如果成功处理请求，则为true;如果尝试打开URL资源失败，则为false。 |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationWillResignActive(application)
+
+当应用从活动状态主动变为非活动状态的时的回调函数。
+
+**参数**
+| 名称 | 类型 | 必填 |
+| :- | :- | :- |
+| application | UIApplication | 否 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationDidBecomeActive(application)
+
+应用完全激活时的回调函数。<br/>应用程序冷启动或者从后台转到前台后都会完全激活应用程序。
+
+**参数**
+| 名称 | 类型 | 必填 |
+| :- | :- | :- |
+| application | UIApplication | 否 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationDidEnterBackground(application)
+
+应用程序进入后台时的回调函数。
+
+**参数**
+| 名称 | 类型 | 必填 |
+| :- | :- | :- |
+| application | UIApplication | 否 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationWillEnterForeground(application)
+
+当应用在后台状态，将要进入到前台运行时的回调函数。<br/>应用程序冷启动时不会回调此方法。
+
+**参数**
+| 名称 | 类型 | 必填 |
+| :- | :- | :- |
+| application | UIApplication | 否 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationMain(argc, argv)
+
+应用程序的 main 函数。
+
+**参数**
+| 名称 | 类型 | 必填 |
+| :- | :- | :- |
+| argc | Int32 | 是 |
+| argv | UnsafeMutablePointer\<UnsafeMutablePointer\<CChar> \| null> | 是 |
+
+**返回值**
+| 类型 |
+| :- |
+| void |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### applicationContinueUserActivityRestorationHandler(application, userActivity, restorationHandler)
+
+当应用程序接收到与用户活动相关的数据时调用此方法，例如，当用户使用 Universal Link 唤起应用时。
+
+**参数**
+| 名称 | 类型 | 必填 | 描述 |
+| :- | :- | :- | :- |
+| application | UIApplication | 否 | App 的 UIApplicationDelegate 对象。 |
+| userActivity | NSUserActivity | 否 | 包含与用户正在执行的任务相关联的数据的活动对象。使用这些数据来继续用户在iOS应用中的活动。 |
+| restorationHandler | (res?: \[any\]) => void | 否 | 需要执行的回调，该回调是可选的，默认值为 null。 |
+
+**返回值**
+| 类型 | 描述 |
+| :- | :- |
+| boolean | true表示你的应用处理了这个活动，false表示让iOS知道你的应用没有处理这个活动。 |
+
+**兼容性 **
+
+**uni-app x 兼容性 **
+| iOS | iOS UTS 插件 |
+| :- | :- |
+| x | 4.11 |
+
+**uni-app 兼容性 **
+| iOS UTS 插件 |
+| :- |
+| 3.97 |
+
+### 参见
+[相关 Bug](https://issues.dcloud.net.cn/?mid=uts.platformObject.UTSiOSHookProxy)

package/data/uniappx/vapor-benchmark.md

@@ -0,0 +1,9 @@
+layout: SimpleLayout
+
+文档已迁移，请前往
+
+- [vapor-benchmark-android](./benchmark/vapor-benchmark-android.md)
+- [vapor-benchmark-ios](./benchmark/vapor-benchmark-ios.md)
+- [vapor-benchmark-harmony](./benchmark/vapor-benchmark-harmony.md)
+
+查看最新文档

package/data/uniappx/vue/README.md

@@ -0,0 +1,313 @@
+# uvue概述
+
+[vue.js](https://vuejs.org/) 是流行的js框架，它提供了：
+1. 简易的模板式写法。降低使用门槛，UI和逻辑分离更清晰。
+2. 数据双向绑定。减少手写dom，diff机制提高性能。
+3. 组件机制。封装UI和逻辑，让轮子更加丰富。
+
+但 vue.js 并不支持web之外的其他平台，也不支持uts。
+
+uni-app x 为vue开发者提供了跨平台的解决方案。
+
+uni-app x 中，web平台内置了vue.js，其他平台为 DCloud 参考vue规范提供的兼容实现。
+
+在 uni-app x 中，页面和组件的文件后缀名均为 `*.uvue`。u 即 uni 的意思。
+
+页面与组件均符合vue的单文件组件规范，只不过页面需要在pages.json中注册且多了一批生命周期和API。
+
+在非web平台，uvue 尽可能拉齐了vue.js的功能，但仍有些不常用的功能暂未提供，需注意查看相关文档的兼容性。同时 uvue 也新增了 [easycom](./component.md#easycom) 等技术，简化组件的使用。
+
+hello uvue 是非常重要的vue示例，演示了各种vue功能的应用。
+
+- 插件地址：[https://ext.dcloud.net.cn/plugin?id=15021](https://ext.dcloud.net.cn/plugin?id=15021)
+- 源码地址：[https://gitcode.com/dcloud/hello-uvue](https://gitcode.com/dcloud/hello-uvue)，注意有master和alpha分支，对应HBuilderX最新的正式版和alpha版。
+
+# 版本对应@ver
+HBuilderX/uni-app x，会跟踪vue版本的升级，版本映射表如下
+
+|HBuilderX	|vue版本	|
+|--	|--	|
+|4.14	|3.4	|
+
+# 页面/组件内容构成@sfc
+
+一个 uvue 页面/组件，符合vue单文件组件规范（SFC），有3个根节点标签：
+
+1. 模板组件区 `<template>`
+2. 脚本区 `
+
+<style>
+	.content {
+		width: 750rpx;
+	}
+</style>
+```
+
+可以看出整体和html还是很接近的。但响应式变量和绑定机制，可以免去写大量的dom操作代码，让开发更高效轻松。
+
+## template
+
+template中文名为`模板`，它类似html的标签。但有2个区别：
+
+1. html中 `script` 和 `style` 是 html 的二级节点。但在 uvue 文件中，`template`、`script`、`style` 这3个是平级关系。
+2. html 中写的是 web 标签，但 vue 的 `template` 中写的全都是 vue 组件（包括[内置基础组件](../component/README.md)、自定义前端uvue组件、[uts原生插件组件](../plugin/uts-component.md)），每个组件支持属性、事件、vue 指令，还可以绑定 vue 的 data 数据。
+
+组件，即component，是vue中非常重要的概念，或者说现代开发框架都离不开组件概念。
+
+我们知道js逻辑可以封装为函数或类库。而对于页面上可视的元素，则可以将ui、样式、逻辑一起封装为组件。详见[uvue组件规范](./component.md)
+
+在 uni-app x 中， `<view>`是最基本的视图容器组件，`<text>`则是文字组件，`<button>`是按钮组件。这些都是[内置组件](../component/README.md)
+
+一个页面或组件只能有一个template标签，template下面可以有多个二级节点，即多个根组件。如下：
+
+```vue
+<template>
+	<view>
+		<text v-if="titleShow" :style="'color:' + titleColor">{{title}}</text> 
+	</view>
+	<scroll-view >
+		<button @click="buttonClick_changeText" type="primary">修改文字内容</button>
+		<button @click="buttonClick_showHide">点击让文字组件显示或消失</button>
+		<button @click="buttonClick_changeColor">修改文字颜色</button>
+	</scroll-view>
+</template>
+
+```
+
+组件有很多概念，属性、事件、指令。如果还不了解相关概念，请参阅 [组件介绍](../compiler/README.md)
+
+## script
+
+script中编写逻辑代码。
+uvue文件中只能有一个script标签。
+
+script标签有2个属性，lang和setup。
+
+```vue
+
+```
+
+### 选项式API
+选项式 API，也称 Option API，指在script中写`export default {}`，在其中通过多个选项的对象来定义data、method和生命周期。选项所定义的属性都会暴露在函数内部的 this 上，它会指向当前的组件实例。
+
+以下代码的逻辑与上一章节组合式API的示例相同，只是写法改成了选项式写法。
+
+```vue
+<template>
+	<view>
+		<button @click="buttonClick">{{title}}</button>
+	</view>
+</template>
+
+```
+
+对比之前组合式的、相同业务逻辑的代码，可以看到两种方式的差异：
+1. 选项式由于有框框的存在，看起来结构清晰些，但代码行数也更长
+2. 组合式更灵活，代码更短。高级开发者也可以自己保证代码结构的清晰整洁。但初学者如果代码写的很长，容易乱糟糟
+
+上述代码比较简单，如果涉及到响应式变量的类型定义，那么会更明显的感受到组合式的灵活和简洁。
+
+#### `export default` 外的代码@export-default-out
+
+选项式主代码在`export default {}`里。但既然有`export default {}`里的代码，那么就有 `export default {}` 外面的代码。
+
+写在外面一般有几种情况：
+
+1. 引入第三方 uts 模块
+2. 引入非 easycom 的组件（一般组件推荐使用[easycom](./component.md#easycom)，无需导入注册）
+3. 定义 type，对 data 进行类型定义
+4. 定义作用域更大的变量
+
+```html
+
+```
+
+开发者应谨慎编写 `export default {}` 外面的代码，这里的代码有2个注意事项：
+
+1. 影响应用性能。不管写在哪个页面，这部分代码都在应用启动时执行，而不是页面加载。如果`export default {}`外的代码写的太复杂，会影响应用启动速度，占用更多内存。
+2. 不跟随组件、页面关闭而回收。在外层的静态变量不会跟随页面关闭而回收。如果必要，你需要手动处理。比如 `unmounted` 或 `onUnload` 生命周期进行处理。
+
+### JSX/TSX
+
+uni-app x 除web平台外，其他平台不支持使用 JSX/TSX 编写页面和组件，请使用 Vue 的 `template` 模板语法。
+
+在 App 端蒸汽模式下，视图层代码，即 Vue 文件中 `template` 和 `style` 内的代码，会在编译期进行静态分析，并直接编译为高度优化的机器码或字节码，它的运行速度远快于arkts、kotlin及k/n。
+
+JSX/TSX 是编写在 JavaScript/TypeScript 中的表达式语法，目前不支持将 JSX/TSX 编译为与 `template` 相同的高性能机器码或字节码，为了发挥 App 端蒸汽模式的视图层性能优势时，应使用 `template` 和 `style` 编写视图代码。
+
+## style（CSS功能） @css
+
+style的写法与web的css基本相同。但在App端，由于并非webview渲染，支持的css是子集。[详见](../css/README.md)
+
+本章节重点讲解uvue下样式的使用注意事项。
+
+一个页面/组件允许有多个style标签。
+
+style通过lang属性，可以支持less、scss、stylus等css预处理语言。
+
+### style 标签 @style
+
+##### 兼容性 
+| Web | 微信小程序 | Android | iOS | HarmonyOS |
+| :- | :- | :- | :- | :- |
+| 4.0 | √ | 3.9 | 4.11 | 4.61 |
+
+##### 属性 
+| 名称 | 类型 | 兼容性 |
+| :- | :- |  :-: |
+| lang | string | Web 4.0 / 微信小程序 √ / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 |
+| 合法值 | 兼容性 |
+| :- |  :-: |
+| scss | Web 4.0 / 微信小程序 √ / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 |
+| less | Web 4.0 / 微信小程序 √ / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 |
+| stylus | Web 4.0 / 微信小程序 √ / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 |
+| scoped | boolean | Web 4.0 / 微信小程序 x / Android x / iOS x / HarmonyOS x（部分支持，见上） |
+| module | Any | Web 4.0 / 微信小程序 x / Android x / iOS x / HarmonyOS x（部分支持，见上） |
+
+##### 参见
+
+### Class 与 Style 绑定 @class-style
+
+- `uni-app x` 在VDOM模式下支持绑定  `UTSJSONObject` 和 `Map` 类型数据。蒸汽模式不支持 `Map` 类型数据。
+- VDOM模式下，在App-Android平台上 `Map` 的性能高于 `UTSJSONObject` 数据类型。从 `uni-app x 4.01` 起，Web平台在uts2js时也支持了 `Map` 类型绑定。
+
+如下示例中，给 view 组件的 style 和 class 分别绑定了两个响应式变量，就可以通过在逻辑代码里修改变量而实现动态修改样式。
+```vue
+<template>
+  <view>
+    <view :style="styleMap" :class="classMap"></view>
+  </view>
+</template>
+
+<style lang="scss" scoped>
+  .w-100 {
+    width: 100px;
+  }
+  .h-100 {
+    height: 100px;
+  }
+  .rounded {
+    border-radius: 8px;
+  }
+</style>
+```
+
+- [参见](https://uniapp.dcloud.net.cn/tutorial/vue3-basics.html#class-%E4%B8%8E-style-%E7%BB%91%E5%AE%9A)
+
+### 深度选择器 @scoped
+
+什么是 scoped CSS？
+
+参考 Vue 文档了解 [组件作用域 CSS](https://cn.vuejs.org/api/sfc-css-features.html) 基本用法。
+
+> 处于 `scoped` 样式中的选择器如果想要做更“深度”的选择，也即：影响到子组件，可以使用 `:deep()` / `::v-deep` 方案：
+
+```vue
+<style scoped>
+.a :deep(.b) {
+  /* ... */
+}
+
+.a ::v-deep .b {
+	/* ... */
+}
+</style>
+```
+
+在 uni-app x 项目中，深度选择器 `:deep()` / `::v-deep` 只在 Web 平台生效。
+
+但一般推荐使用[uni-app x样式隔离策略2.0](../css/common/style-isolation.md)，而不是深度选择器。
+
+如果使用样式隔离策略1.0，需注意如下：
+- 在 Web 平台，uni-app x 中 style 会自动添加 `scoped`（因为web端最终是编译成单页应用SPA，需要隔离不同页面间的样式），因此需要使用深度选择器，来影响子组件样式。
+- 微信小程序、App 平台页面可直接影响子组件，添加 scoped、使用深度选择器无意义
+
+HBuilderX 4.71 起，App 端可以使用深度选择器控制台不再告警，视为后代选择器。
+
+### CSS 中的 v-bind() @css-v-bind
+
+|App|Web|
+|:-:|:-:|
+|x  |4.13+  |
+
+[示例](./data-bind.md#v-bind-css-data)
+
+单文件组件的 `<style>` 标签支持使用 `v-bind` CSS 函数将 CSS 的值链接到动态的组件状态：
+
+选项式写法：
+
+```vue
+<template>
+  <text class="text">hello</text>
+</template>
+
+<style>
+.text {
+  color: v-bind(color);
+}
+</style>
+```
+
+组合式写法： `
+
+<template>
+  <text class="view">hello</text>
+</template>
+
+<style scoped>
+.view {
+  color: v-bind('theme.color');
+}
+</style>
+```
+
+## 利用AI将选项式转换为组合式@ai
+
+推荐使用[uni-agent](https://doc.dcloud.net.cn/uni-app-x/ai/)，可以直接转换选项式代码为组合式代码，并自动监控控制台报错然后自动修复。\
+官方的很多页面如 hello uni-app x，都是这样转的。
+
+如果您使用其他AI，可以使用下面的提示词：
+
+把本项目下的页面改成组合式写法
+1. 在进行“选项式 API → 组合式 API”改造时，只做语法层面的转换，保证代码不报错，避免引入业务逻辑变更。
+2. 在改造过程中，不要删除或遗漏任何已有代码和注释，确保代码完整性。
+3. 在组合式 API 中，必须保证所有函数和变量在调用前已定义，如顺序不对，要根据依赖关系调整函数定义顺序，避免未定义前调用。
+4. 在组合式 API 中，不需要 import 所有 vue 的 API 和 uni-app-x 的生命周期函数（如 `ref、computed、watch、onLoad、onMounted` 等），uni-app x 会自动引入。
+5. 在选项式 API 中的 `onShow、onHide` 页面生命周期，改为组合式 API 时，分别改成 `onPageShow、onPageHide`。
+6. 在组件生命周期兼容性方面，选项式 API 的 `beforeUnmount、mounted、unmounted`，改为组合式 API 时，分别改成 `onBeforeUnmount、onMounted、onUnmounted`，避免生命周期名称不一致；选项式 API 的 created 改为组合式的 `<script setup>` 顶层代码直接执行。
+7. 在使用 ref 时
+- 如果引用内置组件（例如：scroll-view、swiper、slider等），类型应为：Uni组件名(驼峰)Element，例如 `<slider>` 组件类型为 `UniSliderElement`，声明为 `const sliderRef = ref<UniSliderElement | null>(null)`；避免类型错误，错误示例：swiper上的ref写成了`const swiper = ref<UniElement|null>(null)`。
+- 如果引用内置 DOM 元素（例如：view、text），类型为 `ref<UniElement|null>(null)` 或 `ref<UniElement[]|null>(null)`；
+- 如果引用自定义组件，类型为 `ref<ComponentPublicInstance|null>(null)` 或 `ref<ComponentPublicInstance[]|null>(null)`，避免类型声明错误。
+8. 在组合式 API 中，每个 ref 要单独声明，变量名与模板 ref 保持一致，直接用 `xxx.value` 访问，避免变量名与 import 的组件名重复，否则会报错。
+9. 在组合式 API 下，子组件方法不会自动暴露给父组件，只有通过 `defineExpose` 显式暴露的方法，父组件才能通过 ref 调用，避免父组件无法访问子组件方法。
+10. 在测试例页面用到页面中的数据或方法时，必须通过 `defineExpose` 显式暴露数据和方法，避免测试无法访问。
+11. 在页面生命周期中，`onPullDownRefresh` 应作为页面生命周期函数处理，而不是写成普通方法。
+12. 检查控制台的编译报错，如果有报错自行修复，并再次检查编译报错，直到无报错编译通过。
+
+## 利用 AI 适配蒸汽模式@ai-vapor
+
+下面提示词用于把已有 uni-app x 页面适配到蒸汽模式。
+
+把本项目下的页面适配为可用于蒸汽模式的写法
+
+1. 只做蒸汽模式兼容适配和必要的组合式改造，避免引入业务逻辑变更。
+2. 不要删除或遗漏任何已有代码、注释、测试入口和外部调用链路；确实需要调整时，保持原有功能等价。
+3. 蒸汽模式仅支持组合式 API。如果页面仍使用选项式 API，先转换为 `<script setup>` 组合式写法，再继续处理蒸汽模式兼容。
+4. 在组合式 API 中，保证所有函数和变量在调用前已定义；如定义顺序不合理，按依赖关系调整顺序，避免未定义前调用。
+5. 在组合式 API 中，不需要 import 所有 Vue API 和 uni-app x 生命周期函数，例如 `ref`、`reactive`、`computed`、`watch`、`onLoad`、`onMounted` 等，uni-app x 会自动引入；不要额外引入无必要的 import。
+6. 选项式 API 中的 `onShow`、`onHide` 页面生命周期，改为组合式 API 时分别使用 `onPageShow`、`onPageHide`。
+7. 选项式 API 中的 `beforeUnmount`、`mounted`、`unmounted`，改为组合式 API 时分别使用 `onBeforeUnmount`、`onMounted`、`onUnmounted`；`created` 的逻辑放到 `<script setup>` 顶层执行。
+8. 页面生命周期 `onPullDownRefresh` 不要当作普通方法处理；如果蒸汽模式当前平台不支持页面下拉刷新，改为使用页面内 `scroll-view` 等可兼容方案，并保持交互等价。
+9. 子组件方法、页面测试入口或外部需要访问的数据和方法，必须通过 `defineExpose` 显式暴露，避免父组件、测试用例或外部调用失效。
+10. 不要继续使用 `mixin`，将其中的数据、计算逻辑、方法和生命周期合并到当前组件的组合式代码中，或抽成普通 composable 函数。
+11. 检查模板中蒸汽模式不支持或行为变化的写法，按项目现有规范改成兼容写法，保持页面结构和交互不变。
+12. 检查 `scroll-view`、`swiper` 等组件的布尔属性；不要依赖旧默认值，按页面实际需要显式补齐 `true` 或 `false`，避免行为变化。
+13. 检查 `list-view` / `list-item`：用于复用的 `list-item` 循环必须有稳定 `:key`；`list-view` 和需要复用的 `list-item` 应在同一个 uvue 文件内；`list-item` 内文本必须使用 `text` 包裹；不要依赖横向滚动、`margin` 等不兼容能力。
+14. 检查 `swiper` 相关页面：如依赖内容高度、指示器样式或 `swiper-item` 定位，按蒸汽模式支持的属性和插槽调整，避免显示异常。
+15. 检查 CSS 选择器，避免运行时依赖复杂关系选择器；将 `.parent .child`、深层后代选择器等改为明确的 class 命名，优先使用 BEM 风格表达层级关系。
+16. 可以保留 SCSS 等编译期写法，但最终运行时应落到蒸汽模式支持的简单 class 选择器或分组选择器。
+17. 检查组件样式隔离影响。外部页面或全局样式不要默认假设能影响组件内部同名 class；如组件确实需要受外部样式影响，在 `<script setup>` 中通过 `defineOptions` 设置合适的 `styleIsolation`，并说明原因。
+18. 调整样式时保持视觉效果尽量一致，不要借适配蒸汽模式的机会重构设计或改动无关样式。
+19. 改造后检查控制台编译报错和运行时报错；如果有报错，自行修复并再次检查，直到无报错编译通过。
+20. 适配完成后，列出本次修改点、涉及的蒸汽模式差异，以及仍需人工在真机或目标平台确认的行为。