fix: 🧩 fixed the problem of using the swiper in the pop-up window

Author: Ru1ers

Diff for: docs/zebra-swiper-docs/api/basic.md

@@ -196,10 +196,18 @@ Swiper 的初始启用状态。当 Swiper 被禁用时，它将隐藏所有导
 ## height
 
 :::warning
-设置swiper高度请使用`custom-style`。
+正常设置swiper高度请使用`custom-style`。
+
+单位为`px`。如果需要设置`rpx`，请通过`uni.rpx2px()`转换后再传给swiper。
+:::
+
+::: tip
+在 `popup` 中使用 `swiper` 时，小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中，即使弹窗尚未显示，其内容在页面加载后仍会被预加载。这种情况下，通过 `uni.createSelectorQuery()` 方法获取宽高会返回 `null`。
+
+为了应对这一问题，可以通过预设配置为 `swiper` 设置固定宽度，从而确保其正常显示和功能实现。
 :::
 
-强制设置swiper容器的高度。仅在隐藏时初始化swiper时才有用。
+强制设置swiper容器的高度。仅在隐藏时初始化swiper时使用。
 
 <ComponentInfo type="Number" value="-"></ComponentInfo>
 
@@ -275,10 +283,18 @@ Swiper 的初始启用状态。当 Swiper 被禁用时，它将隐藏所有导
 ## width
 
 :::warning
-设置swiper宽度请使用`custom-style`。
+正常设置swiper宽度请使用`custom-style`。
+
+单位为`px`。如果需要设置`rpx`，请通过`uni.rpx2px()`转换后再传给swiper。
+:::
+
+::: tip
+在 `popup` 中使用 `swiper` 时，小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中，即使弹窗尚未显示，其内容在页面加载后仍会被预加载。这种情况下，通过 `uni.createSelectorQuery()` 方法获取宽高会返回 `null`。
+
+为了应对这一问题，可以通过预设配置为 `swiper` 设置固定宽度，从而确保其正常显示和功能实现。
 :::
 
-强制设置swiper容器的宽度。仅在隐藏时初始化swiper时才有用。
+强制设置swiper容器的宽度。仅在隐藏时初始化swiper时使用。
 
 <ComponentInfo type="Number" value="-"></ComponentInfo>
 

Diff for: docs/zebra-swiper-docs/guide/faq.md

@@ -43,3 +43,13 @@ outline: deep
  @use "@/uni_modules/zebra-swiper/modules/navigation/navigation.scss";
 </style>
 ```
+
+## 小程序在弹窗 `popup` 中使用 `swiper` 时的加载问题 {#swiper-on-popup-error}
+
+在小程序和 H5 中，弹窗`v-show`的加载机制存在显著差异。
+
+小程序在页面加载时，即使弹窗未被显示，其内容也会被加载。然而，此时通过 `uni.createSelectorQuery()` 获取弹窗内容的宽高可能返回 `null`，导致 `swiper` 无法正常加载。
+
+为了解决这一问题，可以通过配置 `width` 或 `height` 属性，预先为 `swiper` 设置固定的宽高值，从而确保其正常加载和渲染。
+
+相关配置：[`width`](/api/basic#width) | [`height`](/api/basic#height)

Diff for: example/normal/uni_modules/zebra-swiper/components/z-swiper/z-swiper.vue

@@ -436,6 +436,20 @@ onMounted(() => {
         .catch((error) => {
           console.error(error)
         })
+    } else {
+      mountSwiper(
+        {
+          el: swiperElRef.value as unknown as HTMLElement,
+          adapterEl: swiperElRef.value,
+          nextEl: nextElRef.value,
+          prevEl: prevElRef.value,
+          paginationEl: paginationElRef.value,
+          scrollbarEl: scrollbarElRef.value,
+          swiper: swiperRef.value as unknown as SwiperInterface
+        },
+        swiperParams
+      )
+      emit('swiper', swiperRef.value)
     }
   }
 })

Diff for: src/components/z-swiper/z-swiper.vue

@@ -436,6 +436,20 @@ onMounted(() => {
         .catch((error) => {
           console.error(error)
         })
+    } else {
+      mountSwiper(
+        {
+          el: swiperElRef.value as unknown as HTMLElement,
+          adapterEl: swiperElRef.value,
+          nextEl: nextElRef.value,
+          prevEl: prevElRef.value,
+          paginationEl: paginationElRef.value,
+          scrollbarEl: scrollbarElRef.value,
+          swiper: swiperRef.value as unknown as SwiperInterface
+        },
+        swiperParams
+      )
+      emit('swiper', swiperRef.value)
     }
   }
 })

Diff for: tests/normal-test/pages/popup/popup.vue

@@ -1,19 +1,29 @@
 <template>
 	<view class="demo-swiper">
 		<demo-block title="normal">
-			<view class="">
-				<z-swiper v-model:list="virtualList" loop :modules="modules">
+			<view v-show="showSwiper">
+				<z-swiper :width="swiperWidth" effect="cube" :modules="modules">
 					<z-swiper-item v-for="(item,index) in virtualList" :key="item.id">
 						<demo-item :item="item"></demo-item>
 					</z-swiper-item>
 				</z-swiper>
 			</view>
 		</demo-block>
+		<demo-block title="normal">
+			<view v-if="showSwiperIf">
+				<z-swiper v-model:list="virtualListNative" loop :modules="modules">
+					<z-swiper-item v-for="(item,index) in virtualListNative" :key="item.id">
+						<demo-item :item="item"></demo-item>
+					</z-swiper-item>
+				</z-swiper>
+			</view>
+		</demo-block>
 	</view>
 </template>
 
 <script setup>
 	import {
+		onMounted,
 		ref,
 		watch
 	} from 'vue'
@@ -42,6 +52,18 @@
 	]
 	const list = ref([])
 
+	const showSwiper = ref(false)
+	const swiperWidth = ref(300)
+
+	const showSwiperIf = ref(false)
+
+	onMounted(() => {
+		setTimeout(() => {
+			showSwiper.value = true
+			showSwiperIf.value = true
+		}, 2000)
+	})
+
 	const virtualList = ref(
 		Array.from({
 			length: 3
@@ -56,7 +78,7 @@
 	)
 	const virtualListNative = ref(
 		Array.from({
-			length: 1000
+			length: 3
 		}).map((item, index) => {
 			const randomValue = Math.floor(Math.random() * 7)
 			return {