fix(motion): 站内跳转白屏——路由内容不再走 AnimatePresence wait 退场
现象:生产环境所有站内跳转白屏,地址与标题已切换,刷新才恢复。
根因:AnimatePresence mode="wait" 要求新页等旧页退场完成才挂载;App Router
导航期间的重复渲染会重置退场完成标记,切换 state 的窗口被错过,
motion.div 永久停在 exit 变体(opacity:0; translateY(-8px))。
修法:路由内容只保留 key={pathname} 的 280ms 入场;首屏仍由 mounted 渲染
裸 children;reduce 变体改为显式可见终值,避免切到空变体时冻结在半透明。
守卫:新增 client-navigation-visibility(导航后落定再读祖先链乘积);
首屏用例改逐帧采样;视觉用例改逐屏滚动触发 whileInView。
验证:E2E 20/20(四浏览器)、视觉 125/125、单测 1815、type-check/lint 0 error。
This commit is contained in:
1 parent
092ed385b0
commit
2f86c4419a
7 files changed
+167
-54
No files matched your search
@@ -896,3 +896,30 @@ if [ "$A" -eq 0 ] && [ "$B" -eq 0 ]; then git add … && git commit … && git p
|
||||
|
||||
⇒ 通用判据:**当 DOM 祖先可以整体降透明度时,「元素 opacity=1」不构成可见性证明;
|
||||
仪器必须先证明页面处于终态,再解释对比度。**
|
||||
|
||||
### 5.50 AnimatePresence mode="wait" 会让新页永久停在 exit 态(2026-10-20)
|
||||
|
||||
**现象**:生产环境所有站内跳转白屏,地址栏与标题已变,刷新(冷加载)才正常。
|
||||
**复现**:production standalone 产物,首页点「关于我们」;`main#main-content` 的父级 motion.div
|
||||
内联停在 `opacity:0; transform:translateY(-8px)`(exit 变体)且不再变化,祖先链有效 opacity 恒 0。
|
||||
|
||||
**机理**:`<AnimatePresence mode="wait">` 要等旧子树的 exit 完成才挂载新子树。App Router 导航期间
|
||||
本组件会多次重渲染,每次 `children` 引用变化都会让 AnimatePresence 重跑 diff 并把退场完成标记
|
||||
重置为 false,200ms 后切换 state 的窗口被错过。保留 `exit` 也不能只靠 sync 模式兜底:实测旧
|
||||
`main` 节点常驻(`mains: 2`),因为注销同样依赖这套 presence bookkeeping。
|
||||
|
||||
**修法**:路由内容不再包 AnimatePresence,`<motion.div key={pathname}>` 只保留入场动画
|
||||
(280ms,令牌层不变);首屏仍由 `mounted` 门控渲染裸 children。不要用「去掉 exit」或
|
||||
「mode=popLayout」折中——前者留下常驻旧子树,后者留下绝对定位的隐形残影。
|
||||
|
||||
**连带修正(同一条因果链)**:
|
||||
- 移除 presence 的 `initial={false}` 上下文后,子树恢复各自入场,屏下的 ScrollReveal 在全页截图时
|
||||
仍处 opacity:0。视觉用例的「直接跳到底」会跳过中间各屏(IntersectionObserver 只回调当前视口),
|
||||
改为**逐屏滚动**;视觉全量 125/125。
|
||||
- 首屏可见性断言改为**逐帧采样**:并行负载下,单点读 h1 会与「水合后子树重挂、入场重新开始」竞争。
|
||||
|
||||
**回归守卫**:`e2e/client-navigation-visibility.spec.ts` —— 点页脚链接后等 800ms(退场+入场落定)
|
||||
再读祖先链乘积;`E2E_TARGET=production` 下四浏览器通过。
|
||||
|
||||
⇒ 通用判据:**跨路由的「等旧页退场再挂新页」不能依赖 framer 的 presence 状态机;
|
||||
新页面挂载不得以旧页面的动画完成作为前置条件。**
|
||||
@@ -0,0 +1,52 @@
|
||||
import { test, expect } from './fixtures';
|
||||
|
||||
/**
|
||||
* 客户端导航可见性回归(2026-10-20 生产白屏)。
|
||||
*
|
||||
* 缺陷原型:首页点击导航后 URL 与正文都已切换,但 PageTransition 的 motion.div 停在
|
||||
* exit 变体(inline opacity:0; translateY(-8px)),新页面永不进入 ⇒ 整页白屏,刷新才恢复。
|
||||
* 只看 h1 自身 opacity 读不到(恒为 1),必须读祖先链的乘积累积。
|
||||
*
|
||||
* 复核:`E2E_TARGET=production npx playwright test client-navigation-visibility`。
|
||||
*/
|
||||
const NAV_STEPS = [
|
||||
{ href: '/about', label: '关于我们' },
|
||||
{ href: '/products', label: '产品矩阵' },
|
||||
{ href: '/methodology', label: '方法论' },
|
||||
{ href: '/insights', label: '洞察' },
|
||||
{ href: '/about/brand', label: '品牌故事' },
|
||||
];
|
||||
|
||||
function effectiveOpacity(page: import('@playwright/test').Page) {
|
||||
return page.evaluate(() => {
|
||||
const main = document.querySelector('main#main-content');
|
||||
let opacity = 1;
|
||||
let node: Element | null = main;
|
||||
while (node) {
|
||||
opacity *= Number(getComputedStyle(node).opacity);
|
||||
node = node.parentElement;
|
||||
}
|
||||
return opacity;
|
||||
});
|
||||
}
|
||||
|
||||
test('首页经客户端导航到各栏目后内容必须可见', async ({ page }) => {
|
||||
await page.goto('/', { waitUntil: 'networkidle', timeout: 60000 });
|
||||
await expect
|
||||
.poll(() => effectiveOpacity(page), { timeout: 15000 })
|
||||
.toBeGreaterThan(0.99);
|
||||
|
||||
for (const step of NAV_STEPS) {
|
||||
await page.getByTestId('footer').locator(`a[href="${step.href}"]`).first().click();
|
||||
await page.waitForURL(`**${step.href}`, { timeout: 15000 });
|
||||
// 退场 200ms + 入场 280ms 都在 URL 变化之后才落定;URL 一变就采样会读到退场前的 1(假绿)。
|
||||
await page.waitForTimeout(800);
|
||||
|
||||
await expect
|
||||
.poll(() => effectiveOpacity(page), {
|
||||
timeout: 5000,
|
||||
message: `导航到 ${step.href}(${step.label})后整页有效 opacity 未回到 1(白屏)`,
|
||||
})
|
||||
.toBeGreaterThan(0.99);
|
||||
}
|
||||
});
|
||||
@@ -1,5 +1,11 @@
|
||||
import { test, expect } from './fixtures';
|
||||
|
||||
declare global {
|
||||
interface Window {
|
||||
__firstPaint?: Array<{ ready: string | null; opacity: number }>;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 冷首访可见性守卫(2026-10-20)。
|
||||
*
|
||||
@@ -10,13 +16,16 @@ import { test, expect } from './fixtures';
|
||||
*
|
||||
* 断言两条,都能失败:
|
||||
* ① 禁用 JS(等价"脚本没跑起来"):h1 的内联样式仍是 opacity:0,但**计算值必须为 1**;
|
||||
* ② 正常加载:水合后置位 data-content-ready,且 h1 仍可见(交接不闪回 0)。
|
||||
* ② 正常加载:水合后置位 data-content-ready,且 h1 在交接前后每一帧都可见(不闪回 0)。
|
||||
*/
|
||||
test.describe('首屏可见性(无 JS / 水合交接)', () => {
|
||||
test('禁用 JS 时 h1 计算 opacity 为 1(内联仍是 0,靠兜底规则)', async ({ browser }) => {
|
||||
const ctx = await browser.newContext({ javaScriptEnabled: false, viewport: { width: 1280, height: 900 } });
|
||||
const page = await ctx.newPage();
|
||||
await page.goto('/about', { waitUntil: 'domcontentloaded', timeout: 60000 });
|
||||
// JS 关闭时 CSS 仍可能晚于 DOM 到达;不等到 load 就取 computed style,
|
||||
// 会把「样式表还没到」误读成「兜底规则失效」(2026-10-20 并行跑实测)。
|
||||
await page.waitForLoadState('load', { timeout: 30000 });
|
||||
const snap = await page.evaluate(() => {
|
||||
const h1 = document.querySelector('h1') as HTMLElement | null;
|
||||
return {
|
||||
@@ -29,12 +38,26 @@ test.describe('首屏可见性(无 JS / 水合交接)', () => {
|
||||
await ctx.close();
|
||||
});
|
||||
|
||||
test('水合后 800ms 置位 data-content-ready 且 h1 仍可见', async ({ page }) => {
|
||||
test('水合后 800ms 置位 data-content-ready 且 h1 始终可见', async ({ page }) => {
|
||||
// 单点读 h1 会与「水合后子树重挂、入场动画重新开始」的瞬间竞争(并行跑偶发读到 0)。
|
||||
// 改为逐帧采样:交接前(data-content-ready 未置位)每一帧都必须可见,交接后也必须可见。
|
||||
await page.addInitScript(() => {
|
||||
const samples: Array<{ ready: string | null; opacity: number }> = [];
|
||||
window.__firstPaint = samples;
|
||||
const tick = () => {
|
||||
const h1 = document.querySelector('h1');
|
||||
if (h1) {
|
||||
samples.push({
|
||||
ready: document.documentElement.getAttribute('data-content-ready'),
|
||||
opacity: Number(getComputedStyle(h1).opacity),
|
||||
});
|
||||
}
|
||||
requestAnimationFrame(tick);
|
||||
};
|
||||
requestAnimationFrame(tick);
|
||||
});
|
||||
await page.goto('/about', { waitUntil: 'domcontentloaded', timeout: 60000 });
|
||||
const h1 = page.locator('h1').first();
|
||||
await expect(h1).toBeVisible({ timeout: 10000 });
|
||||
const early = await h1.evaluate((el) => Number(getComputedStyle(el).opacity));
|
||||
expect(early, '首帧(水合前后)h1 必须是可见的').toBe(1);
|
||||
await expect(page.locator('h1').first()).toBeVisible({ timeout: 10000 });
|
||||
|
||||
await expect
|
||||
.poll(() => page.evaluate(() => document.documentElement.getAttribute('data-content-ready')), {
|
||||
@@ -44,7 +67,13 @@ test.describe('首屏可见性(无 JS / 水合交接)', () => {
|
||||
.toBe('1');
|
||||
|
||||
await page.waitForTimeout(400);
|
||||
const after = await h1.evaluate((el) => Number(getComputedStyle(el).opacity));
|
||||
expect(after, '交接后不得闪回 opacity:0').toBe(1);
|
||||
const samples = await page.evaluate(() => window.__firstPaint ?? []);
|
||||
const beforeHandoff = samples.filter((s) => s.ready === null);
|
||||
expect(beforeHandoff.length, '采样必须覆盖交接前(否则本用例什么都没测到)').toBeGreaterThan(0);
|
||||
expect(
|
||||
Math.min(...beforeHandoff.map((s) => s.opacity)),
|
||||
'交接前 h1 任一帧都不得为 0',
|
||||
).toBe(1);
|
||||
expect(samples.at(-1)?.opacity, '交接后不得闪回 opacity:0').toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -64,11 +64,13 @@ for (const { path, lateHeading } of CASES) {
|
||||
});
|
||||
expect(h1Opacity, '首屏 h1 的祖先链不得停在半透明/0').toBeGreaterThan(0.99);
|
||||
|
||||
// 滚到底部,让 whileInView 触发;reduce 下应「一步到位」变可见
|
||||
await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
|
||||
await page.waitForTimeout(1000);
|
||||
// 把目标滚进视口,让 whileInView 触发;reduce 下应「一步到位」变可见。
|
||||
// 不能 `window.scrollTo(0, scrollHeight)` 直接跳底:reduce 会禁用平滑滚动(瞬时跳转),
|
||||
// 目标从视口外被越过、IntersectionObserver 永不回调 ⇒ 探针自设条件造成假红。
|
||||
const late = page.getByRole('heading', { name: lateHeading }).first();
|
||||
await expect(late, '末段标题应存在(页面完整)').toBeVisible({ timeout: 10000 });
|
||||
await late.scrollIntoViewIfNeeded();
|
||||
await page.waitForTimeout(1000);
|
||||
await expect
|
||||
.poll(
|
||||
async () =>
|
||||
|
||||
@@ -46,14 +46,22 @@ async function waitForPageStable(page: Page) {
|
||||
await page.waitForLoadState('networkidle');
|
||||
await page.waitForTimeout(2000);
|
||||
|
||||
// 触发全页 ScrollReveal / StaggerReveal:先滚到底再回顶,让所有 below-the-fold
|
||||
// 触发全页 ScrollReveal / StaggerReveal:逐屏滚到底再回顶,让所有 below-the-fold
|
||||
// 模块的 whileInView 动画进入最终态,避免全页截图时内容停在 opacity:0 初始态。
|
||||
// 视觉回归项目已统一 reducedMotion:'reduce',此滚动作为双保险,覆盖任何媒体查询
|
||||
// 在 viewport resize 期间短暂失真的边界情况。
|
||||
await page.evaluate(() => window.scrollTo({ top: document.body.scrollHeight, behavior: 'instant' }));
|
||||
await page.waitForTimeout(800);
|
||||
await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'instant' }));
|
||||
await page.waitForTimeout(200);
|
||||
// 不能直接 `scrollTo(scrollHeight)` 一跳到底:IntersectionObserver 只会回调当前视口
|
||||
// 内的目标,中间各屏被跳过 ⇒ 截图出来是空白段(2026-10-20 移除路由级 AnimatePresence
|
||||
// 后首屏不再替子树屏蔽 initial,这条路径才真正被走到)。
|
||||
await page.evaluate(async () => {
|
||||
const step = Math.max(400, Math.floor(window.innerHeight * 0.8));
|
||||
for (let y = 0; y <= document.body.scrollHeight; y += step) {
|
||||
window.scrollTo({ top: y, behavior: 'instant' });
|
||||
await new Promise((resolve) => setTimeout(resolve, 120));
|
||||
}
|
||||
window.scrollTo({ top: document.body.scrollHeight, behavior: 'instant' });
|
||||
await new Promise((resolve) => setTimeout(resolve, 400));
|
||||
window.scrollTo({ top: 0, behavior: 'instant' });
|
||||
await new Promise((resolve) => setTimeout(resolve, 200));
|
||||
});
|
||||
|
||||
await page.evaluate(() => {
|
||||
document.querySelectorAll('img').forEach(img => {
|
||||
|
||||
@@ -48,14 +48,20 @@ export default function MarketingTemplate({
|
||||
|
||||
// 2026-10-20:**不再早返回 `<>{children}</>`** —— 那会让树结构与 SSR 不同
|
||||
// (服务端永远渲染 motion.div,客户端 reduce 用户渲染裸 Fragment)⇒ React #418。
|
||||
// 改为结构恒定,只在挂载后把 variants 换成空组(时长 0、无位移)。
|
||||
// 2026-10-20(导航白屏修复的连带回归):reduce 变体不能写成 `{}`。motion.div 挂载时
|
||||
// hook 仍是 false(首帧与 SSR 一致),它按 pageVariants 开始 0→1 的入场;effect 切到
|
||||
// reduce 后 `animate="enter"` 若映射到空变体,framer 会停在当前帧(实测 opacity 0.2)
|
||||
// 而不是「一步到位」。改为显式给可见终值 + 0 时长。
|
||||
const variants = shouldReduceMotion
|
||||
? { initial: {}, enter: {}, exit: {} }
|
||||
? {
|
||||
initial: { opacity: 1, y: 0 },
|
||||
enter: { opacity: 1, y: 0, transition: { duration: 0 } },
|
||||
}
|
||||
: pageVariants;
|
||||
|
||||
return (
|
||||
<motion.div
|
||||
initial="initial"
|
||||
initial={shouldReduceMotion ? false : 'initial'}
|
||||
animate="enter"
|
||||
exit="exit"
|
||||
variants={variants}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
'use client';
|
||||
|
||||
import { motion, AnimatePresence } from 'framer-motion';
|
||||
import { motion } from 'framer-motion';
|
||||
import { usePathname } from 'next/navigation';
|
||||
import { useEffect, useState } from 'react';
|
||||
import { useReducedMotion } from '@/hooks/use-reduced-motion';
|
||||
@@ -22,15 +22,6 @@ const pageVariants = {
|
||||
staggerChildren: 0.05,
|
||||
},
|
||||
},
|
||||
exit: {
|
||||
opacity: 0,
|
||||
y: -8,
|
||||
scale: 0.98,
|
||||
transition: {
|
||||
duration: 0.2,
|
||||
ease: [0.22, 1, 0.36, 1] as const,
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
export function PageTransition({ children }: { children: React.ReactNode }) {
|
||||
@@ -47,34 +38,33 @@ export function PageTransition({ children }: { children: React.ReactNode }) {
|
||||
return <>{children}</>;
|
||||
}
|
||||
|
||||
// 2026-10-20(多端复核):reduce 下**不能**在 mounted 之后切回裸 children。
|
||||
// 原先 `if (!mounted || shouldReduceMotion) return children` 会让已挂载的 motion.div
|
||||
// 在 reduce 状态落地的瞬间被 AnimatePresence 的 exit 链接管,而在 headless/移动仿真里
|
||||
// exit 链没有稳定落点,实测整页祖先停在 opacity 0.15–0.35(桌面 1440 甚至 0)。
|
||||
// 现在无论是否 reduce 都保留同一个 motion.div,只用零时长 + 可见变体把动画「一步到位」。
|
||||
// 2026-10-20(生产导航白屏):**不再用 AnimatePresence 包裹路由内容**。
|
||||
// 原写法 `<AnimatePresence mode="wait"><motion.div key={pathname} exit="exit">` 会让新页面
|
||||
// 等旧页面退场完成后才挂载;而 Next App Router 在导航过程中会多次重渲染本组件,每次新的
|
||||
// children 引用都会让 AnimatePresence 重跑 diff 并把退场完成标记重置,200ms 退场动画结束后
|
||||
// 切换 state 的机会被错过 ⇒ 同一个 motion.div 永久停在 exit 变体(实测 inline opacity:0;
|
||||
// translateY(-8px)),整页白屏,刷新(走 mounted=false 的裸 children 路径)才恢复。
|
||||
// 现在只保留入场:key 随 pathname 变化触发重挂,入场动画仍按令牌层 280ms 播放。
|
||||
// 回归守卫:e2e/client-navigation-visibility.spec.ts。
|
||||
const reducedVariants = {
|
||||
initial: { opacity: 1, y: 0, scale: 1 },
|
||||
animate: { opacity: 1, y: 0, scale: 1, transition: { duration: 0 } },
|
||||
exit: { opacity: 1, transition: { duration: 0 } },
|
||||
};
|
||||
const variants = shouldReduceMotion ? reducedVariants : pageVariants;
|
||||
|
||||
return (
|
||||
<AnimatePresence mode="wait" initial={false}>
|
||||
<motion.div
|
||||
key={pathname}
|
||||
variants={variants}
|
||||
initial={shouldReduceMotion ? false : 'initial'}
|
||||
animate="animate"
|
||||
exit="exit"
|
||||
style={{
|
||||
willChange: 'transform, opacity',
|
||||
backfaceVisibility: 'hidden',
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</motion.div>
|
||||
</AnimatePresence>
|
||||
<motion.div
|
||||
key={pathname}
|
||||
variants={variants}
|
||||
initial={shouldReduceMotion ? false : 'initial'}
|
||||
animate="animate"
|
||||
style={{
|
||||
willChange: 'transform, opacity',
|
||||
backfaceVisibility: 'hidden',
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</motion.div>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -125,8 +115,7 @@ export function StaggerChildren({
|
||||
{child}
|
||||
</motion.div>
|
||||
))
|
||||
: children
|
||||
}
|
||||
: children}
|
||||
</motion.div>
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user