fix(runtime-vapor): clear template ref when switching to unresolved async component

edison1105 · edison1105 · commit e09b67ab1530 · 2026-03-19T10:53:12.000+08:00
diff --git a/packages/runtime-vapor/__tests__/components/KeepAlive.spec.ts b/packages/runtime-vapor/__tests__/components/KeepAlive.spec.ts
@@ -2278,4 +2278,77 @@ describe('VaporKeepAlive', () => {
     expect(mountedSpy).toHaveBeenCalledTimes(0)
     expect(activatedSpy).toHaveBeenCalledTimes(0)
   })
+
+  test('should clear template ref when switching to unresolved async component', async () => {
+    const timeout = (n: number = 0) => new Promise(r => setTimeout(r, n))
+
+    let resolveAsync: (comp: any) => void
+    const AsyncComp = defineVaporAsyncComponent(
+      () =>
+        new Promise(r => {
+          resolveAsync = r
+        }),
+    )
+
+    const Comp = defineVaporComponent({
+      name: 'Comp',
+      setup() {
+        return template('<div>comp</div>')()
+      },
+    })
+
+    const instanceRef = ref<any>(null)
+    const toggle = ref(false)
+
+    define({
+      setup() {
+        const setRef = createTemplateRefSetter()
+        return createComponent(VaporKeepAlive, null, {
+          default: () =>
+            createIf(
+              () => toggle.value,
+              () => {
+                const comp = createComponent(AsyncComp)
+                setRef(comp, instanceRef)
+                return comp
+              },
+              () => {
+                const comp = createComponent(Comp)
+                setRef(comp, instanceRef)
+                return comp
+              },
+            ),
+        })
+      },
+    }).render()
+
+    await nextTick()
+    // Comp is mounted — ref should point to it
+    expect(instanceRef.value).not.toBe(null)
+
+    // switch to async component (unresolved)
+    toggle.value = true
+    await nextTick()
+    // ref should be null while async is pending
+    expect(instanceRef.value).toBe(null)
+
+    // resolve async
+    resolveAsync!(
+      defineVaporComponent({
+        name: 'AsyncResolved',
+        setup() {
+          return template('<div>async</div>')()
+        },
+      }),
+    )
+    await timeout()
+    await nextTick()
+    // ref should now point to the resolved component
+    expect(instanceRef.value).not.toBe(null)
+
+    // switch back to Comp
+    toggle.value = false
+    await nextTick()
+    expect(instanceRef.value).not.toBe(null)
+  })
 })
diff --git a/packages/runtime-vapor/src/apiTemplateRef.ts b/packages/runtime-vapor/src/apiTemplateRef.ts
@@ -108,11 +108,12 @@ function setRef(
 
   // async component
   if (isVaporComponent(el) && isAsyncWrapper(el)) {
-    // unresolved: handled in DynamicFragment's updated hook
-    if (!el.type.__asyncResolved) return
-
     // resolved: set ref to the inner component
-    el = (el.block as DynamicFragment).nodes as VaporComponentInstance
+    if (el.type.__asyncResolved) {
+      el = (el.block as DynamicFragment).nodes as VaporComponentInstance
+    }
+    // unresolved: el stays as async wrapper, getRefValue returns null
+    // → ref will be cleared through normal setRef logic below
   }
 
   const setupState: any = __DEV__ ? instance.setupState || {} : null
@@ -198,6 +199,11 @@ function setRef(
     if (_isString || _isRef) {
       const doSet: SchedulerJob = () => {
         if (refFor) {
+          // for unresolved async components, refValue is null.
+          // skip adding null to the array — the ref will be re-set
+          // when the async component resolves via DynamicFragment's updated hook.
+          if (refValue == null) return
+
           existing = _isString
             ? __DEV__ && canSetSetupRef(ref)
               ? setupState[ref]
@@ -262,6 +268,8 @@ function setRef(
 
 const getRefValue = (el: RefEl) => {
   if (isVaporComponent(el)) {
+    // unresolved async wrapper: return null so ref gets cleared
+    if (isAsyncWrapper(el) && !el.type.__asyncResolved) return null
     return getExposed(el) || el
   } else if (isTeleportFragment(el)) {
     return null
