Communitygithub.com

xzedm/clipplic-landing

使用 React View Transition API 实现流畅、原生感动画的完整指南

clipplic-landing 是什么?

该技能详细介绍了如何利用 React 的 View Transition API(包括 `<ViewTransition>` 组件、`addTransitionType` 和 CSS 视图过渡伪元素)在网页应用中添加平滑的动画效果。它涵盖了页面过渡、路由切换、共享元素动画、组件进入/退出、列表重排以及方向性导航动画等多种场景。技能文档强调了在 Next.js 中的开箱即用集成,并指导开发者遵循特定的实现顺序,优先实现共享元素和悬停揭示等模式。通过定义过渡类型和 CSS 类,开发者可以精细控制动画行为,同时确保在不支持的浏览器上优雅降级。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/xzedm/clipplic-landing/tree/HEAD/.agents/skills/vercel-react-view-transitions

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

clipplic-landing preview
clipplic-landing preview

文档

React 视图过渡

使用浏览器原生 document.startViewTransition 在不同 UI 状态之间制作动画。用 <ViewTransition> 声明什么,用 startTransition / useDeferredValue / Suspense 触发何时,用 CSS 类控制如何。不支持的浏览器会优雅地跳过动画。

何时添加动画

每个 <ViewTransition> 都应传达空间关系或连续性。如果你无法说明它传达了什么,就不要添加它。

按此顺序实现列表中所有适用的模式:

优先级模式传达的信息
1共享元素 (name)“同一个东西,更深入了”
2Suspense 揭示“数据已加载”
3列表标识 (每个项目 key)“相同项目,新排列”
4状态变化 (enter/exit)“某物出现/消失了”
5路由变化 (布局级别)“前往新地方”

这是实现顺序,不是“挑选一个”的列表。实现适合应用的所有模式。只有当应用没有使用场景时才跳过某个模式。

选择动画风格

上下文动画原因
层级导航(列表 → 详情)类型键控的 nav-forward / nav-back传达空间深度
横向导航(标签页到标签页)裸 <ViewTransition>(淡入淡出)或 default="none"没有深度需要传达
Suspense 揭示enter/exit 字符串属性内容到达
重新验证 / 后台刷新default="none"静默,不需要动画

将方向性滑动保留给层级导航(列表 → 详情)和有序序列(上一张/下一张照片、轮播、分页结果)。对于有序序列,方向传达位置:“下一张”从右侧滑入,“上一张”从左侧滑入。横向/无序导航(标签页到标签页)不应使用方向性滑动。这会错误地暗示空间深度。


可用性

  • Next.js: 不要安装 react@canary:App Router 已在内部捆绑了 React canary。ViewTransition 开箱即用。npm ls react 可能显示一个看起来稳定的版本;这是预期的。
  • 没有 Next.js: 安装 react@canary react-dom@canary(ViewTransition 不在稳定的 React 中)。
  • 浏览器支持:Chromium 111+, Firefox 144+, Safari 18.2+。在不支持的浏览器上优雅降级。

实现工作流程

在为现有应用添加视图过渡时,逐步遵循 references/implementation.md。 从审计开始,不要跳过。将 references/css-recipes.md 中的 CSS 配方复制到全局样式表中,不要编写自己的动画 CSS。


核心概念

<ViewTransition> 组件

import { ViewTransition } from 'react';

<ViewTransition>
  <Component />
</ViewTransition>

React 自动分配一个唯一的 view-transition-name 并在后台调用 document.startViewTransition。永远不要自己调用 startViewTransition。

动画触发器

触发器触发时机
enter<ViewTransition> 在过渡期间首次插入
exit<ViewTransition> 在过渡期间首次移除
update<ViewTransition> 内部的 DOM 突变。对于嵌套的 VT,突变应用于最内层的那个
share命名 VT 卸载而另一个同名 name 在同一个过渡中挂载时

只有 startTransition、useDeferredValue 或 Suspense 能激活 VT。常规 setState 不会产生动画。

关键放置规则

<ViewTransition> 只有在它出现在任何 DOM 节点之前时才会激活 enter/exit:

// 有效
<ViewTransition enter="auto" exit="auto">
  <div>内容</div>
</ViewTransition>

// 无效,div 包裹了 VT,抑制了 enter/exit
<div>
  <ViewTransition enter="auto" exit="auto">
    <div>内容</div>
  </ViewTransition>
</div>

使用视图过渡类定义样式

属性

