tmui-cli 5.3.1 → 5.3.3

package/data/uni-app-x-docs/vue/README.md

@@ -178,15 +178,18 @@ VDOM模式lang的值域只有uts。Android平台按uts2kt执行，此时要求
 	`JSON.parseArray`、`JSON.parseObject`在非uts环境下也无法使用，使用`JSON.parse`方法代替即可。
 
 	undefined转null的js内置API：
-		* Array.prototype.pop
-		* Array.prototype.shift
-		* Array.prototype.find
-		* Array.prototype.findLast
-		* Array.prototype.at
-		* Map.prototype.get
-		* WeakMap.prototype.get
-		* String.prototype.at
-		* String.prototype.codePointAt
+	
+		```js
+		Array.prototype.pop
+		Array.prototype.shift
+		Array.prototype.find
+		Array.prototype.findLast
+		Array.prototype.at
+		Map.prototype.get
+		WeakMap.prototype.get
+		String.prototype.at
+		String.prototype.codePointAt
+		```
 
 5.31+，不同后缀的文件，比如`*.js`、`*.ts`、`*.uts`，互相import的时，都按各自独立的编译器编译。
 
@@ -400,7 +403,7 @@ style通过lang属性，可以支持less、scss、stylus等css预处理语言。
   </view>
 </template>
 
-<script setup lang="uts">
+<script setup lang="ts">
   const styleMap = ref(new Map<string, string>([['border', '2px solid red'], ['background-color', 'green']]))
   const classMap = ref(new Map<string, boolean>([['w-100', true], ['h-100', true], ['rounded', false]]))
 </script>
