css transition 不支持自定义属性动画，因规范限制；view transitions api 要求主题切换必须包裹在 document.startviewtransition() 中同步执行，且仅通过 ::view-transition-old/new(root) 或命名过渡控制动画。
直接改 :root 变量 + transition 为什么没动画？
因为 CSS transition 根本不支持自定义属性（如 --bg、--text）作为可过渡属性，这是规范限制，不是浏览器兼容性问题。哪怕你写了：
:root {
--bg: #fff;
transition: --bg 0.3s;
}
.theme-dark {
--bg: #121212;
}
这段代码在所有稳定版浏览器里都不会触发任何过渡——DOM 没有重绘帧调度上下文，浏览器连“该不该动”都不知道。
常见错误还包括：试图靠 JS 批量修改几十个 --xxx 变量再等 transitionend，结果发现事件根本不触发，页面直接闪切。
document.startViewTransition() 必须包裹同步 DOM 更新
View Transitions API 不是“给现有换肤加个动效”的补丁，它要求你把主题切换动作明确包进 startViewTransition 回调里，且更新必须是同步的：
- ✅ 正确：在点击按钮后立刻切换
document.documentElement.classList或更新data-theme - ❌ 错误：先发请求加载新 CSS，再异步插入
<link>，然后改 class —— 这会导致静默失败或InvalidStateError - ⚠️ 注意：如果用框架（如 React/Vue），确保 DOM 更新发生在回调内，而不是靠状态驱动的异步渲染周期
简单示例：
button.addEventListener('click', () => {
document.startViewTransition(() => {
document.documentElement.classList.toggle('theme-dark');
});
});
::view-transition-old(root) 和 ::view-transition-new(root) 是唯二可控入口
CSS 层面你只能通过这两个伪元素控制整页过渡行为，不能写 .theme-dark ::view-transition-new 这类组合选择器——浏览器会忽略。
关键约束：
- 它们只对
root（即html元素）生效；想控制局部区域需用命名过渡（见下一条） - 动画必须用
@keyframes显式定义，不能依赖transition或will-change -
animation-duration建议设为0.3s–0.5s，过长会让用户感知卡顿，过短则失去意义
最小可用 CSS：
::view-transition-old(root) { animation: fade-out 0.3s ease-out; }
::view-transition-new(root) { animation: fade-in 0.3s ease-in; }
@keyframes fade-out { from { opacity: 1; } to { opacity: 0; } }
@keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
局部换肤或卡片展开要用 view-transition-name，不是 id 或 class
如果你只想让某个卡片、标题或图片在主题切换或路由跳转时单独过渡，必须显式声明 view-transition-name 属性，且新旧 DOM 中值要完全一致：
- ✅ 正确：
<h1 view-transition-name="page-title">首页</h1>→ 切换后新页面也得有同名元素 - ❌ 错误：一个写
"title"，另一个写"header"；或新页面里该元素被移除/未渲染 - ⚠️ 注意：同一页面内不能有两个相同
view-transition-name的元素，否则映射会错乱
命名过渡的 CSS 写法是：
::view-transition-old(page-title) { animation: slide-up 0.4s; }
::view-transition-new(page-title) { animation: slide-down 0.4s; }
别忘了：这些元素必须在切换前后都存在于 DOM 中（哪怕 display: none），否则浏览器找不到映射目标，直接退化成硬切。
真正难的不是写几行代码，而是确保新旧视图中参与过渡的元素结构稳定、命名唯一、生命周期可控——稍有偏差，动画就消失，还查不出错在哪。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