值:"auto"(浏览器交叉淡入淡出)、"none"(禁用)、"class-name"(自定义 CSS)或 { [type]: value } 用于类型特定的动画。

<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />

如果 default 是 "none",所有触发器都关闭,除非明确列出。

CSS 伪元素

  • ::view-transition-old(.class):即将离开的快照
  • ::view-transition-new(.class):即将进入的快照
  • ::view-transition-group(.class):容器
  • ::view-transition-image-pair(.class):旧 + 新配对

参见 references/css-recipes.md 获取现成的动画配方。


过渡类型

用 addTransitionType 标记过渡,以便 VT 可以根据上下文选择不同的动画。多次调用以堆叠类型,树中不同的 VT 对不同的类型做出反应:

startTransition(() => {
  addTransitionType('nav-forward');
  addTransitionType('select-item');
  router.push('/detail/1');
});

传递一个对象将类型映射到 CSS 类。适用于 enter、exit和 share:

<ViewTransition
  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
  default="none"
>
  <Page />
</ViewTransition>

enter 和 exit 不必对称。例如,淡入但方向性滑出:

<ViewTransition
  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
  default="none"
>

TypeScript: ViewTransitionClassPerType 要求对象中有一个 default 键。

对于具有多个页面的应用,将类型键控的 VT 提取为可重用的包装器:

export function DirectionalTransition({ children }: { children: React.ReactNode }) {
  return (
    <ViewTransition
      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
      default="none"
    >
      {children}
    </ViewTransition>
  );
}

router.back() 和浏览器返回按钮

router.back() 和浏览器的后退/前进按钮不会触发视图过渡(popstate 是同步的,与 startViewTransition 不兼容)。请改用带有显式 URL 的 router.push()。

类型和 Suspense

类型在导航期间可用,但在随后的 Suspense 揭示期间不可用(单独的过渡,没有类型)。对页面级别的 enter/exit 使用类型映射;对 Suspense 揭示使用简单的字符串属性。


共享元素过渡

两个 VT 具有相同的 name,一个卸载,一个挂载,会创建一个共享元素变形:

<ViewTransition name="hero-image">
  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>

// 在另一个视图中,同名
<ViewTransition name="hero-image">
  <img src="/full.jpg" />
</ViewTransition>
  • 一次只能挂载一个具有给定 name 的 VT。使用唯一的名称(photo-${id})。注意可重用组件:如果一个带有命名 VT 的组件同时在模态框/弹出框和页面中渲染,两者同时挂载会破坏变形。要么使名称有条件(通过属性),要么将命名 VT 移出共享组件到特定的消费者中。
  • share 优先于 enter/exit。仔细考虑每个导航路径:当没有形成匹配的对时(例如,目标页面没有相同的 name),enter/exit 会触发。考虑这些路径上元素是否需要回退动画。
  • 永远不要在带有共享变形的页面上使用淡出退出。改用方向性滑动。

常见模式

进入/退出