@@ -576,7 +579,10 @@ const theme = {
 9. 在组合式 API 下，子组件方法不会自动暴露给父组件，只有通过 `defineExpose` 显式暴露的方法，父组件才能通过 ref 调用，避免父组件无法访问子组件方法。
 10. 在测试例页面用到页面中的数据或方法时，必须通过 `defineExpose` 显式暴露数据和方法，避免测试无法访问。
 11. 在页面生命周期中，`onPullDownRefresh` 应作为页面生命周期函数处理，而不是写成普通方法。
-12. 检查控制台的编译报错，如果有报错自行修复，并再次检查编译报错，直到无报错编译通过。
+12. 组合式写法不支持 `mixins` 选项：
+- 选项中若使用了 `mixins: [...]`，必须去掉，把 mixin 提供的 data、computed、watch、methods 和生命周期合并进当前组件的组合式代码，或抽成普通 composable 函数；
+- 若使用了 `uniCloud.mixinDatacom`，改用其对应的组合式 API：用 `const props = defineProps({ ...uniCloud.datacomProps })` 展开内置 props，再 `const datacom = uniCloud.useDatacom(props)` 创建实例并调用 `datacom.easyGet({})`，模板改用 `datacom.resData`/`datacom.loading`/`datacom.errorMessage`（不用 `.value`），不要手动拷贝其内部实现；注意：`uniCloud.useDatacom` 从 HBuilderX 5.32 版本起才支持，且仅在项目已关联 uniCloud 服务空间时可用，使用前需先关联服务空间。
+13. 检查控制台的编译报错，如果有报错自行修复，并再次检查编译报错，直到无报错编译通过。
 
 ## 利用 AI 适配蒸汽模式@ai-vapor
 
@@ -593,7 +599,9 @@ const theme = {
 7. 选项式 API 中的 `beforeUnmount`、`mounted`、`unmounted`，改为组合式 API 时分别使用 `onBeforeUnmount`、`onMounted`、`onUnmounted`；`created` 的逻辑放到 `<script setup>` 顶层执行。
 8. 页面生命周期 `onPullDownRefresh` 不要当作普通方法处理；如果蒸汽模式当前平台不支持页面下拉刷新，改为使用页面内 `scroll-view` 等可兼容方案，并保持交互等价。
 9. 子组件方法、页面测试入口或外部需要访问的数据和方法，必须通过 `defineExpose` 显式暴露，避免父组件、测试用例或外部调用失效。
-10. 不要继续使用 `mixin`，将其中的数据、计算逻辑、方法和生命周期合并到当前组件的组合式代码中，或抽成普通 composable 函数。
+10. 不要继续使用 `mixin`：
+- 普通 `mixins: [...]` 必须去掉，把 mixin 提供的 data、computed、watch、methods 和生命周期合并进当前组件的组合式代码，或抽成普通 composable 函数；
+- 若使用了 `uniCloud.mixinDatacom`，改用其对应的组合式 API：用 `const props = defineProps({ ...uniCloud.datacomProps })` 展开内置 props，再 `const datacom = uniCloud.useDatacom(props)` 创建实例并调用 `datacom.easyGet({})`，模板改用 `datacom.resData`/`datacom.loading`/`datacom.errorMessage`（不用 `.value`），不要手动拷贝其内部实现；注意：`uniCloud.useDatacom` 从 HBuilderX 5.32 版本起才支持，且仅在项目已关联 uniCloud 服务空间时可用，使用前需先关联服务空间。
 11. 检查模板中蒸汽模式不支持或行为变化的写法，按项目现有规范改成兼容写法，保持页面结构和交互不变。
 12. 检查 `scroll-view`、`swiper` 等组件的布尔属性；不要依赖旧默认值，按页面实际需要显式补齐 `true` 或 `false`，避免行为变化。
 13. 检查 `list-view` / `list-item`：用于复用的 `list-item` 循环必须有稳定 `:key`；`list-view` 和需要复用的 `list-item` 应在同一个 uvue 文件内；`list-item` 内文本必须使用 `text` 包裹；不要依赖横向滚动、`margin` 等不兼容能力。

package/data/uni-app-x-docs/vue/built-in.md

@@ -622,14 +622,10 @@
   export default {
     components: { Foo },
     mounted() {
-      // #ifdef APP
-      (this.$refs['input'] as UniInputElement).setAttribute('value', 'input value');
-      // #endif
-      // #ifdef WEB
-      (this.$refs['input'] as UniInputElement).value = 'input value';
-      // #endif
+      // 通过元素引用修改样式
+      (this.$refs['input'] as UniElement).style.setProperty('background-color', '#f0f0f0');
       // 当在 v-for 中使用模板引用时，this.$refs 中对应的值是一个数组
-      (this.$refs['textItems'] as UniTextElement[]).forEach((item : UniTextElement) => {
+      (this.$refs['textItems'] as UniElement[]).forEach((item : UniElement) => {
         item.style.setProperty('color', 'red')
       });
       // 调用自定义组件方法
@@ -642,8 +638,8 @@
 
 <template>
   <view>
-    <input ref="input" />
-    <text v-for="item in 3" ref="textItems" :key="item">{{
+    <input id="input" ref="input" />
+    <text v-for="item in 3" :id="'text-item-' + item" ref="textItems" :key="item">{{
       item
     }}</text>
     <Foo ref="foo" />
@@ -652,39 +648,67 @@
 ```
 `this.$refs` 也是非响应式的，因此你不应该尝试在模板中使用它来进行数据绑定。
 
+对应的 `Foo` 组件（选项式 API）：
+
+```vue
+<!-- components/Foo.uvue -->
+<template>
+  <view>
+    <text>title: {{title}}</text>
+  </view>
+</template>
+
+<script lang="uts">
+  export default {
+    name: "Foo",
+    data() {
+      return {
+        title: 'default title'
+      }
+    },
+    methods: {
+      updateTitle() {
+        this.title = 'new title'
+      }
+    }
+  }
+</script>
+```
+
 使用组合式 API，引用将存储在与名字匹配的 ref 里：
 ```vue
-<script setup lang="uts">
+<script setup lang="ts">
   import Foo from '@/components/Foo.uvue'
 
   // 声明一个 ref 来存放该元素的引用, 必须和模板里的 ref 同名
+  // #ifndef MP
   const input = ref<UniInputElement | null>(null)
+  // #endif
+  // #ifdef MP
+  const input = ref<UniElement | null>(null)
+  // #endif
   // 当在 v-for 中使用模板引用时，对应的 ref 中包含的值是一个数组
-  const textItems = ref<UniTextElement[] | null>(null)
+  const textItems = ref<UniElement[] | null>(null)
   // 声明一个 ref 来存放自定义组件的引用, 必须和模板里的 ref 同名
   const foo = ref<ComponentPublicInstance | null>(null)
 
   onMounted(() => {
-    // #ifdef APP
-    input.value!.setAttribute('value', 'input value')
-    // #endif
-    // #ifdef WEB
-    input.value!.value = 'input value'
-    // #endif
-    textItems.value!.forEach((item: UniTextElement) => {
+    // 通过元素引用修改样式
+    input.value!.style.setProperty('background-color', '#f0f0f0')
+    textItems.value!.forEach((item: UniElement) => {
       item.style.setProperty('color', 'red')
     })
     // 调用自定义组件方法
     foo.value!.$callMethod('updateTitle')
-    // 获取自定义组件响应式数据
-    console.log(foo.value!.$data['title']) // new title
+    // 通过公开方法获取自定义组件响应式数据
+    console.log(foo.value!.$callMethod('getTitle')) // new title
   })
 </script>
 
 <template>
   <view>
-    <input ref="input" />
-    <text v-for="item in 3" ref="textItems" :key="item">{{
+    <input id="input" ref="input" />
+    <text v-for="item in 3" :id="'text-item-' + item" ref="textItems" :key="item">{{
       item
     }}</text>
     <Foo ref="foo" />
@@ -692,6 +716,8 @@
 </template>
 ```
 
+对应的 `Foo` 组件（组合式 API），通过 `defineExpose` 暴露供父组件调用的方法：
+
 ```vue
 <!-- components/Foo.uvue -->
 <template>
@@ -700,27 +726,28 @@
   </view>
 </template>
 
-<script>
-  export default {
-    name:"Foo",
-    data() {
-      return {
-        title: 'default title'
-      }
-    },
-    methods: {
-      updateTitle(){
-        this.title = 'new title'
-      }
-    }
+<script setup lang="ts">
+  const title = ref('default title')
+
+  const updateTitle = () => {
+    title.value = 'new title'
+  }
+
+  const getTitle = (): string => {
+    return title.value
   }
+
+  defineExpose({
+    updateTitle,
+    getTitle
+  })
 </script>
 ```
 
 #### 获取内置组件与自定义组件的区别
-- 使用 `ref` 获取内置组件实例时会获取到对应的 `Element`，例如上述代码示例中，`input` 组件获取到的是 `UniInputElement`, `text` 组件获取到的是 `UniTextElement`，可以调用 `Element` 的方法和属性。
+- App、Web 使用 `ref` 获取内置组件实例时会获取到对应的 `Element`，例如上述代码示例中，`input` 组件获取到的是 `UniInputElement`, `text` 组件获取到的是 `UniTextElement`，可以调用 `Element` 的方法和属性。
 - 使用 `ref` 获取自定义组件实例时会获取到对应的 vue 组件实例，例如上述代码示例中，`Foo` 组件获取到的是 `ComponentPublicInstance`，可以获取自定义组件的属性或调用方法，[详情](./component.md#page-call-component-method)。
-- 小程序平台如果期望使用`ref`获取到`UniElement`需要在此`UniElement`上设置id，此外小程序平台的`UniElement`使用是受限的，详情参考：[UniElement](../mp/README.md#unielement)
+- 小程序平台使用 `ref` 获取内置组件引用时，需要为节点设置 `id`，`v-for` 中各节点的 `id` 应保持唯一。小程序仅支持 `UniElement`，不支持 `UniInputElement`、`UniTextElement` 等类型，且可用的属性和方法受限，详情参考：[UniElement](../mp/README.md#unielement)。
 
 
 ### is

package/data/uni-app-x-docs/vue/component.md

@@ -534,6 +534,8 @@ defineOptions({
 ```
 这个 `$attrs` 对象包含了除组件所声明的 `props` 和 `emits` 之外的所有其他 attribute，例如 `class`，`style`，`v-on` 监听器等等。
 
+uni-app x 编译到小程序时，`v-bind="$attrs"` 的显式透传范围存在限制，详见[文档](../mp/README.md#v-bind-attrs)。
+
 有几点需要注意：
 
 - 和 `props` 有所不同，透传 attributes 在 JavaScript 中保留了它们原始的大小写，所以像 `foo-bar` 这样的一个 attribute 需要通过 `$attrs['foo-bar']` 来访问。
@@ -680,7 +682,7 @@ defineOptions({
   </view>
 </template>
 
-<script setup lang="uts">
+<script setup lang="ts">
   // import componentA from './component-a' // 错误用法
   defineOptions({
     name: "component-a"

package/data/uni-app-x-docs/vue/composition-api.md

@@ -444,7 +444,7 @@ watch(
 :::
 
 ```uts
-<script setup lang="uts">
+<script setup lang="ts">
 // 通过 getCurrentInstance 获取当前 UniPage 对象
 const instance = getCurrentInstance()!.proxy!
 const currentPage = instance.$page

package/data/uni-app-x-docs/web/ssr.md

@@ -43,18 +43,20 @@ export default defineConfig({
 
 **示例**
 
-```ts
+下面示例假设 `@/store/index.uts` 已导出 `useItemsStore`，包含按 ID 保存数据的 `items` 状态和异步 `fetchItem(id)` 方法。SSR 配置见下方 [Pinia](#pinia) 章节。
+
+```vue
 <template>
   <text v-if="item">{{ item.title }}</text>
   <text v-else>...</text>
 </template>
 
-<script setup lang="uts">
-  import { useStore } from 'vuex'
+<script setup lang="ts">
+  import { useItemsStore } from '@/store/index.uts'
 
   const id = 1 // 模拟ID
-  const store = useStore()
-  const item = computed(() => store.state.items[id])
+  const store = useItemsStore()
+  const item = computed(() => store.items[id])
 
   onMounted(() => { // 仅客户端执行的生命周期
     if (!item.value) { // 判断服务端是否已正常获取，若未获取，重新调用加载数据
@@ -67,7 +69,7 @@ export default defineConfig({
   })
 
   function fetchItem() {
-    return store.dispatch('fetchItem', id)
+    return store.fetchItem(id)
   }
 </script>
 ```
@@ -80,101 +82,35 @@ export default defineConfig({
 const categories = ssrRef(['c1', 'c2'], 'categories');
 ```
 
-#### vuex
+#### Pinia
 
-对于复杂的数据，如需保持云端客户端一致，建议使用vuex进行存储。下面是一个简单的示例：
+Pinia 的引入和 store 定义见[全局变量与状态管理](../tutorial/store.md#pinia)。SSR 时需为每次请求创建独立的 Pinia 实例，并返回以下 `store` 适配对象，以同步服务端和客户端状态：
 
 **main.uts**
 
 ```ts
 import { createSSRApp } from 'vue'
+import { createPinia } from 'pinia'
+import type { StateTree } from 'pinia'
 import App from './App.uvue'
-import createStore from './store'
+
 export function createApp() {
   const app = createSSRApp(App)
-
-  const store = createStore() // 创建 store
-  app.use(store)
+  const pinia = createPinia()
+  app.use(pinia)
 
   return {
     app,
-    store,// 必须返回 store
-  }
-}
-```
-
-**store/index.uts**
-
-```ts
-import { createStore } from 'vuex'
-
-// 模拟接口获取数据
-function fetchItem(id) {
-  return new Promise((resolve) => {
-    setTimeout(() => {
-      resolve({
-        id,
-        title: 'title' + id,
-      })
-    }, 300)
-  })
-}
-
-export default () => {
-  return createStore({
-    state() {
-      return {
-        items: {},
-      }
-    },
-    actions: {
-      fetchItem({ commit }, id) {
-        return fetchItem(id).then((item) => {
-          commit('setItem', { id, item })
-        })
+    store: {
+      get state() {
+        return pinia.state.value
       },
-    },
-    mutations: {
-      setItem(state, { id, item }) {
-        state.items[id] = item
+      replaceState(state: Record<string, StateTree>) {
+        pinia.state.value = state
       },
     },
-  })
-}
-```
-
-**pages/index/index.uvue**
-
-```vue
-<template>
-  <text v-if="item">{{ item.title }}</text>
-  <text v-else>...</text>
-  <text>{{ JSON.stringify(categories) }}</text>
-</template>
-
-<script setup lang="uts">
-  import { ssrRef } from '@dcloudio/uni-app'
-  import { useStore } from 'vuex'
-
-  const categories = ssrRef(['c1', 'c2'], 'categories')
-  const id = 1 // 模拟ID
-  const store = useStore()
-  const item = computed(() => store.state.items[id])
-
-  onMounted(() => { // 仅客户端执行的生命周期
-    if (!item.value) { // 判断服务端是否已正常获取，若未获取，重新调用加载数据
-      fetchItem()
-    }
-  })
-
-  onServerPrefetch(async () => { // 服务端预取数据的生命周期
-    await fetchItem()
-  })
-
-  function fetchItem() {
-    return store.dispatch('fetchItem', id)
   }
-</script>
+}
 ```
 
 #### page-meta
@@ -278,7 +214,7 @@ uni-app-x内page-meta仅保留了存放head的功能，page-meta内的head节点
 
 ### 注意事项
 
-- 浏览器控制台提示如下警告，说明服务器和客户端渲染的结果不一致，检查模板绑定的属性是否使用了 `ssrRef`
+- 浏览器控制台提示如下警告，说明服务器和客户端渲染的结果不一致，检查模板绑定的状态是否通过 `ssrRef` 或上述 Pinia SSR 方式同步
 
 ```
 [Vue warn]: Hydration node mismatch:

package/data/uniappx/_sidebar.md

@@ -83,9 +83,10 @@
 * [暗黑模式](api/theme-change.md)
 * [宽屏适配](adapt.md)
 * [国际化](i18n.md)
-* [源码和示例](sample.md)
+* [案例和开源示例](sample.md)
 * [兼容性表格导读](tutorial/compatibility.md)
 * 选型参考
+	* [AI时代还需要跨平台框架吗？](./select/crossplatform-on-ai.md)
 	* [一文讲透原生渲染和自渲染](./select/native-render-and-self-render.md)
 	* [uni-app x和uni-app的对比](./uniappvsuniappx.md)
 * [uni-app 升级 uni-app x](uniapptox.md)
@@ -126,6 +127,7 @@
     * [安卓、鸿蒙厂商推送配置](uni-push/vendor_config.md)
     * [谷歌FCM配置](uni-push/google-fcm.md)
   * [uni统计](https://uniapp.dcloud.net.cn/uni-stat-uniappx)
+  * [App升级中心](https://doc.dcloud.net.cn/uniCloud/upgrade-center.html)
 * 教程
 	* [性能优化](performance.md)
 	* [复杂列表开发指南](tutorial/stickynestlist.md)

package/data/uniappx/api/_sidebar.md

@@ -5,6 +5,7 @@
   * [动画帧](animation-frame.md)
   * [Path2D](path2d.md)
   * [Image](image.md)
+  * [UniResizeObserver](uniresizeobserver.md)
 * 基础
   * [环境变量](env.md)
   * [事件总线](event-bus.md)
@@ -28,6 +29,7 @@
   * [设置tabBar](set-tab-bar.md)
   * [页面下拉刷新](pull-down-refresh.md)
   * [将页面滚动到指定位置](page-scroll-to.md)
+  
   * [监听中间按钮的点击事件](on-tab-bar-mid-button-tap.md)
   * [窗口](window.md)
   * [宽屏适配](wide-screen-adaptation.md)
@@ -81,6 +83,8 @@
   * [安装 APK](install-apk.md)
   * [监听权限申请](create-request-permission-listener.md)
   * [请求系统权限](request-system-permission.md)
+  * [蓝牙-通用](bluetooth-general.md)
+  * [蓝牙-低功耗中心设备](bluetooth-le-central.md)
 * 媒体
   * [拍照或从相册选择图片](choose-image.md)
   * [图片预览](preview-image.md)
@@ -101,6 +105,7 @@
   * [获取文件管理器](get-file-system-manager.md)
   * [打开文档](open-document.md)
   * [选择文件](choose-file.md)
+  * [转换为绝对路径](convert2-abs-full-path.md)
 * 数据存储
   * [key-value本地数据存储](storage.md)
 * 画布
@@ -121,6 +126,7 @@
   * [开屏广告manifest配置](https://doc.dcloud.net.cn/uni-app-x/collocation/manifest-modules.html#uni-ad)
   * [激励视频广告](create-rewarded-video-ad.md)
   * [插屏广告](create-interstitial-ad.md)
+  * [短剧](create-drama-ad.md)
 * 支付
   * [支付（requestPayment）](request-payment.md)
   * [虚拟支付（requestVirtualPayment）](virtual-payment.md)