{show && (
  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}

列表重排

{items.map(item => (
  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}

在 startTransition 内部触发。避免在列表和 VT 之间使用包装 <div>。

在列表标识中组合共享元素

共享元素和列表标识是独立的关注点,不要混淆它们。当列表项包含一个共享元素时(例如,一个会变形为详情视图的图像),使用两个嵌套的 <ViewTransition> 边界:

{items.map(item => (
  <ViewTransition key={item.id}>                                      {/* 列表标识 */}
    <Link href={`/items/${item.id}`}>
      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* 共享元素 */}
        <Image src={item.image} />
      </ViewTransition>
      <p>{item.name}</p>
    </Link>
  </ViewTransition>
))}

外层的 VT 处理列表重排/进入动画。内层的 VT 处理跨路由的共享元素变形。缺少任何一层都意味着该动画悄悄地不会发生。

使用 key 强制重新进入

<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
  <ResultsGrid />
</ViewTransition>

注意: 如果包裹 <Suspense>,更改 key 会重新挂载边界并重新获取数据。

Suspense 回退到内容

简单交叉淡入淡出:

<ViewTransition>
  <Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>

方向性揭示:

<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>

更多模式,参见 references/patterns.md。


多个 VT 如何交互

每个匹配触发器的 VT 在单个 document.startViewTransition 中同时触发。不同过渡中的 VT(导航与后续 Suspense 解决)不会竞争。

大量使用 default="none"

没有它,每个 VT 在每个过渡上都会触发浏览器的交叉淡入淡出。Suspense 解决、useDeferredValue 更新、后台重新验证。始终使用 default="none" 并仅显式启用所需的触发器。

两种模式共存

模式 A. 方向性滑动: 每个页面上的类型键控 VT,在导航期间触发。 模式 B. Suspense 揭示: 简单字符串属性,在数据加载时触发(没有类型)。

它们共存是因为它们在不同的时刻触发。两者上的 default="none" 可以防止交叉干扰。始终将 enter 与 exit 配对。将方向性 VT 放在页面组件中,而不是布局中。

嵌套 VT 限制

当父 VT 退出时,内部的嵌套 VT 不会触发它们自己的 enter/exit,只有最外层的 VT 会执行动画。页面导航期间的逐项交错动画目前无法实现。参见 react#36135 了解实验性的选择加入修复。


Next.js 集成

有关 Next.js 设置(experimental.viewTransition 标志、next/link 上的 transitionTypes 属性、App Router 模式、服务器组件),请参见 references/nextjs.md。


可访问性

始终将 references/css-recipes.md 中的减少动画 CSS 添加到全局样式表中。


参考文件

  • references/implementation.md:分步实现工作流程。
  • references/patterns.md:模式、动画时序、事件 API、故障排除。
  • references/css-recipes.md:现成的 CSS 动画配方。
  • references/nextjs.md:Next.js App Router 模式和服务器组件详情。

完整编译文档

有关所有参考文件展开的完整指南:AGENTS.md

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

xzedm/clipplic-landing

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

xzedm/clipplic-landing

Material Design 3 and Android platform guidelines. Use when building Android apps with Jetpack Compose or XML layouts, implementing Material You, navigation, or accessibility. Triggers on tasks involving Android UI, Compose components, dynamic color, or Material Design compliance.

xzedm/clipplic-landing

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

xzedm/clipplic-landing

Design iOS apps following Apple's Human Interface Guidelines. Generate native components, validate designs, and ensure accessibility compliance for iPhone, iPad, and Apple Watch.

xzedm/clipplic-landing

Redesign mobile app UI to feel unmistakably Apple-like, iOS-forward, and native. Use this skill when building iOS apps, applying Apple Human Interface Guidelines, or creating native-feeling mobile interfaces with SF Pro typography, translucency, and system-like components.

xzedm/clipplic-landing

Accessibility engineering for product interfaces, from focus states and keyboard support to ARIA, forms, and screen readers. Use when building or reviewing UI components, modals, menus, forms, custom widgets, or when the user says "make this accessible" or reports keyboard or screen-reader issues. Triggers on accessibility, a11y, WCAG, aria, focus ring, focus-visible, focus trap, keyboard navigation, tab order, tabindex, screen reader, sr-only, aria-live, alt text, hit area, touch target, prefers-reduced-motion, autoplay, toast duration, skip link, semantic HTML, aria-label, form errors, disabled buttons, "not keyboard accessible".

xzedm/clipplic-landing

OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.

xzedm/clipplic-landing

Layout structure for web interfaces, from grouping and alignment to reading order, progressive disclosure, and adaptive breakpoints. Use when structuring a page or component, spacing or aligning controls, deciding what collapses at small sizes, handling RTL layout direction, or reviewing frontend code for layout. Triggers on layout, spacing, alignment, grouping, negative space, whitespace, visual hierarchy, reading order, progressive disclosure, breakpoints, responsive layout, container queries, safe area, full-bleed, edge-to-edge, layout margins, RTL layout, logical properties.

xzedm/clipplic-landing

Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, scaled input text, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.

xzedm/clipplic-landing

Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.

xzedm/clipplic-landing

Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".

xzedm/clipplic-landing

Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.

xzedm/clipplic-landing

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

xzedm/clipplic-landing

Extract design primitives from a public website and generate starter token files for your project.

xzedm/clipplic-landing

Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code', 'convert this modal/dialog/drawer/panel to Figma'. This is the preferred workflow skill whenever the user wants to build or update a full page, modal, dialog, drawer, sidebar, panel, or any composed multi-section view in Figma from code or a description. Discovers design system components, variables, and styles from Code Connect files, existing screens, and library search, then imports them and assembles views incrementally section-by-section using design system tokens instead of hardcoded values.

xzedm/clipplic-landing

**MANDATORY prerequisite**: you MUST invoke this skill BEFORE every `use_figma` tool call. NEVER call `use_figma` directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context, e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically.

xzedm/clipplic-landing

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

xzedm/clipplic-landing

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications.

xzedm/clipplic-landing

Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.

xzedm/clipplic-landing

Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)

相关技能